你会遇到什么

这个工具解决什么问题：给 Claude Code / Codex 加编排、记忆与 swarm（集群）能力。Ruflo 是 Agent 元编排层：init 全量安装写工作区骨架（.claude-flow/ .agents/ .swarm/ 等），start 启动编排系统，doctor 体检，daemon 常驻。 什么时候用：

• 你要多 Agent 编排 + 记忆 + swarm（start/agent/swarm/memory 命令面）；
• 你要工作区级流水线骨架（init 生成）；
• 你要团队协作式 Agent 工作流。

什么时候别用：轻量单会话——它是重档条目（首次安装约 5 分钟 + 1.6GB npx 缓存，init 写多处文件，doctor 拉后台 daemon）。 和相邻工具的边界：CLI 层与 omc/agt/deepcode 实测可共存（实测记录（本地留存））；与 claude-code-router 判定 possible-compatible（2026-08-30 部分实测：本机工作区 settings.json env 仅 CLAUDE_FLOW_*，无 ANTHROPIC_*；ccr 注入 HOME settings.json env ANTHROPIC_* 需 provider 配置后触发；ccr 网关启停与本工具 doctor 并存正常；注入链未全验证，不转 verified）。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：官方推荐 CLI 全量路径 = npx ruflo init（本环境实测通过）：首次 npx 自动下载原生 prebuild 依赖（约 5 分钟，缓存 1.6GB）；init 写入工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db 与 HOME ~/.claude/CLAUDE.md 指针块。命令面 30+：init/start/agent/swarm/memory/mcp/hooks/daemon。lite 形态 = Claude Code 插件（方式 B，未实测）。 关键概念：

• init：全量安装（官方生产推荐，写工作区 + HOME）；
• doctor：健康诊断（⚠ 为警告不阻塞；会拉起 daemon）；
• daemon：后台进程（doctor/start 自动拉起，daemon stop 停止）。

装完它动哪里（写面大）：工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md 指针块。

一步步来

第 1 步：init 全量安装（为什么带三个 --no：消除交互与外网注册）

讲解：npx -y ruflo init 首次运行会自动下载原生 prebuild 依赖（约 5 分钟，缓存 1.6GB）——不是卡死，耐心等。--no-signup --no-skills-sh --no-codex-detect 消除交互与外网注册，适合自动化/无账号环境。init 会写工作区多处文件（见方案总览）。

npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

预期输出: ruflo v3.38.20

海外/可直连网络分支（去掉 npmmirror 前缀，npm 官方 1.2s 可用）：

npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

预期输出: ruflo v3.38.20

装好确认：

• npx -y ruflo --version 输出 v3.38.20；
• 工作区出现 .claude-flow/ 等骨架目录。

卡住怎么办：

• npx 下载很慢 → 首次原生依赖下载约 5 分钟属正常；确认 Node >= 20；国内用 npmmirror 分支；
• 工作区多了文件吓人 → 这是全量形态设计（官方生产推荐）；不想要全量可卸载后走方式 B 插件 lite。

第 2 步：doctor 体检（会拉起 daemon）

讲解：doctor 检查版本/Node/npm/Git/配置/Memory DB/MCP；⚠ 项为警告不阻塞。注意 doctor/start 会拉起后台 daemon，用完 ruflo daemon stop。

npx -y ruflo doctor

预期输出: RuFlo Doctor 检查项（版本/Node/npm/Git/配置/Memory DB/MCP）；⚠ 项为警告不阻塞；用完后 ruflo daemon stop

装好确认：

• 检查项输出完整，无 FAIL（⚠ 可接受）。

卡住怎么办：

• daemon 起了想停 → npx -y ruflo daemon stop。

第 3 步：编排最小场景（本地 ollama provider 实测；零 key）

讲解：不用外部 API key 也能验证编排面——ruflo 内置 Ollama provider，指向本机 ollama（默认 11434）即可。2026-08-30 隔离环境实测：configure → test（本地端点连通 PASS）→ swarm init → swarm start → swarm status 全过。

npx -y ruflo providers configure -p ollama -e http://127.0.0.1:11434 -m qwen2.5-0.5b
npx -y ruflo providers test -p ollama
npx -y ruflo swarm init
npx -y ruflo swarm start -o "最小目标"
npx -y ruflo swarm status

预期输出: Configured: ollama（endpoint 保存）→ Provider Connectivity Test：Ollama Connected at 11434 PASS → Swarm initialized（Swarm ID + hierarchical/15 agents）→ Agent Deployment Plan（coordinator/architect/coder×3/tester×2/reviewer）+ Swarm initialized with 8 agent slots → 状态表（Elapsed 0s）

装好确认：

• 编排层（init/start/status）命令面 + 本地连通全绿（2026-08-30 隔离实测，实测复现日志（2026-08-30））。

卡住怎么办：

• providers test 报 FAIL: ollama: Not configured (no API key found) → 这是云端 ollama 形态需要 key；同输出里本地端点的 PASS: Ollama: Connected at http://127.0.0.1:11434 才是判定项。
• swarm stop 报 Swarm ID is required → 用 swarm stop <Swarm ID>（swarm status <id> 可查 ID）。
• 要 agent 真跑任务 → 编排层就绪后，执行通道是 Claude Code Agent 工具 / claude -p / hive-mind spawn --claude——本环境未验证该通道（无 Claude Code 执行会话），如实标注。

怎么确认修好了

第 1 步：确认版本与骨架目录

讲解：ruflo --version 输出 v3.38.20、工作区出现 .claude-flow/ 等骨架目录，说明 init 全量安装完成。

npx -y ruflo --version
ls -d .claude-flow 2>/dev/null && echo "skeleton: OK" || echo "skeleton: MISSING"

预期输出: ruflo v3.38.20；skeleton: OK

卡住怎么办：

• 版本对不上 → 重跑 init（带 --no-signup --no-skills-sh --no-codex-detect）；
• 骨架缺失 → 确认在目标项目目录内执行 init。

第 2 步：doctor 体检

讲解：doctor 把版本/Node/npm/Git/配置/Memory DB/MCP 全查一遍，无 FAIL 即环境就绪；⚠ 项是警告不阻塞。

npx -y ruflo doctor

预期输出: RuFlo Doctor 检查项（版本/Node/npm/Git/配置/Memory DB/MCP）；⚠ 项为警告不阻塞

卡住怎么办：

• 有 FAIL 项 → 按提示修（Node 版本/配置）；
• daemon 起了想停 → npx -y ruflo daemon stop。

其它环境的表现（常见变体）

• 网络：海外/可直连网络用 npm 官方分支（实测 1.2s）；国内必须 npmmirror 前缀。
• Node 版本：要求 >= 20；首次安装原生依赖下载约 5 分钟 + 1.6GB npx 缓存（重档，属正常）。
• 后台进程：doctor/start 会自动拉起 daemon，不用时 ruflo daemon stop。
• 写面大：工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md 指针块——不想要全量形态可卸载后走插件 lite（方式 B）。
• 与其它工具共装：CLI 层与 omc/agt/deepcode 实测共存；与 omc 插件形态判定 possible-conflict（共享 .claude/ 写面未实测）；与 claude-code-router 判定 possible-compatible（2026-08-30 部分实测：env 字段/层级不重叠，见「和相邻工具的边界」）。

日常使用

启动与入口

• 编排：npx -y ruflo start；
• 后台：daemon（doctor/start 自动拉起，daemon stop 停止）；
• 命令面：npx -y ruflo --help（30+ 命令）。

常用操作

操作一：查看命令清单

npx -y ruflo --help

预期输出: 以 Ruflo v3.38.20 开头，含 init/start/agent/swarm/memory/mcp/hooks/daemon 等 30+ 命令

操作二：健康诊断（本环境实测；注意会拉起后台 daemon）

npx -y ruflo doctor

预期输出: RuFlo Doctor 检查项（版本/Node/npm/Git/配置/Memory DB/MCP）；⚠ 项为警告不阻塞；用完后 ruflo daemon stop

操作三：停止后台 daemon（doctor/start 会拉起）

npx -y ruflo daemon stop

预期输出: Worker daemon stopped

操作四：编排最小场景（本地 ollama provider 实测；零 key）

npx -y ruflo start

预期输出: 编排系统启动状态（swarm/agents/memory 就绪；实测 2026-08-30：providers configure/test 本地端点连通 PASS → swarm init → swarm start → swarm status 全过，实测复现日志（2026-08-30））

操作五：查看 swarm 状态（实测）

npx -y ruflo swarm status

预期输出: 状态表（Performance Metrics：Elapsed Time 0s / Success Rate no data；Coordination：Messages Sent 0 / Consensus Rounds 0——任务未跑时多列为 no data / 0 属正常）

操作六：停止 swarm（实测坑：必须带 Swarm ID）

npx -y ruflo swarm stop <Swarm ID>

预期输出: swarm 停止确认（实测：不带 ID 直接 ruflo swarm stop 报 [ERROR] Swarm ID is required；Swarm ID 用 swarm status 或 init 输出查）

数据与目录

• 工作区：.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db；
• HOME：~/.claude/CLAUDE.md（Ruflo 指针块）、~/.claude-flow/。

卸载与清理

note: npm 包卸载自动执行（幂等）；工作区专属文件（.claude-flow/ .swarm/ ruvector.db）从 ruflo 初始化目录运行本卸载会一并删除；通用名文件按下方清单手动确认

npm rm -g ruflo || true
rm -rf -- .claude-flow .swarm ruvector.db 2>/dev/null || true
command -v ruflo >/dev/null 2>&1 && echo "ruflo 仍存在" || echo "ruflo removed: OK"

预期输出: ruflo removed: OK

手动确认清单（通用名文件，可能含用户其他配置，不自动删）：

• 工作区：.claude/（ruflo 生成 agents/commands/helpers/settings.json/skills 子项）、.agents/、.mcp.json（删除 claude-flow 注册段）、CLAUDE.md（删除 Ruflo 指针）
• HOME：~/.claude/CLAUDE.md（删除 Ruflo Integration 指针块）、~/.claude-flow/

依赖警告

• 版本：[3.38.20, 3.38.20] 锁定（收录实测版本）。
• 环境：Node >= 20；首次安装原生依赖下载约 5 分钟 + 1.6GB npx 缓存（重档）。
• 网络：npm 官方 1.2s 可用（海外）；国内用 npmmirror 分支。
• 写面（大）：工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md 指针块；另：仅运行 --version/--help 也会在 HOME 写 ~/.claude-flow/update-state.json（更新检查状态，2026-08-31 隔离实测确认）。
• 后台进程：daemon（doctor/start 自动拉起，daemon stop 停止）。
• 共装：CLI 层与 omc/agt/deepcode 实测共存（实测记录（本地留存））；与 omc 插件形态共享 .claude/ 与 ~/.claude/CLAUDE.md 未实测 → possible-conflict；与 claude-code-router → possible-compatible（2026-08-30 部分实测：工作区 env CLAUDE_FLOW_* vs HOME env ANTHROPIC_*，字段/层级不重叠；注入链未全验证）。

FAQ（常见问题）

• 问：npx 下载很慢/装不上？答：确认 Node >= 20；国内用安装段方式 A 的 npmmirror 分支；首次原生依赖下载约 5 分钟属正常。
• 问：安装后工作区多了好多文件？答：init 是 CLI 全量安装（官方生产推荐），写入 .claude/.claude-flow/.agents/.swarm/.mcp.json/CLAUDE.md；不想要全量可用方式 B 插件 lite 形态。
• 问：后台有个进程是什么？答：ruflo daemon（doctor/start 自动拉起），ruflo daemon stop 停止。
• 问：跑任务报没有模型？答：需要 LLM provider（deepcode provider/ruflo providers 配置 API key）。
• 问：和其他插件能一起装吗？答：CLI 层实测可共存（omc/agt/deepcode 互不干扰，见 实测记录（本地留存））；与 omc 的 Claude 插件形态共享 .claude/ 与 ~/.claude/CLAUDE.md 未实测（本机未登录），判定 possible-conflict。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。