Ruflo：68.5K Star 的「Agent 神经系统」——一个 npx 给 Claude Code 装上 100+ 专属 Agent、跨机器联邦、自学习记忆，代价是 333 个 MCP 工具每轮白烧 6 万 token

先建立坐标系：Agent = Model + Harness，Ruflo 是后者

过去一年「coding agent」这个词被用烂了，但 Ruflo 的 README 第一行给了个极干净的拆解：Agent = Model + Harness。模型负责「想」，harness 负责「能」——工具、记忆、循环、沙箱、权限控制，全在 harness 层。Claude Code 本身是个 harness，Codex 也是，而 Ruflo 管自己叫 meta-harness：它不是又一个写代码的 agent，而是套在 Claude Code / Codex 外面的一层编排系统，解决的是「单 agent 单上下文」的天花板。

单跑 Claude Code 的体验大家都熟：会话结束记忆清零、一个任务只能一个 agent 从头干到尾、换台机器就失联。Ruflo 的卖点就是把这三件事补上——记忆持久化 + 多 agent 蜂群协作 + 跨机器联邦通信。它的架构图长这样：

User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers
                          ^                           |
                          +---- Learning Loop <-------+

用大白话讲：npx ruflo init 跑完，你的 Claude Code 目录里会多出 hooks、MCP server、技能文件和一套配置——之后你照常用 Claude Code，hooks 在后台自动把任务路由给对应的专属 agent、把相关记忆检索出来塞进上下文、干完活把成功模式存回去。README 原话：「你不必学 314 个 MCP 工具或 26 条 CLI 命令，init 之后正常用 Claude Code 就行。」

注意这个项目的时间线：2025 年 6 月 2 日建仓（当时叫 claude-flow），一年到 68.5K Star、8,237 fork、830 个 open issue——活跃度是真的，但「改名叫 Ruflo」这件事做得相当不彻底，这点后面坑里细说。

核心机制一：Swarm 编排——女王蜂 + 8 种工蜂 + 5 种共识算法

多 agent 协作最大的问题是「谁说了算」。Ruflo 的答案是经典的蜂群模型：queen（女王）负责规划，worker（工蜂）负责执行，而且 queen 分三种——Strategic（战略：拆目标）、Tactical（战术：排执行）、Adaptive（自适应：优化）。worker 有 8 类：Researcher、Coder、Analyst、Tester、Architect、Reviewer、Optimizer、Documenter。

真正有技术含量的是共识层：agent 之间对决策达成一致，不靠人拍板，靠算法——

这套设计明显是从分布式系统抄的作业——Raft、BFT 这些词过去只出现在数据库和区块链论文里，现在被搬来协调 AI agent。集体记忆走 SQLite + WAL + LRU 缓存，spawn 一批 agent 是并行拉起。CLI 侧对应 hive-mind 命令组：ruflo hive-mind init、ruflo hive-mind spawn "Build API" --queen-type tactical。拓扑也支持 hierarchical（女王-工蜂）、mesh（点对点）和 adaptive（动态伸缩）三种。

核心机制二：自学习记忆——AgentDB + HNSW，token 账本算得很细

记忆是 Ruflo 投入最重的一块，也是它跟 claude-mem 这类「会话记忆工具」拉开差距的地方。技术栈是 AgentDB（向量库）+ HNSW 索引 + ONNX 本地嵌入（Xenova/all-MiniLM-L6-v2）+ SONA 神经模式 + ReasoningBank。嵌入模型跑在本机，不调外部 API——我实测 ruflo memory init 时它现场下载并加载了 Transformers.js 的 MiniLM 模型，离线可用。

有意思的是 README 给了一组诚实到反常的 benchmark：HNSW 相对暴力搜索，N=20k 时快 ~1.9x、N=5k 时快 ~3.2x–4.7x，recall@10 ≈ 0.99——但文档明确写了「ANN 在交叉点以上才赢，小数据量下打平甚至更慢」。这不是营销话术，是实测报告（还附了复现脚本 scripts/benchmark-intelligence.mjs）。在满嘴 10x 的开源圈里，这种「小数据别用我」的坦白反而可信。

记忆不是只存不用的，它直接参与省钱。文档给的 token 节省账：

外加一个 Thompson sampling 模型路由：Haiku/Sonnet/Opus 三档不再是静态阈值，而是多臂老虎机——每次调用记录结果更新 Beta(α,β) 先验，约 50 次调用后路由分布自动纠偏，每次路由开销 45µs。这个设计挺妙：它把「哪个模型性价比高」从人工配置变成了在线学习问题。

核心机制三：Agent Booster——WASM 直接干，<1ms，$0

最「反直觉省钱」的一招：有些代码编辑根本不需要 LLM。Agent Booster 用 Rust 编译的 WASM 处理 6 类简单变换——var-to-const、add-types、add-error-handling、async-await、add-logging、remove-console。hooks 检测到这类意图时直接走 WASM：延迟 <1ms、成本 $0，而走 LLM 要 2-5 秒、$0.0002-$0.015。跑起来时 hooks 输出里会出现这类信号：

[AGENT_BOOSTER_AVAILABLE] Intent: var-to-const
→ Use Edit tool directly, instant (regex-based, no LLM call) than LLM

[TASK_MODEL_RECOMMENDATION] Use model="haiku"
→ Pass model="haiku" to Task tool for cost savings

本质上是把「这活不用动脑」的先验写死在 harness 里——LLM 只处理真正需要理解的任务。这套思路跟 DeepSeek-Reasonix 的「缓存优先」异曲同工：省 token 的第一步不是压缩，而是能不调就不调。

核心机制四：零信任联邦——Slack for Agents

Ruflo 最野的部分：agent 可以跨机器、跨组织协作，协议是 mTLS + ed25519 挑战应答，没有共享密钥。每台机器上的 agent 加入 federation 后可以互相发现、验证身份、交换任务——但数据不是裸奔的：

• PII 门控：14 类检测管道扫每条出站消息，按信任级别执行 BLOCK / REDACT / HASH / PASS 四种策略，邮件、SSN、密钥在离开节点前被剥掉。
• 行为信任分：公式 0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity 持续评估对端；升级需要历史记录，降级是即时的——干坏事立刻降权，不需要人介入。
• 合规模式：HIPAA / SOC2 / GDPR 审计轨迹，每次联邦事件生成结构化记录，可用 HNSW 检索。

# Team A: 初始化联邦并生成密钥对
npx ruflo federation init

# Team A: 加入 Team B 的联邦端点
npx ruflo federation join wss://team-b.example.com:8443

# Team A: 发任务——PII 在离开前自动剥离
npx ruflo federation send --to team-b --type task-request \
  --message "Analyze transaction patterns for account anomalies"

# 查看对端信任等级
npx ruflo federation status

文档里给的场景是「两个团队共享欺诈信号但不共享客户数据」——agent 之间直接谈，人只审结果。还带预算熔断器：federation_send 支持 budget/maxHops 元数据，默认 maxHops: 8，防止递归委托死循环（ADR-097，已实测修复）。

上手：我在沙箱实测跑通的命令

Ubuntu 无头沙箱，Node v22.22.3。全链路：安装 → init → doctor → mcp → memory → swarm，都通了。

# 1) 安装：两条路任选
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
#   或（交互式向导，跨平台）
npx ruflo@latest init wizard
#   或全局装（推荐，实测走这条）
npm install -g ruflo@latest        # 611 个包，实测 2 分钟

# 2) 初始化（--minimal 免交互；--no-signup 跳过注册引导）
ruflo init --minimal --no-signup
#    实测生成 16 个文件：CLAUDE.md、.claude/settings.json、
#    .claude/skills/（8 个 SKILL.md）、.mcp.json、.claude-flow/config.yaml

# 3) 体检
ruflo doctor                          # 实测 13 passed / 14 warnings

# 4) 核心服务
ruflo mcp status                      # Running, stdio transport
ruflo memory init                     # 建 .swarm/memory.db，加载 MiniLM 嵌入
ruflo swarm init                      # 实测：hierarchical 拓扑，15 agents，自动伸缩

# 5) 注册进 Claude Code 当 MCP server
claude mcp add ruflo -- npx ruflo@latest mcp start

实测关键输出摘录：ruflo mcp status 返回 Running + PID + stdio；ruflo memory init 现场拉取 Transformers.js MiniLM-L6-v2，schema version 3.0.0，hybrid backend；ruflo swarm init 生成 swarm ID、hierarchical 拓扑、max agents 15、auto scale enabled。

实测与踩坑：5 个坑，第 2 个最贵

• 坑 1（最直观）：npx 冷启动是个灾难。我第一次 npx -y ruflo@latest --help，180 秒超时被 SIGTERM 杀掉，一行帮助都没看到——依赖树里有 koa-router、keygrip、prebuild-install 一堆 deprecated 包，首次拉取要下几百个包。README 自己也承认冷缓存 npx 约 35 秒（那是 @claude-flow/cli-core 精简版），全量版实测 3 分钟起步。结论：别用 npx 跑，直接全局装。611 个依赖包本身就是个信号——这不是个轻量工具。
• 坑 2（最贵）：333 个 MCP 工具 ≈ 61,550 schema tokens/轮。这是 ruflo doctor 实测报告里的原话：「MCP Schema Overhead: 333 advertised tools ≈ 61550 schema tokens (all tools)」。MCP 工具定义要随每次请求发给模型，333 个工具的 schema 就是每轮对话约 6 万 token 的固定开销——按 Claude Sonnet 定价约 $0.09-0.18/轮，还没干活先烧钱。这是「功能全」的暗面：工具数量本身就是成本。真要上生产，得自己裁剪工具集，别 all-in。
• 坑 3：改名改了一半。npm 包叫 ruflo（v3.38.16），但仓库 package.json 的 name 还是 claude-flow；README 的 Star 徽章链接指向 ruvnet/claude-flow（该仓库已不存在）；--help 的 EXAMPLES 里写的还是 $ claude-flow init；issues 链接也指向 claude-flow。看文档时命令名 ruflo/claude-flow 混着出现，全按 ruflo 执行即可，但第一次看到会懵。
• 坑 4：安全默认值比想象中松。doctor 实测：Encryption at Rest: Off — session/terminal/memory stores are plaintext (mode 0600 only)——加密默认关，要自己设 CLAUDE_FLOW_ENCRYPT_AT_REST=1 开启（AES-256-GCM，ADR-096）。另外 aidefence_* MCP 工具依赖可选的 @claude-flow/aidefence 包，不装的话这些工具会报错。装完建议先跑一遍 doctor，14 条 warning 逐条看。
• 坑 5：真实环境依赖多。doctor 实测警告了 Claude Code CLI 未安装、API keys 为空、memory 未初始化、非 git 仓库——这些在干净沙箱里全亮黄灯。它默认你已经有 Claude Code 和至少一个 LLM 的 key，纯 CLI 无模型环境里只能初始化，干不了活。还有 ruflo doctor 会自动拉起后台 daemon（输出里直接告诉你「Started Ruflo background daemon」），不想要记得 ruflo daemon stop。

对比：跟「给 agent 加外挂」的邻居们

一句话定位：claude-mem 只解决「记忆」，herdr 只解决「agent 有地方待」，oh-my-openagent 只解决「多模型并行」，superpowers 只解决「agent 懂规矩」——Ruflo 想一次性全包：记忆、编排、协作、安全、省钱。野心是最大的，代价（复杂度、工具面、冷启动）也是最大的。

值不值得装：三个场景对号入座

• 重度 Claude Code 用户、被「每次会话失忆」折磨的：值得试。ruflo init --minimal 几分钟就绪，hooks 自动干活，记忆持久化是实打实的体验提升。先把 333 个工具砍到够用为止，控制 schema 开销。
• 团队/多机协作、想让 agent 之间直接对接的：federation 是这个生态里独一份的能力，mTLS + PII 门控的设计比「把 key 贴给对面」靠谱得多。但这是最复杂的一块，建议等核心跑稳再上。
• 只想给 Claude Code 加个记忆的轻量用户：先看 claude-mem。Ruflo 对你来说过重——611 个依赖、3 分钟冷启动、6 万 token 的工具面开销，都是实打实的成本。

最后说句公道话：68.5K Star、一年 8,237 fork、每天还在发版，Ruflo 是 2025-2026 这波「agent harness 军备竞赛」里野心最大的项目之一。它的价值不只是能用，更是一份「给 coding agent 加编排层」的完整设计说明书——共识算法选型、token 账本、WASM 免 LLM 通道、零信任联邦，每一个都值得单独抄作业。装它之前先想清楚：你要的是神经系统，还是只缺一根记忆神经。MIT，仓库 github.com/ruvnet/ruflo，npm ruflo。