dsh-flat-teams

English | 中文

DeepSeek Harness（DSH）扁平团队插件：让多个独立 Agent 窗口（顶层会话）组成无队长的扁平团队，跨窗口互派结构化任务，并由内置"记录员"服务实时记账，用户在任何成员窗口都能问出真实进展。

功能

• 扁平团队：team_create 建队（可预置成员规格，编程创建新成员窗口，继承当前工作区）、已有窗口 team_join 自注册、team_leave、team_roster 查花名册（成员/领域/在线状态）。没有队长，任何成员可直接互派任务。
• 结构化任务派发：task_dispatch 按成员名或负责领域（area）派活；任务状态机 pending → delivered → claimed → in_progress → completed | failed | cancelled（+timeout 终态），每次迁移换新 attemptId 并追加事件流。
• 三段式投递不丢任务：任务先落盘 + 写收件成员邮箱（<DSH_HOME>/flat-teams/<teamId>/inbox/），再尽力实时唤醒（在线 followup / 离线冷恢复后 followup）；唤醒失败任务停在 delivered 留邮箱。
• 记录员：纯服务，不占窗口、无管理权限；订阅事件流维护 progress.json（每任务状态与结果摘要、每成员在手任务与完成数、团队时间线）。它只是事件流的缓存投影，可随时从 events.jsonl 完全重建。
• 用户查询：team_status 返回记录员的结构化进展；内置提示词协议教模型：派活要自包含、接活先认领、完工必须回传、问进展先查记录员不得编造。
• Web 看板：安装到 web profile 后，浏览器右上角出现"团队看板"浮层——主表（团队列表：成员数/在线数/进行中数/沉寂标记）→ 二级（花名册/任务看板/进展时间线）。看板提供用户专属管理操作：解散团队、踢出成员（均二次确认，经 POST /plugins/flat-teams/teams/<teamId>/disband|kick 端点；成员 agent 无此能力）。数据来自 GET /plugins/flat-teams/state（5s 轮询）。

安装

# npm（推荐，预构建产物，免构建授权）
dsh plugin --profile <name> add dsh-flat-teams

# 或 git 形式（lib/ 已入库，同样免构建授权）
dsh plugin --profile <name> add github:whateverboy2333/dsh-flat-teams

# 本地路径（开发调试）
dsh plugin --profile <profile> add /absolute/path/to/dsh-flat-teams

安装后重启该 profile 生效。验证：

dsh --profile <profile> --dump-config   # 组合树应出现 flat-teams 行（# == dsh-flat-teams 层）

卸载：dsh plugin --profile <name> remove dsh-flat-teams。

适配版本

• DSH 0.1.0-rc.6（@deepseek-ai/* 全栈同通道；@deepseek-ai/cordis ^4.0.1）
• Node ^22.19 或 >=24
• 插件内置运行时版本守卫：运行在不匹配的 DSH 版本上会拒绝加载并打印响亮错误，而不是静默出错

工具速查

权限全部代码强制：身份从调用方会话反查花名册，取消仅限派发方，认领/完成仅限指定接收成员。

使用示例（自然语言）

建队并招人：

帮我建一个扁平团队「官网改版」，成员加一个小测（负责测试）和阿文（负责文档）。

派活（无需记工具名）：

让小测把登录页的边界用例补全，周五前要。

接活窗口会收到 [task from … #task-…] 消息，按提示词协议先认领、干完回传。

问进展（任何成员窗口）：

项目现在进展如何？有没有任务卡住了？

Agent 会调 team_status 拿记录员数据后如实回答。

已知限制（MVP）

1. 仅同进程跨会话：所有成员窗口必须在同一个 DSH 进程内（同进程内跨工作区已支持——团队状态在 DSH_HOME 级全局共享）；跨进程/跨机器留 v0.2（计划文件注册表传输）。
2. 跨重启成员窗口不自动复活：编程创建的成员窗口由插件 fiber 持有，插件卸载或进程退出即销毁；成员身份与任务数据在 <DSH_HOME>/flat-teams/ 持久，但窗口本身需重新创建/加入。
3. 离线投递无自动重投：目标离线且冷恢复失败时任务留在邮箱（delivered 状态可查），但没有自动重投调度，需上线后再触达（v0.2 补）。
4. 取消不撤回已投递的 turn：task_cancel 只迁移状态机，已到接收方窗口的消息不会被撤回。
5. area 不强制独占：area 只做路由参考；同一 area 允许多个成员，此时派发必须按成员名明确指定。

另有：多进程同时写 <DSH_HOME>/flat-teams/ 未做防护（MVP 声明限制，v0.2 解决）。

迁移说明（v0.1.0 内）：早期内部版本（开源前）团队状态存于 <workspace>/.flat-teams/，已声明作废——旧目录不自动迁移、不再读写，可手动删除。

状态目录

团队状态与工作区无关，存于 DSH_HOME 级（任何工作区的窗口都能加入同一团队）：

<DSH_HOME>/flat-teams/<teamId>/
├── team.json        # 花名册（磁盘为真相源）
├── tasks/<id>.json  # 任务记录（状态机 + attemptId）
├── events.jsonl     # 事件流（唯一事件真相源，可重放）
├── inbox/<成员>.jsonl  # 投递邮箱（持久副本）
└── progress.json    # 记录员缓存投影（可由 events.jsonl 完全重建）

开发

pnpm install
pnpm build      # tsc（host + client）→ tsdown → lib/

注：冒烟验证脚本（scripts/）未随仓库发布；pnpm verify 仅对持有完整开发副本的贡献者可用。

License

MIT