扁平智能体团队whateverboy2333/dsh-flat-teams

dsh-flat-teams

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 并追加事件流。
- 三段式投递不丢任务：任务先落盘 + 写收件成员邮箱（/flat-teams//inbox/），再尽力实时唤醒（在线 followup / 离线冷恢复后 followup）；唤醒失败任务停在 delivered 留邮箱。
- 记录员：纯服务，不占窗口、无管理权限；订阅事件流维护 progress.json（每任务状态与结果摘要、每成员在手任务与完成数、团队时间线）。它只是事件流的缓存投影，可随时从 events.jsonl 完全重建。
- 用户查询：team_status 返回记录员的结构化进展；内置提示词协议教模型：派活要自包含、接活先认领、完工必须回传、问进展先查记录员不得编造。
- Web 看板：安装到 web profile 后，浏览器右上角出现“团队看板”浮层——主表（团队列表：成员数/在线数/进行中数/沉寂标记）→ 二级（花名册/任务看板/进展时间线）。看板提供用户专属管理操作：解散团队、踢出成员（均二次确认，经 POST /plugins/flat-teams/teams//disband|kick 端点；成员 agent 无此能力）。数据来自 GET /plugins/flat-teams/state（5s 轮询）。

安装

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

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

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

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

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

卸载：dsh plugin --profile  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 持有，插件卸载或进程退出即销毁；成员身份与任务数据在 /flat-teams/ 持久，但窗口本身需重新创建/加入。
3. 离线投递无自动重投：目标离线且冷恢复失败时任务留在邮箱（delivered 状态可查），但没有自动重投调度，需上线后再触达（v0.2 补）。
4. 取消不撤回已投递的 turn：task_cancel 只迁移状态机，已到接收方窗口的消息不会被撤回。
5. area 不强制独占：area 只做路由参考；同一 area 允许多个成员，此时派发必须按成员名明确指定。

另有：多进程同时写 /flat-teams/ 未做防护（MVP 声明限制，v0.2 解决）。
迁移说明（v0.1.0 内）：早期内部版本（开源前）团队状态存于 /.flat-teams/，已声明作废——旧目录不自动迁移、不再读写，可手动删除。

状态目录

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

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

开发

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

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

License

MIT