moflo

<p align="center"> <img src="https://raw.githubusercontent.com/eric-cielo/moflo/main/docs/Moflo_md.png?v=6" alt="MoFlo" /> </p> # MoFlo **一款独立、有自己意见的AI智能体编排工具包，适用于Claude Code，优化本地开发。** **[官网](https://cielolimitada.com/moflo)** · [npm](https://www.npmjs.com/package/moflo) · [GitHub](https://github.com/eric-cielo/moflo) ## 简介 MoFlo 让 Claude Code 记住它所学到的内容，在探索文件之前检查它所知道的内容，并随着时间的推移变得更加智能——所有这些都是自动的。安装它，运行 `flo init`，重启 Claude Code，一切就都正常工作了：您的文档和代码会在会话开始时被索引，这样 Claude 可以立即搜索它们，门控防止 Claude 无效地探索，任务结果反馈到路由中，以便下次选择正确的智能体类型，上下文耗尽警告告诉您何时启动新会话。无需配置，无需 API 密钥，无需云服务——所有这些都在您的本地机器上运行。 ## 快速开始 ```bash npm install --save-dev moflo flo init ``` 重启 Claude Code。就这样 - 内存、索引、门控和路由都已启用。 或者 - 只需让 Claude 在您的项目中安装 MoFlo 并初始化它！ 要验证所有功能是否正常运行，请在重启后在 Claude Code 中运行 **`/healer`** 技能（或在 CLI 中运行 `flo healer`）- 它会运行完整的诊断测试。如果出现任何问题，请运行 **`/healer --fix`** 以自动修复问题。 ## 下一步：咨询 Eldar 安装 moflo 后，您可以做的对体验最有价值的一件事就是在 Claude Code 会话中运行 **`/eldar`**。 其中 `/healer`（或 CLI 中的 `flo healer`）验证 **moflo 本身** 是否正确连接，**`/eldar`** 会审计 Claude 如何设置以实际使用您的项目 - 指导文档、CLAUDE.md、内存命名空间、钩子/MCP 连线、模型路由，以及您的堆栈中的每个技术（TypeScript、Python、Rust、Go 等）是否有与 Claude 匹配的指导。仅凭堆栈→指导交叉引用，就能解决 *"Claude 在此代码库中感到困惑"* 和 *"Claude 了解此代码库"* 之间的差异。 ``` /eldar # 只读审计；分类查找结果，按严重程度排序 /eldar --fix # 交互式分类 - 选择要修复的内容，Eldar 会指导您完成 ``` 在任何新项目中运行它，任何时候 Claude 感觉不对劲时，或者作为定期健康检查运行。除核心安装外，这是 moflo 提供的最有影响力的功能 - 在 **`/eldar`** 部分中有更多详细信息 [如下](#eldar--咨询-eldar-项目设置审计--向导). ## 有自己意见的默认值 MoFlo 做出了刻意的选择，这样您就不必这样做： - **完全自包含** - 无外部服务，无云依赖，无 API 密钥。所有功能都在您的本地机器上运行。 - **最小依赖** - 小型运行时依赖集，所有 WASM 或预编译二进制文件。无需本地编译，无 `node-gyp`，无需平台特定构建步骤。 - **Node.js 运行时** - 专门针对 Node.js。所有脚本、钩子和工具都是 JavaScript/TypeScript。无需 Python，无 Rust 二进制文件，无本地编译。 - **node:sqlite（内置）** - 内存数据库使用 Node 22 的内置 SQLite 引擎。无需 `better-sqlite3` 本地绑定，无 WASM 往返，无平台特定构建步骤。在 Windows、macOS 和 Linux 上工作相同。 - **默认神经嵌入** - 使用 `all-MiniLM-L6-v2` 进行 384 维嵌入。无哈希回退，无对等可选设置，无安装提示 - 开箱即用的语义搜索。`postinstall` 步骤根据您的平台修剪嵌入运行时，并剥离运行时永远不会加载的 GPU 专用库，在 Linux 上回收大约 340 MB，在 Windows 上回收大约 150 MB。设置 `MOFLO_NO_PRUNE=1` 以跳过修剪，或设置 `ONNXRUNTIME_NODE_INSTALL_CUDA=true` 以保留 CUDA GPU 支持。 - **出厂即完整的学习栈** - 所有功能均已配置并从 `flo init` 开始运行，无需手动设置： - **SONA** （自我优化神经架构）- 从任务轨迹中学习 - **MicroLoRA** - 快速 rank-2 权重适配（~1µs per adapt） - **EWC++** （弹性权重巩固）- 防止跨会话的灾难性遗忘 - **HNSW 向量搜索** - 快速最近邻搜索您的知识库 - **语义路由** - 通过学习模式（ReasoningBank）将任务映射到正确的智能体 - **轨迹持久性** - 结果在会话之间存活 - 所有本地，无 GPU，无 API 密钥，无外部服务。 - **内存优先** - Claude 必须搜索它已经知道的内容，然后再探索文件。通过钩子强制执行，而不是指令。 - **代理注册前任务** - 子代理在跟踪工作之前无法启动。防止智能体蔓延。 - **学习路由** - 任务结果自动反馈到路由系统。无需手动配置 - 它会随着使用而变得更智能。 - **增量索引** - 指导和代码映射索引在每个会话开始时运行，但跳过未更改的文件。首次运行后速度很快。 - **Claude Code 是唯一目标** - MoFlo 构建并发布适用于 Anthropic 的 Claude Code（CLI，IDE 扩展，网页）。它 **不是** Claude Desktop 集成：没有任何内容读取或写入 `~/.claude/claude_desktop_config.json` 或 `%APPDATA%/Claude/`，添加路径到那里始终是一个错误。MCP 工具，内存系统和钩子在原则上可以与任何 MCP 兼容的客户端一起工作，但 Claude Code 是 **唯一** 我们为其编写，测试或接受错误报告的界面。 - **GitHub 导向** - `/flo` 技能，PR 自动化和问题跟踪围绕 GitHub 构建。借助 Claude 的帮助，您可以将其适配到您自己的问题跟踪器和源控制系统。 - **跨平台** - 在 macOS，Linux 和 Windows 上工作相同。 ## 功能 | 功能 | 功能描述 | |---------|-------------| | **语义记忆** | 384 维领域感知嵌入。存储知识，立即搜索。 | | **反思** | 蒸馏会话中的持久教训到可搜索的记忆中 - 自动（自动冥想），或按需使用 `/meditate`。 | | **跨安装共享** | 持久的 `learning` 自动跟随 git 工作树（无需设置）- 以及通过 `flo memory sync` 或 git 跟踪的工件，跨您的机器或整个团队。结构命名空间保持本地。[完整文档 →](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md) | | **代码导航** | 索引您的代码库结构，以便 Claude 可以回答“X 生活在哪里？”而无需 Glob/Grep。 | | **指导索引** | 将您的项目文档（`.claude/guidance/`，`docs/`）分段并使其可搜索。 | | **门控** | 通过 Claude Code 钩子强制执行内存优先和任务创建模式。防止 Claude 跳过步骤。 | | **学习路由** | 将任务路由到正确的智能体类型。从结果中学习 - 随着时间推移变得更好。 | | **拼写引擎** | 将多步骤自动化定义为 YAML - shell 命令，智能体生成，条件，循环，内存操作。[完整文档 →](docs/SPELLS.md) | | **`/flo` 技能** | 通过完整流程执行 GitHub 问题：研究→增强→实施→测试→简化→PR。（也可用作 `/fl`。） | | **上下文跟踪** | 监视上下文窗口使用情况（FRESH → MODERATE → DEPLETED → CRITICAL）并相应地提供建议。 | | **跨平台** | 在 macOS，Linux 和 Windows 上工作。 | ## 入门指南 ### 1. 安装和初始化 ```bash npm install --save-dev moflo flo init ``` `flo init` 自动扫描您的项目以查找指导，代码和测试的位置，然后将结果写入 `moflo.yaml`。它查找： | 什么 | 检查的目录 | 默认值 | |------|----------------------|----------------------| | **指导** | `.claude/guidance`，`docs/guides`，`docs`，`architecture`，`adr`，`.cursor/rules` | `.claude/guidance` | | **源代码** | `src`，`packages`，`lib`，`app`，`apps`，`services`，`server`，`client` | `src` | | **测试** | `tests`，`test`，`__tests__`，`spec`，`e2e`，以及 `src/` 内的 `__tests__` 目录 | `tests` | | **语言** | 扫描检测到的源目录的文件扩展名 | `.ts`，`.tsx`，`.js`，`.jsx` | 它还会生成： | 生成的文件 | 用途 | |----------------|---------| | `moflo.yaml` | 具有检测到的指导/代码位置的项目配置 | | `.claude/settings.json` | Claude Code 的门控钩子 | | `.claude/skills/flo/` | `/flo` 问题执行技能（也可用作 `/fl`） | | `CLAUDE.md` 部分 | 教导 Claude 如何使用 MoFlo | | `.gitignore` 条目 | 排除 MoFlo 状态目录 | 在交互模式下（`flo init` 而不是 `--yes`），它会显示它找到的内容，并让您在写入之前确认或调整。 #### 从 Claude Flow / Ruflo 迁移 如果 `flo init` 检测到现有的 `.claude/settings.json` 或 `.claude-flow/` 目录（来自以前的 Claude Flow 或 Ruflo 安装），则将其视为已初始化的项目，并以 **更新模式** 运行 - 将 MoFlo 的钩子和配置合并到您现有的设置中，而不覆盖您的数据。具体来说： - **钩子** - 如果您的 `.claude/settings.json` 已经有 MoFlo 样式的门控钩子（`flo gate`），则跳过钩子步骤。否则，将 MoFlo 的钩子写入文件（不会删除现有的非 MoFlo 钩子）。 - **MCP 服务器** - MoFlo 在 `.mcp.json` 中将自己注册为 `moflo` 服务器。如果您以前配置了 `claude-flow` 或 `ruflo` MCP 服务器，则这些条目保持不变 - 您可以手动删除它们，一旦您验证 MoFlo 正在工作。 `/healer` 技能（或 CLI 中的 `flo healer`）专门检查 `moflo` 服务器。 - **配置文件** - `moflo.yaml`，`CLAUDE.md` 和 `.claude/skills/flo/` 遵循相同的跳过如果存在逻辑。使用 `--force` 重新生成它们。 要强制在现有设置上进行干净的重新初始化： ```bash flo init --force ``` #### 首次运行注意事项：初始索引期间的 CPU 峰值 **首次** MoFlo 在您的项目中运行 - 通常在 `flo init` 之后和下一次会话启动时 - 它会从头开始构建初始指导，代码映射和测试索引，并为每个块生成 384 维嵌入。对于中等大小的项目，这需要 **一到几分钟**，您可能会在此期间看到 CPU 升高。它在后台运行，因此您可以立即开始工作；您可能会听到风扇的声音，但仅此而已。 之后，索引是 **增量和惰性** 的 - 每个后续会话开始时只重新处理自上次运行以来实际更改的文件，通常在不到一秒的时间内完成，不会产生明显的 CPU 活动。一次性成本是一种刻意的权衡：支付一次，然后每个未来的会话都可以在您的项目已经可搜索的意义上打开。 > **提示：** 让初始索引完成后再运行 **`/healer`** （或 `flo healer`）。Healer 的嵌入和语义质量检查期望索引存在 - 如果您在构建过程中运行它，可能会提示警告，这些警告会在索引完成的那一刻自行解决。 ### 2. 查看您的指导和代码设置 打开 `moflo.yaml` 以查看 `init` 检测到的内容。两个关键部分： **指导** - 帮助 Claude 了解您的项目的文档（约定，架构，领域上下文）： ```yaml guidance: directories: - .claude/guidance # 项目规则，模式，约定 - docs # 一般文档 ``` **代码映射** - 用于索引的源文件以导航“X 生活在哪里？”： ```yaml code_map: directories: - src # 您的源代码 - packages # 共享包（monorepo） extensions: [".ts", ".tsx"] exclude: [node_modules, dist, .next, coverage] ``` **测试** - 用于索引的测试文件，以映射“哪些测试涵盖 X？”： ```yaml tests: directories: - tests # 您的测试文件 - __tests__ # jest 样式的测试目录 patterns: ["*.test.*", "*.spec.*", "*.test-*"] extensions: [".ts", ".tsx", ".js", ".jsx"] exclude: [node_modules, coverage, dist] namespace: tests ``` MoFlo 将您的指导文件分成语义嵌入，索引您的代码结构，并将测试文件映射回其源目标 - 以便 Claude 在触摸任何文件之前搜索您的知识库。根据这些目录调整： ```yaml # 具有共享文档的 Monorepo guidance: directories: [.claude/guidance, docs, packages/shared/docs] code_map: directories: [packages, apps, libs] ``` ### 3. 索引和验证 ```bash flo memory index-guidance # 索引您的指导文档 flo memory code-map # 索引您的代码结构 flo healer # 验证所有功能是否正常（别名：flo doctor） ``` 两个索引在安装后会自动在会话开始时运行，因此您只需在首次设置或进行重大结构更改时手动运行它们。第一个索引可能需要一两分钟大型代码库（1,000+ 文件），但在后台运行 - 您可以立即开始工作。后续索引是增量式的，通常在不到一秒的时间内完成。重新索引所有内容： ```bash flo memory refresh # 重新索引所有内容 + 重新生成嵌入 + 清理 + 清除 ``` ## 自动索引 MoFlo 在每个会话开始时自动索引三种类型的内容，以便您的 AI 助手始终拥有最新的知识，无需手动干预。 ### 索引内容 | 索引 | 内容 | 生成内容 | 命名空间 | |-------|---------|------------------|-----------| | **指导** | 指导目录中的 Markdown 文件（`.claude/guidance/`、`docs/`等） | 分段文本，带有 384 维语义嵌入 - 启用跨项目文档的自然语言搜索 | `guidance` | | **代码映射** | 源代码目录中的源文件（`src/`、`packages/`等） | 结构索引导出，类，函数和类型 - 启用“X 生活在哪里？”导航，无需 Glob/Grep | `code-map` | | **测试** | 测试文件匹配配置的模式（`*.test.*`，`*.spec.*`） | 从测试文件到其源目标的反向映射 - 启用“哪些测试涵盖 X？”查找 | `tests` | ### 工作原理 1. **会话启动钩子** - 当 Claude Code 启动新会话时，MoFlo 的 `SessionStart` 钩子启动索引器，依次运行在单个后台进程中。这在后台运行 - 您可以立即开始工作。 2. **增量** - 每个索引器跟踪文件修改时间。只有自上次索引运行以来更改的文件将被重新处理。第一次运行可能需要一两分钟大型代码库，但后续运行通常在不到一秒的时间内完成。 3. **嵌入生成** - 指导块使用 MiniLM-L6-v2（384 维，WASM）嵌入。这些向量存储在 SQLite 内存数据库中，用于语义搜索。 4. **不阻塞** - 索引器在后台运行，不会阻止您的会话启动。您可以立即开始工作。 ### 配置 每个索引器都可以独立在 `moflo.yaml` 中切换： ```yaml auto_index: guidance: true # 会话开始时索引文档 code_map: true # 会话开始时索引代码结构 tests: true # 会话开始时索引测试文件 ``` 将任何设置为 `false` 以禁用该索引器。底层数据保留在内存中 - 您只需自动刷新它。您仍然可以手动运行索引器： ```bash flo memory index-guidance # 手动指导重新索引 flo memory code-map # 手动代码映射重新索引 flo memory refresh # 重新索引所有内容 + 重新生成嵌入 + 清理 + 清除 ``` ### 自动冥想 — 自动对应 **自动冥想** 在无需请求的情况下执行相同的任务。在您工作时，一个轻量级钩子会注意到一个持久的教训出现 — 更正，您修复的错误，您做出的决定。在下一次会话启动时，一个简短的后台传递使用与 `/meditate` 相同的持久性条和去重存储协议，将它们提炼成 `learnings`。它重用您现有的 Claude Code 会话（无需额外的 API 密钥），在后台运行，**默认启用**。 ```yaml auto_meditate: enabled: true # 设置为 false 以退出 — /meditate 仍可手动使用 ``` 这两个是互补的：自动冥想是始终开启的安全网，`/meditate` 是刻意策划的传递。两者都写入相同的 `learnings` 命名空间，并且都去重，因此它们不会污染彼此 — 并且它们存储的任何内容都可以从那时起用于语义搜索。 ### 跨安装共享学习成果 `learnings` （和 `knowledge`）命名空间是 **持久** 的内存切片 — 用户创作的，值得跨 checkout 携带。数据库的其余部分（代码映射、指导块、运行状态）是结构性或短暂的，可以廉价地重建，因此保持本地。对于持续同步，MoFlo 只共享持久切片 — **从不 *实时共享* 整个 `moflo.db`** 两个守护进程之间，这会导致每个守护进程的内存搜索索引出现分歧。 根据拓扑结构选择机制： | 您希望跨...共享 | 使用 | 如何 | |---------------------------|-----|-----| | Git 工作树 / Conductor 工作空间（同一台机器） | **自动** — 无需设置 | 工作树在会话启动时共享学习成果（存储在 `<git-common-dir>/moflo/durable.db`）。使用 `memory.durable_path` 覆盖；使用 `memory.worktree_sharing: false` 退出 | | 您的笔记本电脑 + 台式电脑 + CI | `flo memory sync --to/--from <file>` | 导出到同步文件夹（Dropbox/iCloud）或复制的文件，在另一台机器上导入 | | 一个团队在一个存储库上 | `flo memory team-export` → 提交 `.moflo/shared/learnings.jsonl` | 队友的会话启动导入合并后 `git pull`（先写入优先；作者出处保留） | | 一个需要快速准备的新工作空间 | `flo memory backup/restore` 或 `memory.hydrate_from` | 从 **整个数据库快照** 播种新工作空间，以便在第一个会话中可搜索 — 无冷重建索引。因为每个工作空间都拥有自己的副本（一次性还原，非实时共享） | 使用 `flo doctor -c shared-db` 验证您的设置（如果您意外地指向了完整的 `moflo.db` 进行实时共享，它会发出警告）。完整指南： [`moflo-cross-install-memory-sharing.md`](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md). ## 门控系统 MoFlo 安装 Claude Code 钩子，在每次工具调用时运行。这些门控共同创建一个 **反馈环路**，防止 Claude 在盲目探索上浪费令牌，并确保它建立在先前的知识之上。 ### 门控解释 | 门控 | 强制执行内容 | 触发时机 | 重要性 | |------|-----------------|------------------|----------------| | **内存优先** | Claude 必须在对指导文件使用 Glob、Grep 或 Read 之前搜索内存数据库 | 在每次 Glob/Grep 调用之前，以及针对 `.claude/guidance/` 的 Read 调用之前 | 防止 AI 重新探索它（或以前的会话）已经索引的文件。强制它首先检查已知内容，节省令牌和上下文窗口。 | | **TaskCreate 优先** | Claude 必须在通过 Task 工具生成子代理之前调用 TaskCreate | 在每次 Task（代理生成）调用之前 | 确保每个委托工作的跟踪。防止在没有明确计划的情况下，Claude 生成失控的代理。 | | **上下文跟踪** | 跟踪对话长度，并警告上下文耗尽 | 在每次用户提示（UserPromptSubmit 钩子） | 随着对话的增长，AI 质量会下降。MoFlo 跟踪交互次数，并分配一个括号（FRESH → MODERATE → DEPLETED → CRITICAL），建议 Claude 在质量下降之前检查进度或启动新会话。 | | **路由** | 分析每个提示并推荐最佳代理类型和模型层 | 在每次用户提示（UserPromptSubmit 钩子） | 通过建议简单任务的 haiku、中等任务的 sonnet、复杂推理的 opus 来节省成本 — 无需您考虑模型选择。 | ### 智能分类 内存优先门控不会盲目阻止每个请求。它会对每个提示进行分类： - **简单指令** （例如，“提交”，“是的”，“继续”，“看起来不错”）— 完全跳过门控，无需内存搜索 - **面向任务的提示** （例如，“修复身份验证错误”，“在 API 中添加分页”）— 强制门控，必须先搜索内存 ### 转义口 在提示符前加上 `@@` 以绕过内存优先门控： ``` @@ 您对这种方法有什么看法？ @@ 问题 — 是否有更好的方法来处理身份验证令牌？ ``` `@@` 前缀在 Claude 看到提示符之前会被剥离，因此不会影响响应。 ### 禁用门控 所有门控都可以在 `moflo.yaml` 中配置： ```yaml gates: memory_first: true # 设置为 false 以禁用内存优先强制执行 task_create_first: true # 设置为 false 以禁用 TaskCreate 强制执行 context_tracking: true # 设置为 false 以禁用上下文括号警告 ``` 您还可以通过删除相应的钩子条目，在 `.claude/settings.json` 中禁用个别钩子。 ## `/flo` 技能 在 Claude Code 中，`/flo`（或 `/fl`）斜杠命令驱动 GitHub 问题执行： ``` /flo <issue> # 完整流程（研究 → 实现 → 测试 → PR) /flo -t <issue> # 仅限票证（研究和更新票证，然后停止) /flo -r <issue> # 仅限研究（分析问题，输出发现) /flo -s <issue> # 群组模式（多代理协调) /flo -h <issue> # 蜂巢模式（基于共识的协调) /flo -n <issue> # 正常模式（默认，单个代理，无群组） ``` 有关完整选项和详细信息，请键入 `/flo` 且不带参数 — Claude Code 将显示完整的技能文档。也可以使用 `/fl`。 ### 史诗处理 当您传递一个问题编号时，`/flo` 会自动检查它是否是史诗 — 无需额外标志。如果问题满足以下条件，则将其视为史诗： - 它具有与 `epic`、`tracking`、`parent` 或 `umbrella` （不区分大小写）匹配的标签 - 其正文包含 `## Stories` 或 `## Tasks` 部分 - 其正文具有待办事项链接的问题： `- [ ] #101` - 其正文具有编号的问题引用： `1. #101` - 问题具有 GitHub 子问题（通过 API） 当检测到史诗时，`/flo` 会顺序处理每个子故事 — 每个故事的完整流程（研究 → 实现 → 测试 → PR），一次一个，按列出的顺序。 对于具有独立故事的简单史诗， `/flo <epic>` 就是您需要的。对于复杂的功能，您需要状态跟踪、恢复能力和故事之间的自动合并，请使用 `flo epic` 代替。 ### 功能编排（`flo epic`） `flo epic` 是强大的史诗运行器 — 它在 `/flo` 的基础上添加了持久状态、从失败恢复和每个故事的自动合并。它接受一个 GitHub 史诗问题编号： ```bash flo epic 42 # 获取史诗 #42，顺序运行所有故事 flo epic 42 --dry-run # 预览执行计划而不运行 flo epic 42 --strategy auto-merge # 每个故事的 PR 与故事之间的自动合并 flo epic status 42 # 检查进度（哪些故事通过/失败） flo epic reset 42 # 重置状态以重新运行 ``` `flo epic` 从 GitHub 获取史诗，提取子故事，然后使用状态跟踪通过 `/flo` 运行每个子故事。如果一个故事失败，您可以修复问题并重新运行 `flo epic 42` — 它会从中断的地方继续，跳过已经通过的故事。（`flo epic run 42` 是同一个简写的显式别名。） | | `/flo <epic>` | `flo epic <epic>` | |---|---|---| | **状态跟踪** | 否 | 是（`epic-state` 内存命名空间） | | **从失败恢复** | 否 | 是（跳过已通过的故事） | | **自动合并 PR** | 否 | 是（`--strategy auto-merge`） | | **干运行预览** | 否 | 是 | ## 咒语 ### 什么是咒语？ 咒语是声明性 YAML 自动化，由可插拔的步骤命令组成。它们之所以存在，是因为 shell 脚本会漂移，临时提示不可重现，CI/CD 管道是本地自动化的错误工具。咒语是 **确定性** 的（相同的输入 → 相同的步骤），**可审查** 的（一个 YAML 文件，您像配方一样阅读），并且 **可重放** 的（明天重放，行为相同）。咒语从 CLI (`flo spell cast`)、Claude Code 内的 MCP 工具调用或按计划运行。 ### 它们如何工作？ 每次施放都经过相同的生命周期： 1. **解析和验证** — 解析 YAML，并检查每个步骤的 `config` 是否与其命令的模式匹配。 2. **解析能力** — 每个步骤声明它需要什么（`shell`、`net`、`fs:read`、`fs:write`、`memory`、`credentials`、`browser`、`agent`）。未声明的访问权限在执行前被拒绝。 3. **执行步骤图** — 默认情况下，步骤顺序运行，或在具有 `depends_on` 的顺序和 `condition`/`loop` 的并行组中运行。 4. **输出流向前** — 任何步骤都可以引用先前步骤的输出作为 `{stepId.field}`，以便后续步骤可以消耗先前的结果。 5. **持久性** — 内存写入、工件和每个步骤的日志在运行之间持续存在；支持暂停/恢复和干运行。 ```bash flo spell cast -n development # 施放命名咒语 flo spell cast -f ./my-spell.yaml # 从文件施放 flo spell cast -n sa --dry-run # 验证而不施放 flo spell list # 列出可用咒语和最近的运行 flo spell grimoire list # 浏览内置咒语模板 flo spell schedule list # 列出已计划的咒语 ``` ### 定义咒语 ```yaml name: my-spell steps: - name: lint command: npm run lint - name: test command: npm test - name: deploy command: ./deploy.sh depends_on: [lint, test] ``` 步骤支持 shell（`bash`）、代理生成、内存读写、条件、循环、并行组、浏览器自动化、GitHub/IMAP/Outlook/Slack/MCP 集成、提示、等待、图表和复合步骤。请参阅 [docs/SPELLS.md](docs/SPELLS.md) 以获取完整的模式。 ### 沙盒和安全 咒语以 **最小特权访问** 运行。每个步骤命令声明它需要的功能（`shell`、`net`、`fs:read`、`fs:write`、`memory`、`credentials`、`browser`、`browser:evaluate`、`agent`），而运行器会阻止任何未声明的访问。咒语作者可以进一步限制每个步骤的功能 — 例如 `fs:read: ["./config/"]` 或 `shell: ["cat", "jq"]` — 但永远不会扩展它们。 Bash 步骤在可用的操作系统沙盒中运行。MoFlo 会自动选择您机器上安装的最好层级： | 层级 | 平台 | 隔离 | |------|----------|-----------| | Docker | 所有 | 容器，最严格 | | bwrap | Linux | 用户命名空间 | | sandbox-exec | macOS | Apple seatbelt 配置文件 | | 无 | 备用 | 仅能力强制执行 | 沙盒默认情况下为 `network-off`；步骤必须显式声明 `net` 才能访问外部世界。以 `{credentials.X}` 引用的凭据将从加密凭据存储中解析，在日志中屏蔽，并且永远不会写入磁盘。破坏性模式检查器会拒绝运行类似 `rm -rf /`、`git push --force` 等 bash 命令。有关完整模型，请参阅 [docs/SPELL-SANDBOXING.md](docs/SPELL-SANDBOXING.md)。 ### 可重用性 您在三个层级与咒语交互： 1. **已发货的咒语** — 与 MoFlo 捆绑并准备好施放的咒语。使用 `flo spell grimoire list` 浏览它们。 2. **用户咒语** — 您放入 `.claude/spells/` 的 YAML 文件。在 `moflo.yaml` 中覆盖位置： ```yaml spells: userDirs: - .claude/spells - my/project/spells ``` 具有与已发货咒语相同 `name` 的用户咒语会获胜 — 这就是您在不分叉的情况下自定义已发货咒语的方法。 3. **自定义步骤命令和连接器** — 将 TypeScript/JavaScript 文件放入 `.claude/spells/steps/`（新的步骤类型）和 `.claude/spells/connectors/`（新的连接器）。它们在启动时自动发现。包装重型 SDK（IMAP、MCP）的连接器会将这些 SDK 声明为 `optionalDependencies`；仅当您的咒语使用它们时才安装它们。 ### 调度 咒语可以按计划运行。MoFlo 背景守护进程每分钟轮询一次到期咒语并施放它们 — 无需外部 cron，无需额外服务。 **三种计时选项：** ```bash # Cron（5 个字段：分钟 小时 日期 月份 星期几） flo spell schedule create -n nightly-audit --cron "0 2 * * *" # 间隔（例如，90s，30m，6h，1d） flo spell schedule create -n health-check --interval 30m # 一次性（ISO 8601 日期和时间） flo spell schedule create -n migration --at 2026-04-15T09:00:00Z ``` 您也可以在咒语 YAML 中直接声明计划 — 这会在每次守护进程启动时注册它： ```yaml name: nightly-audit schedule: cron: "0 2 * * *" steps: - id: audit type: bash config: command: ./scripts/audit.sh ``` **守护进程先决条件。** 调度仅在守护进程运行时触发。为了在重启后继续运行： ```bash flo daemon install # 注册一个 OS 级别自启动服务 flo daemon status # 显示服务是否已注册并正在运行 ``` `flo spell schedule create` 会发出警告，当守护进程未安装时，您不会默默错过运行。 **监控。** **[Luminarium](#the-luminarium)** — moflo 的 localhost 守护进程仪表盘 — 显示实时调度、最近的执行和每个调度的控制（禁用 / 重新启用 / 立即运行），以及工作器健康状况、内存统计和 Claude Code 会话统计信息。在您的 Claude 会话中询问 `/luminarium`，它将打印链接。 有关完整配置（`scheduler:` 块在 `moflo.yaml` 中）、事件类型和重启后的追赶窗口，请参阅 [docs/SPELLS.md#scheduling](docs/SPELLS.md#scheduling)。 ### 使用 `/spell-builder` 技能构建咒语 在 Claude Code 中，使用 `/spell-builder` 技能交互式地创建、编辑和验证咒语定义。该技能了解完整的咒语模式和可用的步骤命令，因此您可以自然语言描述您想要的内容，它将生成 YAML： ``` /spell-builder # 启动咒语生成器 ``` ### MoFlo 随附的其他 AI 客户端技能 除了 `/flo`、`/spell-builder` 和 `/eldar` 之外，MoFlo 还附带了几个专注的斜杠命令技能，这些技能在您 `flo init` 后可以在任何使用者项目中使用： | 技能 | 目的 | |-------|---------| | `/guidance` | 作者和审核指导文档。默认情况下，Claude 的指导写入 `.claude/guidance/` 作为 Markdown，应用 moflo 的通用规则。`-h` 切换受众为人类（更轻松的规则集，写入 `docs/`）。 `--html` 发出 HTML 以及最小的默认样式表。 `-a` 审核 `.claude/guidance/` 中的每个文档以对抗通用规则。 | | `/flo-simplify`（别名 `/distill`） | 当前差异的自适应代码审查。基于层级的分发 — 微不足道的编辑获得自我审查，小差异获得一个路由代理，跨切割重构获得三个并行代理。通过 moflo 模型路由器路由以实现成本感知执行。（命名为 `/flo-simplify` 以避免与 Claude Code 内置的 `/simplify` 冲突；也可用作 `/distill` 以获得更神奇的感觉。） | | `/quicken`（别名 `/perf-audit`） | 临时性能审计 — “加速代码库”。揭示 N+1 查询、不必要的重新渲染、缺少缓存、内存泄漏和冗余计算，然后在 **会话中内联** 处方。默认情况下，它的作用范围是当前差异（或您命名的路径），因此它永远不会重新审计整个树。取代旧的始终开启的 `optimize` 守护进程工作器。 | | `/ward`（别名 `/test-gaps`） | 临时测试间隙审计 — “保护代码库”。揭示未测试的函数、未覆盖的边缘情况和缺少的错误处理/集成测试，然后生成可粘贴的测试代码段 **在会话中内联**。默认情况下，它的作用范围是当前差异（或您命名的路径）。取代旧的始终开启的 `testgaps` 守护进程工作器。 | | `/commune` | 苏格拉底式需求阐明。将模糊的“我想知道我到底需要什么”想法转变为一个具体的规格，然后将其交给 `/flo` 票证、咒语或内存。 `/meditate` 的执行前对应 — 使用它来 *打开* 一个工作单元。 | | `/divine` | 具有显式置信度门控的多跳网络研究。计划查询、搜索网络、评估其自身的置信度，并在达到答案支持良好（或达到跳跃上限）之前继续挖掘 — 然后返回引用的综合和记忆有效的方法，以便下一次研究运行开始时更加智能。 | | `/meditate` | 深思熟虑的会话回顾 — 将持久的教训提炼到 `learnings` 内存命名空间中，并与已有的内容去重。有关完整内容，请参阅 [Learning From Your Sessions](#learning-from-your-sessions)，包括其自动对应项 auto-meditate。 | | `/spell-schedule` | 在本地 moflo 守护进程（cron、间隔或一次性）上安排咒语，无需离开聊天。 对于远程Anthropic云代理上的调度，请改用Claude Code内置的 `/schedule`。 | 在没有任何参数的情况下运行任意一个，以查看完整的用法，或在 `.claude/skills/` 中浏览源代码（每个技能都是一个单独的 `SKILL.md` 文件）。 ### 史诗 史诗是一种处理 GitHub 问题 的专门流程，这些问题包含多个子故事。当你将 GitHub 问题传递给 `/flo`，并且它被检测为史诗时，MoFlo 会通过完整的 `/flo` 流程（研究 → 实现 → 测试 → PR）依次处理每个子故事。 对于简单的史诗，`/flo <史诗编号>` 就足够了。对于需要状态跟踪、从失败中恢复和故事间自动合并的复杂功能，请使用专用的 `flo epic` 命令： ```bash flo epic 42 # 运行史诗 #42 中的所有故事 flo epic 42 --strategy auto-merge # 每个故事的 PR 都带有自动合并 flo epic 42 --dry-run # 预览执行计划 flo epic status 42 # 检查进度 flo epic reset 42 # 重置状态以重新运行 ``` 有关史诗的检测标准以及 `/flo <史诗>` 和 `flo epic run` 之间的比较，请参阅上面的 [史诗处理](#史诗处理) 部分。 ## 光明园 光明园是 MoFlo 的本地主机守护进程仪表盘。它在后台守护进程启动时自动启动（无需安装额外的服务），并且只要守护进程运行，它就会一直运行。 ### 查找 URL 在 MoFlo 项目的 Claude Code 会话中，询问 **`/luminarium`** — 该技能会打印当前项目的仪表盘 URL。`flo daemon status` 会打印相同的 URL，以及健康状况摘要。每个项目都绑定自己的端口，因此同一台机器上的两个项目永远不会冲突。 ### 显示内容 | 选项卡 | 您看到的内容 | |-----|--------------| | **工作进程** | 守护进程运行的实时代理进程（状态栏更新器、索引器、嵌入器等） | | **调度** | 所有已注册的咒语调度（cron / 间隔 / 一次性），具有立即运行和禁用控制 | | **执行** | 最近的咒语运行 — 持续时间、退出代码、逐步输出 | | **内存** | 内存命名空间分解、向量计数、嵌入后端、HNSW 索引健康状况 | | **Claude 统计** | 每个会话的 Claude Code 转录统计 — 标记、调用的工具、触摸的文件（仅限本地主会话） | ### 标志 - `flo daemon start --no-dashboard` — 完全禁用 HTTP 服务器（守护进程本身仍在运行） - `flo daemon start --dashboard-port <N>` — 固定到特定端口，覆盖每个项目的默认端口。也可以接受 `MOFLO_DAEMON_PORT` 环境变量，MoFlo 在与守护进程通信时尊重该变量 ## 命令 您不需要运行这些命令来进行正常使用 — `flo init` 会设置所有内容，钩子会自动处理内存、路由和学习。这些命令用于手动设置、调试和调整。 ### 内存 ```bash flo memory store -k "键" --value "数据" # 存储 384 维嵌入 flo memory search -q "身份验证模式" # 语义搜索 flo memory index-guidance # 索引指导文档 flo memory code-map # 索引代码结构 flo memory rebuild-index # 重新生成所有嵌入 flo memory refresh # 重新索引所有 + 重新生成 + 清理 + 真空 flo memory stats # 显示统计信息 ``` ### 路由和学习 ```bash flo hooks route --task "描述" # 将任务路由到最佳代理 flo hooks learn --pattern "..." --domain "." # 存储模式 flo hooks patterns # 列出已学习的模式 flo hooks consolidate # 提升/修剪模式 ``` ### 网关 ```bash flo gate check-before-scan # 在内存未搜索之前阻止 Glob/Grep flo gate check-before-agent # 在没有 TaskCreate 的情况下阻止 Agent 工具 flo gate prompt-reminder # 上下文括号跟踪 flo gate session-reset # 重置网关状态 ``` ### 诊断 ```bash flo healer # 快速健康检查（环境、依赖项、配置） flo healer --fix # 自动修复问题（内存数据库、守护进程、配置、MCP、僵尸进程） flo diagnose # 完整集成测试（内存、集群、蜂巢、钩子、神经） flo diagnose --suite memory # 仅运行内存测试 flo diagnose --json # JSON 输出用于 CI/自动化 ``` `flo doctor` 仍然被接受为 `flo healer` 的别名 — 以下每个标志和子命令都在两个名称下工作。 #### `flo healer` — 健康检查 `flo healer` 对您的环境运行 38 个并行健康检查，并为每个检查报告通过/警告/失败： | 检查 | 验证内容 | |-------|-----------------| | **版本新鲜度** | 已安装的 MoFlo 版本是否与 npm 上的最新版本匹配（检测过时的 npx 缓存） | | **Node.js 版本** | Node.js >= 20 已安装 | | **npm 版本** | npm >= 9 已安装 | | **Claude Code CLI** | `claude` 命令可用 | | **Git** | Git 已安装 | | **Git 仓库** | 项目位于 Git 仓库内 | | **配置文件** | 有效的 `moflo.yaml` 存在 | | **状态栏** | 状态栏配置已在 `.claude/settings.json` 中连接（自动修复时缺失） | | **守护进程状态** | 后台守护进程正在运行（检查 PID，清理过时的锁） | | **内存数据库** | SQLite 内存数据库存在且可访问 | | **嵌入** | 内存数据库中索引的向量，HNSW 索引存在 | | **嵌入卫生** | 索引器写入保留现有嵌入而不是覆盖它们 | | **测试目录** | `moflo.yaml` 中的测试目录存在于磁盘上，报告自动索引状态 | | **MCP 服务器** | `.mcp.json` 中配置了 `moflo` MCP 服务器 | | **磁盘空间** | 足够的可用磁盘空间（80% 时警告，90% 时失败） | | **TypeScript** | TypeScript 编译器可用 | | **语义质量** | 语义搜索返回相关、不同的结果，相似性得分可接受 | | **智能** | SONA、ReasoningBank、PatternLearner、LoRA、EWC++ 和 RL 子系统已加载 | | **咒语引擎** | 核心咒语模块、步骤命令、加载器和索引存在 | | **僵尸进程** | 没有孤立的 MoFlo node 进程运行 | | **子代理健康** | 代理生命周期（启动 → 状态 → 终止）成功完成 | | **咒语执行** | 端到端咒语探针运行一个真实的步骤并捕获输出 | | **MCP 工具调用** | MCP 工具模式已加载且可调用 | | **MCP 咒语集成** | MCP 工具和咒语引擎功能之间桥梁正确 | | **钩子执行** | 钩子执行器功能正常，可以触发钩子 | | **网关健康** | 所有网关案例、钩子绑定和状态文件完好无损 | | **MofloDb 桥** | 内存数据库适配器（node:sqlite + HNSW）已连接且可路由 | | **沙盒层** | 检测到哪个沙盒后端可用（Docker / bwrap / sandbox-exec / none） | **自动修复模式** (`flo healer --fix`) 尝试自动修复每个失败的检查： | 问题 | `--fix` 执行的操作 | |-------|------------------| | 内存数据库缺失 | 创建 `.swarm/` 目录并初始化 SQLite 数据库 | | 嵌入未初始化 | 初始化内存数据库并运行 `embeddings init` | | 配置文件缺失 | 运行 `config init` 生成默认值 | | 状态栏未连接 | 将 `statusLine` 配置块添加到 `.claude/settings.json` | | 过时的守护进程锁 | 删除过时的 `.moflo/daemon.lock` 并重启守护进程 | | 格式错误的 `.mcp.json`（例如，未转义的 Windows 路径） | 备份损坏的文件为 `.mcp.json.malformed-<ts>`，重新生成干净的文件，验证其解析（#1126） | | 有效的 `.mcp.json` 中缺少 MCP 服务器 | 运行 `claude mcp add moflo` 以注册服务器 | | 缺失的 Claude Code CLI | 全局安装 `@anthropic-ai/claude-code` | | 僵尸进程 | 终止孤立的 MoFlo 进程（跟踪 + 操作系统级扫描） | 自动修复后，修复程序重新运行所有检查并显示更新的结果。无法自动修复的问题会列出手动修复命令。 附加标志： ```bash flo healer --install # 自动安装缺失的 Claude Code CLI flo healer --kill-zombies # 查找并终止孤立的 MoFlo 进程 flo healer -c memory # 仅检查特定组件 flo healer -c embeddings # 仅检查嵌入健康状况 flo healer --verbose # 详细输出 ``` #### `/eldar` — 咨询埃尔达（项目设置审计 + 向导） `/eldar` 审核 Claude 如何设置和使用项目 — 指导、CLAUDE.md、内存命名空间、钩子/MCP 连线、模型路由和栈感知指导差距 — 然后引导您修复您选择的问题。在启动新项目时，当 Claude 感到迷失或效率低下时，或作为定期健康检查时使用。 ``` /eldar # 只读审计；分类报告 + 排名前 3 的推荐 /eldar --fix # 审计，然后交互式故障排除菜单 — 选择要解决的问题 ``` 埃尔达 **咨询** 修复者（他们调用 `flo healer --json` 作为审计检查之一） — 它们不能替代修复者。审计类别包括设置健康、索引新鲜度、版本偏差、模型/令牌路由、CLAUDE.md 大小 + 引用完整性、指导内容 + 结构、内存健康、钩子/MCP 连线、设置健全性、咒语 + 子代理库存、**栈 → 指导交叉引用**（检测到 package.json/pyproject.toml/Cargo.toml/go.mod 中的技术栈并标记每个检测到的技术栈没有匹配的指导文档 — 新采用者的最大杠杆发现），以及历史记录中尽力而为的反模式检测。 在 `--fix` 模式下，每个选择的问题都会驱动适当的子流程：修复者用于修复设置，`/guidance` 技能用于指导作者（向导，绝不自动生成），用于缺失的 CLAUDE.md 的栈感知脚手架，`flo init --upgrade` 用于钩子/MCP 连线。每个写入操作在落地前都会得到确认。 #### `flo diagnose` — 集成测试 而 `healer` 检查您的环境，`diagnose` 端到端地测试每个子系统：内存 CRUD、嵌入生成、语义搜索、集群生命周期、 hive-mind 共识、任务管理、钩子、配置、神经模式和初始化幂等性。每个测试后都会清理所有测试数据 — 不会留下任何内容。 ### GitHub 仓库设置 ```bash flo github setup # 一次性：生成 CI + 应用仓库设置 + 分支保护 flo github setup --dry-run # 预览所有更改而不进行更改 flo github ci # 从项目配置生成 .github/workflows/ci.yml flo github ci --dry-run # 将 CI 配置打印到 stdout flo github settings # 通过 gh CLI 应用仓库设置 + 分支保护 flo github settings --dry-run # 预览设置更改 ``` `flo github ci` 自动从 `moflo.yaml` 和 `package.json` 中检测您的包管理器（npm/pnpm/yarn/bun）、TypeScript 和测试目录，然后生成带有安装、构建、 lint、类型检查和测试步骤的 GitHub Actions CI 管道。 `flo github settings` 通过 `gh` CLI 应用推荐的默认值：删除分支后合并、带有 PR 标题/正文的压缩合并、自动合并、线性历史记录和可配置的分支保护（需要审查、拒绝过时的审查、阻止强制推送）。需要 `gh auth login`。 ### 系统 ```bash flo init # 初始化项目（一次性设置） flo --version # 显示版本 ``` ## 默认情况下附带的内容 `flo init` 会自动连接以下系统。以下是每个系统的作用、重要性以及它是否默认启用。 ### 钩子（默认启用） 钩子是 Claude Code 在其生命周期中的特定阶段自动运行的 shell 命令。MoFlo 在 8 个生命周期事件中安装了 26 个钩子绑定。您不需要调用这些 — 它们会自动触发。 | 钩子事件 | 触发 | 执行 | 默认启用 | |------------|-----------|-------------|:---:| | **PreToolUse: Write/Edit** | `flo hooks pre-edit` | 记录即将编辑的文件，捕获编辑前状态以便学习 | 是 | | **PreToolUse: Glob/Grep** | `flo gate check-before-scan` | 内存优先网关 — 在搜索内存之前阻止文件资源管理器 | 是 | | **PreToolUse: Read** | `flo gate check-before-read` | 在搜索内存之前阻止直接读取指导文件 | 是 | | **PreToolUse: Bash** | `flo gate check-dangerous-command` | 对 shell 命令的安全检查 | 是 | | **PreToolUse: Bash** | `flo gate check-before-pr` | 在 `gh pr create` 之前验证 PR 准备情况 | 是 | | **PostToolUse: Write/Edit** | `flo hooks post-edit` | 记录编辑结果，可选地训练神经模式 | 是 | | **PostToolUse: Write/Edit** | `flo gate reset-edit-gates` | 在写入完成后重置编辑相关的网关状态 | 是 | | **PostToolUse: Agent** | `flo hooks post-task` | 记录任务完成情况，将结果反馈到路由学习器 | 是 | | **PostToolUse: TaskCreate** | `flo gate record-task-created` | 记录已注册任务（清除 TaskCreate 网关） | 是 | | **PostToolUse: Bash** | `flo gate check-bash-memory` | 检测 Bash 中的内存搜索命令（清除内存网关） | 是 | | **PostToolUse: Bash** | `flo gate record-test-run` | 记录 Bash 中的测试运行情况，用于测试输出网关 | 是 | | **PostToolUse: Skill** | `flo gate record-skill-run` | 记录技能调用情况（清除与技能相关的网关） | 是 | | **PostToolUse: memory_search** | `flo gate record-memory-searched` | 记录已搜索内存（清除内存优先网关） | 是 | | **PostToolUse: TaskUpdate** | `flo gate check-task-transition` | 验证任务状态转换（防止跳过状态） | 是 | | **PostToolUse: memory_store** | `flo gate record-learnings-stored` | 记录已将学习结果存储到内存中 | 是 | | **UserPromptSubmit** | `prompt-hook.mjs` | 重置每提示网关状态，跟踪上下文括号，将任务路由到代理 | 是 | | **UserPromptSubmit** | `meditate-capture.mjs meditate-detect` | 自动冥想：检测到持久化课程在实时会话中出现，并将其排队进行蒸馏 | 是 | | **SubagentStart** | `subagent-start` | 将上下文和指导注入生成的子代理 | 是 | | **SessionStart** | `session-start-launcher.mjs` | 启动自动索引器（指导、代码映射、测试），恢复会话状态，触发自动冥想蒸馏过程 | 是 | | **SessionStart** | `auto-memory-hook.mjs` | 从 Claude 的持久内存中导入自动内存条目 | 是 | | **Stop** | `flo hooks session-end` | 持久化会话指标，导出学习数据 | 是 | | **Stop** | `auto-memory-hook.mjs` | 在会话关闭时同步自动内存状态 | 是 | | **Stop** | `session-continuity.mjs capture` | 捕获“您离开的地方”的会话摘要，用于相关性网关注入在下一个会话开始时 | 是 | | **Stop** | `meditate-capture.mjs meditate-scrape` | 自动冥想：刮取此会话中识别的课程到蒸馏队列 | 是 | | **PreCompact** | `flo gate compact-guidance` | 在上下文压缩前注入指导摘要 | 是 | | **Notification** | `flo hooks notification` | 通过 MoFlo 将 Claude Code 通知路由 | 是 | ### 系统（开箱即用） 这些是钩子和命令交互的后端系统。 | 系统 | 功能 | 重要性 | 开箱即用 | |--------|-------------|---------------|:---:| | **语义记忆** | SQLite 数据库（Node 内置 `node:sqlite`）存储知识条目，带有 384 维向量嵌入 | 您的 AI 助手在多个会话中积累项目知识，而不是每次都从头开始 | 是 | | **HNSW 向量搜索** | 分层导航小世界索引，用于快速最近邻搜索 | 数千个存储条目的搜索结果在毫秒内返回，而不是线性扫描 | 是 | | **指导索引** | 将 markdown 文档分成重叠的段落，每个段落都嵌入 MiniLM-L6-v2 | 项目文档变得可搜索，不仅限于关键词，还包括含义（例如“身份验证如何工作？”） | 是 | | **代码映射** | 解析源文件中的导出、类、函数、类型 | AI 可以从索引中回答“X 在哪里定义？”而不是运行 Glob/Grep | 是 | | **测试索引** | 将测试文件映射到其源目标，基于命名模式 | AI 可以回答“哪些测试涵盖 X？”并识别未测试的代码 | 是 | | **门控** | 基于钩子的内存优先和任务注册模式强制执行 | 防止 AI 在盲目探索和未跟踪的代理生成上浪费令牌 | 是 | | **上下文跟踪** | 带有括号分类（新鲜/中等/耗尽/临界）的交互计数器 | 在上下文质量下降之前发出警告，并在需要时建议检查点或重新开始 | 是 | | **语义路由** | 将任务描述与代理类型匹配，使用 12 个内置模式的向量相似性 | 自动将工作路由到合适的专家（安全架构师、测试人员、编码人员等） | 是 | | **学习路由** | 记录任务结果（代理类型 + 成功/失败）并将其反馈到路由中 | 路由随着时间的推移变得更加智能；成功的模式在未来的推荐中权重更高 | 是 | | **SONA 学习** | 自优化神经架构，从任务轨迹中学习 | 根据实际结果调整路由权重，而不仅仅是关键词匹配 | 是 | | **MicroLoRA 适配** | 成功模式的秩-2 LoRA 权重更新（~1µs per adapt） | 细粒度模型适配，无需完整重新训练 | 是 | | **EWC++ 巩固** | 弹性权重巩固，防止灾难性遗忘 | 新学习内容不会覆盖早期会话的模式 | 是 | | **会话持久性** | 停止钩子导出会话指标；会话启动钩子恢复先前状态 | 星期一学习的模式在星期五可用 | 是 | | **自动冥想** | 在实时会话中识别持久的教训，并在下一个会话启动时将它们提炼到 `learnings` 命名空间中 | 每个会话中的高信号教训都会自动保留；无需记住运行 `/meditate` | 是 | | **状态栏** | 显示 git 分支、会话状态、内存统计信息、MCP 状态的实时仪表盘 | 一目了然地了解 MoFlo 正在执行什么 | 是 | | **MCP 工具服务器** | 80+ MCP 工具，用于内存、钩子、协调、咒语、集群等（默认延迟模式） | 让 Claude Code 直接调用 MoFlo 功能 | 是（延迟） | ### 系统（可用但默认关闭） | 系统 | 功能 | 如何启用 | |--------|-------------|---------------| | **模型路由** | 根据复杂性分析自动选择 haiku/sonnet/opus 模型 | 在 `moflo.yaml` 中设置 `model_routing.enabled: true` | | **MCP 自动启动** | 在会话开始时自动启动 MCP 服务器 | 在 `moflo.yaml` 中设置 `mcp.auto_start: true` | | **工具模式预加载** | 在启动时加载所有 MCP 工具模式（100+），而不是按需加载 | 在 `moflo.yaml` 中设置 `mcp.tool_defer: false` | ## 两层任务系统 MoFlo 不会取代 Claude Code 的任务系统；它会将其包装。Claude Code 处理生成代理和运行代码。MoFlo 在其上添加了一个协调层，处理内存、路由和学习。 ``` ┌──────────────────────────────────────────────────┐ │ CLAUDE CODE（执行层） │ │ 生成代理，运行代码，流式传输输出 │ │ TaskCreate → 代理 → TaskUpdate → 结果 │ ├──────────────────────────────────────────────────┤ │ MOFLO（知识层） │ │ 路由任务，控制代理生成，存储 │ │ 模式，从结果中学习 │ └──────────────────────────────────────────────────┘ ``` 以下是典型任务通过两层的流程： 1. **MoFlo 路由** - 在工作开始之前，MoFlo 分析提示并通过钩子或 MCP 工具推荐代理类型和模型层。 2. **MoFlo 门控** - 在代理生成之前，MoFlo 验证内存是否已搜索以及任务是否已注册。这防止了盲目探索。 3. **Claude Code 执行** - 实际代理通过 Claude Code 的原生任务系统运行。MoFlo 不管理代理；Claude Code 处理执行、输出和完成。 4. **MoFlo 学习** - 在代理完成任务后，MoFlo 在其内存数据库中记录了什么有效（或无效）。成功的模式会反馈到未来的路由中。 关键见解：**Claude Code 处理执行，MoFlo 处理知识。** Claude Code 擅长生成代理和运行代码。MoFlo 擅长记住发生了什么，路由到正确的代理，并确保在开始探索之前检查先前知识。 对于复杂的工作，MoFlo 将任务结构化为波浪 - 一个研究波浪发现上下文，然后一个实现波浪对其采取行动 - 依赖关系通过 Claude Code 的任务系统和 MoFlo 的协调层跟踪。完整的集成模式在 `.claude/guidance/moflo-claude-swarm-cohesion.md` 中有文档记录。 `/flo` 技能将两个系统结合起来，用于 GitHub 问题 - 驱动整个过程（研究 → 增强 → 实现 → 测试 → 简化 → PR），使用 Claude Code 的代理执行和 MoFlo 的内存进行连续性。 ### 智能代理路由 MoFlo 配备了 12 个内置任务模式，将常见工作映射到正确的代理类型： | 模式 | 关键词 | 主要代理 | |---------|----------|---------------| | security-task | auth, password, encryption, CVE | security-architect | | testing-task | test, spec, coverage, e2e | tester | | database-task | schema, migration, SQL, ORM | architect | | feature-task | implement, add, create, build | architect → coder | | bugfix-task | bug, fix, error, crash, debug | coder | | api-task | endpoint, REST, route, handler | architect → coder | | ... | | *(12 patterns total)* | 当您路由任务（`flo hooks route --task "..."` 或通过 MCP）时，MoFlo 运行语义相似性与这些模式对抗，使用 HNSW 向量搜索，并返回具有置信度分数的排名推荐。 **路由随着时间推移变得更加智能。** 每次任务成功完成，MoFlo 的任务后钩子都会记录结果 - 完整的任务描述，处理它的代理以及是否成功。这些学习模式与内置种子相结合，在每次未来的路由调用中。 由于学习模式包含丰富的任务描述（不仅仅是简短的关键词），因此它们在积累过程中具有更好的区分度。 路由结果在会话之间持续。您可以使用 `flo hooks patterns` 检查它们，或使用 `flo hooks transfer` 在项目之间传输它们。 ### 内存和知识存储 MoFlo 使用 SQLite 数据库（通过 Node 22 内置的 `node:sqlite` - 无原生依赖）存储三种类型的知识： | 命名空间 | 存储内容 | 如何存储 | |-----------|---------------|-------------------| | `guidance` | 分段项目文档（`.claude/guidance/`，`docs/`）带有 384 维嵌入 | 会话启动时的 `flo-index` | | `code-map` | 源文件的结构索引（导出、类、函数） | 会话启动时的 `flo-codemap` | | `tests` | 测试文件 → 源目标反向映射 | 会话启动时的 `flo-testmap` | | `patterns` | 从成功任务结果中学习到的模式 | 代理工作后的任务后钩子 | **语义搜索** 使用神经嵌入（MiniLM-L6-v2，384 维）的余弦相似度。当 Claude 搜索内存时，它会根据语义相似度获得最相关的分段排名 - 而不是关键词匹配。 **会话启动索引** - 背景索引器（指导、代码映射、测试）在每个会话启动时运行。它们是增量式的 - 不变的 文件被跳过 - 并且并行运行，因此它们不会阻塞会话。 **跨会话持久性** - 存储在数据库中的所有内容都可以在会话之间存活。星期一学习的模式在星期五可用。停止钩子导出会话指标，会话恢复钩子加载先前状态。 ### 适用于 Claude 当运行 `flo init` 时，它会在您的 CLAUDE.md 中追加一个部分，教导 Claude： - 总是在 Glob/Grep/Read 之前搜索内存（由门控强制执行） - 使用 `mcp__moflo__memory_search` 进行知识检索 - 使用 `/flo <issue>`（或 `/fl`）进行问题执行 - 在任务完成后存储学习成果 ## 完整的配置参考 `flo init` 生成一个 `moflo.yaml` 在您的项目根目录下。以下是完整的选项集： ```yaml project: name: "my-project" guidance: directories: [.claude/guidance] namespace: guidance code_map: directories: [src, packages] extensions: [".ts", ".tsx"] exclude: [node_modules, dist] namespace: code-map tests: directories: [tests, __tests__] patterns: ["*.test.*", "*.spec.*", "*.test-*"] extensions: [".ts", ".tsx", ".js", ".jsx"] exclude: [node_modules, coverage, dist] namespace: tests gates: memory_first: true # 必须在文件探索前搜索内存 task_create_first: true # 必须在 Agent 工具之前创建任务 context_tracking: true # 跟踪上下文窗口耗尽 auto_index: guidance: true # 会话启动时自动索引文档 code_map: true # 会话启动时自动索引代码 tests: true # 会话启动时自动索引测试文件 auto_meditate: enabled: true # 将持久的会话经验提炼到学习命名空间 mcp: tool_defer: true # 延迟 MCP 工具模式（100+）；按需加载 auto_start: false # 会话开始时自动启动 MCP 服务器 hooks: pre_edit: true # 跟踪文件编辑以便学习 post_edit: true # 记录编辑结果 pre_task: true # 任务生成前的代理路由 post_task: true # 记录任务结果以便学习 gate: true # 门控强制执行 route: true # 智能任务路由 stop_hook: true # 会话结束时的持久性 session_restore: true # 启动时恢复会话状态 models: default: opus research: sonnet review: opus test: sonnet model_routing: enabled: false # 设置为 true 以进行自动模型选择 confidence_threshold: 0.85 cost_optimization: true circuit_breaker: true status_line: enabled: true branding: "MoFlo V4" mode: compact # single-line, compact, or dashboard show_dir: true # 当前目录名称（仅限 compact/dashboard） show_git: true show_session: true show_swarm: true show_mcp: true ``` ### 工具延迟 默认情况下，`tool_defer` 为 `true`。MoFlo 公开 100 多个 MCP 工具 - 在对话开始时加载所有工具模式会消耗大量上下文。启用延迟后，仅在启动时列出工具 **名称** （紧凑），并在需要时通过 `ToolSearch` 动态获取完整模式。钩子和 CLI 命令继续正常工作，因为它们直接调用守护进程，而不是通过 MCP 工具模式。 如果您希望所有工具模式立即可用（在离线/隔离环境中很有用），请设置 `tool_defer: false`。 ### 模型路由 默认情况下，MoFlo 使用 **静态模型偏好** - 每个代理角色都使用 `models:` 中指定的模型。这是可预测的，并为您提供完全的控制。 启用 `model_routing.enabled: true` 以启用 **智能路由**，它分析每个任务的复杂性并自动选择最具成本效益的模型： | 复杂度 | 模型 | 示例任务 | |-----------|-------|---------------| | 低 | Haiku | 拼写错误，名称更改，配置更改，格式化 | | 中 | Sonnet | 实现功能，编写测试，修复错误 | | 高 | Opus | 架构，安全审计，复杂调试 | 路由器从结果中学习 - 如果模型失败某个任务，电路中断器会对该模型进行惩罚，并升级到更具能力的模型。 您可以在启用路由时固定特定代理： ```yaml model_routing: enabled: true agent_overrides: security-architect: opus # 绝不降低安全工作级别 researcher: sonnet # 将研究固定为 sonnet ``` ## 架构 - **9 个二进制文件** 随 npm 一起发布：`flo`（主要 CLI），`moflo`，`claude-flow`（别名），`flo-setup`，`flo-codemap`，`flo-search`，`flo-embeddings`，`flo-index`，`flo-testmap` - **项目配置系统**：`moflo.yaml` 用于每个项目的设置 - **一键初始化**：`flo init` 生成 OOTB 操作所需的一切 ## 与 Ruflo / Claude Flow 的关系 MoFlo 源自 [Ruflo/Claude Flow](https://github.com/ruvnet/ruflo)，但现在是一个独立项目。两者共享根源和一些命名约定，但代码库、运行时和设计优先级已完全分离。MoFlo 作为一个 npm 包发布 - 安装 `moflo`，运行 `flo init`，就这样了。 ## 我为什么要做这个 Ruflo / Claude Flow 是一项了不起的工作。 [rUv](https://github.com/ruvnet) 和贡献者投入到原始的工程 - 集群拓扑， hive-mind 共识，HNSW 向量搜索，神经路由等等 - 使其成为可用的最全面的代理编排框架之一。它是为支持广泛的场景而构建的：分布式系统，多代理集群，企业编排，研究工作流等。 我的用例只是其中一个场景：日常本地编码，增强我正常的 Claude Code 体验，在单个项目上使用。原始支持了这一点 - 它都在那里 - 但由于项目服务于许多不同的需求，我每次拉取更新时都需要配置和调整我的特定设置。那不是原始的缺点；这是灵活性和强大的自然权衡。 所以我从那个基础上开始，并缩小了焦点，以满足我特定的需求。我加入了我一直手动设置的默认值，添加了自动索引和会话启动时的内存门控，并调整了开箱即用的体验，以便 `npm install` 和 `flo init` 直接进入编码。随时间推移，MoFlo 构建了自己的架构（工作空间折叠，树内快速嵌入运行时，node:sqlite + HNSW 内存层，拼写引擎，守护进程驱动的调度）以及两个项目完全分开。 如果您正在探索代理编排的全部范围，请查看 Ruflo / Claude Flow - 它是真正的。如果您的需求与我类似 - 一个专注的，有偏见的本地开发设置，只需开箱即用 - MoFlo 适合您。 ## 贡献 欢迎贡献 - 错误报告，文档，测试和代码。参见 **[CONTRIBUTING.md](./CONTRIBUTING.md)** 以了解设置，约定以及如何开启拉取请求。参与者请遵守我们的 **[行为准则](./CODE_OF_CONDUCT.md)**。 ## 许可证 MIT