Ruflo 项目分析：Agent 编排、记忆学习与执行边界

原仓库：ruvnet/ruflo。

AI 参与说明（Agent：Codex）：本文依据提交 070349a6949aee7d5cb798a354f0712121285324 分析能力、架构与实际调用链，整理日期为 2026-10-20；该快照和当日 npm 最新版均为 3.57.2。使用项目 Anatomy 重建记忆候选窗口与评分的教学交互，并使用 humanizer-zh 编辑中文。未运行付费模型任务或独立复测上游性能基准。执行入口为 Codex Desktop；模型与 reasoning effort 未取得任务级运行记录。

Ruflo 围绕 Claude Code、Codex 建立了一套协作工具：安排角色、记录任务、保存经验、选择模型、限制操作，并用控制台展示运行状态。它原名 Claude Flow，因此发行包、目录和配置中仍大量保留 claude-flow。

理解这个项目，关键是追问每个入口实际做了什么：保存一条任务、请求一次模型，以及启动能够读写文件的执行器，是三种不同的动作。沿着这条线读源码，比数 Agent 和 Tool 的数量更容易判断它能否解决自己的问题。

先认识几个核心名称

项目能力与对应代码入口

Ruflo 面向已经使用 Coding Agent 的开发者，尝试把复杂任务组织成可跟踪、可复用、可约束的过程。角色定义中有开发、测试、审查、架构和安全等分工；许多定义本质上是 Markdown 或 YAML 指令，配合模型和工具权限使用。例如 coder.md 定义模型与开发要求，角色数量不能直接换算成独立训练模型的数量。

表中包目录均位于 v3/@claude-flow/，顶层 plugins/ 除外。实际可用的 Tool、角色和插件取决于版本与安装方式，文档中的数量不是一份统一的运行时清单。

流程层还提供 SPARC 方法与 autopilot 插件。SPARC 按 Specification、Pseudocode、Architecture、Refinement、Completion 五阶段组织产物与检查；autopilot 则与宿主的循环、唤醒能力配合。它们需要接到实际执行器，创建阶段记录本身不会完成实现。SPARC、autopilot

运行架构：宿主执行，Ruflo 提供协调与上下文

Ruflo separates coordination records from executable work. swarm_init 保存协作配置；agent_spawn 注册角色；需要实际模型输出或文件修改时，还要进入对应执行路径。

flowchart TB
  User[用户任务] --> Host[Claude Code / Codex]
  Host --> Execution[宿主 Tool Loop<br/>读文件、改代码、运行测试]
  Host <--> Entry[Ruflo MCP / CLI / Hook]
  Entry --> Coordination[Agent / Task / Swarm 状态]
  Entry <--> Memory[Memory / Trajectory / Router]
  Entry --> Inline[agent_execute<br/>直接请求模型文本]
  Entry --> External[显式启动外部执行器]
  External --> Execution
  Execution --> Feedback[结果与反馈]
  Feedback --> Memory

这张图保留了两类执行：一类由宿主提供 Tool Loop；另一类是 Ruflo 的 agent_execute 直接请求模型。后者的 HTTP 请求包含模型、system 和 messages，但没有完整的工具执行循环。需要反复读文件、编辑和运行测试的工作，通常由宿主或显式启动的外部执行器承担。模型请求

MCP 是主要业务入口之一。stdio 启动器接收 tools/list 和 tools/call，再将调用交给 mcp-client.ts 的工具注册表；调用 handler 前经过策略授权。仓库另有 server manager 路径，因此核对限流、授权或传输行为时，需要先确定实际启动入口。注册表与分发

发行与代码组织

ruflo 是品牌发行入口，依赖同版本的 @claude-flow/cli。根包仍名为 claude-flow。CLI 内部按 commands/、mcp-tools/、services/、init/ 等组织，而记忆、学习、安全、通信等能力又拆为多个包。目录分层能够帮助定位职责，但并不意味着每个用户命令都会启动相应 SDK 的全部机制。Ruflo 依赖

flowchart TB
  Wrapper[ruflo / claude-flow 发行入口] --> CLI[cli<br/>commands / mcp-tools / services / init]
  CLI --> Shared[shared / mcp / security]
  CLI --> Codex[codex<br/>项目生成与执行器接入]
  CLI --> Memory[memory / neural<br/>封装与学习组件]
  Memory --> Optional[AgentDB / RuVector / 原生或 WASM 依赖]
  Plugins[plugins<br/>角色、技能、Hook、Console] --> CLI
  SDK[swarm SDK<br/>Coordinator / MessageBus / AgentPool] --> Worker[由接入方连接 Worker 并回报完成]

项目主体是 TypeScript。Rust workspace 包含 federation peer 等组件，部分加速依赖来自外部 npm、原生或 WASM 包；不能把这些依赖的全部功能都算作本仓库的自实现。Cargo workspace

核心数据模型

这些模型可从 AgentRecord、SwarmState 创建、Task 创建、WorkflowRecord 核对。

沿着一次 agent_execute 看状态怎样变成输出

假设已有一个注册的 coder，客户端通过 MCP 调用 agent_execute 并传入 agentId 与 prompt。这是假设输入；下面的函数和状态转换来自固定提交。

sequenceDiagram
  participant Client as MCP Client
  participant Registry as Tool Registry
  participant Core as executeAgentTask
  participant Store as Agent Store
  participant Provider as Model Provider
  Client->>Registry: agent_execute(agentId, prompt)
  Registry->>Registry: authorizeMcpTool
  Registry->>Core: handler 调用
  Core->>Store: 查找 AgentRecord
  alt 不存在或 terminated
    Core-->>Client: 返回错误
  else 可执行
    Core->>Core: 解析 provider、model、instructions
    Core->>Store: busy，taskCount 加一
    Core->>Provider: 发送模型请求
    Provider-->>Core: 文本或错误、usage
    Core->>Store: 保存结果与执行记录
    Core-->>Client: output、usage、duration 或 error
  end

executeAgentTask() 先校验 Agent 是否存在、是否已终止，再解析具体模型和指令。提供方选择支持 per-Agent 配置、环境变量及持久化配置等来源；请求前将 Agent 设为 busy 并增加任务计数，结果再关联回 Agent。执行核心

这里返回 success，首先表示 API 请求成功。它不自动证明输出正确，也不证明代码被写入或测试通过。源码专门区分了 API 成功与任务质量。结果语义

与此相对，Codex loop 会通过 Node spawn 启动 codex exec，由 Codex 执行工具；Claude Code 接入也有显式启动实例的路径。判断一个流程是否实际修改了项目，应看执行器输出、文件差异和测试结果，而不能只看注册状态。Codex loop、Claude Code 启动

Memory：数据库里有记录，为什么可能搜不到

普通 CLI 与 MCP Memory 操作会进入 memory-initializer.ts，优先尝试 AgentDB bridge，bridge 不可用时有其他后端与降级实现。AgentDB 本身是外部依赖，Ruflo 提供控制器封装、路径管理及工具适配。写入入口、查询入口

The standard bridge search limits candidates before computing relevance. bridgeSearchEntries() 先过滤有效记录、namespace 和来源类型，再按 updated_at DESC 取最多 1000 条。只有进入窗口的记录，才参与后面的向量和 BM25 打分。

flowchart TB
  Query[query / namespace / threshold / limit] --> Embed[尝试生成 Embedding]
  Query --> Filter[有效记录与 namespace / provenance 过滤]
  Filter --> Window[updated_at DESC<br/>LIMIT 1000]
  Window --> Score[逐条 cosine / BM25 / coverage]
  Embed --> Score
  Score --> Threshold[score 大于等于 threshold]
  Threshold --> TopK[按 score 降序取 limit]
  TopK --> Result[内容、来源、score 与检索方法]

这与“从全库 HNSW 召回近邻”有明显差别。Ruflo 有可选 HNSW 实现，但不能把某个索引的微基准推广到此默认 bridge 路径。候选窗口、算法状态说明

混合分数怎样计算

这里 cosine 表示向量余弦相似度，coverage 表示查询词命中比例。设 s 是 cosine，m = min(BM25 / 10, 1)，c 是查询词在文本中命中的比例；代码取 l = max(m, c)，然后计算：

blended = 0.6 × max(0, s) + 0.4 × l
score = max(blended, s)

coverage 为短文本保留精确词命中的贡献，最后的 max 保证结果不低于纯语义分数。score 是混合相关性，不能解释为成功概率。完整打分与排序

无可用向量时，语义项为零，关键词仍可能产生结果。可选 smart=true 在上层加入扩展检索与重排；不能据此推断底层候选窗口自动消失。CLI 显式 keyword/hybrid 等入口也可能走其他实现，因此这里的 1000 是这条搜索路径的候选上限，它不是数据库容量上限，也不适用于所有 Memory API。

交互：改变更新时间，观察高相关记忆是否进入候选

下面解剖的是 bridgeSearchEntries()。教学场景固定查询 token login，初始过滤后有 1100 条记录。A 的 cosine 预设为 0.72；B 的文本包含全部查询词，cosine 为 0.10；C 的 cosine 为 0.95，但初始更新时间排名是 1001。其余记录不命中查询，cosine 为零。

这些 cosine 是用于解释公式的假设输入，未由 MiniLM 实测。窗口、打分公式与过滤顺序来自源码；分选机构是视觉比喻。图中先让记录取得参与评分的资格，再显示语义项、词法项和阈值如何共同决定输出。

关闭 JavaScript 时，也可以用下表核对结果。默认 threshold 为 0.2；这里仅列相关的三条记录，输出条数足够容纳它们。

B 的 coverage 为 1，所以 l=1；即使不计算具体 BM25，也能确定有向量时 0.6×0.10+0.4=0.46，无向量时为 0.40。A 和 C 不含查询词，词法项为零。窗口外的 C 没有实际 score，图中不会把预设 cosine 当成已经执行的评分结果。

存储与 Embedding 的部署边界

此提交中，CLI 通常显式传入 .swarm/memory.db；MCP handler 不传路径时，bridge 默认使用同一 memory root 下的 agentdb-memory.db。此外还有学习 JSON、路由状态和可选索引文件。跨 CLI、MCP 和插件共享经验时，应检查实际路径与 namespace，不能只因为工具都叫 Memory 就假定它们读写同一文件。CLI 路径、bridge 路径

Embedding 链支持本地 MiniLM 等实现，也有失败降级。首次加载模型可能需要下载；依赖不可用时，不应把返回了某个维度的数组当作真实语义模型正常工作的证据。RUFLO_REQUIRE_REAL_EMBEDDINGS=1 可以禁止部分路径以 hash 替代真实 Embedding，具体失败处理仍以调用入口为准。Embedding policy

自学习：哪些状态会随着反馈变化

Task feedback updates local patterns and routing state. It does not, by itself, train the remote Claude or Codex model.

本地学习链收集 Trajectory，把 success、partial、failure 映射为奖励，查找相关 Pattern 并调整置信度，再把成功步骤保存为可复用经验。状态持久化后，后续会话可以读到变化。Trajectory 反馈

路由还需分开看两个问题。选择哪个角色时，hooks_route 会比较任务和角色关键词；默认 router embedder 是字符 hash，设置 CLAUDE_FLOW_ROUTER_EMBEDDER=minilm 才尝试句向量，失败会回到 hash 并标记实际后端。选择哪个模型时，ModelRouter 使用复杂度启发式与 Thompson Sampling，反馈更新持久化先验；神经后端有单独的启用条件。角色向量、模型路由

仓库也包含 LoRA、EWC、对比学习和 WASM 集成。它们是否处于实际执行路径、是否得到有效训练信号，需要逐项核对；例如源码仍记录了特定 MicroLoRA WASM 后端对推理输出无变化的限制，不能将该路径的存在等同于已证实的适配收益。后端限制

项目自己的 2026-05-29 审计验证过反馈学习，同时发现并修订了多项夸大指标。应连同文末 remediation 阅读，不能把已修复的问题继续当成当前缺陷。当前 README 的 HNSW 数据限定了数据规模和基线，约 1.9 倍或 3.2～4.7 倍；这类结果仍不代表端到端编码时间会提高同样倍数。项目审计

安装与使用：先跑通一条完整链路

Ruflo 包声明 Node.js 至少为 20。实际编码需要 Claude Code 或 Codex 自身可用并完成认证；初始化和 MCP 启动不统一要求 Anthropic API key，直接调用 Provider 时再准备相应凭据或本地端点。以下按本文版本固定命令，后续升级时重新核对配置差异。包声明

Claude Code 项目先运行：

npx ruflo@3.57.2 init wizard

这会生成或修改项目指令、MCP、Hook 及辅助配置；应先检查 Git diff，再重启或重新加载宿主。若需要手工添加 MCP：

claude mcp add claude-flow -- npx -y ruflo@3.57.2 mcp start

Codex 项目使用：

npx ruflo@3.57.2 init --codex
codex mcp list

初始化会尝试自动注册。只有实际列表中出现了正确服务，才说明该环节成功；必要时手工注册：

codex mcp add ruflo -- npx -y ruflo@3.57.2 mcp start

当前 Codex 共享配置使用 ruflo 服务名和 120 秒启动超时；部分旧文档仍写 claude-flow。同时生成两端配置可使用 init --dual。Codex MCP 配置

先在同一 CLI 入口验证一条记忆的写入与检索：

npx ruflo@3.57.2 memory store \
  --namespace patterns \
  --key token-refresh \
  --value "Merge concurrent token refresh requests to avoid duplicate refreshes."

npx ruflo@3.57.2 memory search \
  --namespace patterns \
  --query "token refresh"

预期检查的是 key、namespace、内容和检索结果是否对应；不同 Embedding 后端下分数可能不同，不能要求固定值。再让宿主检索同一知识时，应核对前面提到的路径差异。以上命令已核对源码，本次没有在目标项目实际执行。

Claude Code 插件路径

想先体验工具和控制台，可在 Claude Code 中运行：

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo

当前 console/mods 路径要求 Claude Code 2.1.287 或更高版本。core 提供基础工具，console 提供运行界面，mods 在宿主进程内参与路由与策略；它们使用宿主账号权限。插件安装与完整 CLI 初始化的覆盖面不同，不能从安装成功推断所有 Hook、后台 worker 或后端都已可用。安装路径

接入后可给执行器一个明确任务：

Search project memory for token refresh patterns. Fix concurrent refreshes.
Use an implementation role and an independent review role when available.
Run the relevant tests, inspect the actual diff, and store verified findings.
Report what changed and which checks passed.

验收看实际差异、测试和保存的经验是否对应，而不是角色注册数量。初次接入只启用完成该任务所需的能力，更容易定位收益和失败原因。

特点、工程边界与采用方式

Ruflo 的特点在于对 Coding Agent 的整合深度：它复用宿主工具，再把 Memory、Hook、角色、任务状态和控制台接入同一工作过程。团队已经依赖 Claude Code 或 Codex 时，可以逐步加入经验复用、分工与审查，不必先重建全部执行环境。Federation、策略与审计又把范围扩展到跨节点协作和受控执行。

不过，SDK、CLI handler、插件和宿主能力之间存在明确边界：

• swarm_init 保存的拓扑和共识配置，不代表已经启动 UnifiedSwarmCoordinator 的通信网络。接入方仍须连接实际 Worker，并接收其完成回报。
• 当前 CLI workflow runtime 明确拒绝 parallel、loop 步骤，仅接受 task、wait、condition 等已支持步骤；不能把该入口当成完整并行 DAG 引擎。步骤校验
• Raft、Byzantine 等名称说明项目包含相关协调机制；transport 和实现完整程度仍需检查。共识也不能替代对生成代码的正确性判断。Raft transport
• 可选原生依赖、Embedding 模型和后端降级会改变实际行为。Tool 已注册与能力健康是两回事。
• 文档版本和能力计数有漂移；仓库还保留历史测试失败基线，部分 CI 检查非阻塞。应核对自己的关键路径，不把一个绿色状态推广为全部能力已经完备。测试基线

比较稳妥的采用方式，是固定版本，用同一组真实任务比较接入前后：完成时间、模型费用、实际测试结果、经验召回，以及审查发现的问题。先用少量角色和核心 Memory，再根据可观察收益开启后台任务、跨节点通信或高级学习模块。更多 Agent 会增加交接与上下文成本，最终收益要由交付结果说明。

继续阅读源码

建议按“入口、分发、状态、执行、反馈”的顺序阅读：ruflo/bin/ruflo.js → cli/src/index.ts → cli/src/mcp-client.ts → agent-tools.ts / agent-execute-core.ts → memory-bridge.ts → memory/intelligence.ts。需要理解完整协调 SDK，再读 swarm/src/unified-coordinator.ts；需要真实文件执行，再看 codex/src/loop/index.ts。

站内可继续对照 Rakazo 的 Task、Run 与恢复机制、Mastra 的 Workflow 与状态恢复。它们能帮助区分任务记录、执行循环与可恢复状态分别属于哪一层。