ruflo Claude-Flow CLI 速查手册：从系统管理到多智能体编排的完整命令实战指南

本文以仓库内置的 .claude/commands/claude-flow-help.md 帮助文档为骨架，结合 @claude-flow/cli（即 ruflo 的 Claude Code 编排命令行）源码逐条展开，整理成一份可直接查阅、可验证的 CLI 命令参考。读完你可以掌握系统启动/监控、Agent 生杀、任务编排、记忆存取、SPARC 开发工作流、Swarm 协同与 MCP 接入的完整命令面，并理解每条命令背后在仓库中的实现位置与真实参数语义，从而在自己的 Claude Code 环境中落地一套可复用的多智能体开发流程。

这份帮助文档在仓库中的定位

claude-flow-help.md 是随 CLI 一起分发、供 Claude Code 斜杠命令直接调用的内嵌命令帮助页（frontmatter 中 name: claude-flow-help、description: Show Claude-Flow commands and usage）。它在仓库中存在三个同源副本：

• 根目录副本 .claude/commands/claude-flow-help.md（本文默认引用对象）；
• CLI 包内副本 v3/@claude-flow/cli/.claude/commands/claude-flow-help.md（随 npm 包发布，files 清单包含 .claude）；
• MCP 包内副本 v3/@claude-flow/mcp/.claude/commands/claude-flow-help.md。

更有意思的是初始化逻辑：在 v3/@claude-flow/cli/src/init/executor.ts 中，claude-flow-help.md、claude-flow-swarm.md、claude-flow-memory.md 三个文件被归入 core 核心命令集，意味着每次执行初始化时这三份帮助文档会被安装进用户工作区，之后可以直接在 Claude Code 中通过 /claude-flow-help 唤出命令速查。

从包描述（v3/@claude-flow/cli/package.json）看，这份 CLI 是 ruflo 面向 Claude Code 的编排工具，声明支持 60+ 专业 Agent、Swarm 协同、MCP Server、自学习 Hooks 与向量记忆。命令的顶层注册集中在 v3/@claude-flow/cli/src/commands/index.ts，其中 start、task、agent、swarm、memory、mcp 六个命令为同步加载的核心命令，其余按需懒加载以控制启动时间——这也是帮助文档把命令分成六大类的原因。

安装与初始化

帮助文档给出的初始化入口为：

npx -y claude-flow@latest init --sparc

--sparc 表示初始化时同时铺设 SPARC 开发方法论相关的工作流与模式命令。init 阶段会执行上文提到的 executor.ts 的"核心命令集"安装逻辑（core: ['claude-flow-help.md', 'claude-flow-swarm.md', 'claude-flow-memory.md']），把速查页写入 .claude/commands/。

初始化完成后，推荐直接用本地启动器：

./claude-flow --help

而不再每次敲 npx claude-flow。这一点与帮助文档"Best Practices"中的建议一致，也和 package.json 里注册的两个 bin（claude-flow、claude-flow-mcp）对应——前者是编排 CLI 入口，后者是 MCP Server 入口。

命令全景速查

帮助文档按职责把命令划分为六个域。下表为总览，每个域后文逐条展开并结合源码补充参数细节。

分类	命令族	一句话用途
System Management	start / status / monitor / stop	编排系统的生命周期与状态
Agent Management	agent spawn/list/info/terminate	智能体创建、查看与回收
Task Management	task create/list/status/cancel/workflow	任务级编排
Memory Operations	memory store/query/stats/export/import	跨会话持久记忆
SPARC Development	sparc / modes / run / tdd / info	结构化软件开发工作流
Swarm Coordination	swarm + --strategy/--background/--monitor/--ui/--distributed	多 Agent 蜂群协同
MCP Integration	mcp status/tools/config/logs	MCP 工具面管理
Claude Integration	claude spawn / batch	增强引导的 Claude 子进程

System Management：系统生命周期管理

帮助文档给出的系统管理命令：

./claude-flow start          # 启动编排系统
./claude-flow start --ui     # 带交互式进程管理 UI 启动
./claude-flow status         # 查看系统状态
./claude-flow monitor        # 实时监控
./claude-flow stop           # 停止编排

在最新源码中，status 命令的实现（v3/@claude-flow/cli/src/commands/status.ts）远比"查看状态"更丰富，可以作为日常监控的进阶入口：

• ./claude-flow status —— 查看整体系统状态；
• ./claude-flow status --watch —— 持续刷新的看板模式（--watch -i 5 可设 5 秒刷新间隔）；
• ./claude-flow status --health-check —— 执行健康检查后退出；
• ./claude-flow status --json —— 输出机器可读的 JSON 状态；
• ./claude-flow status agents / status tasks / status memory —— 分别深入 Agent、任务、记忆的明细。

从源码结构看，帮助文档里的 monitor 可以理解为这类实时状态监控的统一别名：status --watch 提供了进程看板，agent health --watch 提供了 Agent 粒度的 5 秒刷新监控（见下文），Swarm 场景则可用 swarm --monitor。建议把 ./claude-flow status --health-check 纳入 CI 或开机自检脚本，用退出码判断编排系统是否健康。

Agent Management：智能体的创建与回收

帮助文档的命令面：

./claude-flow agent spawn <type>        # 创建新 Agent
./claude-flow agent list                # 列出活跃 Agent
./claude-flow agent info <id>           # 查看 Agent 详情
./claude-flow agent terminate <id>      # 停止 Agent

对应实现集中在 v3/@claude-flow/cli/src/commands/agent.ts，需要注意：实际 CLI 采用显式标志（flag）而非纯位置参数。spawn 子命令（agent.ts）支持的参数包括：

标志	别名	说明	默认值
--type / -t	必填	Agent 类型，来自 AGENT_TYPES 枚举	无（缺省报错）
--name / -n	可选	Agent 名称/标识	自动生成
--provider / -p	可选	模型供应商（anthropic/openrouter/ollama）	anthropic
--model / -m	可选	指定模型	跟随 provider
--task	可选	交给 Agent 的初始任务	无
--timeout	可选	超时（秒）	300
--auto-tools	可选	是否自动启用工具调用	true

仓库内代码示例提供了两种标准用法（agent.ts）：

claude-flow agent spawn --type coder --name bot-1
claude-flow agent spawn -t researcher --task "Research React 19"

AGENT_TYPES 内置类型横跨编码、研究、安全、记忆与架构等角色，例如 coder、researcher、optimizer、security-architect、security-auditor、memory-specialist、swarm-specialist、performance-engineer、core-architect、test-architect 等。这些角色与 plugin/agents 目录下的 Agent 定义（goal、github、hive-mind、flow-nexus 等）一一呼应，用户可先 /claude-flow-help 或 agent spawn 交互提示中的选择列表确认真实可用的 type 名。

其余子命令同样在 agent.ts 中落地：list（支持 --all 包含非活跃 Agent、--type 过滤类型、--status 按 active/busy/idle/terminated 过滤，内部调用 MCP 工具 agent_list）；info 展示单个 Agent 状态详情；terminate（源码别名 kill）支持 --force 强制停止与优雅关闭超时。在此基础上源码还延伸出 pool（Agent 池与自动伸缩，如 pool --size 5、pool --min 2 --max 15）和 health（健康与指标，可 --watch 每 5 秒刷新），适合规模化团队做容量管理。

Task Management：任务编排

./claude-flow task create <type> "description"   # 创建任务
./claude-flow task list                          # 列出全部任务
./claude-flow task status <id>                   # 查看任务状态
./claude-flow task cancel <id>                   # 取消任务
./claude-flow task workflow <file>               # 执行工作流文件

任务管理模块的源码入口是 v3/@claude-flow/cli/src/commands/task.ts，与 Agent 命令互补：Agent 是"角色"，Task 是"要被完成的动作"。生产建议是遵循帮助文档 Quick Examples 的组合模式——用 agent spawn 造出带 --task 初始目标的角色后，用 task list/status 追踪其执行；需要跑"预设流程"时，仓库还单独提供了顶层 workflow.ts 命令执行工作流配置文件，仓库中的真实工作流定义可参考 .claude/workflows（如 full-system-test.js、intelligence-system-hardening.js）与 v3/@claude-flow/cli/src/commands/workflow.ts。

Memory Operations：跨会话持久记忆

./claude-flow memory store "key" "value"    # 存储数据
./claude-flow memory query "search"         # 检索记忆
./claude-flow memory stats                  # 记忆统计
./claude-flow memory export <file>          # 导出记忆
./claude-flow memory import <file>          # 导入记忆

记忆系统是 ruflo 强调"跨会话上下文"能力的关键一环。帮助文档 Quick Examples 特别展示了带命名空间的写入方式：

./claude-flow memory store "project_requirements" "e-commerce platform specs" --namespace project

--namespace 在源码中是一等公民：内存入读、查询都围绕 namespace 做隔离与过滤（v3/@claude-flow/cli/src/commands/memory.ts）。例如当查询命中了多个 namespace 时，CLI 会提示你补上 --namespace <name> 缩小范围；而 purge 这类破坏性操作强制要求显式传 --namespace，如 memory purge --namespace stale-cache --dry-run（先预览）与 --force（免确认批量清理），防止误删。也就是说，建议养成"每条记忆都归入 namespace"的习惯，既保证检索准确，又让后续按项目/模块做导出、导入与清理变得安全可控。

更进一步的实现细节可从以下文件印证：内存命令族还包含 memory-backup（commands/memory-backup.ts）与 memory-distill（commands/memory-distill.ts），前者负责导出备份，后者对记忆做蒸馏压缩；底层向量存储与检索则由 commands/memory.ts 联动 ruvector/AgentDB 完成。

SPARC Development：结构化开发工作流

./claude-flow sparc "task"          # 运行 SPARC 编排器
./claude-flow sparc modes           # 列出全部 SPARC 模式
./claude-flow sparc run <mode> "task"  # 以指定模式运行
./claude-flow sparc tdd "feature"   # TDD 工作流
./claude-flow sparc info <mode>     # 查看模式详情

SPARC 是 ruflo 内置的结构化软件交付方法论，其方法论四支柱（Specification → Pseudocode → Architecture → Refinement，配合 Coding）可在 plugin/agents/sparc 下找到对应 Agent 文档：specification.md、pseudocode.md、architecture.md、refinement.md。实际可用的模式命令则沉淀在 .claude/commands/sparc 目录下，共 32 个模式文档，覆盖一条完整研发链路：

• 拆解/分析：analyzer、researcher、architect、spec-pseudocode；
• 开发实施：coder、code、designer、integrator、debugger、optimizer；
• 质量保障：reviewer、tester、tdd、security-review、documenter、post-deployment-monitoring-mode；
• 团队协作：orchestrator、swarm-coordinator、workflow-manager、batch-executor；
• 专项：mcp、memory-manager、supabase-admin、tutorial 等。

帮助文档中"17+ 模式"的说法随版本演进已扩展——以 .claude/commands/sparc 实际文件数为准（32 个）。想查看当前环境全量模式，直接运行 ./claude-flow sparc modes；而 sparc tdd "user authentication" 则是把"红-绿-重构"塞进单一命令的高频用法，可与 .claude/commands/sparc/tdd.md 中定义的步骤对照执行。

Swarm Coordination：多 Agent 蜂群协同

./claude-flow swarm "task" --strategy <type>   # 以指定策略启动蜂群
./claude-flow swarm "task" --background        # 长时后台任务
./claude-flow swarm "task" --monitor           # 带监控
./claude-flow swarm "task" --ui                # 交互 UI
./claude-flow swarm "task" --distributed       # 分布式协同

Swarm 命令源码位于 v3/@claude-flow/cli/src/commands/swarm.ts。结合实现来看，帮助文档的简写形式在 CLI 中由 swarm start 承担，其核心标志为：

• -o, --objective：蜂群要完成的目标/任务（如 -o "Build REST API"）；
• -s, --strategy：执行策略，交互模式下会弹出选择器，默认回落到 development（另有 adaptive 等，swarm.ts）；
• --parallel：开启并行执行（如 swarm start -o "Analyze codebase" --parallel）；
• --monitor：实时监控执行过程。

对应帮助文档的语义：

速查写法	实际落地	适用场景
swarm "task" --strategy development	swarm start -o ... -s development	默认分工明确的多角色开发
swarm "task" --monitor	加 --monitor 标志	需要实时进度跟踪
swarm "task" --background	长耗时任务放后台（配合文档建议 >30 分钟必用）	后台/无头运行
swarm "task" --distributed	依赖环境中的分布式运行时	跨节点/容器协同

从仓库结构推断，策略与角色规划（getAgentPlan(strategy)）会在启动时按策略展开成具体的 Agent 组合，例如 development 策略会派出专门化角色；adaptive 则依据任务特征动态选型。想深入了解蜂群本身的编排策略，可直接阅读 .claude/commands/swarm（含 development/analysis/testing/optimization 等分域示例与 swarm-background/swarm-monitor/swarm-strategies 专项文档）以及配套的 .claude/commands/claude-flow-swarm.md 帮助页。

MCP Integration：工具面管理

./claude-flow mcp status    # MCP Server 状态
./claude-flow mcp tools     # 列出可用工具
./claude-flow mcp config    # 查看配置
./claude-flow mcp logs      # 查看 MCP 日志

MCP 命令注册于 v3/@claude-flow/cli/src/commands/mcp.ts。ruflo 的 MCP Server 与 CLI 共用配置上下文，接入点在 .claude/mcp.json 与 v3/@claude-flow/cli/src/mcp-server.ts。实用建议：

1. 环境刚就绪或模型切换后先跑 ./claude-flow mcp status，确认 Server 在线；
2. ./claude-flow mcp tools 全量盘点当前可用工具面（Agent 编排、记忆、GitHub、浏览器等能力都以 MCP 工具形态暴露，agent.ts 中的 agent_list/agent_terminate 正是 CLI 回调 MCP 工具的例子）；
3. 排查工具"消失"或权限问题时看 ./claude-flow mcp logs 与 mcp config，核对 Server 是否被正确加载。

Claude Integration：增强引导的 Claude 子进程

./claude-flow claude spawn "task"       # 以增强引导生成 Claude 子进程
./claude-flow claude batch <file>       # 执行工作流配置文件

claude 命令面服务于"以增强引导运行 Claude Code"的场景：claude spawn 为单个任务拉起一个注入了 guidance/引导上下文的 Claude 进程；claude batch <file> 则按配置批量执行。这与仓库把 @claude-flow/codex 一并纳入依赖的做法互为印证（v3/@claude-flow/cli/package.json），说明编排层对不同模型后端做了抽象；若你的团队同时使用 Codex，可参考 plugin/agents/dual-mode 中的 codex-coordinator.md / codex-worker.md / dual-orchestrator.md，以双模式协调器统一派发任务。

组合实战示例

把上面的命令面串成真实工作流（帮助文档 Quick Examples 的完整展开）：

1) 启动编排系统并做健康自检：

./claude-flow start
./claude-flow status --health-check

2) 启动一个"构建 REST API"的开发蜂群（带监控与代码评审）：

./claude-flow swarm "Build REST API" --strategy development --monitor --review

3) 用 TDD 模式实现用户认证：

./claude-flow sparc tdd "user authentication"

4) 沉淀项目级上下文，供跨会话复用：

./claude-flow memory store "project_requirements" "e-commerce platform specs" --namespace project

5) 按角色分工生成专业 Agent（带优先级）：

./claude-flow agent spawn researcher --name "Senior Researcher" --priority 8
./claude-flow agent spawn developer --name "Lead Developer" --priority 9

6) 执行预设工作流配置并清理闲置 Agent：

./claude-flow task workflow .claude/workflows/intelligence-system-hardening.js
./claude-flow agent list --status idle
./claude-flow agent terminate <id> --force   # 或别名 ./claude-flow agent kill <id>

最佳实践与运维建议

帮助文档给出的五条最佳实践，结合源码可进一步落到可执行动作：

• 初始化后用 ./claude-flow 而非 npx claude-flow：本地启动器避免每次拉包、锁版本，也保证 init 安装的 .claude/commands/ 帮助集（含本速查页）持续可用；
• 重要上下文写入 memory 实现跨会话持久化：统一加 --namespace，项目级用 project 类命名空间，配合 memory stats 关注库体量、memory export 定期备份（破坏性 purge 必须先 --dry-run 预览）；
• 复杂任务交给 Swarm：先在 swarm start 的交互选择器里挑 strategy，默认 development，复杂任务考虑 adaptive，必要时 swarm init 预设拓扑与最大 Agent 数；
• 实时进度用监控三件套：进程级 status --watch -i 5、Agent 级 agent health --watch、蜂群级 swarm --monitor；
• 超过 30 分钟的任务放后台：配合 --background 运行，再以 status / agent list / swarm 状态命令轮询结果，避免占用交互终端。

进一步阅读

本文只是命令面速查，更深的"为什么"与"怎么配"可以从以下仓库内部资源继续：

• .claude/commands/claude-flow-swarm.md 与 .claude/commands/claude-flow-memory.md：与本文同批由 init 安装的两份专项帮助文档；
• v3/@claude-flow/cli/README.md 与 v3/@claude-flow/cli/CLAUDE.md：CLI 包自述与开发约束；
• .claude/commands/sparc 与 .claude/commands/swarm：32 个 SPARC 模式与 17 个 Swarm 命令的逐条定义；
• .claude/agents 与 plugin/agents：Agent 类型目录，可对照 agent spawn --type 的候选值与各角色实际职责；
• v3/@claude-flow/cli/src/commands/index.ts：顶层命令注册表，查看最新命令全集与加载策略。

说明：帮助文档末尾原有的 Documentation / Examples / Issues 外链指向上游项目页面；在当前仓库中，请以本仓库上述内部路径为准进行阅读与验证。文中命令在不同版本间存在简写与全称差异，实际可用参数与类型以 ./claude-flow <command> --help 输出为准。