RuFlo / Claude Flow Plugin 企业级 AI Agent 编排插件完全指南：Swarm 群、SPARC 流程、GitHub 自动化与 MCP 集成

在 Claude Code 中把"一个助手"扩展成"一支可编排的 AI 团队"，是本文要解决的问题。.claude-plugin/README.md 描述并定义了仓库内的 claude-flow（claude-flow 2.5.0）插件包：一套面向企业级场景的多 Agent 编排插件，包含 150+ 斜杠命令、74+ 专用 Agent、SPARC 方法论工作流、Swarm 群协调、GitHub 自动化与神经训练能力。读完本文，你将掌握该插件的完整目录结构、安装方式、命令与 Agent 体系、三大 MCP 服务器的接入配置，以及 hooks 事件钩子与高级拓扑参数的具体写法，并能在当前仓库中逐一找到对应的真实文件与源码佐证。

插件定位与核心能力总览

插件描述将其定位为 "Enterprise AI agent orchestration plugin"，即面向企业级使用场景的 Claude Code 多 Agent 编排层。仓库内的插件清单 plugin.json 给出了硬性版本约束：

• name：claude-flow，version：2.5.0
• engines：claudeCode >= 2.0.0、node >= 20.0.0
• license：MIT
• mcpServers：内联声明三台 MCP 服务器（详见下文"MCP 集成"一节）

从 README 看，其能力地图可以概括为五条主线：

能力维度	关键数字	说明
Swarm 群协调	4 种拓扑、最多 100 个并发 Agent	分层、网格、环形、星型，支持自动 spawn 与拓扑自优化
SPARC 方法论	18 个专属模式	Spec → Pseudocode → Architecture → Refinement → Code 全生命周期
GitHub 自动化	14+ 工具 / 18 条命令	PR、Issue、Release、多仓库同步
神经训练	27+ 模型、WASM 加速	模式学习与跨会话上下文保留
命令与 Agent	150+ 命令、74+ Agent	覆盖 19+ 命令分类与 20+ Agent 分类

需要提醒的是，README 末尾列出的 84.8% SWE-Bench 解决率、32.3% token 削减、WASM 2.8-4.4x 加速 属于插件文档自述的性能声明；本仓库中并未附带对应的独立复现基准，引用时请将其视为产品宣称指标而非仓库实测结果。

插件的仓库结构与元数据

README 的 Components 一节给出了通用布局；而在本仓库中，插件的真实资产按以下路径组织，可用文件一一对应验证：

.claude-plugin/                 # 插件元数据、分发清单、安装脚本与文档
├── plugin.json                 # 插件清单（name/version/engines/mcpServers）
├── marketplace.json            # ruflo 插件市场分发清单
├── hooks/hooks.json            # 事件钩子配置（PreToolUse/PostToolUse/PreCompact/Stop）
├── scripts/
│   ├── install.sh / uninstall.sh / verify.sh
│   └── ruflo-hook.cjs / ruflo-hook.sh
└── docs/
    ├── QUICKSTART.md / INSTALLATION.md
    ├── PLUGIN_SUMMARY.md / STRUCTURE.md
plugin/                         # 插件功能资产（命令、Agent、钩子、技能）
├── commands/                   # 斜杠命令：coordination/sparc/github/hive-mind/swarm/...
├── agents/                     # 专用 Agent：core/consensus/github/sparc/swarm/...
├── hooks/hooks.json
├── scripts/
└── skills/

仓库内附的文档还包括：快速开始指南、安装指南、插件状态汇总、目录结构说明。

值得注意的是本仓库的双重身份：plugin.json 声明的插件名为 claude-flow（legacy 发布包），而 marketplace.json 则声明了一个名为 ruflo 的 Claude Code 插件市场，收录了 ruflo-core、ruflo-swarm、ruflo-rag-memory、ruflo-intelligence、ruflo-graph-intelligence、ruflo-agntcy、ruflo-arena 等 38+ 个子插件，覆盖记忆、测试、安全、浏览器自动化、联邦、工作流等领域。README 中大量能力（如 swarm、SPARC、memory）在仓库内都有对应的实现沉淀于 plugin/commands/ 与 plugin/agents/ 目录。

74+ 专用 Agent：五大类角色详解

README 将 Agent 归纳为若干类别，以下为官方清单中给出的核心角色（对应真实文件见 plugin/agents 下的分类目录，例如 core 目录 中实际存放着 coder.md、planner.md、researcher.md、reviewer.md、tester.md）：

Core Development（5）

coder（代码实现）、planner（规划与路线图）、researcher（信息收集与分析）、reviewer（代码质量与安全审查）、tester（测试编写）。

Swarm Coordination（5）

hierarchical-coordinator（Queen 主导的命令结构）、mesh-coordinator（对等协调）、adaptive-coordinator（动态拓扑管理）、collective-intelligence-coordinator（分布式决策）、swarm-memory-manager（跨 Agent 记忆协调）。

Consensus & Fault Tolerance（7）

byzantine-coordinator（拜占庭容错）、raft-manager（Raft 共识）、gossip-coordinator（Gossip 共识）、crdt-synchronizer（无冲突数据复制）、quorum-manager（动态法定人数）、security-manager（安全协议）、performance-benchmarker（共识性能测试）。这类"协议级" Agent 说明该插件不止做任务编排，还引入了分布式系统理论中的容错与一致性设计。

GitHub Automation（13）

pr-manager、code-review-swarm（多 Agent 代码评审）、issue-tracker、release-manager、workflow-automation、repo-architect、multi-repo-swarm、sync-coordinator 等。

Specialized Development（8）

backend-dev、mobile-dev（React Native）、ml-developer、cicd-engineer、api-docs（OpenAPI/Swagger）、system-architect、code-analyzer、base-template-generator。

另有 SPARC 方法论专用 Agent（specification/pseudocode/architecture/refinement）与 Hive Mind、Optimization 等类别。在仓库 plugin/agents 下还可见 analysis/、data/、dual-mode/、flow-nexus/、neural/、payments/、sona/、sublinear/、templates/、v3/ 等更多分类，README 所称"74+"即为这些目录的集合。Agent 文件采用 Markdown + YAML frontmatter 编写（详见 PLUGIN_SUMMARY 的格式规范），Claude Code 可据此在合适时机自动委派。

150+ 斜杠命令体系速查

命令按 plugin/commands/ 下的子目录组织（如 coordination 目录包含 swarm-init.md、agent-spawn.md、task-orchestrate.md 等）。README 按 14 个类别的官方分组如下：

类别	数量	代表命令
Coordination	6	coordination-swarm-init、coordination-agent-spawn、coordination-task-orchestrate
SPARC	18	sparc-modes、sparc-coder、sparc-tdd、sparc-architect、sparc-reviewer、sparc-optimizer、sparc-debugger 等
GitHub	18	github-code-review、github-code-review-swarm、github-pr-manager、github-issue-triage、github-release-swarm、github-multi-repo-swarm、github-sync-coordinator 等
Hive Mind	11	hive-mind-init、hive-mind-spawn、hive-mind-consensus、hive-mind-memory、hive-mind-wizard 等
Memory	5	memory-usage、memory-persist、memory-search、memory-neural
Monitoring	5	monitoring-status、monitoring-agent-metrics、monitoring-swarm-monitor、monitoring-real-time-view
Optimization	5	optimization-topology-optimize、optimization-auto-topology、optimization-parallel-execution、optimization-cache-manage
Analysis	5	analysis-performance-report、analysis-bottleneck-detect、analysis-token-usage、analysis-token-efficiency
Automation	6	automation-smart-spawn、automation-self-healing、automation-session-memory
Hooks	7	hooks-setup、hooks-pre-task、hooks-post-task、hooks-pre-edit、hooks-post-edit、hooks-session-end
Swarm	15	swarm-init、swarm-spawn、swarm-status、swarm-monitor、swarm-background、swarm-development、swarm-research
Workflows	5	workflows-create、workflows-execute、workflows-export
Training	5	training-neural-train、training-pattern-learn、training-model-update
Flow Nexus	9	flow-nexus-swarm、flow-nexus-workflow、flow-nexus-sandbox、flow-nexus-login

这些命令并非空壳——它们对应仓库中真实存在的命令文件。以 swarm-init.md 为例，其完整 CLI 参数为：

npx claude-flow swarm init [options]
# -t, --topology <type>   拓扑：mesh | hierarchical | ring | star（默认 hierarchical）
# -m, --max-agents <n>    最大 Agent 数（默认 8）
# -s, --strategy <type>   执行策略：balanced | parallel | sequential（默认 parallel）
#     --auto-spawn        根据任务复杂度自动生成 Agent
#     --memory            开启跨会话记忆持久化
#     --github            开启 GitHub 集成

例如"网格拓扑做研究任务""分层拓扑做开发任务"的两种形态：

npx claude-flow swarm init --topology mesh --max-agents 5 --strategy balanced
npx claude-flow swarm init --topology hierarchical --max-agents 10 --strategy parallel --auto-spawn

快速开始与三种安装方式

插件面向 Claude Code 使用，安装前后都需满足 plugin.json 中的引擎要求（Claude Code >= 2.0.0、Node.js >= 20.0.0），并需具备项目目录读写权限、Git（用于 GitHub 集成功能）。

方式一：市场直装（推荐）

在 Claude Code 会话中执行：

/plugin add ruvnet/claude-flow
/restart

方式二：本地目录安装

将本仓库 clone 到本地后，在仓库根目录的 Claude Code 会话中执行：

/plugin add .
/restart

方式三：npx 一次性初始化

npx claude-flow@alpha init --plugin

该命令会自动：创建 .claude 目录、拷贝全部命令与 Agent、配置 MCP 服务器、设置 hooks。仓库内同时提供了脚本式安装与验证手段：install.sh、uninstall.sh 与 verify.sh（卸载也可在 Claude Code 中执行 /plugin remove claude-flow）。

安装验证

/plugin list        # 确认 claude-flow 处于 active
/coordination-swarm-init   # 冒烟测试

输入 / 即可浏览全部 150+ 命令是否生效。

常用工作流实战

1. 初始化并编排一个 Swarm

/coordination-swarm-init
/coordination-agent-spawn          # 从 74+ Agent 中选择 coder/tester/reviewer/planner 等
/coordination-task-orchestrate "Build a REST API with authentication"

按 README 描述，群体会自动执行：分析需求 → 生成合适的 Agent → 协调并行执行 → 监控进度 → 汇总结果。

2. SPARC 开发流

/sparc-modes specification "User authentication system"   # 规格分析
/sparc-architect                                           # 架构设计
/sparc-tdd "Implement JWT authentication"                  # TDD 实现
/sparc-reviewer                                            # 评审
/sparc-optimizer                                           # 优化

3. GitHub 自动化

/github-repo-analyze          # 仓库分析
/github-pr-manager            # 带自动评审的 PR
/github-code-review-swarm     # 多 Agent 评审
/github-multi-repo-swarm      # 跨仓库发布协调

4. Hive Mind 群智协调

/hive-mind-init
/hive-mind-spawn              # 带共识机制 spawn
/hive-mind-consensus          # 共识状态检查
/hive-mind-memory             # 查看共享记忆

5. 监控与复盘类命令

/monitoring-status              # 系统概览
/monitoring-swarm-monitor       # 实时群视图
/analysis-performance-report    # 性能报告
/analysis-bottleneck-detect     # 瓶颈定位
/optimization-auto-topology     # 拓扑自动选择

仓库内的快速开始文档还给出了一个端到端示例（Todo App）：先 swarm-init 初始化 → sparc-modes specification 描述需求（React 前端 + Express 后端）→ sparc-architect 设计 → sparc-tdd 实现 → monitoring-swarm-monitor 观察 → sparc-reviewer / sparc-optimizer 收尾 → analysis-performance-report 出报告。

MCP 集成：三台服务器与配置写法

README 与 plugin.json 一致声明插件会配置三台 MCP 服务器（合计 110+ 工具）。其中 claude-flow 为必需项，其余两台的 optional 标志在 plugin.json 中分别为 true，即缺失时插件可优雅降级。

claude-flow（必需，40+ 工具）

{
  "mcpServers": {
    "claude-flow": {
      "command": "npx",
      "args": ["claude-flow@alpha", "mcp", "start"]
    }
  }
}

职责：Swarm 初始化与管理、Agent 生成与协调、任务编排、记忆管理、神经训练、性能监控。工具命名与命令体系对齐（如 swarm_init、agent_spawn、task_orchestrate、memory_usage、neural_train）。

ruv-swarm（可选，增强协调）

{
  "mcpServers": {
    "ruv-swarm": {
      "command": "npx",
      "args": ["ruv-swarm", "mcp", "start"]
    }
  }
}

职责：WASM 加速（文档声称 2.8-4.4x 速度提升）、SIMD 优化、高级拓扑管理、拜占庭容错。

flow-nexus（可选，需鉴权，70+ 工具）

{
  "mcpServers": {
    "flow-nexus": {
      "command": "npx",
      "args": ["flow-nexus@latest", "mcp", "start"]
    }
  }
}

职责：E2B 沙箱执行、分布式神经训练、事件驱动工作流、应用市场、实时协作。plugin.json 中明确标注 "requires authentication"。

命令行接入方式

claude mcp add claude-flow npx claude-flow@alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start            # 可选
claude mcp add flow-nexus npx flow-nexus@latest mcp start   # 可选，需鉴权

验证时可在 Claude Code 中直接询问 "List available MCP tools for claude-flow"，期望看到 40+ 工具被列出。若 MCP 未生效，可用 npx claude-flow@alpha --version 排查包是否可用。

高级配置：拓扑、神经训练与事件钩子

自定义 Swarm 拓扑

{
  "swarmCoordination": {
    "topology": "mesh",
    "maxAgents": 50,
    "autoSpawn": true,
    "autoOptimize": true
  }
}

字段含义：topology 决定协调结构（mesh/hierarchical/ring/star），maxAgents 为并发上限，autoSpawn 是否按任务复杂度自动创建 Agent，autoOptimize 是否动态调整拓扑。该配置与上文 swarm init 的 CLI 参数一一对应。

启用神经训练

{
  "neuralTraining": {
    "enabled": true,
    "wasmAcceleration": true,
    "simdOptimization": true
  }
}

事件钩子配置

README 的通用示例如下：

{
  "hooks": {
    "PreToolUse": { "enabled": true },
    "PostToolUse": { "enabled": true },
    "SessionEnd": { "enabled": true }
  }
}

而仓库内真实的钩子实现位于 hooks/hooks.json，其结构与通用示例不同：它是一个面向 Bash/编辑类工具事件的分发清单，所有事件都转发给 scripts/ruflo-hook.sh（经由 ${CLAUDE_PLUGIN_ROOT} 定位，命令尾部的 || true 保证 CLI 失败不会阻断 Claude Code 的回合）。真实清单覆盖四个事件：

• PreToolUse：Bash 匹配 modify-bash；Write|Edit|MultiEdit 匹配 modify-file；
• PostToolUse：通过 jq + xargs 提取 Bash 命令/文件路径，分别触发 post-command --track-metrics true --store-results true 与 post-edit --format true --update-memory true；
• PreCompact：manual / auto 两种压缩路径都会注入提醒（Agent 清单、并发执行规则等）；
• Stop：触发 session-end --generate-summary true --persist-state true --export-metrics true。

需要特别说明的边界（来自 hooks.json 自身的描述）：该清单 仅面向 POSIX（macOS/Linux），使用 /bin/bash、jq/xargs/tr 管道；在原生 Windows 上不可用，其被标记为 _legacy_unaudited_shim 且未来需要基于 Node 的跨平台重写。若你的团队运行在 Windows 环境，应自行评估后选择等价钩子方案，而非直接沿用本文件。

验证、排错与卸载

症状	排查手段
命令不出现	bash scripts/verify.sh；检查 plugin/commands/ 目录是否完整；/restart
MCP 不工作	查看 ~/.claude/settings.json；npx claude-flow@alpha --version；重装全局包
Agent 不自动 spawn	确认 plugin/agents/ 下的 .md 文件与 YAML frontmatter 格式正确；检查目录权限；/restart
安装失败	改用本地安装：clone 后进入仓库根目录执行 /plugin add .

更新插件：/plugin update claude-flow（本地 clone 场景下也可直接 git pull 更新仓库后重启）。卸载：/plugin remove claude-flow，将移除全部命令、Agent 与 hooks。

延伸阅读

本文所依据的完整插件文档就在仓库内，可继续深入：

• 插件主文档（本文源头）
• 快速开始指南：5 分钟上手 + Todo App 完整演练
• 安装指南：三种安装方式与管理命令
• 插件状态汇总：目录/命令/Agent 数量总表
• 目录结构说明：官方插件格式规范说明
• 插件清单 与 插件市场清单：版本、引擎与 MCP 声明的权威来源
• 命令目录 与 Agent 目录：150+ 命令与 74+ Agent 的实际落地文件

这套插件体系的核心价值在于把"命令 + Agent + 协议 + 钩子 + MCP"组合成一条可演进的 Agent 工程生产线——它既定义了 swarms 如何协同、SPARC 如何分阶段交付，也给出了 GitHub 自动化、记忆持久化乃至共识容错等企业级诉求的具体落点。对于希望基于 Claude Code 搭建多 Agent 开发团队的工程人员，以上即是从"知道有哪些能力"到"在仓库中找到每项能力对应实现"的完整索引。