ruvnet/ruflo · 上手攻略
- 仓库：ruvnet/ruflo
- 链接：https://github.com/ruvnet/ruflo
- 分类：agent（Agent 编排框架）
- 作者：Tom
- 更新：2026-07-06
这是什么
Ruflo（原名 Claude Flow）是一个 Agent 元编排框架（meta-harness）。它的核心理念一句话：Agent = Model + Harness——模型负责写作，框架负责给它配上工具、记忆、循环、沙箱和控制机制。Ruflo 就是这个框架层。
它运行在 Claude Code 和 Codex 之上，通过 npx ruflo init 一次性为这些 AI 编码客户端加上：100+ 专业化 Agent、蜂群协作、自学习记忆、跨机器联邦通信、企业级安全护栏。本质上是把单兵作战的 Claude Code 升级为一个有"神经系统"的 Agent 团队。
⚠️ 注意：Stars 数量（63K）较高，但该仓库功能极多（33 个插件、100+ Agent），建议按需安装，不要一股脑全量部署。
解决什么问题
单 Agent 顺序执行复杂软件工程任务（大型代码库重构、跨50个文件的架构评审、多阶段功能实现）受到单线程本质的限制。Ruflo 用多 Agent 协作和蜂群架构打破这个瓶颈：
- 路由决策：不需要人类决定用什么工具——Hook 系统自动路由
- 记忆断层：AgentDB（HNSW 向量数据库）在 N=20k 时比 brute force 快约 1.9 倍，N=5k 时快 3.2–4.7 倍
- 经验流失：每次成功的任务模式会被 SONA 自学习系统记住
- 跨机器协作：Federation 插件让不同机器上的 Agent 可以安全地交换任务，不需要暴露数据
快速安装
方式一：插件市场（轻量体验）
# 在 Claude Code 内
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo
这种方式不注册 MCP 服务器，memory_store、swarm_init、agent_spawn 等工具不可用。仅适合试用某个插件。
方式二：CLI 完整安装（推荐生产使用）
POSIX 系统（macOS / Linux / WSL / Git-Bash）：
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
全平台（含 Windows PowerShell）：
# 交互式引导安装
npx ruflo@latest init wizard
# 或静默快速安装
npx ruflo@latest init
全局安装：
npm install -g ruflo@latest
安装 MCP 服务器（可选）
# 将 Ruflo 注册为 Claude Code 的 MCP 服务器
claude mcp add ruflo -- npx ruflo@latest mcp start
核心用法
初始化后的核心体验
安装完成后，直接正常使用 Claude Code 即可——Hook 系统会在后台自动路由任务、协调 Agent、记录经验，不需要额外命令。
核心插件一览
| 插件 | 用途 |
|---|---|
ruflo-core |
基础设施：服务器、健康检查、插件发现 |
ruflo-swarm |
多 Agent 团队协作（层级、网格、自适应拓扑） |
ruflo-autopilot |
Agent 自主循环运行 |
ruflo-loop-workers |
定时后台任务调度 |
ruflo-workflows |
可复用多步骤任务模板 |
ruflo-federation |
跨机器 Agent 安全协作（零信任） |
ruflo-agentdb |
快速向量数据库（Agent 记忆） |
ruflo-rag-memory |
混合搜索、图跳、多样性排序的智能检索 |
ruflo-rvf |
跨会话保存/恢复 Agent 记忆 |
ruflo-ruvector |
GPU 加速搜索、Graph RAG（103 工具） |
ruflo-knowledge-graph |
实体关系图构建与遍历 |
ruflo-intelligence |
Agent 从成功案例中自学习（SONA 神经模式） |
ruflo-graph-intelligence |
子线性图推理（PageRank、增量更新） |
ruflo-ruvllm |
本地 LLM（Ollama 等）智能路由 |
ruflo-goals |
大目标分解为计划并跟踪进度 |
ruflo-testgen |
自动发现缺失测试并生成 |
ruflo-browser |
Playwright 浏览器自动化测试 |
ruflo-docs |
自动生成和维护文档 |
ruflo-security-audit |
漏洞和 CVE 扫描 |
ruflo-aidefence |
阻断提示注入、检测 PII |
ruflo-adr |
架构决策记录（Architecture Decision Records） |
ruflo-metaharness |
评估 Agent 配置安全性和成熟度（1-100分） |
ruflo-arena |
Agent 策略竞技场（让不同 Agent 方案相互竞赛进化） |
ruflo-cost-tracker |
Token 用量跟踪和预算告警 |
关键命令（60+ 命令中必知的几个）
# 查看可用命令
ruflo --help
# 启动 MCP 服务器
ruflo mcp start
# 初始化蜂群
ruflo swarm init
# 生成 Agent 记忆快照
ruflo memory save
# 扫描项目安全风险
ruflo audit --security
# 成本跟踪
ruflo cost report
MetaHarness：评估你的 Agent 配置
ruflo 自带一个配置审计工具：
ruflo eject
这把一个 ruflo 项目转换为独立的 Agent 工具包，有自己的名字。适合想把某个特定能力剥离出来单独使用时操作。
完整指南见：docs/metaharness-user-guide.md
Web UI（免安装试用）
不想安装？可以到 flo.ruv.io 直接试用：
- 支持 Qwen、Claude、Gemini、OpenAI
- 内置 ~210 个工具，浏览器内可运行 18 个
- 并行工具调用（一次响应触发 4–6+ 工具）
- 自带记忆持久化
Web UI 也支持 Docker 自托管：
# 在 ruflo/src/ruvocal/ 有 Dockerfile
docker build -t ruflo-web --build-arg INCLUDE_DB=true .
GOAP 任务规划（goal.ruv.io）
高阶目标 → 可执行计划：访问 goal.ruv.io 输入"ship the auth refactor with tests and a PR"，Ruflo 会用 A* 规划器将其分解为前置条件、动作序列、执行路径，实时推送给 Agent 执行。
典型适用场景
大型代码库重构
单 Agent 顺序修改 50+ 文件容易遗漏依赖关系。用 ruflo-swarm 启动多个 Agent 并行分析，每个负责不同模块，最后合并——重构覆盖率大幅提升。
安全审计
ruflo-security-audit + ruflo-aidefence 可以自动扫描代码库漏洞、CVE、提示注入风险，适合 CI 集成。
跨团队 Agent 协作
Federation 插件让不同机器、不同组织的 Agent 可以在零信任模式下安全交换任务结果，适合分布式研发团队。
成本控制
ruflo-cost-tracker 追踪每次会话的 Token 消耗，设置预算阈值，防止月末账单超支（对 Claude Code 的用量特别有用）。
坑与注意
-
全量安装文件多：完整
ruflo init会在工作区写入.claude/、.claude-flow/、CLAUDE.md、helpers/、settings等文件。如果只需要某个插件功能，用插件市场方式更轻量。 -
Stars 高≠开箱即用：Ruflo 是个庞大系统，建议从
ruflo-core+ruflo-swarm开始，逐步加插件，而不是一次装 33 个。 -
MCP 服务器需单独注册：插件市场路径不注册 MCP server，完整功能（包括
agent_spawn等）需要走npx ruflo@latest init方式。 -
Windows 兼容性：PowerShell 用户可直接用
npx ruflo@latest init wizard，但curl | bash方式需要 POSIX shell（Git-Bash / WSL / MSYS）。 -
依赖 Claude Code/Codex：Ruflo 是框架不是独立应用，需要先有 Claude Code 或 Codex CLI 作为底层引擎。
-
ADR 文件多：仓库里有大量 Architecture Decision Records（ADR），是内部设计决策文档，不是给终端用户看的——不要被吓到。
与同类对比
| 工具 | 定位 | 优势 | 不足 |
|---|---|---|---|
| Ruflo | Claude Code/Codex 的元编排层 | 蜂群协作、自学习记忆、联邦安全、100+ Agent | 需要深度学习，复杂度高 |
| LangChain Agents | LLM 工具调用框架 | 生态丰富，文档完善 | 非专为 Claude 设计，蜂群能力弱 |
| AutoGPT | 自主 Agent | 开源早期探索 | 稳定性差，无蜂群概念 |
| Microsoft AutoGen | 多 Agent 协作 | 微软生态集成 | 偏研究，生产成熟度一般 |
| n8n | 工作流自动化 | 低代码，AI 节点丰富 | 非 Agent 专用，无自学习 |
Ruflo 的护城河是自学习记忆（SONA）+ 蜂群协作 + 联邦安全三者的结合，尤其适合已经深度使用 Claude Code/Codex 但受限于单 Agent 瓶颈的团队。
一句话推荐结论
如果你用 Claude Code 但被"单 Agent 顺序执行"困住——先试 npx ruflo@latest init wizard，它给 Claude Code 加上一层神经系统，让 Agent 自己组织成蜂群、记住经验、协同工作，而你要做的只是继续写代码。