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 + 自动调度 + 浮层 UI

---

🧩 架构（双 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 官方插件安装流程：

# ① 桌面端(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 / 视觉模型）

.\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	队长	归档并解散

快速开始：

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}

3) 团队活动浮层

右下角「团队」胶囊（1s 轮询 /dsh-subagent-team/state），深/浅色跟随主题；无团队时显示空态。

---

🔧 常见排查

• 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