dsh-subagent-team

Readme

# dsh-subagent-team

> DeepSeek Harness 的「子代理团队」插件：9 个分工明确的专职子代理 + 代码质量流水线 + 持久化多代理团队运行时。

一个**官方 bundle 形态**的独立插件，可经 **GitHub / npm** 安装到 DSH（桌面端与 web 端皆可）。
提供**模型可见的角色工具**（`team_read` / `team_write` / `team_code_write` / `team_code_review` …），
以及一套**真正的事件驱动团队运行时**（建队 / 成员 / 任务依赖 / 邮箱 / 自动调度 / 「子代理」活动标签页）。

---

## ✨ 特性一览

| 能力 | 说明 |
|---|---|
| **角色分工** | 9 个专职子代理：读、码读、识图、写文件、写码、写文档、修码、审码、统筹 |
| **代码质量流水线** | 写 → 审（可借力 ocr） → 修 → 复审 → 补文档，闭环留痕 |
| **可续做长任务** | `continuable`：会话被截断/打断后可续做、可追问 |
| **Token / 预算可调** | 每角色 `maxTokens`、`team_budget` 结合外部并发槽 |
| **性能优化** | 快任务一次性、稳定 KV、黑板去重、后台并行不阻塞 |
| **独立优先** | 外部插件（如 ocr）是增强项，缺失时自动落内置兜底，**绝不报错** |
| **团队运行时** | `team_create/member_add/create_task/claim/update/reassign/send/status/delete` + 自动调度 + 「子代理」标签页 |

---

## 🧩 架构（双 half + client）

```
cordis.patch.yml    配置 half：按官方 bundle 挂载 9 个角色实例（复用 dsh-subagent 委派引擎）
src/index.mjs      编译 half：注册 team_run/team_note/team_stat/team_budget/team_env 与动态授权的 team_code_*
src/team-runtime.mjs 团队运行时（M1-M4）：状态机 / 邮箱 / 事件调度 / 快照 / UI 路由
src/client.js       client half：「子代理」标签页（按 __ModuleLoader__ 协议，零依赖）
```

- **独立优先 + 能力边界**：每个角色只拿到完成本角色职责所需的工具与调用权；外部工具“注册了才注入”。
- **改必留痕、审必有记**：所有会改文件的角色完成后必须写 `change-*.md`，审码角色必须写 `review-*.md`。

---

## 📦 安装（官方流程）

本插件声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，因此走 DSH **官方插件安装流程**：

```powershell
# ① 桌面端(xuqingsakura/deepseek-harness)：设置 → 插件 → 添加
#    GitHub：   github:xuqingsakura/dsh-subagent-team#main

# ② CLI（等价）
dsh plugin --profile web add "github:xuqingsakura/dsh-subagent-team#main"
dsh plugin --profile web remove dsh-subagent-team
```

> 安装器会把本包追加进 `dsh.profile.bundles`。**改完 bundle / settings 后需完全退出并重启桌面端。**

### 安装后配置（API Key / 视觉模型）

```powershell
.\scripts\setup.ps1 -CheckOnly   # 只读体检
.\scripts\setup.ps1              # 检查 + 自动补写 mimo-v2.5 的 input（改前备份）
.\scripts\setup.ps1 -SetKey      # Key 缺失时引导写入 $DSH_HOME\.env
```

会校验/补写 `settings.yaml` 中视觉模型（如 `mimo-v2.5`）的 `input: [text, image]`（`read_image` 放行前提），
并检查 OpenAI 兼容 Key（`.credentials.yaml` / 环境变量 / `.env`），不打印明文。

---

## 🚀 使用

### 1) 角色工具（模型直接调用）

`team_read` / `team_code_read` / `team_vision` / `team_write` / `team_code_write` / `team_doc` /
`team_code_fix` / `team_code_review` / `team_lead`。在会话中直接调用即可。

### 2) 团队工具（跨会话协作）

| 工具 | 归属 | 作用 |
|---|---|---|
| `team_create` | 队长 | 建队（一个工作区一队） |
| `team_member_add` / `team_member_remove` | 队长 | 添加/移除**可持续续做**成员 |
| `team_create_task` | 队长 | 建任务，可接依赖、可指派 |
| `team_list` | 全体 | 平铺列出成员/任务/状态/依赖 |
| `team_claim_task` | 全体 | 领取就绪任务，返回 `attempt_id` |
| `team_update_task` | 全体 | 状态流转（必须带 `attempt_id`，陈旧即拒） |
| `team_reassign_task` | 队长 | 重试/改派/接管 |
| `team_send` | 全体 | 邮箱互发 |
| `team_status` | 全体 | 全量观测快照 |
| `team_delete` | 队长 | 归档并解散 |

**快速开始**：
```text
team_create {name, description}
team_member_add {name, role}
team_create_task {subject, description, dependencies, assignee}
# 调度器自动把就绪任务派给空闲成员 → 成员 team_claim_task → 干活 → team_update_task
team_status
team_delete {confirm: true}
```

---

## 🔧 常见排查

- `team_run` / 角色工具报 spawn 类错误 → 确认当前会话 **`maxDepth ≥ 1`**（宿主放开，非插件 bug）。
- 报 `value.results[0].error must be a string` 等 schema 拒绝 → `node test-smoke.mjs` 的 schema 检查定位结构。
- `team_env` 卡顿 → 确认装的是最新版（异步探测 ocr，不再阻塞事件循环）。
- 改完不生效 → 完全退出并重启桌面端 + `Ctrl+F5` 硬刷新。

---

## ⚠️ 已知限制

- `toolFilter` 是**可见性/组合**限制，不是安全边界（沙箱/授权由父级作用域继承）。
- 9 个角色会让父级每请求 schema 开销随角色数线性增加；用不上的角色可删行（`cordis.patch.yml`）。
- 子代理总花费靠 `maxTokens`/深度/工具面约束，暂无硬性全局 Token 预算（见 `docs/ANALYSIS.zh.md`）。
- 换视觉模型需两处同步：`settings.yaml` 声明 `input` + 插件 `agentOptions.model`。

---

## 📚 文档

- `docs/DESIGN.zh.md` — 设计要点与能力边界
- `docs/ANALYSIS.zh.md` — 现状审计与风险
- `docs/PLAN.zh.md` — 完善计划（S1–S7 / M1–M4 已实现）
- `docs/EVENTS.zh.md` — 会话事件词汇表与守卫
- `test-smoke.mjs` — 端到端 smoke

## 📄 License

MIT