使用指南（详细）

September 3, 2026 · View on GitHub

本文档收纳 dsh-agent-teams 的详细使用内容：工作原理、Web UI 行为、工具一览、配置与已知限制。README 只保留简介与快速上手。

工作原理

dsh-agent-teams 复用 DSH 的能力接缝（capability seam），不依赖 workflow 引擎：

DSH 能力	AgentTeams 用法
`ctx.tools` 注册表	注册 10 个 `agent_teams_*` 工具（与 `tool-workflow` 同一注册路径）
`ctx.subagents.startContinuable()`	创建成员：durable 可续聊子代理，带成员 persona
`ctx.subagents.interrupt()` + `sendMessage()` / `Agent.cancel()` + `followup()`	默认插话：先打断收件人当前轮次再立刻投递；`mode=queue` 才不打断。成员投递走公开的 `sendMessage`（steer 到最近 step）；队长报告仍用 `Agent.followup`
`ctx.subagents.listChildren()` + `ctx.agents.get().status`	查询成员是否正在跑一轮（store 里的 `running` 只表示会话还在内存，停掉的对话仍可能是 `running`）
`ctx.systemPrompt.section()`	注册"AgentTeams 使用策略"提示段
Web server 路由注册	活动面板数据路由 `/plugins/dsh-agent-teams/state` + 鲸鱼图片静态服务（`webServer`/`httpServer` 双键兼容，见下）
文件系统	团队状态持久化在 `<workspace>/.agent-teams/<teamId>/`

数据链路：工具执行 → 磁盘状态（真相源）→ host 快照路由 → 浮层 1s 轮询渲染；会话日志同时写入 agent-teams/* 事件（审计/重放/复盘）。

内测版本兼容：npm latest（0.0.1-rc.1）的服务键仍是 ctx.httpServer / ctx.workspace，后续 next（rc.2）重命名为 ctx.webServer / ctx.workspaceRegistry。插件对两组键都做了探测（新键优先、旧键回退，internal/service 事件同时监听两组），两个版本都能注册路由。

Web UI

右上角活动面板（body-portal 浮层，参考 Claude Code 桌面端 SessionActivityPanel）：默认只显示右上角小浮标（团队数 + 活动脉冲点），点浮标或对话流卡片才会展开；每个团队一节——👑 队名 + 统计 + ● n 工作中；成员块（职业头像 · 名字 · 角色 · 状态 · 进度 · 未读角标，点击打开成员子会话并立即收起面板），块下直接挂任务栈（当前任务置顶高亮 + 6 态徽章：待领取/已认领/进行中/已完成/失败/已取消 + 依赖提示 ← t1 · alice）；无主任务进"待认领"块；底部队长收件箱预览。任务依赖图的「固定」只是把某一条上下游链高亮钉住，方便看依赖，不改任务状态。
小鲸鱼形象：队长/成员头像为 DeepSeek 小鲸鱼职业插画（assets/agent-teams/，8 角色 + 6 动作），按角色关键词匹配；状态动作小图随成员状态切换并带动画（工作浮动 / 空闲呼吸 / 未知思考），未读消息头像外圈光晕；遵循 prefers-reduced-motion。
会话跟随：面板只显示当前会话的团队（按 captainSessionId 匹配）；切走会话会收起，不会因为有团队就自动再打开。
对话流卡片：团队创建时对话流出现轻量卡片（成员一览、点击跳转成员会话、"活动面板"按钮可重新激活已关闭的浮层）。
历史复盘：agent_teams_delete 将团队归档保留（<stateRoot>/archive/<teamId>/，任务与依赖图、邮箱完整留存）；打开历史会话点卡片即可恢复完整团队（成员 + 任务栈 + 依赖 + 消息），供重建任务依赖关系。

团队状态文件

<workspace>/.agent-teams/<teamId>/
├── team.json            # 团队记录：成员、任务（含依赖）、任务序号
└── inbox/
    ├── captain.jsonl    # 队长邮箱（成员 → 队长）
    └── <member>.jsonl   # 每个成员一个邮箱（JSONL）

任务状态机：pending → claimed → in_progress | completed | failed | cancelled，in_progress 可省略；迁移白名单校验；领取前校验依赖（未完成依赖报错列出）。

工具一览

工具	作用
`agent_teams_create`	创建团队，调用者成为队长（一个队长同时只带一个团队）
`agent_teams_add_member`	拉成员入队并立刻派发第一份任务（出生 brief 就是这份任务，不是欢迎轮；`prompt` 可用 `brief`/`instructions`/`task_description` 兜底；可选 `cwd` 钉死工作区）
`agent_teams_remove_member`	移除成员（尽力打断其当前轮次）
`agent_teams_create_task`	给已存在的成员创建后续任务；`assignee` 必须是在册成员；`dependencies` 只能用先前返回的 `t1`/`t2`/…
`agent_teams_claim_task`	领取任务（校验依赖；队长可代领，成员只能领自己的/未指派的）
`agent_teams_update_task`	推进任务状态并写入 `output` 结果
`agent_teams_send_message`	任意成员→任意成员/队长：消息直达对方邮箱；默认插话打断当前轮次，`mode=queue` 才排到下一轮；禁止空的「请继续」催办；无队长转发；拒绝冒名 `from`
`agent_teams_status`	团队全景：成员活动、任务清单、队长邮箱、各成员待读消息
`agent_teams_delete`	结束团队：打断成员并清空其排队消息，团队目录归档保留（任务与依赖图、邮箱完整留存）
`agent_teams_report_issue`	队长或未建队会话把插件缺陷报到 `Wuxie233/dsh-plugin-agent-teams`；成员不可见也不可用

agent_teams_add_member 必须带上第一份任务：task_subject，以及一份 spawn brief。文档字段是 prompt；如果模型发不出这个字段名，brief / instructions / task_description / task_subject 都可以顶上。runtime 要求 spawn 时提交一条 user prompt，所以这份 brief 就是成员的第一轮，不再单独欢迎。也可以传已有的 task_id 来认领。默认不需要模型参数：它会快照队长当前请求真正生效的 LLM provider、model 与思考强度。用户明确要求某个角色使用其他模型时，可以同时传入可选的 provider + model；只覆盖 model 时沿用队长当前 LLM provider。插件不会为每个成员发起二次选择或弹窗，也不暴露逐成员思考强度参数。

可选参数 cwd 是成员工作目录的绝对路径。队长会话停在伞目录时，把目标仓库绝对路径传进来，成员就不会去翻兄弟仓库。cwd 不等于队长工作区时会写 captain-pointer.json。可选参数 worktree 是队长已经建好的 git worktree 绝对路径，要求目录里有 .git，只读角色拒绝。两者同时传时必须是同一条路径。建树、合并、删除 worktree 都是队长的 git 操作，插件不管生命周期。默认不要传：写者共享队长工作区、靠独占路径并行。

配置

在 profile 的 cordis.patch.yml 中覆盖：

- id: agent-teams
  config:
    stateDir: .agent-teams        # 团队状态目录名（工作区下）
    memberProvider: spawn         # 子代理运行后端（spawn / fork），不是 LLM provider
    memberModel: deepseek-v4      # 可选：成员模型覆盖
    memberMaxDepth: 1             # 成员再委派深度上限（0 = 禁止）
    # maxMembers: 8               # 可选在册人数上限；省略表示不封顶

省略 maxMembers 表示不限制在册人数；显式配置数字后仍会拒绝超员。最终优先级为：成员显式 provider + model / model → memberModel → 队长当前路由。思考强度默认继承队长当前值，并在目标 provider/model 上创建前校验；不兼容时成员创建会明确失败。最终生效的 provider/model/思考强度会写入 team.json，供状态查询和成员冷恢复使用。

使用协议

插件提示段会指导模型按协议执行：建团队 → 按角色拉成员并带上第一份任务 brief（出生即开工）→ 成员存在后再用返回的 t1/t2/… 拆后续任务 → 派完就等成员报告或 stall 通知，不要空催 → 有新指令或改方案时用 agent_teams_send_message 插话投递 → 汇报后 agent_teams_delete。成员之间可以直接互发消息，无需队长中转。不要先给还不存在的人 create_task，也不要发明 task-1。

已知限制

成员在收到消息后才行动，没有常驻轮询。队长派完第一份 brief 后等待成员报告或 stall 通知，不因工作区还没文件就催「请继续」。在线投递默认插话打断当前轮次；mode=queue 才排到下一轮。被 interrupt 后若仍占着 claimed/in_progress 任务且 inbox 为空，会给队长发一条 stall 通知（插件观测，不是成员回报），任务不会被自动失败或取消认领。队长会话 resume 不会自动喊成员继续。队长离线时消息留在邮箱、待下次在线时投递。
一个队长同时只能带一个团队（与 Claude Code AgentTeams 一致）。
成员 persona 替换部署默认 persona。写者默认拥有完整工具集；只读角色在 spawn 时被拒绝 write / edit / bash。
可选成员 cwd / worktree 依赖 runtime 的 child-cwd 传输；缝没打上时 spawn 会 fail loud 并打断该成员，不会静默写回队长树。deployment 的 pnpm install 会冲掉这份缝。
默认不限制在册人数。只有显式配置 maxMembers 才会在超员时 fail loud（错误信息含 liveCount/cap）。
团队状态为文件级持久化，多进程同时操作同一团队不保证一致（同一 dsh 进程内已用锁串行化）。
对话流卡片从 create / add_member / remove_member 的 tool/result.meta 折叠花名册；活动面板仍读磁盘真相（1s 轮询，快照路由有超时）。成员「工作中」只看 live Agent 是否正在跑一轮；会话还在内存、对话已停止时显示空闲，不沿用 listChildren().activity。快照失败时卡片保留折叠花名册，不把它显示成 0 人。
右上角浮层通过 body portal 挂载；宽屏展开时主对话列平滑向左礼让空间，窄屏退回 overlay 模式，左侧导航保持不动。
成员（模型）不总是严格走工具"仪式"（如完成时不调 agent_teams_update_task）——面板如实反映磁盘真相，队长以 agent_teams_status/文件为准汇总。

验证

离线冒烟：pnpm build && pnpm typecheck && node scripts/verify.mjs；组合验证 dsh --profile agent-teams-check --dump-config
真实 e2e：dsh plugin --profile headless add <path> 后 dsh --profile headless "用 AgentTeams …"，核对 .agent-teams/ 状态文件与会话日志事件流
GUI：独立实例 + ego-browser（详见 verification-guide.md）