# dsh-agent-team-gui

> 为 DeepSeek Harness Web 注入可复用的多模型 Agent 小队：成员独立配置模型与工具，按依赖图协作，持久化运行历史与官方 Token 用量。

## Metadata

- Author: [@toolclub](https://github.com/toolclub)
- Repo: <https://github.com/toolclub/dsh-agent-team-gui.git>
- GitHub: [toolclub/dsh-agent-team-gui](https://github.com/toolclub/dsh-agent-team-gui)
- Stars: 111
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://github.com/toolclub/dsh-agent-team-gui#readme>
- Topics: `agent`, `agent-orchestration`, `ai-agents`, `dag`, `deepseek-harness`, `deepseek-harness-plugin`, `dsh`, `dsh-plugin`, `dsh-plugins`, `multi-agent`, `multi-model`, `orchestration`, `react`, `token-usage`, `typescript`, `workflow-engine`
- Forks: 1
- Open Issues: 0
- Last push: 2026-08-19T02:37:45.000Z
- Added: 2026-08-17T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:toolclub/dsh-agent-team-gui
```

## Wiki

## 一句话定位
为 DeepSeek Harness Web 注入可复用、可版本化的多模型 Agent 小队，让用户在普通对话框旁选择持久化的"团队",由主模型按有界依赖图自动派单、汇总与记录官方 Token 用量。

## 核心能力
- 在 Settings 里创建可复用的成员库：每个成员独立绑定 provider/model、专属角色提示词、可选备用路由、Token 上限与最小权限工具白名单
- 在 Settings 里创建持久化小队：组合成员、选择串行或并行、设置激活策略（始终/智能/手动）与可选质量门禁
- 在普通对话框旁切换 Team / Solo / Inherited 三种模式,可叠加一次性"下一条消息"选择与项目级默认
- 动态 DAG 编排：当前对话的模型作为有界规划器生成角色分工与无环依赖图,失败时自动回退到确定性角色分工
- 后台运行、可取消、可重试,并写入持久运行历史,主模型只能看到有界的交接信息
- 直接展示官方 provider 上报的 Token 用量（输入/缓存读/缓存写/输出）与完整/部分/无覆盖度,绝不伪造价格

## 技术实现
- **语言**: TypeScript(Host service + React 18 Web 客户端,双 tsconfig 分离打包)
- **关键依赖**: `@deepseek-ai/cordis`（Cordis 依赖注入容器）、 `@deepseek-ai/dsh-agent`/`dsh-llm`/`dsh-storage`/`dsh-storage-domain`/`dsh-tools`/`dsh-jobs`（宿主服务接缝）、 `zod`（所有读写 schema）、 `@deepseek-ai/schemastery`（配置 schema）、 `react@^18.2.0`（Web UI）
- **架构模式**: 双端 Cordis 服务——Host 端通过 `Service` 类注入到 DSH 宿主进程,在 `agent/pre-step` 钩子里拦截普通消息并按小队模式派单;浏览器端通过 `apply` 注入到 4 个既有 additive slot(settings.section、conversation.input.right、conversation.input.dock、conversation.view),并通过 loopback-only Connection RPC(`/agent-team-gui`) 与 Host 通信;Domain 用 8 张表(agents/squads/session_modes/next_modes/message_claims/runs/squad_versions/project_defaults)做 v0 持久层,严格新写 schema 与宽松 v0 读 schema 分离
- **入口文件**: Host 端 `src/index.ts`;浏览器端 `src/client/index.ts`;模型工具 `src/tools/dispatch-to-squad.ts`;RPC 适配层 `src/rpc.ts`;Domain 规范 `src/spec.ts`;Cordis 注入声明 `cordis.patch.yml`

## 适用场景
适合在 Web profile 里做"长任务多角色协作"的 DSH 用户——比如让一支小队同时承担规划、实现、审核、修复四类角色,自动按依赖关系派发;也适合需要复用团队配置(模型路由、角色分工、触发策略)跨项目使用的团队管理员。如果你只想做一个能持续对话的智能体,或根本不开 Web profile,这个插件并不合适。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | >=0.1.0-rc.5,<0.2.0 | peerDependencies 声明范围;CI 当前验证 0.1.0-rc.6 |
| Node.js | ^22.19.0 或 >=24.0.0 | engines 字段;README 明确"Node 23 不支持" |
| DSH profile | 仅 Web profile | 仓库 dsh.bundle.client.platform=web,只对 Web bundle 注册 UI |
| DSH provider/model | 至少一条 | 小队成员需要绑定现有 DSH 路由,凭证由 DSH 管理 |
| pnpm | 任意支持版本 | Git 源安装时 pnpm 10+ 可能要求 allowBuilds |

## 安装方式
```bash
dsh plugin --profile web add github:toolclub/dsh-agent-team-gui
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| defaultProvider | 字符串 | DSH 子 Agent 默认 provider 名,作为成员创建时的兜底 | `spawn` |
| defaultExecutionMode | serial / parallel | 小队未指定执行模式时的兜底(串行或并行) | `serial` |
| defaultContextMode | spawn / fork / chain | 小队未指定上下文模式时的兜底;`chain` 仅在 serial 下有效 | `spawn` |
| historyMaxRuns | 0~5000 整数 | 自动清理多少条已结束运行;`0` 表示不按数量清理 | `0` |
| historyMaxAgeDays | 0~3650 整数 | 多少天前的已结束运行自动清理;`0` 表示不按时间清理 | `0` |
| versionMaxPerSquad | 0~1000 整数 | 每个小队最多保留多少个不可变版本;`0` 表示不清理版本 | `0` |

## 常见问题

**Q: 安装后需要重启 DSH Web 进程吗？**

A: 需要。README 明确要求安装或更新后必须重启 Web 进程,新的 `agent-team-gui` Host 行才会被加载。

**Q: 必须使用 Web profile 吗？headless 能装吗？**

A: 必须 Web。Settings UI、对话模式控件、运行中心都依赖 Web bundle 注入的 storage 与 Connection RPC;其他进程内插件若注入了必需 service,仍可调用导出的 Host service,但没有官方配置界面。

**Q: 安装前还要准备什么？**

A: DSH 处于 `0.1.0-rc.5` 至 `0.2.0` 之间,Node.js 22.19+ 或 24+(Node 23 不支持),pnpm,以及至少一条已经在 DSH 里配好的 provider/model 路由——小队成员必须挂到现有路由上。

**Q: 卸载插件会一起清掉小队数据吗？**

A: 不会。插件删除时不会自动删除 Domain 里的 8 张持久表,小队定义、版本、运行历史都留在 DSH 存储里,要手动清理。

**Q: 安装时 pnpm 弹出 allowBuilds 提示怎么办？**

A: 只把 `dsh-agent-team-gui` 这一个包加入 pnpm 提示的 Web profile 工作区文件(默认 `~/.dsh/profiles/web/pnpm-workspace.yaml`)的 `allowBuilds`,其他包一律不授权,然后重复同一条固定版本命令。

**Q: 旧 v0.4 数据还能用吗？**

A: 能打开、可以导入,但不能再以 v2 上限写入。旧运行如果没有记录原始计划,会被显式拒绝重试。

**Q: 模型工具调用一定能触发小队吗？**

A: 不一定。模型工具触发是 best-effort,因为 DSH 还没暴露 `toolChoice` 控制;想要稳定自动触发,把小队触发模式设成 `guaranteed`,它由 Host 驱动并按持久消息幂等。

**Q: 可以远程 URL 拉取配方吗？**

A: 不可以。`snapshotSchema.capabilities.remoteRecipeFetch` 固定为 `false`,v0.5 故意禁掉远程 URL 以避免未做 SSRF 加固的 Host 网络请求面;请导入已经审查过的本地 JSON。

## 上手难度
进阶 — 需要先理解 DSH Web profile 与 Cordis 注入模型,再阅读 Settings 里的"成员-小队-触发模式"配置矩阵;此外,质量门禁、激活策略、上下文模式(spawn/fork/chain)等概念对小队行为有显著影响,只看 README 不跑一遍比较容易踩坑。

## 已知问题与限制
- 仅支持 Web profile;没有 headless Settings 页面;其他进程内插件可消费导出的 Host service,但官方配置 UI 不存在(`README.md:334-335`)
- 声明兼容范围 `>=0.1.0-rc.5 <0.2.0`,但 CI 当前只在 rc.6 上验证过,DSH 与本插件都未稳定,生产必须固定版本(`README.md:336-337`)
- 模型工具触发模式(model-tool)是 best-effort:DSH 没有暴露 `toolChoice` 控制,模型可能不会自动调用 `dispatch_to_squad`;需要稳定自动触发请用 guaranteed 模式(`README.md:346-347`)
- DSH 当前没有"注册自定义 squad/* Session 事件"的官方 seam,插件使用自己的持久运行表 + 标准 child Session/Tool 事件 + Jobs + 日志组合实现,事件可见性与官方 Session 事件并不一致(`README.md:344-345`)
- 软 Token 预算(`tokenBudget`)只能阻止后续成员被调度,无法在已运行 provider 上强制中断;真正的硬上限是每个成员自己的 `maxTokens`(`README.md:342-343`)
- v0.5 禁止从 URL 拉取配方:`snapshotSchema.capabilities.remoteRecipeFetch` 写死为 `false`,且 README 明确指出是为了避免暴露没有 SSRF 防护的 Host 网络面(`src/rpc.ts:259-261` / `README.md:192-193`)
- Provider Token projection 是可选能力,partial/unavailable 覆盖率是正常且显式的状态;没有上报样本之前 UI 显示 "Metering…",不会出现假的 0(`README.md:154-165`)
- v0 持久定义域 `version: 0` 故意保留且 storage-domain 不提供迁移 API,Domain 表结构只增不删(`src/spec.ts:347-352`)
- 源码中未发现 TODO/FIXME/HACK/XXX 注释(grep 结果为空),暂无开发者标记的待办项

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-agent-team-gui](https://deepseek-plugin.org/plugins/toolclub/dsh-agent-team-gui)
Wiki generated by AI (model: `MiniMax-M3`)