RuFlo - 完整学习教程

教程级别： 从零到一 预计学习时间： 8-10 小时 前置知识： Claude Code 使用经验、命令行操作、TypeScript/JavaScript 基础、Anthropic API Key

环境搭建指南

系统要求

• 操作系统：macOS、Linux 或 Windows（WSL）
• 运行时/依赖版本：Node.js >= 18（推荐 LTS 版本）、npm 或 npx
• API Key：Anthropic API Key（必需），可选 OpenAI/Google API Key（多 LLM 场景）

安装步骤

# 方式一：一键安装脚本（推荐）
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/claude-flow@main/scripts/install.sh | bash

# 方式二：通过 npx 初始化（无需全局安装）
npx ruflo@latest init --wizard

# 方式三：添加 MCP 到 Claude Code
claude mcp add ruflo -- npx -y ruflo@latest mcp start

# 设置 API Key
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# 可选：多 LLM 支持
export OPENAI_API_KEY=sk-your-openai-key
export GOOGLE_API_KEY=your-google-key

验证安装

# 检查版本
npx ruflo@latest --version

# 查看帮助
npx ruflo@latest --help

预期输出：

RuFlo v3.5.x - The leading agent orchestration platform for Claude

第一部分：入门篇

1.1 理解 RuFlo 的核心概念

概念讲解：

RuFlo 的核心思想是将 Claude Code 从单 Agent 工作模式转变为多 Agent 协作平台。理解以下关键概念是使用 RuFlo 的基础：

• Swarm（群体）：一组协作的 Agent 集合，通过特定拓扑结构协调工作。
• Agent（代理）：执行具体任务的 AI 实体，每个 Agent 有特定的角色和能力（如编码、测试、审查）。
• Topology（拓扑）：Agent 之间的通信方式（Hierarchical、Mesh、Ring、Star）。
• Queen（蜂后）：在 Hierarchical 拓扑中，负责协调和分配任务的中心 Agent。
• Worker（工蜂）：在 Hierarchical 拓扑中，执行具体任务的专业化 Agent。

代码示例：

# 初始化一个 Hierarchical Swarm
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 5,
  strategy: "specialized"
})

# 生成 Agent
mcp__ruv-swarm__agent_spawn({ type: "coder", name: "feature-coder" })
mcp__ruv-swarm__agent_spawn({ type: "tester", name: "test-agent" })
mcp__ruv-swarm__agent_spawn({ type: "reviewer", name: "code-reviewer" })

# 查看状态
mcp__ruv-swarm__swarm_status()

执行结果：

Swarm initialized with topology: hierarchical
Max agents: 5, Strategy: specialized

Agent spawned: feature-coder (type: coder, status: idle)
Agent spawned: test-agent (type: tester, status: idle)
Agent spawned: code-reviewer (type: reviewer, status: idle)

Swarm Status:
  Agents: 3/5 active
  Topology: hierarchical
  Queen: auto (Strategic)

练习题： 1. 创建一个 Mesh 拓扑的 Swarm，观察与 Hierarchical 的区别。 2. 尝试生成所有 8 种 Worker 类型的 Agent（Researcher、Coder、Analyst、Tester、Architect、Reviewer、Optimizer、Documenter）。

1.2 基本任务执行

概念讲解：

在 1.1 中我们创建了 Swarm 并生成了 Agent。现在学习如何让 Agent 执行任务。RuFlo 支持通过 CLI 和 MCP 两种方式提交任务。

代码示例：

# 方式一：通过 CLI 直接执行任务
npx ruflo@latest --agent coder --task "实现一个简单的 Express.js REST API，包含用户 CRUD 操作"

# 方式二：通过 SPARC 模式执行（系统化开发流程）
npx claude-flow sparc run "实现用户认证模块"

# 方式三：通过 MCP 工具提交任务
mcp__claude-flow__task_orchestrate({
  task: "为现有项目添加单元测试",
  mode: "swarm",
  topology: "mesh",
  agents: ["coder", "tester"]
})

执行结果：

Task submitted: "实现一个简单的 Express.js REST API"
Agent: coder (feature-coder)
Status: running...

Phase 1: Analyzing requirements...
Phase 2: Generating code structure...
Phase 3: Implementing CRUD operations...
Phase 4: Adding error handling...

Task completed successfully.
Files created:
  - src/routes/users.ts
  - src/controllers/userController.ts
  - src/models/user.ts
  - src/middleware/auth.ts

练习题： 1. 使用不同类型的 Agent（coder vs architect）执行同一任务，对比输出差异。 2. 使用 --monitor 标志实时观察任务执行过程。

1.3 选择合适的 Swarm 拓扑

概念讲解：

在 1.2 中我们使用了默认的拓扑执行任务。现在深入学习 4 种拓扑的适用场景和选择策略。

代码示例：

# 场景 1：大型功能开发 — 使用 Hierarchical
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})
# Queen 自动选择 Strategic 类型，协调多个 Worker

# 场景 2：并行代码生成 — 使用 Mesh
mcp__ruv-swarm__swarm_init({
  topology: "mesh",
  maxAgents: 4,
  strategy: "balanced"
})
# 4 个 Coder Agent 并行生成不同模块

# 场景 3：代码审查流水线 — 使用 Ring
# Coder → Tester → Reviewer → Optimizer → Documenter
mcp__ruv-swarm__swarm_init({
  topology: "ring",
  maxAgents: 5,
  strategy: "sequential"
})

练习题： 1. 分别使用 Hierarchical 和 Mesh 拓扑完成同一个任务（如"创建一个 CLI 工具"），对比执行时间和输出质量。 2. 设计一个适合 Ring 拓扑的多阶段任务场景。

第二部分：进阶篇

2.1 SPARC 开发方法论

概念讲解：

SPARC 是 RuFlo 内置的系统化开发方法论，将开发过程分解为 5 个阶段：

1. Specification（规格）：定义需求和约束条件
2. Pseudocode（伪代码）：设计算法和逻辑
3. Architecture（架构）：设计系统结构和接口
4. Refinement（精炼）：TDD 驱动的迭代实现
5. Completion（完成）：集成、部署、文档

SPARC 提供 17 种开发模式，每种模式针对不同的工作流。

代码示例：

# TDD 模式 — 测试驱动开发
npx claude-flow sparc tdd "实现一个支持增删改查的 Todo List 服务"

# Orchestrator 模式 — 多 Agent 编排
npx claude-flow sparc orchestrator "设计和实现一个完整的电商后端 API"

# Code Review 模式
npx claude-flow sparc reviewer "审查 src/auth 模块的安全性和代码质量"

# 通过 MCP 执行 SPARC 模式
mcp__claude-flow__sparc_mode({
  mode: "coder",
  task_description: "实现 OAuth2 认证流程",
  options: {
    parallel: true,
    monitor: true,
    memoryNamespace: "auth-patterns"
  }
})

注意事项： - SPARC 模式需要在 Claude Code 环境中使用，MCP 工具需要在 Claude Code 中配置 RuFlo MCP Server。 - 不同模式的执行时间和 Token 消耗差异很大，Orchestrator 模式最耗时。 - 建议先用简单模式（coder、reviewer）入门，再尝试复杂模式（orchestrator、swarm-coordinator）。

练习题： 1. 使用 TDD 模式开发一个简单的排序算法库，体验"测试先行"的工作流。 2. 对比 coder 模式和 orchestrator 模式在同一任务上的表现差异。

2.2 记忆系统与知识共享

概念讲解：

RuFlo 的记忆系统是 Agent 之间共享知识和上下文的关键机制。三层记忆架构（工作记忆、情景记忆、语义记忆）使 Agent 可以： - 在任务之间传递上下文 - 积累长期知识 - 避免重复工作

代码示例：

# 存储知识到记忆系统
mcp__claude-flow__memory_usage({
  action: "store",
  namespace: "project-patterns",
  key: "auth-strategy",
  value: "项目使用 JWT + Refresh Token 双令牌认证方案"
})

# 搜索记忆
mcp__claude-flow__memory_usage({
  action: "search",
  namespace: "patterns",
  query: "authentication patterns"
})

# 跨 Agent 共享知识
mcp__claude-flow__memory_usage({
  action: "share",
  source_agent: "architect",
  target_agent: "coder",
  namespace: "design-decisions"
})

注意事项： - 工作记忆有 1MB 限制，不要存储过大的数据。 - 记忆命名空间（namespace）建议按项目或功能模块组织，便于管理。 - 记忆数据存储在本地（AgentDB），不发送到外部服务。

练习题： 1. 在一个 Agent 中存储项目架构决策，在另一个 Agent 中检索并基于该决策执行任务。 2. 设计一个多命名空间的记忆结构，用于管理不同类型的知识（架构、模式、最佳实践）。

第三部分：高级篇

3.1 多 LLM 路由与成本优化

概念讲解：

RuFlo 的三层模型路由（ADR-026）根据任务复杂度自动选择最合适的模型：

• Layer 1（Agent Booster/WASM）：简单转换（var-to-const、add-types），<1ms，$0
• Layer 2（轻量模型如 Haiku）：简单任务，~500ms，低成本
• Layer 3（重量模型如 Sonnet/Opus）：复杂推理，2-5s，较高成本

# 配置多 LLM 路由
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

# RuFlo 自动选择最优路由
# 简单任务 → Layer 1/2，复杂任务 → Layer 3

注意事项： - 三层路由的成本节省声明（75%）来自项目自报，建议自行测试验证。 - Agent Booster（WASM）层需要在本地编译 WASM 模块，初次使用可能需要额外设置。

3.2 性能优化

• 并发控制：调整 maxAgents 参数控制并发 Agent 数量，避免 API 速率限制。
• 工具组配置：通过 CLAUDE_FLOW_TOOL_GROUPS 环境变量只加载需要的工具组，减少不必要的开销。

# 只加载开发相关工具
export CLAUDE_FLOW_TOOL_GROUPS=implement,test,fix,memory

# 或使用预设模式
export CLAUDE_FLOW_TOOL_MODE=develop

3.3 最佳实践

1. 从简单拓扑开始：先用 Mesh 拓扑执行简单任务，熟悉后再尝试 Hierarchical。
2. 锁定版本使用：指定固定版本（如 ruflo@3.5.80），避免自动升级导致的兼容性问题。
3. 合理设置 Agent 数量：通常 3-5 个 Agent 即可满足大部分任务需求，过多 Agent 反而增加协调开销。
4. 善用记忆系统：将项目架构决策、编码规范等存储在记忆中，让所有 Agent 共享同一知识库。
5. 关注 Token 消耗：多 Agent 场景下 Token 消耗可能快速增长，建议设置预算上限并监控。

第四部分：实战项目

项目需求

构建一个多 Agent 协作的 REST API 开发流水线，包含： - Architect Agent 设计 API 架构 - Coder Agent 实现代码 - Tester Agent 编写测试 - Reviewer Agent 审查质量

本项目综合运用：Swarm 拓扑（1.3）、任务执行（1.2）、SPARC 方法论（2.1）、记忆系统（2.2）共 4 个知识点。

项目设计

todo-api-project/
├── src/
│   ├── routes/
│   ├── controllers/
│   ├── models/
│   ├── middleware/
│   └── index.ts
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
│   └── api-design.md
└── package.json

完整实现步骤

# Step 1: 初始化 Hierarchical Swarm
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 5,
  strategy: "specialized"
})

# Step 2: 生成专业化 Agent
mcp__ruv-swarm__agent_spawn({ type: "architect", name: "api-architect" })
mcp__ruv-swarm__agent_spawn({ type: "coder", name: "api-coder" })
mcp__ruv-swarm__agent_spawn({ type: "tester", name: "test-writer" })
mcp__ruv-swarm__agent_spawn({ type: "reviewer", name: "code-reviewer" })

# Step 3: Architect 设计 API 架构
npx claude-flow sparc architect "设计一个 Todo List REST API，支持用户认证、CRUD 操作、分页查询"

# Step 4: 存储架构决策到记忆
mcp__claude-flow__memory_usage({
  action: "store",
  namespace: "todo-api",
  key: "architecture",
  value: "Express.js + JWT auth + SQLite storage + RESTful endpoints"
})

# Step 5: Coder 实现代码
npx claude-flow sparc coder "基于架构设计实现 Todo List REST API 的完整代码"

# Step 6: Tester 编写测试
npx claude-flow sparc tdd "为 Todo List API 编写完整的单元测试和集成测试"

# Step 7: Reviewer 审查质量
npx claude-flow sparc reviewer "审查 Todo List API 的代码质量、安全性和性能"

# Step 8: 查看最终状态
mcp__ruv-swarm__swarm_status()

代码解析

• 知识点 1（Swarm 拓扑 1.3）：使用 Hierarchical 拓扑，Queen（Strategic）协调 4 个 Worker Agent 的任务分配和执行顺序。
• 知识点 2（任务执行 1.2）：通过 SPARC 模式将不同阶段的任务分配给对应类型的 Agent。
• 知识点 3（SPARC 方法论 2.1）：architect → coder → tester → reviewer 的工作流遵循 SPARC 的 Architecture → Refinement → Review 阶段。
• 知识点 4（记忆系统 2.2）：Architect 的设计决策存储在记忆中，供后续 Coder 和 Reviewer 参考，保持一致性。

扩展挑战

1. 添加 Optimizer Agent，在 Reviewer 之后对 API 进行性能优化（添加缓存、优化查询）。
2. 使用 Mesh 拓扑让 Coder 和 Tester 并行工作（Coder 写代码的同时 Tester 准备测试框架）。
3. 实现完整的自学习循环：将成功的开发模式存储到长期记忆中，下次类似项目时自动复用。

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

1. 使用 status --watch 实时监控：运行 npx claude-flow@v3alpha status --watch 实时查看所有 Agent 的状态、任务进度和 Token 消耗，是排查问题的首选方式。

2. 查看记忆日志：检查 AgentDB 中的记忆条目，确认 Agent 之间是否正确共享了知识和上下文。使用 memory_usage({ action: "search", namespace: "debug" }) 查询。

3. 逐步缩小范围：当多 Agent 任务失败时，先用单个 Agent（Mesh 拓扑，1 个 Agent）测试同一任务，排除 Agent 协调问题。逐步增加 Agent 数量定位问题。

第六部分：学习路线推荐

官方文档推荐阅读顺序

1. GitHub README - 快速了解项目概况和安装方式（https://github.com/ruvnet/ruflo）
2. Quick Start - 跑通第一个 Swarm 示例
3. Swarm 拓扑 - 理解 4 种拓扑的区别和选择
4. SPARC 方法论 - 掌握系统化开发流程
5. MCP 工具列表 - 了解 259 个工具的用途和使用方法
6. RuVector 智能层 - 深入理解自学习系统
7. AIDefence 安全 - 了解企业级安全特性
8. ADR 架构决策 - 理解设计决策背后的原因

推荐进阶资源

• RuFlo GitHub 仓库 — 源代码和 README 是最权威的参考资料
• Ultimate Guide to Ruflo v3（YouTube） — 视频教程
• Reddit r/ClaudeCode — 社区讨论和真实使用反馈