ruflo hive-mindQueen 主导的共识式多智能体蜂群协调系统实战指南【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo本文围绕 ruflo 仓库中hive-mind命令文档展开系统讲解 Hive Mind 集体智能系统的完整命令行用法从初始化蜂群拓扑、选择共识算法到批量生成 worker 智能体、以--claude模式启动 Claude Code 协调会话再到状态监控、任务提交、共识投票、共享内存与优雅关闭。读完本文你可以基于 ruflo 的 MCP 工具链在本地跑起一套Queen 协调 多 worker 并行的多智能体工作流并理解每条 CLI 命令背后的源码实现与 MCP 工具调用链。一、hive-mind 是什么ruflo 的hive-mind是一个面向高级 swarm 协调的集体智能系统collective intelligence system for advanced swarm coordination其核心设计是Queen-led consensus-based multi-agent coordination——由一个 Queen 协调者智能体领导整个蜂群worker 之间通过可配置的共识算法做决策。官方命令文档位于 hive-mind.md同目录下还有 init、spawn 等子命令的详细文档索引见 hive-mind 命令 README。基本调用方式为npx claude-flow hive-mind [subcommand] [options]文档列出的核心子命令为子命令作用init初始化 hive mind 系统spawn生成spawnhive mind 蜂群status查看 hive mind 状态resume恢复暂停的会话stop停止运行中的会话官方给出的典型示例# Initialize hive mind npx claude-flow hive-mind init # Spawn swarm npx claude-flow hive-mind spawn Build microservices # Check status npx claude-flow hive-mind status从源码结构看当前 v3 CLI 的实际实现比文档骨架更丰富。hive-mind.ts 中注册的子命令共 11 个init、spawn、status、task、join、leave、consensus、broadcast、memory、optimize-memory、shutdown命令别名是hive。下文按初始化 → 生成 → 监控 → 协作 → 生命周期的顺序逐一展开。二、init拓扑与共识算法决定蜂群形态init子命令通过 MCP 工具hive-mind_init创建蜂群基础设施。源码中定义了两组关键枚举TOPOLOGIES / CONSENSUS_STRATEGIES拓扑topology取值含义hierarchicalQueen 领导 worker 的层级结构mesh对等peer-to-peer协调hierarchical-meshQueen 对等通信默认值官方推荐adaptive根据任务动态选择拓扑共识策略consensus取值含义byzantine拜占庭容错2/3 多数可应对恶意节点默认值raft基于 Leader 的共识gossip最终一致性可扩展性好crdt无冲突复制数据类型quorum简单多数投票init的完整参数摘自 initCommand 定义claude-flow hive-mind init -t hierarchical-mesh -c byzantine -m 15 -p --memory-backend hybrid选项短写说明默认值--topology topology-t蜂群拓扑取值见上表hierarchical-mesh--consensus strategy-c共识策略取值见上表byzantine--max-agents n-m最大智能体数量15--persist/ 布尔-p是否持久化状态true--memory-backend backend记忆后端agentdb、sqlite、hybridhybrid交互模式下如果不传--topology/--consensusCLI 会弹出选择菜单让用户挑选action 逻辑。初始化成功后会输出 Hive ID、Queen ID、拓扑、共识策略、最大 agent 数与记忆后端的配置框并提示Queen agent is ready to coordinate worker agents。--format json可直接输出hive-mind_init的原始结果便于脚本消费。命令文档中的--force强制重新初始化与--config file指定配置文件属于 init 的扩展选项见 hive-mind-init.md。三、spawn从生成 worker 到启动 Claude Code 协调会话spawn是 hive-mind 最核心的子命令。文档hive-mind-spawn.md描述其职责为Spawn a Hive Mind swarm with queen-led coordination并列出--queen-typestrategic / tactical / adaptive、--max-workers n、--consensus type、--claude等选项。v3 源码中的实际参数表spawnCommand 定义选项短写说明默认值--count n-n生成 worker 数量1--role role-rworker 角色worker/specialist/scoutworker--type type-t智能体类型worker--prefix prefix-pworker ID 前缀hive-worker--claude生成带 hive-mind 协调提示词的 Claude Code 会话false--objective obj-o蜂群目标配合--claude无--dangerously-skip-permissions跳过 Claude Code 权限确认true--no-auto-permissions关闭自动跳过权限false--dry-run只展示将执行的动作不实际启动false--non-interactive非交互模式运行 Claude Codefalse--mcp-config path传给 worker 的.mcp.json路径可自动探测自动探测常用示例源码内建 examplesclaude-flow hive-mind spawn -n 5 claude-flow hive-mind spawn -n 3 -r specialist claude-flow hive-mind spawn -t coder -p my-coder claude-flow hive-mind spawn --claude -o Build a REST API claude-flow hive-mind spawn -n 5 --claude -o Research AI patterns3.1 MCP 工具调用链spawn先调用 MCP 工具hive-mind_spawn传入count、role、agentType、prefix返回spawned、workers[]含agentId、role、joinedAt、totalWorkers等字段CLI 随后以表格形式打印每个新 worker 的 ID、角色、状态初始为idle与加入时间spawn action。3.2--claude模式自动生成 Queen 协调提示词加--claude后CLI 会走一条完整的提示词生成 → 落盘 → 拉起 Claude Code链路spawnClaudeCodeInstance生成协调提示词。generateHiveMindPrompt 生成一份完整的 Queen coordinator 系统提示词内容包含Swarm ID / 目标 / Queen Type缺省strategic/ 拓扑缺省hierarchical-mesh/ 共识算法缺省byzantine、按类型分组的 worker 分布以及一套 Hive Mind 执行协议初始化 → 任务分发 → 协调 → 收尾四阶段。提示词中还内嵌了可用 MCP 工具清单如hive-mind_consensus、hive-mind_memory、hive-mind_broadcast、hive-mind_status、task_create、agent_spawn等并要求所有编排操作优先走mcp__ruflo__*工具。提示词落盘。写入.hive-mind/sessions/hive-mind-prompt-swarmId.txt这是后续resume能力的基础见第七节。MCP 配置解析。这是排障重点源码注释记录了两个真实修复。其一issue #1748——若不给 worker 传--mcp-config生成的提示词会引用 worker 根本不认识的mcp__ruflo__*工具导致其静默退出解析顺序为显式--mcp-config标志 → 当前目录./.mcp.json→~/.claude.json→~/.claude/mcp.json配置探测逻辑。其二issue #1780——Claude Code 的--mcp-config是可变参数按两个 argv token 传递会把后面的提示词文本误吞成第二个配置文件路径触发ENAMETOOLONG因此源码改用--mcp-configpath等号语法。权限与交互控制。--dangerously-skip-permissions采用严格布尔判断 true避免undefined被误判为跳过权限且--no-auto-permissions是否定开关可覆盖前者权限判断。--non-interactive会给子进程追加-p --output-format stream-json --verbose。等待子进程退出。源码注释issue #2297说明如果不 await 子进程退出CLI 主进程会提前结束正在初始化的claude子进程会丢失控制终端而在启动中途被杀表现为下一个 shell 提示符前泄漏出多余的XTVERSION回复修复后还会让非交互路径只在 Claude Code 真正完成后才返回。--dry-run模式下不会真正拉起进程只打印提示词长度与前 500 字符预览并告知完整提示词已保存的位置适合先检查生成的 Queen 提示词是否合理。若 PATH 中找不到 Claude Code CLICLI 会降级为手动执行说明提示npm install -g anthropic-ai/claude-code并给出claude promptFile、cat promptFile | claude等手动喂入提示词的命令。即使生成协调提示词的过程抛异常CLI 也会把提示词兜底写入hive-mind-prompt-swarmId-fallback.txt保证产物不丢fallback 分支。四、status蜂群健康度与指标面板status子命令调用 MCP 工具hive-mind_status默认展示一块Hive Mind Status信息框Hive ID、整体状态、拓扑、共识算法以及 Queen 的状态 / 负载百分比/ 排队任务数status action。随后以表格列出所有 workerID、类型、状态、当前任务、已完成任务数worker 列表为空时会提示用spawn添加。参数与进阶输出claude-flow hive-mind status # 基本状态 claude-flow hive-mind status -d # 附带详细指标 claude-flow hive-mind status -w # 监听变化加-d--detailed后会额外输出两张面板指标与健康检查MetricsTotal Tasks、Completed、Failed、Avg Task Timems、Consensus Rounds、Memory UsageHealthOverall / Queen / Workers / Consensus / Memory 五维健康度按healthy绿、warning/degraded黄、critical红着色。源码对 MCP 返回做了兼容处理状态值兼容active | idle | degraded | offline | running | stoppedworker 条目既可能是对象也可能是纯 ID 字符串都能正常渲染。五、task / broadcast / consensus / join / leave蜂群协作原语5.1 task向蜂群提交任务claude-flow hive-mind task -d Implement auth module claude-flow hive-mind task -d Security review -p critical -c参数-d任务描述必填也可用位置参数、-p优先级low/normal/high/critical默认normal、-c要求共识完成后才算完成、--timeout超时秒数默认300taskCommand。这里有一个值得注意的实现细节源码注释issue #1791.1指出hive-mind_task从未在捆绑的 MCP 服务器中注册过mcp__ruflo__hive-mind_*表面只暴露 init、spawn、status、broadcast、consensus、memory、shutdown、leave 这些工具CLI 早期直接分发到不存在的工具报MCP tool not found: hive-mind_task。现在的做法是改道到已有的task_create工具type固定为hive-mind蜂群专属选项以consensus:required|none与timeout:ns标签形式保留在tags中数据不丢失等待未来的专用 hive-mind worker 工具接棒重路由逻辑。提交成功后提示用claude-flow hive-mind task-status taskId跟踪进度。5.2 broadcast全蜂群广播claude-flow hive-mind broadcast -m Switch to branch feat/x -p high -f queen-1调用hive-mind_broadcast参数为-m消息必填、-p优先级low/normal/high/critical默认normal、-f发送者 agent ID成功输出会给出消息 ID 与接收 worker 数broadcastCommand。5.3 consensus提案与投票claude-flow hive-mind consensus -a list claude-flow hive-mind consensus -a propose -t decision --value use raft claude-flow hive-mind consensus -a vote -p proposalId -v yes --voter-id agent-2consensus子命令统一封装hive-mind_consensus工具-a支持propose/vote/status/list四种动作默认list打印 Pending Proposals 表格-v yes/no会在 CLI 侧归一化为布尔值传入consensusCommand。这与 init 阶段选择的共识算法如byzantine的 2/3 多数配合构成蜂群的关键决策通道。5.4 join / leave动态调整成员claude-flow hive-mind join -a agent-42 -r specialist claude-flow hive-mind leave -a agent-42分别调用hive-mind_join可带-r角色返回totalWorkers与hive-mind_leave返回remainingWorkersjoin/leave对应提示词中的hive-mind_join/hive-mind_leaveMCP 工具支持运行中增减 worker。六、memory / optimize-memory共享记忆与模式优化6.1 memory读写共享记忆claude-flow hive-mind memory -a list claude-flow hive-mind memory -a set -k deploy.env -v staging claude-flow hive-mind memory -a get -k deploy.env claude-flow hive-mind memory -a delete -k deploy.envmemory子命令封装hive-mind_memory工具-a支持get/set/delete/list默认list打印全部 key-k为键、-v为值参数校验保证 get/delete 必须带 keyset 必须同时带 key 和 valuememorySubCommand。共享记忆是 Queen 执行协议中COMPLETION PHASEStore learnings in collective memory的落地载体配合 init 时的--memory-backendagentdb/sqlite/hybrid决定底层存储形态。6.2 optimize-memory压缩与合并模式claude-flow hive-mind optimize-memory -a --threshold 0.7调用hive-mind_optimize-memory参数-a--aggressive激进优化与--threshold模式保留质量阈值默认0.7。返回 before/after 对照表Patterns 数、Memory 占用以及被删除、被合并的模式数与优化耗时optimizeMemoryCommand。长时间运行的蜂群可以定期执行该子命令控制记忆膨胀。七、会话生命周期暂停pause、恢复resume与关闭shutdown命令文档中的resume/stop语义在 v3 实现中映射为三套机制暂停--claude会话运行时按CtrlCCLI 注册的 SIGINT/SIGTERM 处理器会以SIGTERM终止 Claude Code 子进程提示Session paused并打印提示词文件位置与恢复方式——To resume, run claude with the saved prompt fileSIGINT 处理。恢复提示词已持久化在.hive-mind/sessions/hive-mind-prompt-swarmId.txt恢复即是用该文件重新启动claude会话会话目录管理文档见 hive-mind-sessions.md。子进程以stdio: inherit继承终端、shell: false直接执行Windows 下由resolveClaudeLaunchCommand跟随 npm shim 定位真实可执行入口退出码 0 才算成功。关闭shutdown子命令调用hive-mind_shutdown参数-f--force强制关闭与-s--save-state默认true关闭前保存状态。非强制模式下会先弹确认框Shutdown the hive mind? All agents will be terminated.完成后输出终止的 agent 数、状态是否已保存、关闭时间点shutdownCommand。八、MCP 工具面与源码验证从源码结构看CLI 只是薄封装每个子命令的action都通过callMCPTool把参数转发给对应 MCP 工具真正的蜂群状态、共识与记忆逻辑运行在 ruflo 的 MCP 服务器端MCP 侧工具定义见 hive-mind-tools.ts。hive-mind.ts源码注释中可确认的 MCP 工具面为hive-mind_init、hive-mind_spawn、hive-mind_status、hive-mind_broadcast、hive-mind_consensus、hive-mind_memory、hive-mind_shutdown、hive-mind_join、hive-mind_leave、hive-mind_optimize-memory任务提交则复用通用task_create工具。所有错误路径都区分MCPClientError服务端报错直接打印消息与未知异常失败时返回exitCode: 1适合接入 CI 脚本。相关行为还有专门测试覆盖如 hive-mind-skip-permissions.test.ts 验证权限跳过标志的边界行为。九、完整工作流速查# 1. 初始化hierarchical-mesh 拓扑 拜占庭容错共识最多 15 个 agent npx claude-flow hive-mind init -t hierarchical-mesh -c byzantine -m 15 # 2. 生成 5 个 worker并以 Claude Code 启动 Queen 协调会话 npx claude-flow hive-mind spawn -n 5 --claude -o Build microservices # 3. 查看状态含指标与健康度 npx claude-flow hive-mind status -d # 4. 协作操作 npx claude-flow hive-mind task -d Implement auth module -p high -c npx claude-flow hive-mind broadcast -m Review style guide first -p normal npx claude-flow hive-mind consensus -a list # 5. 收尾优化记忆后保存状态并关闭 npx claude-flow hive-mind optimize-memory -a npx claude-flow hive-mind shutdown -s适用前提与限制--claude模式要求本机已安装 Claude Code CLInpm install -g anthropic-ai/claude-code且建议项目内有.mcp.json或运行过ruflo init生成否则 worker 拿不到mcp__ruflo__*工具--dangerously-skip-permissions默认开启在生产环境中建议显式传--no-auto-permissions恢复逐条确认。文档骨架init/spawn/status/resume/stop与源码实现的完整子命令集对照后读者可以按本文路径继续深入 hive-mind.ts 源码 与同目录下的 consensus 文档、memory 文档、metrics 文档 等文件获得参数级的细节补充。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考