TaskSwarm · 任务蜂群

多 Agent 编排引擎：把一个目标拆成任务树，按依赖波次并行派发子代理，用共享看板让互不可见的子代理"看见"彼此。MCP 服务端零依赖、三平台共用（ZCode / dsh / Codex CLI）。

English | 中文

平台适配现状

一份 mcp/server.mjs，三个宿主共用——差异只在"谁派发子代理、子代理能不能说话"。

结论：看板通道在所有宿主可用——这就是跨平台的意义。dsh 另有子代理 ↔ 父代理直连通道， 能力比 ZCode 版更强（看板从"唯一通道"降级为"公共黑板 + 持久化事实源"）。

验证边界（不夸大）：三个宿主里，只有 ZCode 是端到端跑过真实蜂群的（本插件诞生于此， 172 个测试全部跑在该路径上）。dsh 验证到"MCP 链路 + 11 工具 + 依赖守卫"这一层（以 dsh-mcp-client 相同的方式逐步驱动）；Codex 验证到"MCP 挂载成功"。两边的"模型驱动完整蜂群" 都还没跑过——测试当日所有可用中转 key 余额不足。Codex 另有一项版本相关风险： 子代理能否继承父会话的 MCP 工具随版本变化，需自行验证。详见各 adapters/ 文档的实测记录表。

适配配置与实测记录见 adapters/dsh/ 与 adapters/codex/。

Related MCP server: bothy-board

30 秒看懂

单个 AI 子代理能力很强，但一次只能干一件线性的事。面对"重构登录模块 + 补齐测试 + 更新文档"这种可并行的任务，只能串着做。

TaskSwarm 让主代理把目标拆成任务树，把互不依赖的部分同时派给多个后台子代理，再用一块共享看板让它们交换进度——最后主代理收波、转发关键产出、汇总。

一个目标  →  任务树（带依赖）  →  按波次并行派发  →  共享看板互通  →  汇总

核心设计洞察：子代理之间没有通信能力

这是本插件要解决的根本约束，也是它与"主代理随手开几个子代理"最大的不同。 （下述探测在 ZCode 上做的；dsh 的子代理体系更完整，见 平台适配现状。）

我在实现前先做了能力探测，实测结论：

也就是说：子代理是一群"哑"worker——干得了活，喊不了话，也生不出小代理。

这个约束直接决定了两条通信通道：

1. 看板拉取（默认通道）：子代理通过 MCP 主动读写共享看板。领任务用 task_claim、汇报进度用 task_update、了解全队状态用 board、读同伴的完整结论用 task_notes。因为是"拉取"，子代理永远不需要别人主动通知它。看板可读也可写——任何代理都能给任意任务卡留言（task_update 的 owner 校验只管状态变更），这是子代理之间真正的双向通道。

   3.0 把收信体验补齐了：task_claim 的返回带全量历史笔记（领取即开工，不必二次查询）；board 每任务给最近 2 条摘要（各 80 字符）+ 总数提示；留言不再抢占任务归属。仍然保留的拉取语义：子代理侧没有订阅式推送（有 rev 版本号可轮询对比、可选 webhook 推给外部集成），人类侧由 Web 控制台的 SSE 实时刷新。

2. 主代理推送（补强通道）：主代理是唯一有 SendMessage 的角色，因此它承担"信息搬运工"：派发新任务时把上游产出写进子代理 prompt；收到某子代理完成通知后，把关键结论转发给正在跑的、与之相关的其他子代理。这条通道我做了实测，而且两种状态都通：给一个正在执行长任务的子代理推送带验证码的消息，它中途收到且没被打断；给一个已经置 done 的子代理推送追问，它被在后台唤醒续跑，并保留了完整上下文——能从自己先前写的示例数据反推出费率、承认原稿缺陷、并主动把补订结论写回自己的任务卡。所以"追问一个已完成的同伴"是可行的，只是必须经主代理这一跳。

（可编辑源文件：docs/architecture.drawio）

为什么不能直接用现成的

调研结论（2026-09）：Claude Flow / Ruflo（61k★）、barkain/claude-code-workflow-orchestration、Agent Teams 都是 Claude Code 专用，依赖 ZCode 没有的 TaskCreate / TeamCreate / hooks 实验机制，无法移植。

而 ZCode 这边：原生子代理可以调用 MCP 工具（已探针验证），但没有 SendMessage —— 所以互通必须设计成"看板拉取 + 主代理推送"双通道，而不可能靠代理间直连。

（dsh 的情况更好：它原生提供 send_message / report / list_agents，子代理与父代理可直连。 本插件的看板通道在这两个宿主都可用，dsh 上还能叠加直连通道。）

本插件的架构是 「MCP 提供确定性能力 + SKILL.md 提供编排流程」：

• 确定性部分全部下沉到 MCP Server：任务树存储、依赖判定、防重复领取、并发写盘、看板渲染、笔记分页。这些是"有明确正确答案"的事，不该交给 LLM 每次自由发挥。

• 编排循环留给主代理：何时拆解、拆多细、派给谁、何时收波、如何转发——这些需要判断力，ZCode 没有插件级调度 API 可挂，主代理本身就是调度器。

安装

需要 Node.js ≥ 23.4（内置 node:sqlite），零第三方依赖。

git clone https://github.com/Wersky/taskswarm.git
npm link   # 可选：把 taskswarm（CLI）/ taskswarm-mcp（MCP server）挂进 PATH

ZCode

设置 → 插件管理 → 发现 → 「+」添加本地目录市场，指向包含 marketplace.json 的目录，安装 taskswarm，重启会话。

插件清单使用 ${ZCODE_PLUGIN_ROOT} / ${ZCODE_PROJECT_DIR} 占位符，不硬编码任何本机绝对路径——换台机器克隆下来即可运行。

dsh（DeepSeek Harness）

把 adapters/dsh/cordis.patch.yml 的 insert 段加进你的 profile patch，改掉 args 里的路径：

- insert:
    - id: mcp-taskswarm
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: taskswarm
        transport: stdio
        command: node
        args: ['/你的路径/taskswarm/mcp/server.mjs']

dsh --profile <name> --dump-config | grep mcp-taskswarm   # 确认加载

Codex CLI

codex mcp add taskswarm -- node /你的路径/taskswarm/mcp/server.mjs
codex mcp list

注意 Codex 0.154+ 的 provider 只支持 wire_api = "responses"。详见 adapters/codex/README.md。

使用

/swarm 重构登录模块并补齐测试

或者直接说「任务蜂群：<任务>」「把任务拆解并行处理」。

主代理会展示拆解出的任务树，按依赖波次派发，过程中你可以随时看板：

[T1] (done)        抽出认证接口 @agent-1 💬 接口定稿在 src/auth/types.ts，前端可直接引用
[T2] (in_progress) 重写登录流程 @agent-2 💬 已接通新接口，正在补错误分支
[T3] (pending)     更新登录文档 ← 依赖: T1

什么时候不该用

• < 3 个子项：拆解开销大于并行收益，主代理直接做。

• 强串行依赖：拆了也是一波一波等，没有并行度。

• 需要频繁来回讨论：用圆桌讨论（roundtable 插件）更合适。

• 单纯查资料 / 读代码：Explore 子代理更省。

一条硬规则：改同一批文件的子任务必须串行

并行最常见的翻车方式，是让两个子代理同时改同一个文件——后写的覆盖先写的，而且双方都以为自己成功了。拆解时凡是要动同一批文件的任务，必须用 dependsOn 串起来。

PPR 审核门（2.1.0）

给任务配 reviewer 即启用审核门——未过审时下游不可派发，由机制保证而非约定：

producer 置 done ──▶ 改道 pending_review ──▶ 下游被阻断
                                              │
                      reviewer task_review ───┴──▶ approve: 转 done，下游放行
                                                    reject : 回 in_progress，下游继续阻断

• pending_review 不在「已完成」集合里，所以 task_ready / task_claim 自动拦住下游；

• 驳回必带理由（写入任务笔记，producer 据此重做）；重做交活会重新进入待审核；

• 仅登记的 reviewer 本人可裁决，主代理可用 force:true 代裁（留审计事件）；

• 支持多级审核链（A 过审 → B 开始 → B 过审 → C 放行）；

• 不配 reviewer 行为完全不变（向后兼容）。

配合 swarmbridge 的 plan 消息可做跨机器 PPR：对方发计划（含 role/reviewer 分工）→ 本地建任务树继承审核者 → 本地跑审核门 → 结果回报。

提案与采纳回路（2.2.0）

审核门管「产出合不合格」，提案回路管「计划要不要改」——子代理干活时最清楚原计划缺了什么。

• 提：producer 遇到阻塞或有更好方案，用 swarmbridge 的 proposal 消息发到桥线程（data = {forTask?, problem?, items?, rationale?}）；单机场景可直接写 task_update 笔记，由主代理转发。

• 采：reviewer 认为建议合理，就在 task_review 里带上 proposals——过审的同时新计划项自动进树（可带 role/reviewer/assignee/dependsOn），返回 adopted:{count, ids}。

• 派：主代理按新任务的 assignee 提示分派。assignee 只是建议执行者，不影响 task_claim 的领取权限（与触发审核门的 reviewer 本质不同）。

• 驳回不采纳：reject 会完全忽略 proposals，驳回不得夹带新任务。

• 采纳是原子的：任一项不合法（缺 title、role 非法、依赖不存在）则整批不加，任务树保持原样。

Web 控制台（3.0 新增）

人类观察与审批的界面。与 MCP server 共享同一状态库、同一审核函数——控制台审批不绕状态机：

node ui/server.mjs --workspace <项目目录> --reviewer <审核者身份> [--port 7788]

• 泳道看板（待办 / 进行中 / 待审核 / 已完成 / 失败跳过），任务点开见笔记全文与事件流；

• 待审核任务直接在页面裁决：通过（下游放行）/ 打回（必填理由，写进任务笔记）；

• SSE 实时刷新，零构建（内嵌单页原生 JS），默认只监听 127.0.0.1（无鉴权，勿暴露公网）；

• 可选 TASKSWARM_WEBHOOK_URL：每次写事务 POST {rev, events} 给外部集成。

CLI（3.1 新增）

没有 MCP 宿主的场合（cron、CI、shell 管道、不支持 MCP 的工具），用命令行直接驱动同一个状态库：

node cli/taskswarm.mjs plan-create --goal "重构登录" --tasks-file tasks.json   # 建任务树
node cli/taskswarm.mjs ready                              # 查可派发任务
node cli/taskswarm.mjs claim T1 --owner agent-1            # 原子领取（返回体含上游笔记）
node cli/taskswarm.mjs update T1 --status done --owner agent-1 --note "收工" --cost-tokens 4200
node cli/taskswarm.mjs review T2 --verdict approve --owner reviewer-1       # PPR 裁决
node cli/taskswarm.mjs board                              # 共享看板 + 成本汇总
node cli/taskswarm.mjs serve --workspace . --reviewer reviewer-1            # 一键拉起 Web 控制台

• 与 MCP server 完全同层：同一个 core.mjs、同一个 SQLite 状态库、同一套状态机守卫——CLI 写入与 MCP 写入互相可见，PPR 审核门在 CLI 下同样生效；

• 成功输出 JSON 到 stdout，失败输出 {"error":...} 到 stderr 并退出 1，方便脚本分支；写操作前同样触发失联任务惰性回收；

• 任务数组文件收纯数组或整个 {goal, tasks} 对象，- 表示 stdin；

• 全部命令支持 --workspace <目录>（缺省 = 当前目录）；npm link 后可直接 taskswarm <命令>。

企业版能力（4.0 新增）

面向「凌晨两点出事时能查清、能恢复、能追责」的那部分需求——访问控制与审计。

控制台访问令牌（opt-in）

node ui/server.mjs --workspace <项目目录> --reviewer <身份> --token <访问令牌>
# 或环境变量：TASKSWARM_CONSOLE_TOKEN

• 配置后所有路由（静态页、/api/*、SSE 实时流）统一过认证门：请求头 Authorization: Bearer <t> 或 URL ?token=<t>（浏览器访问直接在 URL 带参数即可，页面内 fetch/SSE 自动透传）；

• 令牌对比先 sha256 归一再 crypto.timingSafeEqual——无长度泄露、无时序侧信道；

• 不配置令牌时行为与 3.x 完全一致（本机回环使用，测试锁定向后兼容）。配置后即可安全暴露到团队内网 / VPC；

• 审批身份（--reviewer）与访问令牌（--token）是两道独立的门：前者管「谁在裁决」，后者管「谁能进来」。

审计导出

完整事件时间线一键导出——历史归档（events-archive-*.jsonl，按序号在前）+ 库内现存事件，附计数与导出摘要 sha256（校验导出件完整性）：

node cli/taskswarm.mjs audit                      # JSONL 到 stdout（纯事件流，管道友好）
node cli/taskswarm.mjs audit --format json        # 含计数与 sha256 的完整对象
node cli/taskswarm.mjs audit --format jsonl --file audit.jsonl   # 落文件，摘要走 stderr
curl -H 'Authorization: Bearer <令牌>' http://127.0.0.1:7788/api/export   # 控制台入口（受令牌保护）

• events 表只追加不删除（超限部分导出到归档文件，eventsDroppedTotal 记账）——导出 = 归档 + 现存，总数守恒；

• sha256 是导出完整性摘要（校验传输/归档过程没丢没坏），不是防篡改链——库内防篡改依赖文件系统权限与「事件只追加」的写入纪律。

多租户与部署形态（口径说明）

• 租户边界 = 工作区边界：每 workspace 一份独立 SQLite 库（<workspace>/任务蜂群/），结构上不存在跨工作区查询路径——隔离是物理的，不是靠查询过滤；

• on-prem 天生满足：零依赖单库文件，数据不出机器；不需要 SaaS 也能用上全部能力（这是与 LangGraph 平台们相反的取舍——我们把数据自主当卖点，不当负担）；

• 尚未做（按客户要求再加）：多租户网关、SSO/LDAP 对接、配额计费、SLA——当前形态定位「团队内网部署的自托管协调层」。

MCP 工具

真实工具名前缀是 mcp__plugin_taskswarm_taskswarm__，例如 mcp__plugin_taskswarm_taskswarm__task_claim。

所有调用都要显式传 workspace（工作区绝对路径）——省略时会落到 server 进程的 cwd，而不是你以为的地方。这条行为有测试锁定（storage-failure.test.mjs 的「省略 workspace 时回退到进程 cwd」）。

测试与可靠性

172 个测试，全部通过；行覆盖 85.0%，函数覆盖 96.0%（口径为 cli/core/server 三文件共 1849 行，绝对覆盖行数 1572 —— 未覆盖部分集中在防御性错误分支、usage 帮助文本与极端锁竞争路径。ui/server.mjs 的控制台链路由 ui/enterprise 测试真实覆盖，但 Windows 下测试以 TerminateProcess 结束子进程、V8 覆盖率数据无法落盘，故不计入本表——这是平台语义，不是未测试）。

npm test          # 172 tests, 0 fail
npm run coverage  # 行覆盖 85.0% (1572/1849) · 函数覆盖 96.0% (170/177)

要求 Node ≥ 23.4（内置 node:sqlite），无任何测试框架依赖（用内置 node:test + node:assert/strict）。

测试为什么全部走子进程

本插件的可靠性承诺——多进程并发写不损坏数据、同一任务不会被重复领取——只有在多个真实进程共享同一个状态文件时才成立。同进程内的 Promise 并发测不出任何东西（事件循环天然串行）。因此所有测试都通过 spawn 启动真实的 MCP server 进程，与生产运行方式完全一致。

这套测试抓出过的真实缺陷

开发和审计过程中，测试（以及另写的独立复现脚本）定位并锁定了以下问题，现在它们都有回归防线：

其中最值得说的一点：board 按 owner 过滤的原版测试断言写成了 !A || B 的形式——后半句恒为真，过滤功能完全失效时测试也会通过。新套件改成了双向断言（甲的视图必须含甲、必须不含乙），并额外校验 activeWorkers 也被过滤（这个字段原来确实漏了过滤，是新测试抓出来的）。

可靠性机制

• 原子替换写盘：写 <file>.tmp-<pid> → fsync → rename。读者永远看不到半截文件（8 次写入中强杀测试零损坏）。

• 跨进程文件锁：openSync(lock, 'wx') 原子加锁，持锁者记录 {pid, at, host}；崩溃残留的陈旧锁通过 PID 存活探测 或 锁龄超时 自动抢占，并留下「锁抢占」日志。

• 损坏自愈：解析失败时先备份原文件再报错，绝不静默当成"没有计划"。

• 失败语义可控：默认上游失败即挡住下游（避免在残缺基础上继续盖楼）；允许带缺陷推进时用 proceed，并在 task_ready 里用 blockedBy 标明是哪个上游出的问题。

• force 是审计机制，不是权限机制：MCP 协议层无法验证"你是不是主代理"，任何调用方都可传 force:true。它的价值在于留下可追溯的审计事件（记录操作者、原 owner、状态迁移），而不是阻止别人。这个边界有专门的测试锁定，防止后人误以为它有防护能力。

工程要点

• 零依赖：只用 Node 内置模块（fs / path / readline / os / node:sqlite / node:http），没有 package-lock 与供应链风险。核心约 2200 行（core 1650 + 协议层 170 + 控制台 340）。

• 可移植：插件清单用占位符；裸 node 启动（有测试从无关 cwd 启动验证）。

• 覆盖率统计的坑：node --experimental-test-coverage 对子进程里跑的代码一无所知——直接跑会得到"0 个文件、100%"的空报告。因此写了 scripts/coverage.mjs：用 NODE_V8_COVERAGE 收集每个子进程的 V8 覆盖率再合并，按「覆盖该行的最内层 range」判定。该脚本先在已知答案的受控样本上验证过才用于正式统计（含一个刻意不调用的函数与一个未走到的分支，确认能正确判为未覆盖）。

• 测试用优雅退出：helpers.mjs 的 kill() 先关 stdin 让 server 正常 exit(0)，超时才强杀——否则 V8 来不及写出覆盖率数据。需要模拟崩溃的场景显式用 killHard()。

Roadmap

• 子代理心跳与超时自动回收（3.0：TASKSWARM_STALE_MINUTES 惰性回收 + 审计事件）

• 任务产出物登记（结构化记录每个任务的产物路径，便于汇总与验收）

• 跨工作区蜂群（当前状态文件按工作区隔离）

• 与 roundtable 插件的组合流程（讨论定方案 → 蜂群做执行）

已知限制

• 并行度：单波建议 ≤ 4 个后台子代理，实测更多会因上下文切换与 token 开销反噬收益。

• 环境要求 Node ≥ 23.4：存储用内置 node:sqlite（3.0 起），旧版 Node 启动即报错。

• MCP 侧仍是拉取语义：子代理互通靠看板轮询（有 rev 对比与可选 webhook 缓解延迟），没有订阅式推送；人类侧有控制台 SSE 实时刷新。

• 控制台无鉴权：只监听 127.0.0.1，不要用 --host 暴露到不受信任的网络。

• 终态回退收紧：曾经过审核门的任务，done/skipped → pending 只有 reviewer 本人（或主代理 force）可执行；failed → pending 保持 owner 可。

• force 非安全边界：见上文"可靠性机制"末条。

• 多蜂群共用工作区会共享状态库：长期任务请用独立工作区。

ZCode 动态工作流宿主（swarm-run 模式）

ZCode 内置的「动态工作流」把编排循环写成确定性 TypeScript 脚本，确认后由 runtime 自动执行；其子代理可完整调用 taskswarm MCP 工具（2026-09-19 实测：工作流内 actor 一次走通 task_claim → task_update → task_notes，服务端事件时间戳与产物字节级核验一致）。

用脚本当调度器、看板当事实源：依赖波次、PPR 审核门、防重复领取仍由 MCP 服务端机制性执行，脚本绕不过去；省掉的是主会话每波一次的 token 消耗与编排记忆。

• 姿势：主代理 plan_create 建好任务树 → CreateWorkflow { saved: "swarm-run", args: { maxRounds?, workersPerRound? } }。每轮 = N 个工人（领→干→done）+ 1 个专职审核员（对 pending_review 真实核对产出物后裁决；工人 prompt 明令禁止 task_review，审核独立性由脚本角色分离保证）+ 只读核验员，直到任务树清空收敛。

• 实测：3 任务计划（T2 带审核门、T3 压双依赖）3 轮收敛；「审核门拦截 → wf-reviewer 通过」时序逐条对齐，T3 在过审后 56 秒才进入 ready 队列，机制性阻断成立。

• 断点恢复：一次 provider 故障把在做 T3 的工人打断在 claimed，ResumeWorkflowRun 后同名 actor 以原 owner 接回任务直接干完——原先「force:true 手动置回 pending」的恢复路径多数场景不再需要。

• 何时仍用主代理调度：执行中要频繁 task_add/proposals 改计划、或需要用户随时插话纠偏——工作流改编排结构要 Amend 换脚本，粒度粗。

• 未实测：reject 打回重做回路、跨机（swarmbridge）联动、大计划下的 token 账单对比。

swarm-run 脚本体是宿主项目资产（.zcode/workflows/swarm-run.dwf.ts），不随插件分发。

姊妹插件（蜂群套件）

三个插件同属一套「蜂群」套件，各司其职，可独立使用、组合互通：

推荐组合：圆桌讨论定方案 → TaskSwarm 拆任务执行；跨机协作时用 SwarmBridge 分发计划与回报结果（见上文「跨机器 PPR」）。

License

MIT © 2026 Wersky

TaskSwarm is a multi-agent orchestration engine: decompose a goal into a task tree, dispatch subagents in dependency waves, and let mutually-invisible subagents coordinate through a shared MCP board. One zero-dependency MCP server, shared across ZCode / dsh / Codex CLI.

Platform adaptation. The MCP server is identical everywhere; only the delegation layer differs. ZCode uses Agent + SendMessage; dsh uses its native subagent / send_message / report / list_agents (richer — subagents can talk back to the orchestrator); Codex CLI wires the same server via [mcp_servers.taskswarm]. See adapters/ for configs and per-platform verification records.

Core insight. Subagents in ZCode have no SendMessage and no Agent tool (verified by probing) — they can work, but they cannot talk to each other. This single constraint shapes the whole design: coordination must happen through two channels, (1) board pull — subagents read/write a shared MCP board (task_claim / task_update / board / task_notes), and (2) orchestrator push — the main agent is the only role with SendMessage, so it forwards key results between running subagents (verified working: a code sent mid-task reached a running subagent).

Deterministic work lives in the MCP server (task tree, dependency resolution, atomic claiming, crash-safe persistence, board rendering); the orchestration loop lives in the main agent (what to decompose, whom to dispatch, when to collect). Zero third-party dependencies.

Reliability. 123 tests (all passing), 90.3% line / 98.0% function coverage. Every test drives a real spawned MCP server process, because the guarantees that matter — no data corruption under concurrent multi-process writes, no double-claiming of the same task — only exist across processes. Measured: two processes appending 120 notes each previously corrupted the state file (217 tool errors, unrecoverable plan loss) and 60 concurrent claim attempts double-claimed 4 times; both are now zero, locked by regression tests. Writes are atomic (temp → fsync → rename) behind a cross-process file lock with stale-lock recovery; corrupt files are backed up rather than silently discarded.

MIT © 2026 Wersky