dsh-flat-teams

Readme

# dsh-flat-teams

[English](README.en.md) | **中文**

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 轮询）。

## 安装

```sh
# 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** 生效。验证：

```sh
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 完全重建）
```

## 开发

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

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

## License

MIT