ruflo hive-mind spawn 实战：以女王协调（Queen-Led）模式拉起多智能体蜂群的完整指南

Hive Mind 是 ruflo 中面向多智能体协作的"蜂群智能"协调框架，而 hive-mind spawn 正是把理论上的蜂群变成实际运行的 worker 智能体的核心命令。本篇技术指南以 .claude/commands/hive-mind/hive-mind-spawn.md 为骨架，结合仓库内 v3 CLI 的完整实现，讲解 spawn 的每个参数含义、真实运行调用链，以及它如何在 Queen（女王/首领）协调下完成任务分发、共识决策与集体记忆。读完本文，你将能够熟练使用该命令拉起一个可观测、可恢复、可协商的多智能体蜂群，也能读懂它落地到 Claude Code 会话时的底层行为。

一、spawn 在 Hive Mind 命令体系中的位置

在 ruflo 仓库中，hive-mind 是一组完整的"集体智能"生命周期命令，文档化入口见 .claude/commands/hive-mind/README.md，共包含 hive-mind、hive-mind-init、hive-mind-spawn、hive-mind-status、hive-mind-resume、hive-mind-stop、hive-mind-sessions、hive-mind-consensus、hive-mind-memory、hive-mind-metrics、hive-mind-wizard 等多个命令。

其中：

• hive-mind init：初始化整个蜂群基础设施，选定拓扑、共识算法与内存后端；
• hive-mind spawn：把 worker 智能体"加入"蜂群（spawn into the hive），是本篇主角；
• hive-mind status：查看蜂群与 Queen 的健康状态、队列负载；
• hive-mind resume / stop：暂停后的恢复与会话终止；
• hive-mind consensus：提案与投票治理；
• hive-mind memory：访问蜂群共享记忆。

主命令描述为 "Queen-led consensus-based multi-agent coordination"，即由 Queen 领导的、基于共识算法的多智能体协调。spawn 的目标描述（objective）非常直白——"Spawn a Hive Mind swarm with queen-led coordination"（以女王协调模式拉起一支 Hive Mind 蜂群）。

在 v3 CLI 的源码中，该命令注册在 v3/@claude-flow/cli/src/commands/hive-mind.ts，别名 hive，其命令行统一入口为 claude-flow（对应 npx claude-flow）。

二、命令用法与基础语法

依据关联文档，spawn 的基本语法如下：

npx claude-flow hive-mind spawn <objective> [options]

其中 <objective> 是要交给蜂群完成的目标描述，例如 "Build API"、"Research patterns"。整条命令整体语义为：为当前蜂群补充 worker 智能体，并以 objective 作为协调指挥的核心目标。目标会进一步进入 Claude Code 协调提示词，成为蜂群执行协议中 Queen 需要对齐的 "YOUR OBJECTIVE"。

从源码看，spawn 子命令注册了更细粒度的选项（见 v3/@claude-flow/cli/src/commands/hive-mind.ts），目标既可以通过 --objective/-o 传入，也可以作为位置参数传入（源码中 ctx.args.join(' ') 即为兜底逻辑）；交互式会话中若未提供目标，还会弹出输入提示，校验规则是目标不能为空。

三、选项详解与取值范围

关联文档列出了 4 个核心选项，下面先按其原貌列出，再结合源码与同族命令补齐取值范围和默认值。

3.1 文档定义的选项

选项	说明	可取值 / 默认
--queen-type <type>	Queen（首领）协调者类型	strategic（战略型，默认）、tactical（战术型）、adaptive（自适应型）
--max-workers <n>	蜂群最大 worker 智能体数量上限	正整数
--consensus <type>	使用的共识算法	byzantine、raft、gossip、crdt、quorum（byzantine 为默认）
--claude	生成并启动 Claude Code 协调会话	布尔开关，默认关闭

3.2 与 v3 实现对应的真实参数面

从 v3 CLI 的 spawn 实现看，当前落地版本的参数粒度更细，同时保留了上述语义：

• -n, --count：本次要 spawn 的 worker 数量，默认 1；
• -r, --role：worker 角色，取值为 worker、specialist、scout，默认 worker；
• -t, --type：worker 的 agent 类型，默认 worker；
• -p, --prefix：worker ID 前缀，默认 hive-worker；
• -o, --objective：蜂群目标（与位置参数等价）；
• --claude：spawn 后携带协调提示词启动 Claude Code；
• --dangerously-skip-permissions：跳过 Claude Code 权限确认（默认 true，需谨慎）；
• --no-auto-permissions：显式关闭自动权限跳过；
• --dry-run：只展示将执行的动作而不真正启动 Claude Code；
• --non-interactive：以 -p --output-format stream-json 非交互模式运行 Claude Code；
• --mcp-config：为被 spawn 的 worker 显式指定 MCP 配置文件。

上述角色 worker / specialist / scout 与仓库中蜂群代理体系一一对应：worker-specialist 负责任务执行与并行处理，scout-explorer 负责情报收集与环境扫描，相关职责描述见 .claude/agents/hive-mind/queen-coordinator.md。

3.3 共识算法与拓扑的取值集合

共识策略在 init 子命令中同样被引用，源码定义了完整的取值集合与提示文案（见 v3/@claude-flow/cli/src/commands/hive-mind.ts）：

值	含义	特性
byzantine	Byzantine Fault Tolerant	2/3 多数裁决，可抵御恶意参与者（默认）
raft	Raft	基于 leader 的共识
gossip	Gossip	最终一致，具备可扩展性
crdt	CRDT	无冲突可复制数据类型
quorum	Quorum	简单多数投票

拓扑取值集合为 hierarchical（Queen 领导 worker）、mesh（对等协调）、hierarchical-mesh（Queen + 对等通信，推荐）、adaptive（按任务动态调整），默认 hierarchical-mesh（见 v3/@claude-flow/cli/src/commands/hive-mind.ts）。在提示词生成器中，这些字段会被写入蜂群配置区块：Queen 类型默认 strategic、共识算法默认 byzantine、拓扑默认 hierarchical-mesh（v3/@claude-flow/cli/src/commands/hive-mind.ts）。

3.4 init 阶段即可预设的蜂群级参数

与 spawn 配合的是 init 子命令提供的一组蜂群级配置（见 v3/@claude-flow/cli/src/commands/hive-mind.ts）：

• -t, --topology：蜂群拓扑，默认 hierarchical-mesh；
• -c, --consensus：共识策略，默认 byzantine；
• -m, --max-agents：最大智能体数，默认 15；
• -p, --persist：是否启用持久化状态，默认开启；
• --memory-backend：记忆后端，取值为 agentdb、sqlite、hybrid，默认 hybrid。

init 会调用 MCP 工具 hive-mind_init 完成基础设施创建，返回 hiveId、topology、consensus、queenId 等配置；随后即可用 spawn 补充 worker。

四、示例逐条演练

关联文档给出了 3 个示例，这里原样继承并补充运行说明与真实扩展用法。

# 示例 1：最简拉起——以默认 strategic Queen、默认 byzantine 共识开始执行
npx claude-flow hive-mind spawn "Build API"

# 示例 2：指定 Queen 类型为自适应型，进行模式研究类任务
npx claude-flow hive-mind spawn "Research patterns" --queen-type adaptive

# 示例 3：仅拉起并生成 Claude Code 协调指令（不附带额外目标，由会话继续推进）
npx claude-flow hive-mind spawn "Build service" --claude

结合仓库内命令库（见 .claude/commands/hive-mind/hive-mind.md）以及 v3 实现的示例字段，可以派生以下高频实战形态：

# 标准流程：先初始化蜂群，再拉起 5 个 worker
npx claude-flow hive-mind init
npx claude-flow hive-mind spawn -n 5

# 初始化时即指定分层网格拓扑 + 拜占庭共识，上限 20 个智能体
npx claude-flow hive-mind init -t hierarchical-mesh -c byzantine -m 20

# spawn 3 个 specialist 角色 worker
npx claude-flow hive-mind spawn -n 3 -r specialist

# 用自定义类型与前缀标识一组 coder worker
npx claude-flow hive-mind spawn -t coder -p my-coder

# 拉起 5 个 worker 并同时以 --claude 启动 Claude Code 协调会话，明确给定目标
npx claude-flow hive-mind spawn -n 5 --claude -o "Research AI patterns"

# 仅做演练：查看将生成的提示词内容而不实际启动 Claude Code
npx claude-flow hive-mind spawn --claude -o "Build a REST API" --dry-run

# 服务器 / CI 场景：非交互模式运行，需要显式提供 MCP 配置
npx claude-flow hive-mind spawn --claude --non-interactive --mcp-config ./.mcp.json -o "Run regression suite"

示例中 --claude 与 --objective 同时出现时，spawn 会先向蜂群写入 worker（对应 MCP 工具 hive-mind_spawn），再把所有 worker 信息与目标一起打包进协调提示词，转交给 Claude Code 会话执行。

五、源码级原理：spawn 一行的背后发生了什么

5.1 两条执行分支

spawn 的 action（v3/@claude-flow/cli/src/commands/hive-mind.ts）按是否带 --claude 分为两条路径：

1. 普通 spawn：调用 MCP 工具 hive-mind_spawn，传入 { count, role, agentType, prefix }，返回包含 spawned、workers（含 agentId、role、joinedAt）、totalWorkers、hiveStatus 的结构；随后以表格输出 worker 列表，Agent ID 按前缀（默认 hive-worker）生成。失败时（success: false）直接返回错误并退出码 1。

2. --claude 路径：在普通 spawn 基础上额外调用 spawnClaudeCodeInstance（v3/@claude-flow/cli/src/commands/hive-mind.ts），执行"提示词生成 → 提示词落盘 → 解析 Claude Code 启动命令 → 拉起子进程 → 等待退出"的完整链路。

5.2 协调提示词的生成与落盘

generateHiveMindPrompt（v3/@claude-flow/cli/src/commands/hive-mind.ts）会组装一份结构化提示词，包含以下区块：

• HIVE MIND CONFIGURATION：Swarm ID、Swarm Name、Objective、Queen Type、Worker Count、Topology、Consensus Algorithm、初始化时间；
• WORKER DISTRIBUTION：按 worker 类型分组的分布统计（由 groupWorkersByType 按 type || role || 'worker' 归类）；
• AVAILABLE MCP TOOLS：分类列出可用于协调的 mcp__ruflo__* 工具面（集体智能、Queen 协调、Worker 管理、任务编排、记忆与学习五大类）；
• EXECUTION PROTOCOL：四阶段执行协议（详见第六节）；
• YOUR OBJECTIVE：本次目标；
• TOOL PREFERENCE RULES：强制优先使用 mcp__ruflo__* 工具完成 spawn、task 分配、记忆与协调，原生文件/Shell 工具仅用于文件操作与命令执行。

提示词生成后会写入会话目录：.hive-mind/sessions/hive-mind-prompt-<swarmId>.txt（目录不存在会自动创建）。这意味着即使中途 Ctrl+C 暂停，提示词文件仍保留，可随时恢复执行。

5.3 参数解析与启动细节

启动 Claude Code 前，spawn 会对参数做数层处理，这些行为都能在源码注释中找到依据：

• MCP 配置自动发现：优先使用显式 --mcp-config；否则按序探测 ./.mcp.json、~/.claude.json、~/.claude/mcp.json。若找不到任何配置，会给出警告——被 spawn 的 worker 将无法获得 mcp__ruflo__* 工具（对应源码中的 #1748 问题修复，见 v3/@claude-flow/cli/src/commands/hive-mind.ts）。
• --mcp-config 使用等号语法：--mcp-config=<path> 而非空格分隔的独立 token，避免提示词较长时被当作第二个配置文件导致 ENAMETOOLONG（源码注释 #1780）。
• 权限标志的严格布尔语义：仅当显式传入 --dangerously-skip-permissions 且未传 --no-auto-permissions / --no-auto-permissions 等价形态时才跳过权限确认（源码注释 HIGH-02 / #2269 描述了三段式判定）。
• 非交互模式：--non-interactive 会给 Claude Code 追加 -p --output-format stream-json --verbose。
• Ctrl+C 暂停：注册 SIGINT/SIGTERM 处理器，暂停会话并终止子进程，同时提示提示词文件位置，方便之后 claude < promptFile 恢复（对应 .claude/commands/hive-mind/hive-mind-resume.md 所描述的生命周期管理）。
• 等待子进程退出：CLI 会 await Claude Code 的退出码（#2297），避免父进程过早结束导致子进程失去控制终端。
• Claude CLI 不可用时回退：若未找到 Claude Code，会打印安装提示（npm install -g @anthropic-ai/claude-code）并给出手动执行指引：claude < promptFile 或 cat promptFile | claude；--dry-run 则只输出提示词长度与前 500 字符预览。

六、Queen 协调下的蜂群执行协议

拉起蜂群后，协调提示词为 Queen 定义了四阶段执行协议（可对照源码提示词模板验证）：

1. INITIALIZATION PHASE（初始化阶段）：确认所有 worker 在线、建立通信通道、加载历史会话状态、初始化共享记忆空间；
2. TASK DISTRIBUTION PHASE（任务分发阶段）：拆解目标为子任务、依据 worker 专长分配、建立依赖与执行顺序、监控并行执行；
3. COORDINATION PHASE（协调阶段）：关键决策走共识、聚合各 worker 结果、使用配置的共识算法（如 byzantine）解决冲突、跨蜂群共享学习成果；
4. COMPLETION PHASE（完成阶段）：核验子任务完成度、汇总结果、把学习写入集体记忆、报告最终状态。

该协议与 .claude/agents/hive-mind/queen-coordinator.md 中 Queen 的职责模型相互印证：Queen 承担战略指挥与资源分配（写 sovereign status、下发 royal directives），并通过分层/民主/应急三种治理模式维持蜂群一致性；worker 聚焦执行，scout 聚焦侦查，collective-intelligence-coordinator 承担复杂共识决策与知识整合。spawn 出来的正是这套分层体系里的 worker 层。

七、spawn 之后：蜂群生命周期管理

一次 spawn 只是蜂群生命周期的中间一环，配套命令保证"拉起后可观测、可恢复、可解散"：

# 查看蜂群与 Queen 状态；-d 展示指标与健康面板，-w 持续监听
npx claude-flow hive-mind status
npx claude-flow hive-mind status -d

# 向蜂群提交任务；-c 要求任务完成需要共识，-p critical 提升优先级
npx claude-flow hive-mind task -d "Implement auth module"
npx claude-flow hive-mind task -d "Security review" -p critical -c

# 暂停后的恢复与停止
npx claude-flow hive-mind resume
npx claude-flow hive-mind stop

# 会话与共享记忆管理
npx claude-flow hive-mind sessions
npx claude-flow hive-mind memory list

# 优雅关闭蜂群（默认保存状态），-f 强制关闭
npx claude-flow hive-mind shutdown

命令间的关系是：init 建巢 → spawn 补员并设定目标 → status/task/consensus 协调运行 → resume/stop/shutdown 管理会话与解散。spawn 产出的 worker 表（Agent ID、Role、Status、Joined）也会在后续 status 的 Worker Agents 面板中持续追踪（含当前任务、已完成任务数）。

八、实战建议与常见问题定位

• 确认已 init：直接 spawn 而蜂群未初始化时，spawn 调用会依赖默认 hiveId（源码中 result.hiveId || 'default'）。规范做法是先 hive-mind init 明确 hiveId 与拓扑、共识。
• 确认 MCP 配置可达：要让 --claude 路径真正生效，需保证 .mcp.json（或 ~/.claude.json）中存在 mcp__ruflo__* 工具注册；缺失时 spawn 会警告并导致 worker 无法协调，此时应显式传 --mcp-config 或先运行 ruflo init 生成。
• 权限与自动化场景：本地联调可接受默认跳过权限；CI/无人值守建议用 --non-interactive 配合流式 JSON 输出，若平台策略严格则传 --no-auto-permissions 显式关闭。
• 先演练再执行：不确定提示词内容时先用 --dry-run 预览，它不会启动 Claude Code，只打印提示词长度与前 500 字符并保存完整文件。
• 会话中断恢复：协调会话被 Ctrl+C 暂停后，提示词文件保留在 .hive-mind/sessions/ 下，用 claude < promptFile 即可恢复，无需重新 spawn。
• 角色搭配：研究型目标建议 -r scout 或 adaptive Queen 组合侦查与探索；工程实现型目标建议 -r specialist + 自定义 -t/-p，便于在 status 面板中按角色识别 worker。

结语

hive-mind spawn 表面是一条拉起命令，实质上是 ruflo 多智能体协调能力的入口：它以 Queen-led 的分层治理为骨架，以可插拔的共识算法与拓扑为决策机制，把目标拆解为可并行的 worker 任务，并通过 MCP 工具面与 Claude Code 会话完成端到端执行。本文所列参数、示例与原理均可在仓库对应源码中验证：命令实现见 v3/@claude-flow/cli/src/commands/hive-mind.ts，命令文档族见 .claude/commands/hive-mind/，Queen 治理模型见 .claude/agents/hive-mind/queen-coordinator.md。如需进一步掌握初始化、状态监控与共识治理，可继续阅读同目录下 hive-mind-init 与 hive-mind-consensus 等命令文档。