february2015/dsh-taskswarm

⚠️ 临时安装通告（2026-08-17 ~ 08-18）：npm 包 dsh-taskswarm 因清理历史版本被整体删除，需要 24 小时冷却（npm 防抢注保护）。8月17日、8月18日这两天请用 GitHub 安装： dsh plugin add https://github.com/february2015/dsh-taskswarm.git 8月19日起恢复 npm 安装：dsh plugin add dsh-taskswarm，届时本通告移除。

DeepSeek Harness 上的多智能体任务编排插件 —— 把一批任务按依赖排成波次，让多个 AI worker 在相互隔离的环境里并行执行，再自动评审、合并产出。

蜂群（自然隐喻）：蜂后指挥全局，工蜂各自埋头推进自己的任务，成百上千个个体并行协作——正是这个项目做的事：supervisor 先规划波次，worker 再在自己的 lane 里并行执行。

• License: MIT
• 上游: TaskPlane（Pi 生态多智能体编排）—— 本项目的原生移植
• English: README.md

核心特性

• Waves / Lanes 并行编排 —— 按依赖 DAG 把任务排成波次，每波任务并行执行；依赖关系自动分层
• Git worktree 隔离 —— 每个任务（lane）在独立 git worktree 里工作，互不干扰，产物通过 taskswarm/orch 集成分支合并
• 任务包（Task Packets） —— 每个任务 = PROMPT.md（使命/步骤/约束）+ STATUS.md（进度），持久记忆，worker 能扛过上下文重置
• 检查点纪律 —— 步骤边界自动 git commit；worker 崩溃不丢已完成的活
• 跨模型评审（Reviewer） —— 独立 reviewer 按任务 Review Level 评审产出，PASS 才合并，REVISE 打回修订
• 文件邮箱（Mailbox） —— worker ↔ supervisor 异步通信（notify / escalate / request），不依赖共享上下文
• 对话式 Supervisor —— 与你共享会话：wave 完成、lane 失败、批次完成自动汇报；可指挥它 start / pause / abort / integrate / 开 dashboard；通知与提示词中英双语（"用英文汇报"即可切换，自动按你的会话语言判断，写入 .taskswarm/config.json 跨重启生效）
• Web Dashboard —— 本地实时仪表盘，零依赖 node:http + SSE，多仓库多实例、端口自动避让。启动批次时自动拉起并打印链接到会话——同一工作区始终只有一个 dashboard 实例（已运行的会被复用，绝不重复拉起）
• 崩溃可恢复 —— 磁盘状态持久化 + 检查点 + lane 分支保留，进程被杀/重启后可抢救产物、清理残留、重跑
• orch 基线 lane —— 每个 lane 工作树从 taskswarm/orch 集成 HEAD 创建，直接继承此前全部已合并产物，不重造共享代码
• 任务包校验 —— /tswarm-check + npm run check:tasks 让坏格式任务包（ID 缺连字符、缺步骤/验收标准）报出可操作原因，不再静默跳过
• LLM merge agent —— lane 并入 taskswarm/orch 冲突时，独立 merger agent 在 orch worktree 内语义化解冲突；无法解决时 lane 进入 conflict 态并暂停批次等 supervisor 处置

为什么用 TaskSwarm，DSH 不是已经有 subagent 了吗？

DSH 原生 subagent / workflow / goal 是会话式、一次性调度——适合临时委派。TaskSwarm 是架在其上的项目级编排层：

	DSH 原生 subagent	TaskSwarm
任务形态	聊天里一句话	任务包（PROMPT.md / STATUS.md）——可版本化、可批量、可复用
并行度	手动	波次规划：按依赖拓扑分波、每波并行 lane
隔离	共享工作区（写文件会冲突）	git worktree 隔离：每 lane 独立分支 + 检查点，合并进 taskswarm/orch
质量门	无	独立 Reviewer（PASS / REVISE）
可恢复	进程结束即消失	持久批次状态（.taskswarm/batches/*.json）：重启 / resume / 跳过已完成 lane
可观测	盯着聊天	supervisor 事件汇报 + Web Dashboard，批次启动自动拉起、链接打印到会话

快速开始

1. 安装（三选一）

# npm registry
dsh plugin --profile web add dsh-taskswarm

# GitHub
dsh plugin --profile web add https://github.com/february2015/dsh-taskswarm.git

# 本地目录（开发/离线）
git clone https://github.com/february2015/dsh-taskswarm.git && cd dsh-taskswarm
npm install && npm run build
dsh plugin --profile web add $(pwd)

安装后重启 dsh web，插件即生效。

升级已装的版本：dsh plugin --profile web add dsh-taskswarm 对已满足依赖范围的旧版会报 "Already up to date" 不升级；要拉新版本需显式指定：dsh plugin --profile web add dsh-taskswarm@<新版本>（或在该 profile 目录 pnpm update --latest），然后重启 dsh web。

2. 初始化示例任务

/tswarm-init        # 生成两个示例任务包（EXAMPLE-001 / EXAMPLE-002）

3. 预览波次计划（不执行）

/tswarm-plan all    # 展示任务按依赖排成的波次

4. 启动批次

/tswarm all         # 并行执行所有任务；也可以指定任务：/tswarm EXAMPLE-002
/tswarm-status      # 随时查看进度

5. 看 Dashboard

启动批次（/tswarm）会自动启动 dashboard 并把链接打印在会话里，波次执行期间 随时可看进度。手动控制仍然可用：

# DSH 会话内（supervisor 命令）
/tswarm-dashboard

# 独立 CLI —— 安装插件后 bin 即在 PATH 上：
npx taskswarm-dashboard --root <仓库路径>

# 不安装、临时拉取（npm 发布后可用）：
npx --package dsh-taskswarm taskswarm-dashboard --root <仓库路径> [--port 8100] [--no-open]

同一工作区只保留一个 dashboard：若该仓库已有实例在跑（手动启动或上次会话残留）， 会自动探测并复用，不会拉起第二个。

工作原理

TaskSwarm 编排 4 类角色：

角色	职责
Supervisor	规划波次、调度 lane、处理事件、与你对话（你发起 /tswarm 的会话即 supervisor）
Worker	每个任务一个 DSH agent，在隔离的 lane worktree 里逐步推进任务包
Reviewer	独立 agent 评审 worker 产出，给出 PASS / REVISE
Merger	lane 完成后自动把产物合并进 taskswarm/orch 集成分支

Git 模型：

taskswarm/orch            ← 集成分支：所有 lane 产物汇总（常驻，勿手动删除）
taskswarm/<taskId>        ← 每个 lane 的工作分支（含步骤检查点 commit，合并后自动删除）

持久状态（<repo>/.taskswarm/）：

.taskswarm/batches/<batchId>.json   # 批次唯一权威状态（phase + lanes）
.taskswarm/mailbox/<batchId>/       # agent 间消息
.taskswarm/worktrees/_orch/         # 集成分支 worktree
.taskswarm/worktrees/<taskId>/      # 各 lane 的隔离 worktree

命令参考

命令	作用
/tswarm [scope]	启动批次（scope: all / 任务 ID / 路径）
/tswarm-plan [scope]	预览波次计划与依赖图（不执行）
/tswarm-status	查看当前批次 / lane 进度
/tswarm-pause / /tswarm-resume	当前波次结束后暂停 / 恢复。failed lane 也会在该波结束后自动暂停（pauseOnLaneFailure，默认开）——resume 时跳过该失败 lane；要重跑用 /tswarm <taskId>
/tswarm-stop-lane <taskId>	立即停掉单个 lane（终止 worker、标记 failed、保留 worktree/检查点）；同波其他 lane 继续，该波结束后批次暂停等处置
/tswarm-switch-model <taskId> <model>	一条命令更换单个 lane 的模型：停掉它、记录覆盖、自动从下一步重跑（检查点保留）。优先级：覆盖 > workerModel > 父会话默认
/tswarm-abort	当前波次结束后中止（并终止运行中 lane）
/tswarm-deps [scope]	查看依赖图
/tswarm-sessions	列出活跃 lane 及其 worktree
/tswarm-integrate	把 taskswarm/orch 合并进当前工作分支
/tswarm-dashboard	启动 Web Dashboard
/tswarm-init [ID]	生成示例任务包

兼容别名：/orch、/orch-status 等 /orch-* 命令等价。

热更 / HMR 行为

• 配置热更：TaskSwarm 是标准 DSH bundle，配置在 profile 的 cordis.patch.yml 中覆盖后由 DSH 热重载、无需重启。但注意：orchestrator 插件被重载时（例如修改它的配置行），卸载清理会 abort 当前运行中的所有批次——批次运行期间请勿修改 orchestrator 配置。
• 源码热更：DSH 官方在 web profile 上未启用插件源码 HMR（cordis-plugin-hmr 默认禁用）；修改 TaskSwarm 源码需 npm run build 后重启 dsh web 生效。
• 批次可恢复：即使重启，.taskswarm/ 磁盘状态 + 检查点 + lane 分支都会保留；重启后可用 /orch-status 查看，并通过 supervisor 恢复或重跑失败 lane，不丢已完成工作。
• 波次计划在批次启动时固定：wave 结构（几个波、每波哪些任务）持久化且绝不在执行中重算——暂停/恢复、崩溃恢复、单个 lane 重跑都在原始 wave 布局内继续。已完成的波保持完成，剩余任务保留原始波次号，dashboard 与 dingo 的 Wave 分段保持一致。

通知与 Token 效率

supervisor 通知按「省 token 且不丢信息」设计：

• 完善的本地位消息 —— 每条通知（定时汇报 / 波次完成 / lane 失败 / 卡住 / 批次完成）都用 完整、可直接阅读的语言写成（随会话 locale 中/英），例如：

  [TaskSwarm] ⏱️ 定时汇报（每 5 分钟）：
  批次 b-msvinu6n — running（已完成 1/4）· 波次 1/2
    lane 1 [已合并] JM-402 · 步骤 8/8，218 步
  

• supervisor agent 不再翻译/复述 —— 系统提示词明确指示：通知已是完整可读的文本， 不要翻译、不要复述；只判断是否有异常或需要动作——有就简要处理/汇报，没有就保持安静或 一句话确认。 这才是真正省 token 的地方：通知只在最便宜的一端（引擎）写一次，模型不用 再花 token 向用户重述一遍。

• 设计原则：不是「把消息压短」，而是「消除复述」。极简消息会逼模型去翻译/展开（更贵）； 完善消息让用户直接可读、让模型只在异常时行动。

与 dsh-dingo 配合

TaskSwarm 向其它 DSH 插件暴露标准 Cordis 服务：

const taskswarm = ctx.get('taskswarm')
const { batches } = taskswarm.getSnapshot()

每个 batch 都带有 ownerSessionId，所以像 dsh-dingo 这样的插件可以在主对话卡片上显示“等待后台/子任务/蜂群”状态，只要批次还在跑。

这样你就能在 dsh-dingo 的卡片面板里直接看到：

卡片清单干净 —— TaskSwarm 内部的 worker / reviewer / merger 会话不会作为用户卡片出现在 dsh-dingo 里：没有多余的紫色草稿计数、没有游离卡片、不会收到子 agent 的提醒。只有发起批次的 主会话以用户卡片形式出现（带"等待蜂群"状态）。

主对话已经完成，但蜂群还在跑，还没有真正交付。

文档

• 运维手册（Runbook） —— 清理残留 / 错误恢复 / 工作抢救的标准作业程序（supervisor / AI 代理必读）
• 发布手册（Release） —— npm 发布、版本号管理、2FA bypass token 的坑（维护者用）
• 已知问题（Known Issues） —— 已修复问题的根因分析与修复记录
• 更新日志（Changelog） —— 逐版本更新说明（English: CHANGELOG.md）

许可与致谢

• MIT License，可自由使用、修改、分发
• 上游 TaskPlane（github.com/HenryLach/taskplane）：波次编排、任务包、mailbox、supervisor 的原始设计，本项目的原生移植
• 运行环境：DeepSeek Harness (DSH)