AI Research 技术调研

Claude-Flow / Ruflo：跑在 Claude Code / Codex 之上的 meta-harness（prompt 生成器 + MCP server + 生命周期 hook）

16分钟阅读

Claude-Flow (ruvnet)

一句话定位

Claude-Flow（现已 rebrand 为 Ruflo，npm 包名 ruflo，version 3.25.6）是一个跑在 Claude Code / Codex 之上的 meta-harness：它本身不含”对 base model 做 agentic tool-use 循环”的能力，而是一个 prompt 生成器 + 手写 JSON-RPC MCP server（约 314 个 tool）+ Claude Code 生命周期 hook 的组合。真正的 agent 执行被委派给三条路径之一（mcp-tools/agent-tools.ts:421-424）：① Claude Code 自己的 Task tool（真子 agent，推荐路径）；② agent_execute —— 一次性单发 Anthropic Messages 调用；③ claude -p headless 子进程。README 自己的标题也是诚实的：“An agent meta-harness for Claude Code and Codex… Ruflo is the harness.”

这个仓库的技术底子（memory 后端、Q-learning router 落盘、Docker 池、EWC/SONA、flywheel eval 门）是真实、可编译、有测试的，但外层叙事被严重过度包装（emoji 密集、ADR 编号满天飞、极长 tool description、自发布的下载/star proof JSON）。本 dossier 对每个维度都标注了”代码支持 / 仅营销声明”的边界。

核心架构总览（目录结构关键路径 + 引用的 commit）

  • 分析 commit：7ef4d4e655d81c0451f6f40f35729cce6c9928e7（2026-07-09，“Merge PR #2619 fix/high-verification-issues”），2026-07-11 浅克隆。
  • 关键结构事实（决定整份分析）：npm 发布包把大部分重活拆到独立发布的依赖包（@claude-flow/cli-core、@claude-flow/mcp、@claude-flow/neural、@claude-flow/shared、agentdb、agentic-flow、@ruvector/*，见 package.json dependencies/optionalDependencies）。仓库内真正的 runtime 源码在 monorepo workspace v3/@claude-flow/cli/src/（不是 npm 安装形态）。以下路径除特别注明外均相对该目录。仓库根 bin/cli.js 只是薄代理 → v3/@claude-flow/cli/bin/cli.js。
  • 关键源文件（相对 v3/@claude-flow/cli/src/）：
    • commands/hive-mind.ts（1479 L）—— swarm/queen 启动、prompt 生成、claude 子进程 spawn
    • commands/swarm.ts（947 L）—— swarm CLI（主要是注册 + guidance，执行委派 Task tool）
    • commands/route.ts（915 L）—— Q-learning task→agent router CLI
    • mcp-tools/agent-tools.ts（934 L）—— agent_spawn/execute/list/terminate 定义 + 3 层 model router
    • mcp-tools/agent-execute-core.ts（701 L）—— 真正的 LLM 调用（Anthropic / OpenRouter / Ollama）
    • mcp-tools/hooks-tools.ts（5361 L，69 个 tool）—— hook + trajectory + self-learning + observability 核心
    • mcp-tools/memory-tools.ts + memory/memory-initializer.ts —— memory 后端（sql.js + 向量 + 图）
    • mcp-tools/tool-loop-guardrail.ts —— 卡死循环熔断器
    • mcp-server.ts（919 L）+ mcp-client.ts —— 手写 JSON-RPC stdio MCP server，约 314 tool
    • services/container-worker-pool.ts —— Docker 沙箱 worker 池
    • services/weight-eft.ts、native-training.ts、ruvector-training.ts —— trajectory→训练
    • services/harness-flywheel.ts（+ harness-loop / harness-improvement-ledger）—— eval 门控自优化
    • memory/sona-optimizer.ts、memory/ewc-consolidation.ts —— SONA / EWC++ 持续学习
    • ruvector/q-learning-router.ts（935 L）、ruvector/enhanced-model-router.ts —— RL router
    • 仓库根 .claude/settings.json —— Claude Code hook + 权限接线

Agent Loop（主循环 / 何时继续何时停）

本仓库没有对 base model 的原生 agentic 循环。“循环”是 Claude Code 的。Ruflo 在启动时做的事：commands/hive-mind.ts 用 generateHiveMindPrompt（:66-178）拼一个巨大的协调 prompt，然后 childSpawn('claude', claudeArgs, {stdio:'inherit'})（:326）—— 起一个 claude 进程扮演 “Queen”。非交互模式追加 -p --output-format stream-json --verbose（:291-293）。CLI await 子进程退出（:385-388）。SIGINT 会暂停并保存 prompt 文件（:333-351）。

仓库内唯一真实的迭代循环有两处：

  • services/headless-worker-executor.ts:1202 —— spawn claude --print 的 headless 批量 sweep（批 worker），worker-daemon.ts 轮询队列分发这些 sweep（:160/:978 的注释记录了一个历史 bug：“泄漏了数万个 headless claude --print sweep”）。
  • benchmarks/gaia-*.ts —— 一个 GAIA benchmark agent（decompose→execute→judge→critic→vote），execSync 调模型；这是自带的 eval harness，不是产品循环。

agent_execute（agent-execute-core.ts:125-217）是单发：一次 POST 到 api.anthropic.com/v1/messages，max_tokens 默认 1024，返回 {text, stopReason}；没有 tools: 参数，没有 tool-use 续跑循环。

continue/stop 控制以 guardrail 形式存在，而非循环驱动：tool-loop-guardrail.ts 是一个连续失败熔断器（ring buffer 64，WARN@3、BLOCK@5，精确命令匹配），默认仅告警。

记忆与上下文管理（压缩、长期记忆、会话持久化）

这一维度是真材实料。 memory/memory-initializer.ts：SQLite 走 sql.js（wasm），有一个 memory_entries 表 + 一个图 relations 表（:431）；可选 @ruvector/core（:512）和一个 agentdb 桥（memory-bridge.ts，ADR-053）做 HNSW 向量检索。旧版 JSON store.json 自动迁移到 sqlite（memory-tools.ts:254-290）。

memory/ 下的检索栈：bge-embedder.ts（embedding）、lucene-bm25.ts（BM25）、hybrid-retrieval.ts（dense+sparse）、cross-encoder-rerank.ts（rerank）、rabitq-index.ts + embedding-quantization.ts（量化向量）、ewc-consolidation.ts（EWC 持续学习）、sona-optimizer.ts、structured-distill.ts。

MCP tool memory_store/retrieve/search 是带命名空间的（默认 default；特殊 namespace trajectories、cost-tracking、patterns），按 embedding 做语义检索。输入校验会拒绝 key/namespace 里的路径穿越 / shell 元字符（memory-tools.ts:71-85）。

会话持久化：.hive-mind/sessions/ 存 prompt 文件；hooks_session-start/-end/-restore（hooks-tools.ts:1959/2097/2187）。memory 跨会话存活（README 的 “remember across sessions” 有代码支撑）。

压缩：memory-distill 命令 + services/memory-distillation.ts + structured-distill.ts 蒸馏 memory；这不是经典的上下文窗口 compaction（那是 Claude Code 的活）。

工具体系（定义/调用协议/注册/权限）

  • 约 314 个 MCP tool 对外暴露（mcp-server.ts:334 注释；跨 mcp-tools/*.ts grep name: 得 520，含重复/子 tool）。在 mcp-client.ts 聚合（import 约 45 个 tool 模块：agentTools、swarmTools、memoryTools、hooksTools(69)、workflowTools(30)、neuralTools(21) 等）。
  • tool 形状 = 纯对象 {name, description, category, inputSchema (JSON Schema), handler}（mcp-tools/types.ts，见 agent-tools.ts:277-301）。description 异常地长，会 coach 模型 Ruflo 的 tool 何时优于原生 Claude tool（反复出现 “Use when native X is wrong because…” 的模式）。
  • 协议：手写 JSON-RPC over stdio（mcp-server.ts:311- startStdioServer、writeFrame），不是官方 MCP SDK server。有精细的 stdout 卫生处理（把误入的 console.log 重定向到 stderr :325-328；setBlocking 对 >64KB 强制原子帧 :330-344），因为 “Codex 在第一行非 JSON stdout 就会关闭 transport”。另有 HTTP server 路径（:630 startHttpServer → createMCPServer）。
  • tool 级权限：Ruflo 自己没有 —— 依赖 Claude Code 在 .claude/settings.json 的 permissions.allow/deny。每个 tool 的输入校验走 mcp-tools/validate-input.ts（validateIdentifier/Text）。

Prompt 设计（系统提示结构、动态组装）

  • Queen/hive prompt 是静态模板 + 槽位插值（hive-mind.ts:80-177）：emoji 打头的分节（config、worker 分配、一份枚举式 MCP-tool 菜单、四阶段 EXECUTION PROTOCOL，以及硬性 “TOOL PREFERENCE RULES (#1422)” 命令模型优先用 mcp__ruflo__* 而非原生 Task/Agent tool）。非模型自适应；字段 = swarmId、objective、queenType、consensus 算法、topology、worker 组。
  • 更讲究的 prompt/guidance 机制在 @claude-flow/guidance 包（v3/@claude-flow/guidance/src/）：compiler.ts、gates.ts、authority.ts、coherence.ts、truth-anchors.ts、conformance-kit.ts、adversarial.ts、uncertainty.ts —— 一个带 truth-anchor 和 gate 的 “guidance 编译器”。MCP 面 guidance-tools.ts（26 tool）做 tool/command/agent/skill 的结构化发现。
  • 每个 agent 的角色 prompt 以 108 个 markdown agent 定义存在于 .claude/agents/**（frontmatter + instructions），当 Claude Code spawn 对应子 agent 时注入。agent_spawn 在 claude -p / fable 路径上可挂 --append-system-prompt 角色文本（services/fable-harness.ts:307）。

Router / 编排（任务分解、多 agent、子 agent）

两个 router：

  • Model router（agent-tools.ts:174-273 determineAgentModel，“ADR-026 3-tier”）：① config 里显式 model → ② 基于任务的 enhanced-model-router.ts，含 Tier-1 确定性 codemod 直接跳过 LLM（$0，canSkipLLM，:209-217）+ 一个 neural/bandit pick，否则退到 basic model-router.ts → ③ agent-type 默认 → ④ sonnet 兜底。可选 model：haiku/sonnet/opus/opus-4.7/inherit；可路由到 OpenRouter/Ollama。
  • Agent router（commands/route.ts + ruvector/q-learning-router.ts）：真 Q-learning —— qTable 为 {qValues[], visits}，epsilon-greedy 带指数衰减，reward 更新，落盘 .swarm/q-learning-model.json（每 100 次更新自动保存，schema 变更时按 encoder-version 迁移）。8 个内置 agent 类型（coder/tester/reviewer/architect/researcher/optimizer/debugger/documenter）。

多 agent 编排是委派的，不是自己拥有的。 agent_spawn（agent-tools.ts:277-425）只写 metadata 到 .claude-flow/agents.json + best-effort 图节点（ruvector/graph-backend.js:addNode）+ 在 swarm store 的 agents[] 注册。它不 spawn 任何进程。它自己的返回 note（:421-424）说执行必须走 Task tool / agent_execute / claude -p。所以 “60+/98/100+ agent 的 swarm” = 一个注册表 + 让 Claude Code 去 spawn 子 agent 的 prompt 指令；并行性是 Claude Code 的 Task tool。

swarm 协调原语的数据结构倒是真实的：v3/@claude-flow/swarm/src/（unified-coordinator.ts、queen-coordinator.ts、consensus/（byzantine/raft 风格）、topology-manager.ts、message-bus.ts、agent-pool.ts）。consensus/topology 被建模；但它是驱动真实分布式执行还是只是记账，stage-1 未验证（鉴于 agent_spawn 是 metadata-only，倾向记账）。

Skill / 插件体系

  • Claude Code 插件市场：.claude-plugin/marketplace.json + plugin.json；plugins/ 有约 40 个 ruflo-* 插件（ruflo-core、ruflo-agent、ruflo-intelligence、ruflo-federation、ruflo-cost-tracker、ruflo-daa、ruflo-graph-intelligence、ruflo-iot-cognitum…）。README 区分两条安装路径：Claude Code Plugin（slash command + 部分 skill，零 workspace 文件）vs. npx ruflo init（完整环：.claude/、.claude-flow/、CLAUDE.md、helper、MCP server、hook、daemon）。
  • Skill：.claude/skills/、.agents/skills/ 等下的 SKILL.md 文件。settings.json 注明跨路径 367 个 SKILL.md（5× 重复），并把 skillListingBudgetFraction 上调到 0.06 以防被截断（#1834）—— 即 skill 就是 Claude Code 的 skill，数量因重复被灌水。
  • 插件 loader：plugins/manager.ts（基于 execFile）。guidance-tools.ts 发现已装的 agent/skill/plugin。可选联邦插件（plugin-agent-federation、plugin-iot-cognitum）。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

这是被吹得最凶、却意外地部分为真的一维。 三层，全都在学小型本地 adapter/config，从不动 base Claude 权重：

  1. Trajectory→routing 学习（在线）：hooks_intelligence_trajectory-start/step/end（hooks-tools.ts:2509/2578/2653）。在 -end（:2664-2772）：trajectory 持久化到 memory ns trajectories，带 embedding + success/failure 标签；SONA optimizer 处理结果（sona-optimizer.ts:306 processTrajectoryOutcome，reward +1.0 成功 / -0.5 失败 → qLearningRouter.update :371）；成功时做 EWC++ 巩固（Fisher-info 更新，用 trajectory embedding 当梯度代理，:2760-2772）；加 runBackgroundLearning()（ruvllm）。是真的 RL/持续学习代码。
  2. Eval 门控 config 自优化（离线 flywheel）：services/harness-flywheel.ts（ADR-176）。每 tick：从本安装自己的 store 采一个自监督 benchmark 语料，在 TRAIN split 上爬山优化 retrieval config（{alpha, subjectWeight, mmrLambda, bodyWeight, typePenaltyFactor}），然后在 HELD-OUT split 上经 runHarnessLoop GATE 冠军：held_out_improves 且 anchor-no-regress（red/blue）且 drift≤thr 且 replay 确定性 且 canary-no-worse；被接受的 champion 链接并记入 harness-improvement-ledger.ts。确定性、$0。它优化的是 memory-retrieval 超参，带真实 eval 门 —— 一个合法的 eval 驱动纠错环（作用域限于 retrieval，不是模型行为）。
  3. Adapter 训练：ruvector-training.ts（MicroLoRA rank-2 adapter、InfoNCE 对比、SONA）；native-training.ts 把 LoRA 训练走 @ruvector/ruvllm TrainingPipeline（真实 epoch/loss/EWC/磁盘 checkpoint）—— 但训的是 embedding pattern-alignment 对，即极小的 router/memory adapter。

代码里写明的诚实边界：weight-eft.ts 头部有一条 “HARD HONESTY RULE (do not overclaim)“：它的 train 从不 spawn，没跑过 GPU tune，捕获归档里的 resolved 标签是代理（“ruflo 没有 SWE-bench gold oracle”）。所以 “越跑越聪明、有证据” 适用于 在自标注数据上的 router/retrieval config，而非可证明的端任务准确率提升。

可观测性（日志 / trace 格式）

  • Trajectory trace = 主结构化 trace：{trajectoryId, task, agent, steps:[{action,result}], success, feedback, duration}，持久化到 memory ns trajectories（hooks-tools.ts:2653+）。有一个原型 MAGE 风格 “execution-state-tree” 镜像：ruvector/trajectory-tree.ts（:2708-2712）。
  • Metrics：hooks_metrics / hooks_intelligence_stats / hooks_model-stats / hooks_intelligence_unified-stats 聚合 routing + cost + pattern 统计。per-agent 成本追踪走 cost-tracking namespace。
  • 日志：MCP server 输出到 stderr，结构化 [ISO-ts] LEVEL [claude-flow-mcp] (sessionId) msg（mcp-server.ts:379-400），stdout 留给 JSON-RPC 帧。log-filters.ts 压掉装饰性 warning。
  • OpenTelemetry：仅以 package.json 里的依赖 override 存在（OTLP exporter、sdk-node）；cli/src 内未找到 OTel span 埋点（grep trace/span 命中的是 distill/embed 数学和 “trajectory”，不是 OTel tracing）。所以 OTel 是传递依赖 pin，不是接好的 trace 管线。标记为声明有、源码无据。

安全与权限（审批门、密钥管理）

  • 审批门是 Claude Code 的，不是 Ruflo 的。 .claude/settings.json 出厂带 permissions.allow（npx/git/node/jq/ls + mcp__claude-flow__*、mcp__ruv-swarm__*、mcp__flow-nexus__*）和 permissions.deny（Read(./.env*)、Bash(rm -rf /)）。Ruflo 在 init 时生成这些列表；执行由 Claude Code 做。
  • --dangerously-skip-permissions 在 hive-mind spawn 路径受支持（hive-mind.ts:308-316），由严格 === true 检查把关（HIGH-02 加固），使 undefined 永不等于 “skip”，并打印警告。
  • 密钥管理：encryption/vault.ts（secrets vault）+ fs-secure.ts（readFileMaybeEncrypted、writeFileRestricted、原子写）。Ed25519 签名（@noble/ed25519）用于跨安装传播里 config-signed champion（ADR-177，在 harness-flywheel 引用）。
  • aidefence 安全 tool（security-tools.ts）：aidefence_scan/analyze/is_safe/has_pii/learn —— 一个 prompt-injection / PII 扫描器（包 @claude-flow/aidefence），即内容风险检测，不是审批门。
  • SECURITY.md 在库；npm run test:security 指向 v3/__tests__/security/。

沙箱与执行隔离

  • 真 Docker 沙箱：services/container-worker-pool.ts —— Docker 容器池，warm/min 定尺，docker run -d --cpus <n> --memory <n> -v <root>:<ws>:ro（只读项目挂载，:416），独立 state volume，-w workspace，可选 --network <name> 隔离（:436），镜像 entrypoint tail -f /dev/null（:441）。向容器传入 ANTHROPIC_API_KEY、CLAUDE_CODE_HEADLESS=true、CLAUDE_CODE_SANDBOX_MODE。
  • SandboxMode 类型来自 headless-worker-executor.ts；container-worker-pool 设 defaultSandbox。这是 headless-worker 路径的真实隔离层。（stage-1 在 run 参数里未见 seccomp/cap-drop flag —— 隔离 = cgroup 限额 + 只读挂载 + 可选 network namespace。）
  • 非容器路径（hive-mind 的 claude spawn、agent_execute API 调用）在进程内 / 宿主机上跑，除 Claude Code 自身外无沙箱。

与模型的协同设计

  • 集成机制 = Claude Code hook（.claude/settings.json hooks）：PreToolUse（Bash → hook-handler.cjs pre-bash）、PostToolUse（Write|Edit|MultiEdit → post-edit）、UserPromptSubmit → route（Q-learning model routing 在每个用户回合触发），加 SessionStart/End。环境 flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1、CLAUDE_FLOW_HOOKS_ENABLED=true。这就是 README 所说的 “神经系统”：Ruflo 挂进 Claude Code 生命周期，而非替换它的循环。
  • 模型感知：model alias 映射到具体当代 ID（agent-execute-core.ts:414-416 haiku→claude-haiku-4-5、sonnet→claude-sonnet-4-6、opus→claude-opus-4-8）；router 对琐碎任务挑便宜模型 / codemod。prompt 硬规则把模型引向 Ruflo MCP tool 而非原生（#1422）。
  • provider 可移植：agent_execute 按 env key 回退 Anthropic → OpenRouter → Ollama（agent-execute-core.ts:125-160），所以它并非严格与 Claude 协同设计，会降级到任意 chat 模型。

轨迹利用（session/trajectory 是否反哺训练/评测）

是的，在仓库内有，但用于本地 adapter/config 与 dry-run 数据导出 —— 不是 base-model 微调。

  • 喂 eval：flywheel 把 trajectory/pattern 采成 benchmark 语料，在 held-out eval 上门控 config 变更（见自进化维度）；harness-frozen-eval.ts、harness-replay.ts、harness-qualification.ts、harness-canary.ts 构成 eval/replay 套件。
  • 喂训练数据：services/weight-eft.ts（@metaharness/weight-eft，ADR-150）把捕获的 run transcript 变成 SFT（OpenAI chat）+ DPO（TRL preference）JSONL + 一份污染/reward-hack/long-context guard 报告 + 一份 GPU 训练 plan（确切的 ruvllm microlora 命令）。runRemoteTrain 是 SSH 远端 GPU 调用，默认 dry-run；真实计算只在显式 execute && yes 后、在用户宿主机上发生。transcript 捕获：ruvector/run-transcript-recorder.ts、router-trajectory.ts、router-parallel-recorder.ts。
  • 喂在线学习：trajectory 结果更新 SONA/Q-learning router + EWC memory（见自进化维度）。

诚实边界：本仓库不发生 base-LLM 权重更新；“训练” 要么是导出给外部 GPU run 的 JSONL，要么是极小 MicroLoRA/router adapter。所用 success 标签是自生成的代理（weight-eft.ts 头部自陈）。

与同类 harness 的关键差异（1-3 条）

  1. 它不是一个 agent，而是”套在 agent 上的壳”：与 Claude Code / Codex / OpenHands 这类自带 tool-use 循环的 harness 不同，Ruflo 没有原生 agentic 循环，所有真实执行委派给 Claude Code 的 Task tool 或单发 API。它的价值主张是 prompt 编排 + MCP 工具面 + hook 生命周期接管，而非跑循环本身。
  2. “self-learning” 是真的但作用域极窄且自陈：真 Q-learning/SONA/EWC + eval 门控 flywheel 落盘到 .swarm/，但只优化 routing 决策与 retrieval 超参，代码里明确写 “never trains base weights / resolved 标签是 proxy”。这种”在代码里自我设限”的诚实在同类过度包装项目里少见。
  3. “swarm/consensus/98 agents” 名不副实：agent_spawn 是 metadata-only（写 JSON 不起进程），consensus/topology 是数据结构层面的建模，真正的并行是 Claude Code 的 Task tool 提供的 —— 所谓 swarm 是 prompt 编排，不是 Ruflo 自己的调度器。

原始源码定位

  • repo: https://github.com/ruvnet/claude-flow （rebrand 为 Ruflo，npm 包 ruflo）
  • commit/version analyzed: 7ef4d4e655d81c0451f6f40f35729cce6c9928e7（2026-07-09）/ package version 3.25.6
  • 关键文件列表（相对 v3/@claude-flow/cli/src/，除注明外）：
    • commands/hive-mind.ts、commands/swarm.ts、commands/route.ts
    • mcp-tools/agent-tools.ts、mcp-tools/agent-execute-core.ts、mcp-tools/hooks-tools.ts
    • mcp-tools/memory-tools.ts、memory/memory-initializer.ts、mcp-tools/tool-loop-guardrail.ts
    • mcp-server.ts、mcp-client.ts、mcp-tools/validate-input.ts
    • services/container-worker-pool.ts、services/headless-worker-executor.ts、services/worker-daemon.ts
    • services/weight-eft.ts、services/native-training.ts、services/ruvector-training.ts
    • services/harness-flywheel.ts、services/harness-improvement-ledger.ts
    • memory/sona-optimizer.ts、memory/ewc-consolidation.ts
    • ruvector/q-learning-router.ts、ruvector/enhanced-model-router.ts
    • 仓库根 .claude/settings.json、.claude/agents/**（108 个 md）
    • v3/@claude-flow/guidance/src/（compiler/gates/truth-anchors 等）、v3/@claude-flow/swarm/src/

一手源存档（sources/）

存于 /Users/zhao/projects/self-wiki/ai-research/sources/harness/claude-flow/：

  • NOTES.md —— stage-1 逐维度源码级笔记（含 provenance、README-claim vs code-support ledger）
  • src-snapshot/ 下留档源文件：
    • hive-mind.ts、route.ts、agent-tools.ts、agent-execute-core.ts
    • hooks-tools.ts、memory-tools.ts、tool-loop-guardrail.ts
    • mcp-server.ts、container-worker-pool.ts
    • weight-eft.ts、harness-flywheel.ts、sona-optimizer.ts
    • claude-code-settings.json（仓库根 .claude/settings.json 副本）

关系图谱

反向链接