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 版本上会拒绝加载并打印响亮错误，而不是静默出错
工具速查
| 工具 | 作用 |
|---|---|
team_create | 建队；可选 members 规格编程创建成员窗口（name/area/persona）；当前窗口自动成为首个成员 |
team_join / team_leave / team_roster | 自注册加入 / 退出 / 查花名册（含实时在线状态） |
task_dispatch | 派任务：to 填成员名或 area（area 多候选会报错要求指明）；任务落盘 + 邮箱 + 尽力唤醒 |
task_claim / task_complete / task_fail | 接收方驱动状态：认领（delivered→claimed→in_progress）/ 完成回传 / 失败说明 |
task_list / task_status / task_cancel | 任务查询（状态/成员过滤）/ 单任务详情 / 取消（仅派发方，支持 attemptId 世代校验） |
team_status | 记录员结构化进展（任务状态与摘要、成员在手、团队时间线） |
flat_teams_ping | 插件自检 |
权限全部代码强制：身份从调用方会话反查花名册，取消仅限派发方，认领/完成仅限指定接收成员。
使用示例（自然语言）
建队并招人：
> 帮我建一个扁平团队「官网改版」，成员加一个小测（负责测试）和阿文（负责文档）。
派活（无需记工具名）：
> 让小测把登录页的边界用例补全，周五前要。
接活窗口会收到 [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