Ready22Race/dsh-team-task

team-task — 面向 DeepSeek Harness 的长周期多智能体任务

npm version
MIT license
DeepSeek Harness plugin

一个 DeepSeek Harness (dsh)
插件：lead 会话规划一张经过评审的 DAG，持久化的 members 执行
其节点，一个常驻的 reconciler 持续推动任务前进——跨越模型
故障、中断的轮次以及 harness 重启。

为耗时数小时而非数轮的目标而构建。

为什么

针对短时爆发优化的团队插件在长任务上会以可预测的
方式失败。team-task 的应对方案，一张表说明：

| 长任务失败 | team-task 的应对 |
|---|---|
| 成员完成了但从未调用完成工具 | 运行时主导的结算：无论怎样，运行都会在其空闲边界结算；工具只是加速，绝不设卡 |
| lead 会话在任务中途离线 | 常驻 reconciler 按定时器重新推动每个任务；lead 一回来工作就恢复 |
| 早期的幻觉污染下游工作 | 评审门：只有 lead 的 approve 才能解锁依赖项；rework 将反馈送回同一节点，尝试次数是一等历史 |
| 被重新分配的 worker 写入迟到的结果 | 在仅追加事件日志上的栅栏令牌；过期栅栏在日志层被拒绝，而非靠礼节 |
| 进程崩溃、唤醒丢失、消息滞留 | 事件日志是唯一真相；投递是调度器的职责，并在每次推动时重试 |
| 每个请求中的协议提示词开销 | 渐进式 playbook：约 8 行的常驻触发器；lead/member 协议按需通过 team_task_playbook 加载 |

完整理由、公理、状态机以及事件日志原生的看板设计：
docs/design.md。

快速开始

前置条件：Node ^22.19 || >=24（Node 23 无法启动 dsh）。

1. 安装 dsh（如果已有可跳过）：

npm i -g @deepseek-ai/dsh

2. 添加插件 —— 任选其一：

npm（推荐）
dsh plugin --profile web add @ready22race/dsh-team-task

直接从 GitHub（仓库自带构建产物——无需构建步骤）
dsh plugin --profile web add github:Ready22Race/dsh-team-task

从源码（贡献者；以指向你本地检出的链接方式安装）
git clone https://github.com/Ready22Race/dsh-team-task.git
cd dsh-team-task && pnpm install && pnpm build
dsh plugin --profile web add .

3. 验证组合（应看到一行 id: team-task）：

dsh --profile web --dump-config

4. 启动 dsh（plugin add 之后需要重启——bundle
列表在进程内被缓存）：

dsh web

5. 首次运行 —— 打开 http://127.0.0.1:3080，设置模型密钥
（Settings → Models）并选择一个工作区，然后发送：

用 team-task 跑一个长任务：先加载 lead playbook，规划一张带依赖和
预指派（assignee）的节点图，逐节点评审，最后合并交付。
你应该看到：对话中有一张任务卡片，右侧有看板浮层（segments / filters / node cards / inspector），以及磁盘上的 /.team-task/tasks//log.jsonl。预分配的节点会在其依赖项批准后自动流转；其他所有内容都等待你的显式派发或审查。

工具

| 工具 | 使用者 | 作用 |
|---|---|---|
| team_task_playbook | 任何人 | 按需加载 lead / member / recovery 协议 |
| team_task_create | lead | 创建任务（+ 可选的初始计划 DAG） |
| team_task_add_member | lead | 生成一个持久成员，带有角色配置（provider/model/effort/playbook；省略的字段继承 lead 的路由） |
| team_task_plan | lead | 添加 / 更新 / 取消计划节点 |
| team_task_dispatch | lead | 派发一个节点（fence++），派发给某个成员、共享池或 lead 自身 |
| team_task_await | lead | 阻塞直到有审查工作出现或所有节点都尘埃落定——而不是轮询 |
| team_task_complete | 被指派人 | 用当前 fence + 自包含的输出认领完成 |
| team_task_review | lead | approve（解锁依赖项）或 rework（必须提供反馈，并带入下一次尝试） |
| team_task_send | 任何人 | 向 lead 或队友发送持久消息；由调度器投递 |
| team_task_status | 任何人 | 快照：节点、运行、fence、成员活动、关注列表、你的收件箱 |
| team_task_finish | lead | 关闭并归档（完整事件历史和每次运行均保留） |

存储

/.team-task/
└── tasks/                                  # 任务列表，按时间顺序排序
└── 20260816-2145-竞品分析示例任务/       # id = 创建时间戳 + 名称 slug（保留 CJK）
├── log.jsonl        # 仅追加的事件日志——唯一真相
├── snapshot.json    # 最新投影（团队情况 + 节点 + seq）；派生
└── inbox/
├── lead.jsonl   # 按收件人的邮箱镜像；派生，人类可读
└── .jsonl

log.jsonl 是唯一真相来源；每个界面（工具、看板路由、离线校验）都折叠相同的事件，任何历史上的“时刻 T 的团队情况”都是对日志前缀的重放。snapshot.json 和 inbox/ 是写穿透的派生视图，供人类使用——可安全读取，绝不手工写入，也绝不会被代码读回。

配置

- id: team-task
config:
stateDir: .team-task
memberProvider: spawn      # 子代理运行时后端，不是 LLM provider
memberMaxDepth: 1
maxMembers: 8
reconcileIntervalMs: 30000

开发

pnpm install
pnpm build
pnpm verify   # 离线：fences、审查门、返工、结算、重放确定性

发布（维护者）

仓库提交了 lib/，因此 github: 安装无需构建步骤——始终从干净的 pnpm build 发布（css-module 哈希是仓库相对的，因此输出与机器无关）。

npm login                      # 账户必须拥有 @ready22race 作用域
npm publish --otp=   # prepublishOnly 会先运行 build + verify

启用 2FA 后，单独执行 npm publish 会返回 403 —— 请传入 --otp，或创建一个
作用域限定为此包、带有“绕过 2FA”权限的细粒度访问令牌，并将其放入
~/.npmrc 以用于令牌化发布。发布后，为发布打标签：
sh
gh release create vX.Y.Z --title "dsh-team-task X.Y.Z" --generate-notes

状态与路线图

- M1（本次发布） —— 宿主插件端到端：工具、事件日志、fence、
调度器 + 协调器、运行时结算、评审/返工、playbook、看板
数据路由（/plugins/team-task/state、/plugins/team-task/log）。
- M2 —— 事件日志原生的看板 UI（看板泳道 + DAG 叠加层 +
关注条 + 每节点运行时间线 + 回放滑块；design.md §6）。
- M3 —— 消费确认式投递与无父级成员唤醒（需要
上游接缝；跟踪于 design.md §7）、npm 发布、按运行成本
核算。

已知限制（v0.1）：成员唤醒仍需要活跃的 lead Agent（这是
上游 followup 约束 —— 协调器会在 lead 返回时恢复工作）；
message_delivered 标记的是收件箱接收，而非轮次消费。

中文速览

team-task 是面向长任务的 dsh 多智能体插件：lead 规划一张需评审的
DAG，durable member 执行节点，常驻 reconciler 保证崩溃/重启后任务继续。

核心主张（详见 docs/design.md）：

1. 事件日志是唯一真相 —— 状态是 log.jsonl 的纯投影，看板/工具/验证
折叠同一份事件，重放即历史。
2. 进度归运行时，表达归模型 —— 成员不调完成工具也会在 idle 边被结算；
工具只是加速，不是闸门。
3. fence 即运行权 —— 每次派发递增 fence，旧 fence 的迟到写入在日志层
被拒；停止 = 撤销 fence，不是发消息。
4. 投递归调度器 —— 消息先落日志（立即安全），调度器在 idle 边 / 定时
sweep 时投递；没有“队长在线才能通信”。
5. 评审是默认闸门 —— 只有 lead approve 才解锁下游；rework 必须带
反馈，原节点重派、attempt 历史完整保留；机械节点可声明 auto_approve
走快速档。
6. 渐进式 playbook —— 常驻 prompt 只有 ~8 行触发器，完整协议按角色
（lead / member / recovery）用 team_task_playbook 按需加载。

License

MIT