Ruflo 完全指南：多智能体编排平台从入门到精通

Ruflo（曾用名 Claude Flow）是一个面向 Claude Code 的多智能体编排平台。它在 Claude Code 之上构建了一层完整的基础设施：Agent 团队可以自发组织成蜂群（Swarm）、从任务经验中持续学习、借助向量记忆跨越会话保持上下文，还能通过联邦（Federation）机制与其他机器上的 Agent 安全协作，而用户只需要正常写代码——编排工作在后台自动完成。

截至本文编写时，Ruflo 在 GitHub 已有约 35,800 颗星、4,090 个分支，采用 MIT 许可证，主语言为 TypeScript，核心路由与向量引擎部分由 Rust 编写的 WASM 模块驱动。

1. 核心概念：为什么需要多智能体编排

1.1 传统单 Agent 的局限

Claude Code 本身是一个强大的单 Agent 工具，但它默认在隔离环境中运行：每个会话的任务之间没有共享记忆，Agent 无法从过去的成功路径中学习，多个 Agent 同时工作时缺乏协调机制。这在处理复杂项目时会成为瓶颈——你不得不手动分派任务、管理上下文、手动追踪进度。

1.2 多智能体编排解决什么问题

Ruflo 的核心思路是把「协调」这件事从用户身上抽离出来，由系统代劳。具体来说：

• 群智协作：多个专业化 Agent（coding、testing、review、security……）组成团队，各司其职，自动分担工作。
• 自我学习：成功的执行路径会被存储并在下次相似任务中复用，系统越用越聪明。
• 共享记忆：HNSW 向量索引支持毫秒级检索，Agent 之间可以共享上下文而不只是各自为战。
• 联邦通信：不同机器、不同组织边界内的 Agent 可以安全地交换任务，数据在发出前自动剥离敏感信息。
• 智能路由：不是所有任务都需要调用最贵的模型，Ruflo 根据任务复杂度自动决定使用 WASM 免费加速、便宜的 Haiku 还是最强的 Opus。

1.3 关键术语

2. 系统架构

2.1 整体架构图

用户层（CLI / Claude Code）
        │
        ▼
安全入口层（AIDefence，输入验证，路径遍历防护）
        │
        ▼
编排层（MCP Server + 路由器 + 27 个 Hooks）
        │
        ├──────────────────────┐
        ▼                      ▼
路由决策（Q-Learning 路由器 + MoE 8 专家）    技能系统（130+ Skills）
        │                      │
        ▼                      ▼
群协调层（拓扑 / 一致性 / Claims）◄──── 记忆与学习（AgentDB + HNSW）
        │
        ▼
100+ 专业化 Agent
（coder, tester, reviewer, architect, security…）
        │
        ▼
资源层（LLM Providers / 12 个后台 Worker / 存储）
        │
        ▼
RuVector 智能层（SONA / EWC++ / HNSW / ReasoningBank / LoRA）
        │
        └───► 学习闭环：RETRIEVE → JUDGE → DISTILL → CONSOLIDATE → ROUTE

2.2 各层职责详解

用户层：通过 CLI 或 Claude Code 与系统交互。推荐方式是将 Ruflo 作为 Claude Code 插件安装，这样所有能力直接集成到 Code 的上下文中，不需要额外启动进程。

安全入口层：所有入站请求经过 AIDefence 模块，处理 prompt injection 检测、PII 识别（14 种敏感数据类型）、路径遍历防护、命令注入拦截。联邦模式下，敏感数据在发出前自动剥离或哈希。

编排层：核心控制平面。MCP Server 暴露约 210 个工具，分 5 个服务器组（Core、Intelligence、Agents、Memory、DevTools）。Router 根据任务特征和历史性能选择最优路径（Q-Learning，公开报告准确率 89%）。27 个 Hook 在关键节点自动触发行为（如 post-task 保存记忆、pre-command 注入安全扫描）。

群协调层：Swarm 的执行引擎。支持 4 种拓扑结构：

• hierarchical：Queen-led 层级结构，Queen 验证每个输出与目标的一致性，是防止目标漂移（goal drift）的推荐模式
• mesh：点对点无中心协调，适合去中心化场景
• ring：环形邻居传播，适合大规模多 Agent 协作
• star：中心辐射型

支持 3 种一致性算法：Majority（简单多数）、Weighted（Queen 权重 3x）、Byzantine（f < n/3 容忍拜占庭故障）。

100+ Agent 层：每个 Agent 被分配特定角色（coder 负责实现、tester 负责测试、reviewer 负责审查……），可以并行启动并通过共享内存交换中间结果。

RuVector 智能层：Ruflo 的学习引擎核心。

2.3 学习闭环

RuVector 的核心是持续运转的五步闭环：

1. RETRIEVE：从 AgentDB 通过 HNSW 检索与当前任务相关的历史轨迹。
2. JUDGE：评估检索到的模式是否适用于当前上下文，计算匹配度。
3. DISTILL：将成功的模式压缩到路由策略和 Agent 行为模板中。
4. CONSOLIDATE：通过 EWC++ 将新知识与已有知识整合，防止遗忘。
5. ROUTE：更新路由器，下一次同类任务直接使用优化后的路径。

整个闭环在后台自动运行，不需要用户介入。

3. 安装与配置

3.1 前置要求

• Node.js 20+
• npm 9+ 或 pnpm / bun
• Claude Code（必须先安装）

3.2 安装方式对比

3.3 完整安装步骤

方式一：CLI 脚本安装（推荐生产使用）

# 基础安装
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

# 完整安装（全局 + MCP 自动配置 + 诊断检查）
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash -s -- --full

安装脚本支持以下参数：

方式二：npm / npx

# 不安装直接运行（适合试用）
npx ruflo@latest init --wizard

# 全局安装
npm install -g ruflo@latest
ruflo init

# 用 bun 更快
bunx ruflo@latest init

方式三：Claude Code 插件（最便捷）

如果主要在 Claude Code 中工作，插件方式最合适——安装后 skills、commands、agents 和 MCP tools 直接集成进 Code，不需要额外进程：

# 添加插件市场（一次性操作）
/plugin marketplace add ruvnet/ruflo

# 安装核心插件
/plugin install ruflo-core@ruflo         # MCP Server + 基础 Agent
/plugin install ruflo-swarm@ruflo        # Swarm 协调
/plugin install ruflo-autopilot@ruflo    # 自主循环执行
/plugin install ruflo-federation@ruflo   # 跨机器联邦通信

Ruflo 共发布 32 个原生插件，可以按需安装，完整列表见 GitHub 仓库 README。

3.4 验证安装

# 检查版本
ruflo --version

# 运行诊断
ruflo doctor

# 初始化项目（创建 CLAUDE.md 等配置文件）
ruflo init

# 查看 MCP 工具列表
claude mcp list

3.5 MCP Server 手动配置

如果安装脚本没有自动配置 MCP，可以手动添加：

claude mcp add ruflo -- npx -y @claude-flow/cli@latest

4. 核心功能详解

4.1 Swarm（蜂群协作）

Swarm 是 Ruflo 多 Agent 协作的核心抽象。一个 Swarm 由一个 Queen（协调者）和多个 Worker（执行者）组成，Queen 负责任务分解、进度追踪和一致性验证，Worker 负责具体执行。

初始化一个 Swarm：

# 启动一个层级 Swarm（推荐用于防止目标漂移）
npx ruflo@latest swarm init --topology hierarchical --max-agents 8

# 启动网状 Swarm（去中心化场景）
npx ruflo@latest swarm init --topology mesh --max-agents 16

拓扑结构选择建议：

防止目标漂移的配置（生产必读）：

// Anti-Drift 配置（所有编码任务建议使用）
swarm_init({
  topology: "hierarchical",  // 单协调器强制对齐
  maxAgents: 8,             // 团队越小漂移面越小
  strategy: "specialized",   // 清晰角色边界减少歧义
  consensus: "raft"           // Leader 维护权威状态
})

4.2 自学习与记忆

向量记忆（AgentDB + HNSW）

AgentDB 是 Ruflo 内置的向量数据库，基于 HNSW 索引。存储和检索的性能：

# 存储一段记忆
npx ruflo@latest memory store "用户偏好 indigo 作为主题色" --namespace user_prefs

# 检索（子毫秒级）
npx ruflo@latest memory search "主题颜色" --namespace user_prefs --top-k 5

ReasoningBank（推理库）

保存完整的任务轨迹，包括问题描述、解决方案和执行路径。下次遇到相似问题时，系统会自动检索并推荐最优路径。

3 层 Agent 记忆作用域：

• Project Scope：仅当前项目内的 Agent 可见
• Local Scope：当前机器上的 Agent 共享
• User Scope：跨项目和机器的用户级别记忆

4.3 智能路由

Ruflo 的路由器根据任务复杂度选择最优处理路径：

路由器持续学习历史执行数据，公开报告的准确率为 89%。

4.4 WASM Agent Booster

Agent Booster 使用 WebAssembly 处理简单代码转换，在 CLI 和浏览器中都可用。支持以下转换意图：

Hook 输出中会显示 [AGENT_BOOSTER_AVAILABLE] 标识，表示当前任务可以使用 WASM 跳过 LLM。

4.5 Token 优化器

Token Optimizer 整合了 agentic-flow 的优化策略，可将 token 使用量降低 30-50%：

组合使用时节省效果叠乘。

4.6 联邦通信（Federation）

Federation 让不同机器或组织边界内的 Agent 可以安全协作，核心是零信任模型：远程 Agent 默认不被信任，身份通过 mTLS + ed25519 挑战-响应机制验证。

联邦工作流：

# 初始化本地方并生成密钥对
npx claude-flow@latest federation init

# 加入对方联邦端点
npx claude-flow@latest federation join wss://team-b.example.com:8443

# 发送任务（敏感信息自动剥离）
npx claude-flow@latest federation send --to team-b --type task-request \
  --message "分析账户异常的交易模式"

# 查看对端信任等级和会话健康状态
npx claude-flow@latest federation status

联邦的信任评分公式：0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity。表现良好的 Agent 逐步提升权限；行为异常立即降级，无需人工介入。

14 型 PII 检测管道在数据发出前自动扫描，支持按信任级别配置策略（BLOCK、REDACT、HASH、PASS）。

4.7 Web UI（FLO）

Ruflo 提供了一个开箱即用的 Web 界面 flo.ruv.io，不需要安装，不需要 API Key 即可试用。

主要特性：

• 多模型支持：默认 Qwen 3.6 Max，同时支持 Claude Sonnet 4.6、Claude Haiku 4.5、Gemini 2.5 Pro/Flash、OpenAI，可接入任何 OpenAI 兼容端点（vLLM、Ollama、LM Studio、Together、Groq 等）
• ~210 个工具：5 个服务器组，加上 18 个工具的浏览器内 WASM Gallery，完全离线可用
• MCP 服务器可扩展：通过聊天输入框中的 MCP (n) 按钮可添加自定义 MCP 端点（HTTP、SSE 或 stdio）
• 并行工具执行：一次模型响应可同时触发 4-6+ 个工具，界面以卡片形式展示完成状态
• 持久记忆：背后是 AgentDB + HNSW，说"记住我喜欢 indigo"几周后依然能回想起来
• 自托管：通过 Docker 部署，源码在 ruflo/src/ruvocal/，支持多阶段构建和 Google Cloud Run

4.8 Goal Planner（目标规划）

goal.ruv.io 是 Ruflo 的目标导向行动规划（GOAP）前端，用自然语言描述目标，系统自动：

1. 提取成功标准与约束条件
2. 用 A* 算法在状态空间中搜索最优路径
3. 将路径拆解为带前置条件的 Action 节点
4. 调度 Agent 执行，每个节点映射到具体 MCP 工具调用

特点：

• 实时可视化计划树，可折叠节点显示进度与阻塞分支
• 失败时从当前状态重新规划（A* replay），而非从头重启
• 与 AgentDB 集成，历史计划通过 HNSW 检索，相同领域问题越规划越快

5. 插件系统

Ruflo 的能力通过插件扩展，目前有 32 个原生插件，分为以下几类：

5.1 核心与编排

5.2 记忆与知识

5.3 智能与学习

5.4 安全与合规

6. 实战演示

6.1 场景一：用 Swarm 开发一个 REST API

假设需要开发一个用户认证服务，按以下步骤用 Ruflo 执行：

步骤 1：初始化项目与 Swarm

# 创建项目目录并初始化
mkdir auth-service && cd auth-service
npx ruflo@latest init

# 启动层级 Swarm（architect + coder + tester + reviewer）
npx ruflo@latest swarm init --topology hierarchical --agents architect,coder,tester,reviewer

步骤 2：定义任务

在 Claude Code 中（已安装 ruflo-core 插件）直接说：

帮我开发一个用户认证服务，包含注册、登录、JWT 签发。
用 Express + TypeScript，包含完整单元测试和 API 文档。

Ruflo 会自动：

1. Architect Agent 分析需求，设计目录结构与接口
2. Coder Agent 实现核心逻辑
3. Tester Agent 生成测试用例并执行
4. Reviewer Agent 检查代码质量

Queen Agent 在每个阶段验证输出与目标的一致性，发现漂移立即纠正。

步骤 3：查看执行结果

# 查看 Swarm 状态和 Agent 执行日志
npx ruflo@latest swarm status

# 查看记忆中的执行轨迹
npx ruflo@latest memory search "auth service" --namespace project

6.2 场景二：联邦协作——跨团队共享威胁情报

团队 A（安全团队）和团队 B（开发团队）分别部署了 Ruflo，现在需要共享恶意流量模式但不暴露具体用户数据：

# 团队 A：初始化联邦，生成密钥
npx claude-flow@latest federation init

# 团队 A：加入团队 B 的联邦端点
npx claude-flow@latest federation join wss://dev-team.example.com:8443

# 团队 A：发送分析任务，PII 自动剥离
npx claude-flow@latest federation send \
  --to dev-team \
  --type intelligence-request \
  --message "分析近 7 天异常登录模式，返回特征向量而非原始日志"

# 查看信任评分变化
npx claude-flow@latest federation status

Federation 处理完所有安全检查后，团队 B 的 Agent 收到请求、执行分析、返回结果，整个过程审计日志完整。

6.3 场景三：Web UI 并行工具调用

打开 flo.ruv.io，选择 Qwen 3.6 Max 模型，输入：

帮我分析这个代码仓库的测试覆盖率，并列出需要补充测试的关键模块。
仓库地址：https://github.com/your/repo

Ruflo 会并行调用多个 MCP 工具（代码抓取 → 分析 → 覆盖率计算 → 生成报告），结果以卡片形式在界面中呈现，“Step 1 — 2 tools completed” 指示器让你清楚看到并行执行进度。

7. 配置参考

7.1 环境变量

Ruflo 支持通过环境变量配置核心行为：

# LLM Provider 配置
ANTHROPIC_API_KEY=sk-...           # Anthropic API 密钥
OPENAI_API_KEY=sk-...              # OpenAI API 密钥
GOOGLE_API_KEY=...                 # Google API 密钥

# 向量数据库
AGENTDB_URL=http://localhost:6333  # AgentDB 连接地址

# 联邦安全
FEDERATION_TRUST_LEVEL=strict      # trust | strict | relaxed
PII_DETECTION_MODE=block           # block | redact | hash | pass

# Swarm 配置
DEFAULT_TOPOLOGY=hierarchical
MAX_AGENTS_PER_SWARM=8

# 日志级别
RUFLO_LOG_LEVEL=info              # debug | info | warn | error

7.2 配置文件结构

Ruflo 的配置文件通常位于 ~/.ruflo/config.json 或项目根目录的 ruflo.config.json：

{
  "providers": {
    "anthropic": { "model": "claude-sonnet-4-20250514" },
    "openai": { "model": "gpt-4o" }
  },
  "swarm": {
    "defaultTopology": "hierarchical",
    "maxAgents": 8,
    "consensusAlgorithm": "raft"
  },
  "memory": {
    "backend": "agentdb",
    "hnsw EfSearch": 128
  },
  "federation": {
    "enabled": false,
    "trustLevel": "strict"
  },
  "hooks": {
    "preTask": ["security-scan", "context-inject"],
    "postTask": ["store-memory", "update-reasoningbank"]
  }
}

7.3 推荐的 Anti-Drift 生产配置

// ruflo.config.json — 生产环境推荐
{
  "swarm": {
    "topology": "hierarchical",
    "maxAgents": 8,
    "strategy": "specialized",
    "consensusAlgorithm": "raft",
    "checkpointInterval": 5,        // 每 5 个任务检查点一次
    "maxTaskDuration": 300          // 超过 5 分钟的任务强制评审
  },
  "hooks": {
    "postTask": [
      "validate-output-consistency",  // 验证输出与目标的一致性
      "store-memory",
      "update-telemetry"
    ],
    "preCommand": [
      "security-scan",
      "pii-detection"
    ]
  },
  "routing": {
    "strategy": "q-learning",
    "fallbackModel": "haiku",
    "complexityThreshold": 0.7      // 复杂度 > 0.7 才动用 Opus+Swarm
  }
}

8. 开发扩展

8.1 创建自定义插件

Ruflo 提供 ruflo-plugin-creator 插件用于脚手架生成：

# 安装插件创建器
npx ruflo@latest plugin install ruflo-plugin-creator@ruflo

# 创建新插件
npx ruflo@latest plugin create my-custom-plugin

# 插件目录结构
my-custom-plugin/
├── src/
│   ├── index.ts           # 入口文件
│   ├── hooks/             # 自定义 Hooks
│   ├── agents/            # 自定义 Agents
│   └── providers/         # 自定义 LLM Provider
├── tests/
├── package.json
└── README.md

8.2 自定义 Hook 示例

Hook 在关键节点触发自定义逻辑。创建一个在每次任务完成后保存上下文的 Hook：

// src/hooks/save-context.ts
import { Hook, HookContext } from '@ruflo/core';

export const saveContextHook: Hook = {
  name: 'save-context',
  trigger: 'post-task',
  async execute(ctx: HookContext) {
    const { task, result, agentId } = ctx;
    // 将任务结果存入记忆
    await ctx.memory.store({
      type: 'task-outcome',
      task: task.description,
      outcome: result.success ? 'success' : 'failure',
      agentId,
      timestamp: Date.now()
    });
    return ctx;
  }
};

8.3 自定义 Agent 示例

// src/agents/security-scanner.ts
import { Agent, AgentConfig } from '@ruflo/core';

export const securityScannerAgent: Agent = {
  name: 'security-scanner',
  role: 'security',
  capabilities: ['static-analysis', 'cve-scan', 'dependency-audit'],
  
  async execute(task: Task, ctx: AgentContext) {
    // 1. 静态分析源码
    const issues = await ctx.tools.run('semgrep', { target: task.filePath });
    // 2. CVE 扫描依赖
    const cvss = await ctx.tools.run('npm-audit', { format: 'json' });
    // 3. 汇总报告
    return ctx.composeReport([issues, cvss]);
  }
};

8.4 接入自定义 MCP 服务器

通过 Web UI 的 MCP 按钮添加任意 MCP 端点（HTTP、SSE 或 stdio）：

1. 点击聊天输入框左侧的 MCP (n) 按钮
2. 选择 Add Server
3. 粘贴 MCP 端点 URL（例如 http://localhost:3000）
4. 自定义工具自动加入并行执行流程

9. 从入门到精通的学习路径

10. 常见问题

Q：Ruflo 和 Claude Code 是什么关系？

Ruflo 构建在 Claude Code 之上，提供多 Agent 编排层。Claude Code 处理单次对话交互，Ruflo 负责多 Agent 协调、记忆持久化和学习。不安装任何插件的情况下也可以通过 CLI 使用 Ruflo，但作为 Claude Code 插件集成体验最完整。

Q：需要自己管理 LLM API 费用吗？

是的。Ruflo 本身免费（MIT 许可证），但调用 Anthropic、OpenAI 等模型的费用由用户自行承担。Ruflo 的智能路由可以帮助降低用量（简单任务用 WASM 免费处理），但 API 调用费用不在控制范围内。

Q：Federation 的安全边界是什么？

Federation 采用零信任模型：远程 Agent 默认不被信任。身份通过 mTLS + ed25519 验证，所有出站数据经过 14 型 PII 检测管道。拜占庭容错一致性算法确保最多 (n-1)/3 个恶意节点无法破坏整体决策。敏感数据可在配置中选择 BLOCK、REDACT 或 HASH 策略。

Q：可以在离线环境使用吗？

可以。Ruflo 支持本地模型（通过 ruflo-ruvllm 插件接入 Ollama），AgentDB 和大部分 Worker 也可离线运行。Web UI 的 WASM Gallery 完全在浏览器内运行，不需要网络。唯一需要网络的功能是调用云端 LLM API。

Q：如何排查安装或运行问题？

# 运行诊断检查
ruflo doctor

# 查看详细日志
RUFLO_LOG_LEVEL=debug ruflo <command>

# 检查 MCP 工具列表
claude mcp list

# 查看 Swarm 状态
ruflo swarm status

Q：最多可以同时运行多少个 Agent？

技术上没有硬性限制，但推荐每个 Swarm 最多 8 个 Agent 以防止协调开销和目标漂移。可以启动多个 Swarm 覆盖不同的任务域。

延伸资源

• GitHub 仓库：https://github.com/ruvnet/ruflo
• 用户指南：docs/USERGUIDE.md
• Web UI（免安装试用）：https://flo.ruv.io/
• Goal Planner：https://goal.ruv.io/
• 插件市场：https://ruvnet.github.io/ruflo
• 社区 Discord：https://discord.com/invite/dfxmpwkG2D