ruflo-swarm 插件实战：在 Ruflo 中编排多 Agent 蜂群、拓扑防漂移与实时监控流-平芜编程栈

ruflo-swarm 插件实战：在 Ruflo 中编排多 Agent 蜂群、拓扑防漂移与实时监控流

【免费下载链接】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-swarm 是 Ruflo 项目（原 agent meta-harness）中负责多 Agent 蜂群（swarm）协调的官方插件，它把@claude-flow/cli的 12 个 MCP 工具、Claude Code 原生多 Agent 工具（Task/SendMessage/Monitor）、Git worktree 隔离以及 AgentDB 命名空间协调打包成一个可插拔的契约单元。读完本文，你将掌握：如何在 Ruflo 中初始化一个带防漂移配置的蜂群、如何通过 Monitor 流实时观测 swarm 事件、如何在 6 种拓扑（hierarchical、mesh、hierarchical-mesh、ring、star、adaptive）中为不同规模的团队选择合适的编排策略，以及如何用smoke.sh以契约方式验证插件自身的完整性。

插件定位与能力总览

根据插件清单（v0.2.1），ruflo-swarm 的核心描述是：

Agent teams, swarm coordination, Monitor streams, and worktree isolation — wraps 4swarm_*+ 8agent_*MCP tools (12 total) plus 6 topologies (hierarchical / mesh / hierarchical-mesh / ring / star / adaptive)

它并非一个独立的 swarm 引擎，而是一个协调层契约：底层运行时由@claude-flow/cli提供，插件负责把 MCP 工具面、拓扑选项、防漂移默认值、命名空间与验证脚本固化下来。插件自带 2 个 Agent（coordinator、architect）、2 个 Skill（swarm-init、monitor-stream）和 2 个命令（/swarm、/watch）。

功能清单

能力	说明
Agent Teams	集成`TeamCreate`、`SendMessage`、`Task`工具，实现多 Agent 协调
Topologies	hierarchical、mesh、hierarchical-mesh、ring、star、adaptive 六种拓扑
Monitor Streams	通过`Monitor("npx @claude-flow/cli@latest swarm watch --stream")`实时获取 swarm 状态
Worktree Isolation	每个 Agent 在自己的 git worktree 中工作，避免并行编辑冲突
Hive-Mind Consensus	Byzantine、Raft、Gossip、CRDT、Quorum 五种共识策略
Anti-Drift	以 hierarchical 拓扑 + specialized 策略实现紧密协调，防止 Agent 漂移

依赖与兼容性

前置依赖：必须安装ruflo-core插件（由它提供 MCP server）。
CLI 版本：固定绑定（pin）到@claude-flow/cliv3.6 的 major+minor 版本，这是 smoke.sh 第 5 项检查强制校验的契约。

安装与加载

在 Ruflo 中通过插件市场命令安装：

/plugin marketplace add ruvnet/ruflo /plugin install ruflo-swarm@ruflo

第一条命令把ruvnet/ruflo仓库注册为插件市场源，第二条从该市场安装ruflo-swarm插件。安装后插件即注册了自身的 MCP 工具前缀（mcp__plugin_ruflo-core_ruflo__swarm_*）与命令、技能。

MCP 工具面：12 个工具的完整契约

ruflo-swarm 包装了 12 个 MCP 工具，分布在两个家族中（详见 ADR-0001）：

Family	Count	Tools
`swarm_*`	4	`swarm_init`、`swarm_status`、`swarm_shutdown`、`swarm_health`
`agent_*`	8	`agent_spawn`、`agent_execute`、`agent_terminate`、`agent_status`、`agent_list`、`agent_pool`、`agent_health`、`agent_update`

对应的源码实现位于 v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts 与v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts。从源码可以确认几个关键实现细节：

swarm 状态持久化：loadSwarmStore()（swarm-tools.ts#L136）每次加载都会做孤儿 swarm 对账（reconcileOrphanSwarms），保证swarm_status/swarm_health永远不会看到"幽灵"运行条目（源码注释 #1799）。
swarm_init 的场景判定（swarm-tools.ts#L249）：官方描述明确说明——只有当需要多 Agent 协调（拓扑、共识、共享内存命名空间、防漂移门控）时才使用swarm_init；对于独立的单次子任务，直接用原生Task工具逐个 spawn 即可。这是一个重要的使用边界。
swarm_status 支持缺省查询（swarm-tools.ts#L394）：swarmId可省略，省略时返回最近创建的 swarm；若无任何活跃 swarm，返回status: "no_swarm"与提示信息。
agent 与 swarm 联动：agent_spawn会向swarm.agents字段写入（源码注释 #2085），该字段正是swarm_status读取的数据源，因此 spawn 后立即 status 即可看到新成员。

CLI 映射

插件自带的/swarm命令（commands/swarm.md）把这 4 个swarm_*工具映射为 CLI 子命令：

npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized npx @claude-flow/cli@latest swarm status npx @claude-flow/cli@latest swarm health npx @claude-flow/cli@latest swarm shutdown

若/swarm不带参数，默认展示 swarm 状态；init 之后建议用 Claude Code 的Task工具（run_in_background: true）并行 spawn 各 Agent。

与 Claude Code 原生多 Agent 工具的配对

ruflo-swarm 的一个重要设计是：不需要 MCP 也能完成基础协调。它直接配对 Claude Code 的内置多 Agent 工具，MCP 层只负责需要持久状态、拓扑与共识的复杂场景：

工具	用途
`Task`	派生子 Agent。用`name:`让子 Agent 可寻址；加`run_in_background: true`实现并行执行
`SendMessage`	Agent 间通信（仅限已命名的 Agent）
`TaskCreate / TaskList / TaskGet / TaskUpdate / TaskOutput / TaskStop`	面向 swarm 流水线的共享任务跟踪器
`Monitor`	从长时运行进程实时流式推送事件（`persistent: true`），是`/loop`的主要唤醒信号
`EnterWorktree / ExitWorktree`	每个 Agent 独立的 git worktree 隔离

/watch命令（commands/watch.md）就是 Monitor 流的典型封装：

npx @claude-flow/cli@latest swarm watch --stream

输出是 NDJSON 事件流，每行一个事件（agent spawn、task update、memory write、health ping），事件发生时即推送通知，无需轮询。一次性状态查询请改用/status或swarm status。

对应的monitor-stream技能（skills/monitor-stream/SKILL.md）进一步规定：优先用 Monitor 流式观测而非在循环里轮询swarm status（其理由记录在 ADR-091），一次性查询走 MCP 的swarm_status/swarm_health。

防漂移默认值：让编码蜂群不跑偏

对于编码类蜂群，README 依据 CLAUDE.md 给出了防止 Agent 漂移（各 Agent 各自为政、重复劳动、边界模糊）的规范默认值：

设置	值	理由
`topology`	`hierarchical`	协调者（coordinator）能及时捕获分歧
`maxAgents`	6–8	更小的团队 = 更少的漂移
`strategy`	`specialized`	角色清晰、互不重叠
`consensus`	`raft`	领导者维护权威状态
`memory`	`hybrid`	SQLite + AgentDB，兼顾快速与持久

超过 10 个 Agent 的团队应改用hierarchical-mesh（queen + peer 通信）：

npx @claude-flow/cli@latest swarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized

从技能看标准的 swarm 启动姿势

swarm-init技能（skills/swarm-init/SKILL.md）给出了完整启动流程，并明确了适用边界：3 个以上协调 Agent 的复杂多文件任务（功能实现、跨模块重构、安全审计）才初始化 swarm；单文件修改或快速问答直接跳过。

两种初始化方式等价：

# CLI 方式 npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized

// MCP 方式 mcp__plugin_ruflo-core_ruflo__swarm_init({ "topology": "hierarchical", "maxAgents": 8, "strategy": "specialized" })

初始化后在一条消息里用Task工具 spawn 所有命名 Agent：name:保证SendMessage可寻址，run_in_background: true保证并行执行；随后为每个 Agent 执行EnterWorktree做 git 安全的并行工作，用SendMessage做 Agent 间协调。

内置 Agent 的职责划分

插件自带的coordinatorAgent（agents/coordinator.md）是 hierarchical 拓扑里的核心角色，其生命周期管理包括：

npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized npx @claude-flow/cli@latest hooks session-start --session-id "SESSION_ID" npx @claude-flow/cli@latest hooks route --task "DESCRIPTION" # 把任务路由到最优 Agent # ... 监控进度并重分配停滞任务 ... npx @claude-flow/cli@latest hooks session-end --export-metrics true

coordinator 的防漂移纪律：Agent 数量保持 6–8、使用 specialized 策略避免角色重叠、每个任务完成后跑post-taskhook 用于学习、协调决策存入swarm内存命名空间。完成一个 swarm 周期后，还可以把协调结果喂给神经学习层：

npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true

architectAgent（agents/architect.md）则负责在编码开始前产出实现方案与契约：先memory search --query "research-TOPIC" --namespace tasks检索历史设计，定义模块边界与 API 契约，评估安全/性能/兼容性风险，再用memory store --key "design-FEATURE" --value "DECISIONS" --namespace tasks持久化决策，最后hooks post-task上报。

命名空间协调：`swarm-state`的归属

ruflo-swarm 声明对 AgentDB 的swarm-state命名空间拥有所有权（kebab-case 命名，遵循 ruflo-agentdb ADR-0001 "Namespace convention" 的约定）。保留命名空间（pattern、claude-memories、default）禁止被遮蔽。

swarm-state索引了三类数据：活跃 swarm、Agent 分配关系、拓扑快照。外部通过memory_*工具（按命名空间路由）访问：

npx @claude-flow/cli@latest memory search --query "active swarm" --namespace swarm-state

验证：smoke 即契约

插件把 scripts/smoke.sh 定义为契约——它不是一个可选的测试脚本，而是插件发布与变更的门禁：

bash plugins/ruflo-swarm/scripts/smoke.sh # Expected: "11 passed, 0 failed"

11 项结构化检查逐条对应 ADR-0001 的决策项：

plugin.json声明 v0.2.1 且包含新关键词（mcp、topologies、worktree-isolation、monitor-stream）；
2 个技能 + 2 个 Agent + 2 个命令齐备且 frontmatter 合法；
4 个swarm_*MCP 工具全部被文档引用；
8 个agent_*MCP 工具全部被文档引用；
README 将@claude-flow/cli固定到 v3.6；
README 引用 ruflo-agentdb 的命名空间约定；
swarm-state命名空间已在 README 中声明归属；
防漂移默认值（hierarchical/specialized/raft + maxAgents 6–8）已文档化；
6 种拓扑全部被文档覆盖；
ADR-0001 存在且状态为Accepted；
技能中不存在allowed-tools: *通配符授权（最小权限原则）。

这套门禁意味着：任何对工具面、拓扑、命名空间或防漂移默认值的变更，都必须同步更新文档并通过 smoke.sh 才能合并，这正是"文档与实现不脱节"的工程保障。

架构决策与相关插件生态

插件唯一的架构决策记录在 docs/adrs/0001-swarm-contract.md（状态 Accepted，2026-05-04 提出、05-09 更新），核心决策包括：README 增补兼容性 pin、12 工具面表格、Monitor/Task 内置工具交叉引用、防漂移指导、swarm-state命名空间声明、验证章节，以及版本号 0.1.0 → 0.2.0 的提升。

在插件生态中，ruflo-swarm 与三个插件协同工作：

ruflo-agentdb— 命名空间约定的所有者，swarm-state的规范来源；
ruflo-autopilot— 为长时运行蜂群提供 270s 缓存感知的/loop心跳；
ruflo-intelligence— 通过hooks_route为每个任务推荐合适的 swarm Agent。

快速上手：三步跑起第一个蜂群

综合以上内容，最小的实战路径是：

# 1. 安装（需先装 ruflo-core） /plugin marketplace add ruvnet/ruflo /plugin install ruflo-swarm@ruflo # 2. 初始化带防漂移默认值的蜂群 npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized # 3. 用 Monitor 流式观测 swarm 事件（替代轮询） # 在 Monitor 工具中运行： # npx @claude-flow/cli@latest swarm watch --stream

随后在一条消息中通过Task工具（name:+run_in_background: true）并行 spawn 各命名 Agent，为每个 AgentEnterWorktree做 git 隔离，并用SendMessage建立 Agent 间通信——一个具备防漂移、实时可观测、并行安全的多 Agent 蜂群就此运转起来。若你的任务规模超过 10 个 Agent，把拓扑切换为hierarchical-mesh即可平滑扩展。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ruflo-swarm 插件实战：在 Ruflo 中编排多 Agent 蜂群、拓扑防漂移与实时监控流