ruflo/Claude Flow 插件安装指南：在 Claude Code 中一键启用 150+ 命令、74+ Agent 与 MCP 集群编排

ruflo（Claude Flow，v2.5.0）是一个面向 Claude Code 的企业级 AI Agent 编排插件，本指南完整讲解其安装、验证、升级与卸载流程。无论你是想通过 /plugin add 一行命令从远端安装，还是克隆本仓库后本地安装，都可以在本篇文章中找到对应的操作步骤、MCP 服务器配置方法以及常见故障排查方案，读完即可在 Claude Code 中启动 swarm 协作、SPARC 开发流程与 GitHub 自动化。

环境前提（Prerequisites）

本仓库 .claude-plugin/plugin.json 中声明了运行该插件所需的最低环境，安装前请先核对：

依赖	最低要求	说明
Claude Code CLI	>= 2.0.0	插件系统的宿主环境，安装与加载均通过 /plugin 命令完成
Node.js	>= 20.0.0	运行 MCP 服务器（npx 启动 claude-flow、ruv-swarm、flow-nexus）所必需
Git	建议安装	GitHub 集成类命令（PR 管理、代码评审、发布协调）依赖 Git 工作区

在仓库自带的一键脚本 scripts/install.sh 中同样包含这三项前置检查：脚本会检测 claude 命令是否存在、通过 node -v 校验大版本号是否大于等于 20，并检查 Git 是否可用；若缺少 Claude Code CLI，脚本会直接报错退出。

快速安装

方法一：从远端仓库安装（推荐）

在 Claude Code 交互窗口中直接执行：

/plugin add ruvnet/claude-flow

插件系统会自动完成如下工作：

• 克隆远端插件仓库；
• 安装 150+ 条斜杠命令（slash commands）；
• 安装 74+ 个专用 Agent；
• 配置 MCP 服务器；
• 注册 hooks 事件处理器。

方法二：从本地目录安装

如果你已经克隆了本仓库，可采用本地安装方式：

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/cl/ruflo
cd ruflo

# 在 Claude Code 中安装本地插件
/plugin add .

对应当前仓库，插件本体即位于仓库内的 .claude-plugin 目录下，其清单文件为 .claude-plugin/plugin.json，内部声明了插件名 claude-flow、版本号 2.5.0、MIT 协议、claudeCode >= 2.0.0 / node >= 20.0.0 引擎要求，以及三个 MCP 服务器的启动配置；命令与 Agent 的实体文件则组织在仓库根目录的 plugin 目录下（commands 与 agents 均为指向 .claude/commands、.claude/agents 的软链接），hooks 配置见 plugin/hooks/hooks.json。

第 2 步：重启 Claude Code

安装完成后需要重启以激活插件：

/restart

第 3 步：验证安装

/plugin list

在激活插件列表中查找 claude-flow。随后可尝试执行一条命令验证可用性：

/coordination-swarm-init

也可以直接输入 / 浏览全部 150+ 条可用命令。

安装后会得到什么（What Gets Installed）

150+ 条斜杠命令

命令按功能类别组织，覆盖 Agent 协调、开发方法论、代码托管平台集成与性能优化等完整工作流：

类别	数量	代表命令
Coordination（协调）	6	swarm-init、agent-spawn、task-orchestrate
SPARC（方法学）	18	coder、tdd、architect、reviewer、optimizer
GitHub	18	pr-manager、code-review-swarm、release-manager
Hive Mind（蜂群心智）	11	init、spawn、consensus、memory
Memory（记忆）	5	usage、persist、search
Monitoring（监控）	5	status、agents、metrics
Optimization（优化）	5	topology-optimize、parallel-execution
Analysis（分析）	5	performance-report、bottleneck-detect
Automation（自动化）	6	smart-spawn、auto-agent
Swarm（集群管理）	15	init、spawn、status、monitor
Workflows（工作流）	5	create、execute、export
Training（训练）	5	neural-train、pattern-learn
Flow Nexus	9	swarm、workflow、sandbox

以仓库内真实命令为例，plugin/commands/coordination/swarm-init.md 定义的 /coordination-swarm-init 支持 --topology/-t（mesh、hierarchical、ring、star，默认 hierarchical）、--max-agents/-m（默认 8）、--strategy/-s（balanced、parallel、sequential）、--auto-spawn、--memory、--github 等选项，可见每条命令都具备独立的参数解析能力。

74+ 个专用 Agent

Agent 可用于委派任务，按领域划分：

• 核心开发（5）：coder、planner、researcher、reviewer、tester；
• 集群协调（5）：hierarchical、mesh、adaptive 三类协调器；
• 共识协议（7）：Byzantine、Raft、Gossip 等；
• GitHub（13）：PR 管理器、代码评审、发布；
• 专用开发（8）：backend、mobile、ML、CI/CD 等。

对应仓库实现位于 plugin/agents/（symlink 至 .claude/agents），例如 plugin/agents/core/coder.md、plugin/agents/core/reviewer.md 等，每个 Agent 均为带 YAML frontmatter 的 Markdown 文件，供主 Agent 在合适时机自动委派。

MCP 集成

插件声明了 3 个 MCP 服务器、合计 110+ 个工具（见 .claude-plugin/plugin.json 中的 mcpServers 字段）：

MCP 服务器	工具量	说明	是否可选
claude-flow	40+	核心编排：swarm 协调、Agent 管理、任务编排	必装
ruv-swarm	—	增强协调能力（WASM 加速）	可选
flow-nexus	70+	云平台功能（需要鉴权）	可选

MCP 服务器配置（可选）

插件会声明 MCP 服务器，但你仍需安装对应的 npm 包才能实际使用工具：

# 核心 MCP（推荐）
npm install -g claude-flow@alpha

# 可选：增强版集群协调
npm install -g ruv-swarm

# 可选：云功能（需要鉴权）
npm install -g flow-nexus@latest

安装插件时 MCP 服务器即会被自动写入配置。其底层 JSON 结构如下（与插件清单中保持一致）：

{
  "mcpServers": {
    "claude-flow": {
      "command": "npx",
      "args": ["claude-flow@alpha", "mcp", "start"],
      "description": "Core Claude Flow MCP server with 40+ orchestration tools",
      "optional": false
    },
    "ruv-swarm": {
      "command": "npx",
      "args": ["ruv-swarm", "mcp", "start"],
      "description": "Enhanced swarm coordination with WASM acceleration",
      "optional": true
    },
    "flow-nexus": {
      "command": "npx",
      "args": ["flow-nexus@latest", "mcp", "start"],
      "description": "Cloud-based orchestration platform with 70+ tools (requires authentication)",
      "optional": true
    }
  }
}

需要留意的是，本仓库的 scripts/install.sh 在写入 ~/.claude/settings.json 时会先判断文件是否存在：若不存在则自动创建并写入 claude-flow MCP 服务器；若已存在，则只打印需要手工追加的三个服务器配置片段，避免覆盖用户已有设置。

如果希望脱离插件走 Claude Code 原生命令手动添加服务器，可以逐个执行：

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   # 可选，需鉴权

安装验证（Verification）

检查插件状态

在 Claude Code 中执行：

/plugin list

确认列表中存在 claude-flow 且状态为 active。

测试命令

输入 / 后查找以下前缀开头的命令：

• coordination-（集群协调）
• sparc-（SPARC 方法学）
• github-（GitHub 集成）
• hive-mind-（蜂群心智）

测试 Agent

Agent 无需手动调用，Claude Code 会在需要时自动委派给合适的专用 Agent。

使用脚本化验证

仓库额外提供了自动化的验证脚本 scripts/verify.sh，其检查项与上面的手工步骤一一对应，适合 CI 或批量环境使用：

1. Claude Code CLI 是否已安装（缺失记为 error）；
2. ~/.claude/commands 与 ~/.claude/agents 目录是否存在并统计命令/Agent 数量；
3. ~/.claude/settings.json 是否存在，且其中是否包含 claude-flow 字样（缺少 MCP 配置记为 warning）；
4. 依次探测 claude-flow@alpha、ruv-swarm、flow-nexus 三个 npm 包是否可通过 npx 运行，只有核心包缺失才算 warning，可选包缺失仅提示。

脚本最终按错误数给出结论：error 为 0 且 warning 为 0 时提示插件完全就绪；仅有 warning 时提示部分功能受限；存在 error 时返回退出码 1。

插件生命周期管理（Managing the Plugin）

查看已安装插件

/plugin list

升级插件

/plugin update claude-flow

或者从远端拉取最新代码后重装：

cd /path/to/claude-flow
git pull

移除插件

/plugin remove claude-flow

该命令会移除全部命令、Agent 与 hooks。

手工安装脚本的补充说明

仓库脚本 scripts/install.sh 支持 4 种安装粒度选择，交互式提示 Select installation type (1-4) [1]：

1. 完整安装（commands + agents + MCP servers）；
2. 仅安装 commands；
3. 仅安装 agents；
4. 仅配置 MCP servers。

安装目标目录均为 ~/.claude/ 下的 commands/、agents/，脚本会以 cp -r 拷贝并以 find -name "*.md" 统计实际安装数量，最后打印引导信息（重启、验证、试运行 /coordination-swarm-init）。

常见问题排查（Troubleshooting）

插件找不到（Plugin Not Found）

# 确认插件是否已安装
/plugin list

# 重新安装
/plugin add ruvnet/claude-flow

命令不显示（Commands Not Showing）

# 确认插件已安装
/plugin list

# 检查目录结构是否完整
ls -la .claude-plugin/
ls -la commands/
ls -la agents/

# 重启 Claude Code
/restart

安装失败（Installation Fails）

# 退回本地安装方式
git clone https://github.com/ruvnet/claude-flow.git
cd claude-flow
/plugin add .

对应到本仓库，即本地目录安装（上文方法二），或直接执行 scripts/install.sh 走手工拷贝路径。

获取帮助（Getting Help）

• 完整文档：见 .claude-plugin/README.md，内含 Overview、Features、Components、MCP 集成与 150+ 命令清单；
• 5 分钟快速上手：见 .claude-plugin/docs/QUICKSTART.md，含初始化首个 swarm、SPARC TDD 流程与 GitHub 自动化示例；
• 安装与结构对照：见 .claude-plugin/docs/INSTALLATION.md 与 .claude-plugin/docs/STRUCTURE.md；
• 状态概览：见 .claude-plugin/docs/PLUGIN_SUMMARY.md。

卸载插件（Uninstalling）

/plugin remove claude-flow

这会移除全部命令、Agent 与 hooks。仓库另提供 scripts/uninstall.sh 手工卸载脚本：它会按文件名模式清理 ~/.claude/commands/ 下的 *coordination*、*sparc*、*github*、*hive-mind* 以及 ~/.claude/agents/ 下的 *coordinator*、*swarm* 文件，并明确提示 MCP 服务器不会从 settings.json 中自动移除，需要手工编辑文件清理。

插件目录结构（Plugin Structure）

按官方 Claude Code 插件规范，安装完成后插件目录结构如下（本仓库中元数据与文档位于 .claude-plugin，命令/Agent 实体位于 plugin）：

claude-flow/
├── .claude-plugin/          # 插件元数据与文档
│   ├── plugin.json          # 插件清单：名称/版本/引擎要求/MCP 服务器
│   ├── README.md            # 完整文档
│   ├── INSTALLATION.md      # 本文档
│   ├── marketplace.json     # 市场分发元数据
│   └── docs/                # QUICKSTART / STRUCTURE / PLUGIN_SUMMARY
├── commands/                # 150+ 斜杠命令（Markdown）
│   ├── coordination/
│   ├── sparc/
│   ├── github/
│   ├── hive-mind/
│   └── ...
├── agents/                  # 74+ 专用 Agent（YAML frontmatter + Markdown）
│   ├── core/
│   ├── swarm/
│   ├── consensus/
│   ├── github/
│   └── ...
├── hooks/                   # 事件处理器
│   └── hooks.json
└── scripts/                 # install.sh / verify.sh / uninstall.sh

其中 .claude-plugin/hooks/hooks.json 注册了 PreToolUse（匹配 Bash 与 Write/Edit/MultiEdit 工具，调用 scripts/ruflo-hook.sh 完成命令/文件改写）、PostToolUse（执行后追踪命令执行记录与编辑结果）、PreCompact（上下文压缩前注入 swarm/SPARC 引导提示）与 Stop（会话结束时生成摘要并持久化状态）等钩子，实现跨会话记忆与行为追踪。值得注意的是，该 hooks 清单声明为仅支持 POSIX（macOS/Linux），在原生 Windows 上不可用，Windows 用户应主要依赖 /plugin 官方命令完成安装与管理。

版本：2.5.0 ｜ 协议：MIT ｜ 作者：rUv ｜ 兼容性：Claude Code >= 2.0.0