Ruflo：把 100 个 AI Agent 变成一支协作团队，GitHub 已超 4 万星

🔖 快速摘要

本文核心结论：

Ruflo（前身为 Claude Flow）是目前多智能体协作领域架构最完整、工程化程度最高的开源项目之一。它的核心不是让一个 AI 变得更强，而是把几十乃至上百个专业化 Agent 组织成一支可以自我协作、自我学习、跨机器安全通信的「AI 团队」。截至 2026 年 5 月，项目在 GitHub 已积累超过 4 万星标，最新稳定版为 v3.6.x，支持 32 个官方插件、215 个 MCP 工具，并引入了基于 HNSW 的持久化向量记忆、零信任跨机器 Federation 以及 WASM 加速的自学习推理内核。对开发者而言，它的真正价值在于：你不需要一个人同时扮演 10 个角色，让 Ruflo 的 Swarm 帮你把任务分拆出去，然后汇总结果回来。

往下看有更详细的原理拆解和操作步骤。

一、从一个真实困境说起

在备考黑龙江节点云计算科技公司的人工智能训练师资格考试期间，我同时在做几件事：整理训练数据标注规范、跑模型微调脚本、写考试复习文档。三件事的上下文完全不同，来回切换之间总有东西遗漏，要么标注规范文档里漏了一段，要么脚本里的注释没跟上最新改动。

那段时间我就在想，如果有一种机制，能把"负责写文档的我"、"负责跑代码的我"和"负责整理资料的我"真正拆开，让三个任务并行推进，彼此之间只在需要同步的节点才交换信息，效率会高多少。

Ruflo 做的，就是这件事——只不过它不是对"一个人"做拆分，而是对"一个 AI"做拆分，然后把拆出来的这些 Agent 重新组织成一个协作系统。

二、Ruflo 是什么，它从哪里来

Ruflo 的早期版本叫做 Claude Flow，是专门为 Claude Code 构建的 Agent 编排框架。随着版本迭代，项目在 2025 年下半年正式更名为 Ruflo，名字来源于作者的两个偏好：Rust（底层 WASM 内核用 Rust 编写）和 Flow State（心流状态）。

从定位上看，Ruflo 并不是一个独立运行的 AI 应用，而是一个中间件层——它介于你（用户）和底层 LLM 服务（Claude、GPT、Gemini、Ollama 等）之间，负责任务路由、Agent 编排、记忆管理和跨节点协作。你继续在 Claude Code 里写代码、提需求，Ruflo 在后台把这些请求分发给合适的专业 Agent，等它们协作完成后把结果汇总还给你。

整个系统的宏观架构可以这样理解：

用户 → Claude Code / CLI ↓ 编排层（MCP Server + Router + 27个Hooks） ↓ Swarm 协调（Queen 调度 + 拓扑管理 + 共识协议） ↓ 100+ 专业 Agent（coder / tester / reviewer / architect / security...） ↓ 记忆与学习层（AgentDB + HNSW + SONA + ReasoningBank） ↓ LLM 提供方（Claude / GPT / Gemini / Cohere / Ollama） ↑ 学习闭环（每次任务完成后回写经验）

这个架构里最关键的环节不是"有多少个 Agent"，而是中间那两层：Swarm 协调决定了多个 Agent 怎么分工，记忆与学习层决定了系统用完一次之后是否比之前更聪明。

三、Swarm 原理：Agent 是怎么协作起来的

"Swarm"这个词来自于蜂群行为研究，描述的是大量个体在没有中央控制的情况下，通过局部交互涌现出整体智能的现象。Ruflo 的 Swarm 系统借用了这个概念，但实际实现上加入了更多工程化的结构控制。

Swarm 的拓扑结构

Ruflo 支持三种 Swarm 拓扑：

• 层级拓扑（Hierarchical）：有一个 Queen Agent 作为总调度，下面挂着若干 Worker Agent，任务由 Queen 拆解后下发，结果向上汇总。这是编码类任务最常用的拓扑，因为软件开发天然有"规划→实现→验证"这样的层级结构。
• 网状拓扑（Mesh）：所有 Agent 之间可以点对点通信，没有中心节点，类似于 P2P 网络。这种拓扑容错性更强，适合需要高可用的分布式场景。
• 自适应拓扑（Adaptive）：系统根据任务的成功率和当前负载动态切换拓扑类型，通过机器学习来判断什么时候该用层级、什么时候切成网状。

共识协议：多个 Agent 怎么"投票"

当多个 Agent 对同一个问题有不同的判断时，Ruflo 通过三种共识协议来解决分歧：

• Raft 协议：偏向于日志复制和领导者选举，适合对顺序性有要求的任务（比如数据库迁移步骤的确认）。
• 拜占庭容错（Byzantine Fault Tolerance）：在存在恶意节点或错误输出的情况下，只要出错的 Agent 数量不超过总数的三分之一，系统仍能得出正确结论。表达式是 (f < \frac{n}{3})，其中 (f) 是故障节点数，(n) 是总节点数。这对于安全审计类任务尤其重要——如果某个 Agent 给出了错误的 CVE 扫描结论，其他 Agent 的结果可以纠正它。
• Gossip 协议：节点之间随机传播状态更新，适合大规模分布式环境下的最终一致性同步。

实际使用中，最常用的是拜占庭容错模式，因为它对 LLM 输出的不稳定性（幻觉、漏判等）有天然的容错能力。

Agent 的类型划分

Ruflo 当前版本内置了超过 100 个专业 Agent，按功能大类分组如下：

这些 Agent 不是独立工作的，它们通过SendMessage机制互相通信。比如一个典型的"开发一个新功能"任务，实际执行流程是：

Task("分析需求", "定义用户故事和验收标准", "specification") Task("规划架构", "设计模块边界和接口", "architecture") Task("实现功能", "编写代码", "coder") Task("编写测试", "覆盖主要路径", "tester") Task("代码审查", "安全+质量双重检查", "reviewer")

这五步在 Swarm 内部是可以部分并行推进的——coder和tester可以同时启动，而不需要等对方完成。

四、记忆系统：Agent 为什么能越用越聪明

传统 AI 工具的一个根本缺陷是无状态：每次对话都从零开始，之前做过什么、学到什么，完全不记得。Ruflo 的记忆系统专门针对这个问题设计，分为三个层次。

HNSW 向量索引：让检索快起来

HNSW（Hierarchical Navigable Small World）是一种图结构向量索引算法。它的工作原理是将高维向量（比如一段代码的语义嵌入）组织成一个多层图，每一层的节点密度不同，上层稀疏用于快速定位区域，下层密集用于精细匹配。

查询时，算法从最稀疏的上层出发，逐层向下收敛到最近邻节点，整体复杂度从暴力搜索的 (O(n)) 降到近似 (O(\log n))。Ruflo 的官方基准测试显示，HNSW 检索比传统向量数据库快 150 倍到 12500 倍，单次查询延迟约 61 微秒，QPS 可达 16400。

这意味着当 Agent 需要"回忆"之前做过的类似任务时，检索几乎是即时的，不会成为系统瓶颈。

SONA + ReasoningBank：存的不只是数据，还有推理路径

Ruflo 设计了一套叫做 SONA（Self-Optimizing Neural Architecture）的机制，专门用来记录 Agent 的推理轨迹。每次任务完成后，系统会把以下信息写入 ReasoningBank：

• 任务的输入描述
• Agent 选择了哪条推理路径
• 中间步骤的关键决策点
• 最终输出结果和质量评分

下次遇到相似任务时，系统会通过语义搜索在 ReasoningBank 里找到历史上成功的推理路径，优先参考这些路径来规划当前任务。整个学习闭环是：

RETRIEVE（HNSW检索相似经验） ↓ JUDGE（对当前结果打分：成功/失败） ↓ DISTILL（提炼有效模式，类似LoRA微调的思路） ↓ CONSOLIDATE（EWC++防止遗忘旧经验）

这套机制让 Ruflo 的 Agent 系统具备了初步的持续学习能力——不是对模型权重的真正微调，而是在检索增强的层面上实现的"经验积累"。

AgentDB：持久化的结构化记忆

AgentDB 是 Ruflo 的底层存储组件，基于 SQLite（sql.js）实现，内置 12 张专业表，用于存储不同类型的记忆：会话上下文、知识图谱节点、任务轨迹、信任评分等。v3.5 之后引入了 8 个新控制器，包括负责密码学证明写入的 MutationGuard 和用于合规审计的 AttestationLog。

五、Federation：跨机器协作时的安全边界

Federation（联邦化）是 Ruflo 最具工程深度的功能之一，解决的是一个现实问题：当两个团队、两套系统需要共享 AI 能力时，如何在不泄露各自私有数据的前提下协作。

官方给出的场景是：两个团队共享欺诈检测信号，但不共享用户数据。这在金融、医疗、企业间合作等场景下极为常见。

身份验证：mTLS + ed25519

Federation 的第一层保护是身份认证。所有远端 Agent 在初始状态下都被标记为"不可信"，必须通过以下方式证明身份：

• mTLS（双向 TLS）：不只是服务器向客户端证明自己，客户端也必须向服务器出示证书，双向验证。
• ed25519 挑战-响应：使用椭圆曲线签名算法，远端 Agent 通过签名一个随机挑战串来证明持有私钥，整个过程不传输任何共享密钥。

这意味着即使网络通信被拦截，攻击者也无法伪造合法的 Agent 身份。

PII 过滤管线

在数据传输层，Ruflo 内置了 14 种个人信息（PII）检测类型，覆盖姓名、身份证号、手机号、银行卡号等常见敏感字段。每条出站消息都会经过这条管线，根据当前信任等级执行不同策略：

• BLOCK：直接拦截，不发送
• REDACT：替换为占位符（如[PHONE_REDACTED]）
• HASH：单向哈希，接收方能验证一致性但无法还原原始值
• PASS：信任等级足够高时放行

行为信任评分

Federation 还引入了动态信任评分机制，公式为：

[

\text{TrustScore} = 0.4 \times \text{success} + 0.2 \times \text{uptime} + 0.2 \times \text{threat} + 0.2 \times \text{integrity}

]

评分持续更新，信任升级需要足够的历史行为记录，信任降级则是即时生效的。系统还支持 HIPAA、SOC2、GDPR 等合规审计模式，每个 Federation 事件都会产生结构化的审计记录，并通过 HNSW 索引使其可检索。

六、GOAP 目标规划：告诉它"做什么"，不用说"怎么做"

Ruflo 集成了 GOAP（Goal-Oriented Action Planning，面向目标的行动规划）引擎，这是一个借鉴自游戏 AI 的规划算法。

传统的任务编排需要你精确定义每一步操作。GOAP 的思路则是：你只说"我要达到什么状态"，规划器来搜索从当前状态到目标状态的最短可行路径。

具体实现上，GOAP 通过 A* 搜索算法在"动作空间"里遍历，每个动作有前置条件（preconditions）和效果（effects），规划器找到一条满足所有约束的动作序列。当某个动作失败或外部状态变化时，规划器会从当前状态重新运行 A* 而不是从头重启整个任务，失败自动成为下一轮学习的输入。

在goal.ruv.io提供的在线演示中，你可以直接用自然语言描述目标，比如"完成 auth 重构并包含测试和 PR"，GOAP 引擎会自动提取成功标准、隐含约束和先决条件，生成一棵可折叠的行动树，你可以看到每个分支的进度、阻塞原因和回滚路径。

七、32 个官方插件：按需组合的能力积木

Ruflo v3.6.10 将插件数量从 21 个扩展到了 32 个，覆盖从代码开发到 IoT 设备管理的完整生命周期。以下是按功能模块的分类说明：

核心与协作

• ruflo-core：基础服务、健康检查、插件发现，这是所有其他插件的依赖基础。
• ruflo-swarm：多 Agent Swarm 编排，支持层级/网状/自适应三种拓扑。
• ruflo-autopilot：让 Agent 进入自动循环模式，持续执行直到目标完成。
• ruflo-federation：跨机器零信任协作，含完整的 mTLS 身份验证和 PII 过滤。
• ruflo-workflows：可复用的任务模板，定义一次，多场景复用。

记忆与知识

• ruflo-agentdb：向量数据库核心，含 G7 控制器（包括密码学证明写入的 MutationGuard）。
• ruflo-rag-memory：升级到 SOTA 水平的混合检索，支持 RRF 融合检索、Graph RAG 多跳推理、MMR 多样性过滤和时间衰减权重。
• ruflo-ruvector：GPU 加速向量搜索 + Graph RAG，集成 FlashAttention-3，同时提供 103 个 MCP 工具。
• ruflo-knowledge-graph：知识图谱构建，利用 PageRank 和社区检测识别高影响力洞见。

开发与测试

• ruflo-testgen：自动分析测试覆盖缺口，补全单元测试。
• ruflo-browser：浏览器自动化测试，可驱动真实浏览器执行 E2E 测试。
• ruflo-jujutsu：基于 Git diff 的代码变更分析，适合 Code Review 辅助。
• ruflo-docs：文档自动生成与维护，保持文档和代码同步。

安全

• ruflo-security-audit：CVE 漏洞扫描，内置常见漏洞特征库。
• ruflo-aidefence：Prompt 注入检测，带有文件权限加固（mode 0600）和静态加密保障。

架构与运维

• ruflo-adr：架构决策记录（Architecture Decision Records），自动归档每一次重要的技术选型。
• ruflo-ddd：领域驱动设计脚手架，快速生成标准化的领域模型结构。
• ruflo-migrations：数据库迁移脚本管理与执行。
• ruflo-observability：日志追踪和监控，集成常见可观测性标准。
• ruflo-cost-tracker：API 用量和费用监控，配合 Federation 预算熔断机制使用。

扩展能力

• ruflo-wasm：WebAssembly 沙箱，为不受信任的代码执行提供隔离环境。
• ruflo-plugin-creator：让 Agent 帮你写新插件，具备一定的自我扩展能力。

八、两个在线体验入口

在本地安装之前，Ruflo 提供了两个无需注册、直接在浏览器里可用的体验入口：

flo.ruv.io是一个多模型聊天 Web UI，内置 5 个服务器组和 18 个工具的完整工具库，支持工具并行执行（一次模型响应可以同时触发 4 到 6 个工具），并带有持久化记忆——你说"记住我喜欢的颜色是靛蓝"，几周后再问它还记得。界面会实时展示每个工具的执行状态，清晰标注"步骤 1 — 已完成 2 个工具"这样的进度信息。

goal.ruv.io是 GOAP 目标规划器的演示入口，你输入一个高层目标（支持自然语言），系统自动拆解成带有依赖关系的行动树，实时显示每个 Agent 的角色、当前步骤、记忆命名空间和 token 预算。可以点进去查看完整的推理轨迹，也可以中途介入、停止某个失控的 Worker 或重新分配任务。

九、本地安装与配置：完整操作步骤

环境准备

在安装之前，先确认你的机器满足以下条件：

• Node.js v18 以上（推荐 v22）
• npm v10 以上
• Git
• 已安装 Claude Code（这是 Ruflo 的宿主环境）

可以通过以下命令快速验证环境：

node -v # 应输出 v18.x 或更高 npm -v # 应输出 10.x 或更高 claude --version # 确认 Claude Code 已安装

安装方式一：通过 Claude Code 插件市场（推荐）

这是官方推荐的方式，适合大多数用户：

# 第一步：添加 Ruflo 插件市场 /plugin marketplace add ruvnet/ruflo # 第二步：安装核心插件 /plugin install ruflo-core@ruflo # 第三步：按需安装功能插件 /plugin install ruflo-swarm@ruflo # 多 Agent 协作 /plugin install ruflo-autopilot@ruflo # 自动驾驶模式 /plugin install ruflo-federation@ruflo # 跨机器协作 /plugin install ruflo-rag-memory@ruflo # 混合检索记忆

注意：通过插件市场安装的方式只会添加斜杠命令和 Agent 定义，不会注册 MCP 服务器，所以memory_store、swarm_init、agent_spawn等工具调用将不可用。如果需要完整功能，请用下面的方式 B。

安装方式二：完整 MCP 模式（功能完整）

# 安装 CLI 工具（三个包名等效，任选一个） npx ruflo@latest init --wizard # 将 Ruflo 注册为 MCP 服务器 claude mcp add ruflo -- npx -y ruflo@latest mcp start # 验证安装状态 npx ruflo doctor

npx ruflo doctor会输出类似这样的诊断信息：

✓ node: v22.14.0 ✓ npm: 10.9.2 ✓ git: 2.47.1 ✓ config: ruflo.config.json found ✓ daemon: Running (PID 12345) ✓ memory: AgentDB initialized (sql.js + HNSW) ✓ agentic-flow: v3.0.0

如果某一项显示✗，可以运行npx ruflo doctor --fix自动修复常见问题。

基础使用示例

安装完成后，在 Claude Code 中你可以这样使用：

启动一个 Swarm 来完成开发任务：

# 初始化一个层级 Swarm，包含 8 个 Agent npx ruflo hive-mind spawn --agents 8 --strategy specialized # 或者在 Claude Code 中直接描述任务，让 Ruflo 自动决定是否启动 Swarm # "帮我实现 OAuth2 登录功能，包含测试和文档"

使用记忆系统存储和检索知识：

# 存储一个技术决策 npx ruflo memory store \ --key "auth-pattern" \ --value "JWT with refresh tokens, 15min access token TTL" \ --namespace patterns # 语义检索（HNSW 索引，近乎即时） npx ruflo memory search \ --query "认证最佳实践" \ --limit 5

让 Agent 自动学习这次任务的成功路径：

# 任务完成后触发学习写回 npx ruflo hooks post-task \ --task-id "task_001" \ --success true \ --store-results true

配置 Federation 与另一台机器上的 Agent 协作：

# 安装 Federation 插件 /plugin install ruflo-federation@ruflo # 查看当前 Federation 状态（包括对端节点的信任评分） npx ruflo federation status # 连接一个远端 Agent 节点 npx ruflo federation connect --endpoint https://peer-agent.example.com

升级已有安装

如果你之前使用的是旧版 Claude Flow，升级命令如下：

# 完全向后兼容，直接更新即可 npx ruflo@latest doctor --fix # 更新 MCP 服务器注册 claude mcp remove claude-flow claude mcp add ruflo -- npx -y ruflo@latest mcp start

旧版的npx claude-flow@latest和npx claude-flow@alpha等别名继续有效，不会突然失效。

十、性能与成本参考

Ruflo v3.5 的发布说明中提到了几个值得关注的性能数据：

• SWE-Bench 基准测试：解决率达到 84.8%，这是衡量 AI 系统解决真实软件工程问题能力的标准测试集。
• 任务完成速度：多 Agent 并行执行相比单 Agent 顺序执行有 2.8 到 4.4 倍的提速。
• API 成本：智能路由机制（根据任务复杂度自动选择最合适的模型）可以节省最多 75% 的 API 调用开销——简单任务用轻量模型，复杂任务才调用大模型。
• 向量检索延迟：HNSW 检索的平均延迟约 61 微秒，每秒可处理 16400 次查询。

十一、适用场景与不适用场景

Ruflo 是一个有明确适用边界的工具，并不是万能的。

它真正发挥优势的场景包括：作为独立开发者或小团队，需要同时推进多个互相依赖的任务模块；团队之间需要在安全边界内共享 AI 工作流；系统需要在长期使用中积累领域知识、让 Agent 越来越了解你的代码库；以及需要对接 GitHub、Jira、Slack 等工具链、把 AI 嵌入现有工作流的情况。

不太适合的场景是：只是偶尔问几个问题、不需要任何协作或记忆能力的轻量使用；机器配置不足（运行多个 Agent 的内存压力相当于同时跑多个进程，建议 16GB 以上）；以及完全没有命令行使用经验、不能接受一定学习成本的情况（不过goal.ruv.io提供的在线版本可以绕过这一点）。

十二、从"工具"到"系统思维"的转变

使用 Ruflo 一段时间后，你会发现它推动的不只是效率上的改变，而是一种看待 AI 工具的方式的转变。

过去我们用 AI 的方式是"对话式"的：我问一句，它答一句，我再问一句。这种模式下，AI 是一个被动的回答者，所有的任务规划、上下文维护、质量把控都压在人这一侧。

Ruflo 构建的是另一种模式：AI 成为一个可以接受目标描述的执行系统，任务分解、专业分工、质量验证、经验积累都在系统内部完成，人只需要在关键节点做决策和确认。

这种模式对使用者的要求是：你需要学会描述目标，而不是描述步骤。"帮我做一个有完整测试覆盖的 JWT 认证模块"比"先帮我写 generateToken 函数，然后帮我写 validateToken 函数，然后……"要好用得多，因为后者把任务规划的认知负担留在了你这里，而前者把它交给了 Swarm。

这恰好也是 AI 训练师这个职业方向上一个很有意思的认知点：怎么描述目标、怎么设计提示词结构，比知道某个具体工具的用法更值得深入理解。

十三、相关资源

• GitHub 项目主页：https://github.com/ruvnet/ruflo
• 在线多模型聊天（flo）：https://flo.ruv.io
• 在线目标规划演示（goal）：https://goal.ruv.io

写在最后

Ruflo 的文档量相当庞大，从 README 到 USERGUIDE 再到各插件的 REFERENCE，全部读完需要相当的时间投入。但它的设计有一个很友好的地方：你不需要理解所有东西才能开始使用它。官方的建议是，新用户直接按npx ruflo@latest init --wizard走完引导流程，然后在 Claude Code 里正常写代码就行——Hooks 系统会在后台自动路由任务、学习模式、协调 Agent，大多数协调工作对你来说是透明的。

从单兵作战到团队协作，这条路 Ruflo 帮你铺好了大半。怎么走，还得你自己来。