toolclub/dsh-agent-team-gui

English | 简体中文

为 DeepSeek Harness 提供持久化的多模型 Agent 小队。 每个成员可独立配置模型和工具策略；在 Settings 中保存可复用小队，然后在对话输入框旁选择小队， 像平时一样发送消息即可协作。

60 秒安装

dsh plugin --profile web add -w github:toolclub/dsh-agent-team-gui#v0.1.0
dsh --profile web

随后打开 Settings → 小队 创建小队，在对话输入框旁选择它并开启小队模式。插件直接复用 dsh 已配置的模型路由和凭据存储，绝不会保存 API key。

你会得到什么	为什么有用
每个 Agent 独立的 provider/model 与工具策略	一个小队可组合强规划、快实现和严审核模型
全局持久化的 Agent 与小队	建一次队伍，即可跨项目、跨对话复用
固定顺序或模型规划顺序	固化可重复流程，或让主模型针对每次任务安排角色
串行/并行执行与 spawn/fork/chain 上下文	按任务选择协作拓扑，不被单一模式限制
父会话工具轨迹与成员子会话	看清每个成员做了什么，也能定位失败原因

如果它确实解决了你的工作流，点一个 GitHub Star 能帮助更多 DeepSeek Harness 用户发现它；也欢迎提交真实小队配方和问题反馈。

[!WARNING] dsh 与本插件目前都是 developer preview。本插件面向 dsh >=0.1.0-rc.5 <0.2.0，并要求 Node.js 22.19 或更高版本。dsh 在稳定版之前可能有破坏性变更；需要可复现时请同时锁定 dsh 与本插件版本。

核心差异

小队不必共享同一个模型配置。每个 Agent 都能独立选择 dsh 中已有的 provider/model 路由、 maxTokens 和工具 allow/deny 策略；这些 Agent 在 Settings 中保存为全局可复用定义，再组合为持久 小队。每个对话可选择一个小队并开启协作；开启后，普通的“发送”就进入协作流程。小队可固定成员 顺序；未固定时，由模型根据任务规划分工与执行顺序。

状态与架构

Settings --> 全局 Agent/小队定义 ---------+
对话 ------> 按 session 保存的小队模式 ----+--> dsh storage-domain --> JSON 后端
                                           |
对话小队选择器 + 协作 toggle
                                           |
普通发送 --> 已设置固定成员顺序 -----------+
        `-> 未设置顺序时由模型规划分工/顺序
                                           |
                 Agent A / Agent B / Agent C
                                           |
              assistant 回复 + 可追溯子会话

自然语言要求 --> dispatch_to_squad（模型工具）--> 同一小队 runtime

本包包含 Web client、仅 loopback 可用的 Connection RPC、宿主服务、持久化注册表和模型派单工具。 Settings → 小队管理全局定义。每个对话都有小队选择器与协作开关；选中小队并开启 协作后，用户仍使用普通输入框发送，不需要单独的派单表单。provider/model 选项来自 dsh 已有的 模型配置。

当前能力：

• 通过 dsh storage-domain 持久化 Agent/小队记录与逐 session 的小队模式选择。
• 在 Settings 中创建、编辑、删除全局 Agent 与小队，并从已配置模型中选择路由。
• 每个对话独立选择小队并显式开启协作；开启后，普通发送会启用所选小队模式并指示主模型协作， 关闭后恢复普通单 Agent 发送。
• 小队可选固定成员顺序；未固定时由模型依据请求决定成员分工与执行顺序。
• 每个 Agent 独立的 { provider, model, maxTokens? } 路由与工具限制；不存储 API key。
• 模型可调用 dispatch_to_squad，可选显式指定每个 Agent 的任务。
• 支持串行或并行，以及 spawn、fork、串行专用的 chain 上下文模式。
• 每个成员都有明确的成功/失败结果；一个成员失败不会静默取消其余成员。
• 父会话 append-only 的 tool/call 与 tool/result 记录完整派单输入/输出，每个成员结果包含 子会话/run ID。

前置条件

• 版本为 >=0.1.0-rc.5 <0.2.0 的 dsh Web profile。本组合包不支持 headless 或裸 profile。
• Node.js 22.19 或更高版本。
• PATH 中有 pnpm。下文 Git 安装说明中的限制适用于 pnpm 10 及更高版本。
• dsh 中已经配置至少一个 provider/model 路由。请通过 dsh Settings 或其凭据机制配置凭据， 不要把凭据写入本插件记录。

下列命令假设使用已安装的 dsh 可执行文件。仅克隆 DeepSeek Harness 源码不会自动全局安装 该命令。在 Harness 仓库根目录先这样验证源码 CLI：

pnpm dsh --version

从其他目录运行时，把下文每条 dsh ... 替换为 pnpm --dir /absolute/path/to/deepseek-harness dsh ...。

从本地目录安装

在包含 dsh-agent-team-gui 的目录中逐条执行。

1. 安装插件开发依赖：

   pnpm --dir ./dsh-agent-team-gui install
   

   预期：pnpm 成功结束，并创建或更新 dsh-agent-team-gui/node_modules。

2. 链接进 profile 前构建 checkout：

   pnpm --dir ./dsh-agent-team-gui run build
   

   预期：命令以状态 0 退出，并在 dsh-agent-team-gui/lib/ 下生成运行时入口。

3. 把本地组合包加入 Web profile：

   dsh plugin --profile web add -w ./dsh-agent-team-gui
   

   预期：pnpm 报告已加入 dsh-agent-team-gui；dsh 不应打印包“declares no dsh.bundle”的警告。

4. 不启动应用，检查组合后的配置：

   dsh --profile web --dump-config
   

   预期：输出包含 dsh-agent-team-gui 组合包层与 agent-team-gui 行。

5. 启动 profile：

   dsh --profile web
   

   预期：dsh 正常启动，Settings → 小队可用，并且对话中出现小队选择器与协作开关。 若启用了宿主 info 级日志，日志还会包含 [agent-team-gui] durable registry and dispatch_to_squad ready。

从 tarball 安装

已构建的 tarball 包含编译产物，因此不需要安装脚本授权。

1. 安装依赖并构建：

   pnpm --dir ./dsh-agent-team-gui install
   pnpm --dir ./dsh-agent-team-gui run build
   

   预期：两条命令均以状态 0 退出，且 dsh-agent-team-gui/lib/ 存在。

2. 生成 tarball：

   pnpm --dir ./dsh-agent-team-gui pack
   

   预期：pnpm 打印生成的归档文件名，通常是 dsh-agent-team-gui-0.1.0.tgz。下一步请使用你的 pnpm 版本实际打印的完整路径。

3. 安装该归档：

   dsh plugin --profile web add -w ./dsh-agent-team-gui/dsh-agent-team-gui-0.1.0.tgz
   

   预期：pnpm 报告已加入 dsh-agent-team-gui，且没有 allowBuilds 提示。若 pack 把归档写到 其他位置，请替换成实际路径。

4. 验证组合包层：

   dsh --profile web --dump-config
   

   预期：dump 中包含 dsh-agent-team-gui 层与 agent-team-gui 行。

5. 重启仍在运行的 dsh Web 进程，然后刷新浏览器。安装或更新只会替换磁盘文件，无法替换进程中 已加载的 Host 模块。UI 会执行 RPC 版本握手；若 Client 与 Host 版本不一致，会明确提示重启， 不再只显示无法解释的感叹号。

从 GitHub 安装

Git 依赖只包含源码，而不是预构建的发布产物。因此本仓库提供自包含的 prepare 路径来构建运行时 入口，不依赖相邻的 dsh monorepo checkout。

你也可以直接对拥有终端权限的 DeepSeek Harness Agent 发送下面这一句话：

根据 https://github.com/toolclub/dsh-agent-team-gui 仓库的 README，把插件安装到 DeepSeek Harness 的 web profile；解析 main 当前 commit 并锁定该 SHA，按 README 配置 pnpm allowBuilds，最后用 dsh --profile web --dump-config 验证安装。

1. 锁定并安装已经审查的 commit：

   dsh plugin --profile web add -w github:toolclub/dsh-agent-team-gui#<commit-sha>
   

   pnpm 10 及以上版本首次执行时的预期：安装可能失败，因为 pnpm 会阻止 Git 依赖的 prepare 脚本。pnpm 会打印精确的包键，dsh 会打印需要修改 pnpm-workspace.yaml 的 profile 目录。

2. 把 pnpm 打印的键原样加入该 profile 的 workspace 文件。使用默认 dsh home 时，编辑 ~/.dsh/profiles/web/pnpm-workspace.yaml；设置了 DSH_HOME 时编辑 $DSH_HOME/profiles/web/pnpm-workspace.yaml：

   allowBuilds:
     dsh-agent-team-gui: true
   

   预期：YAML 保留已有 workspace 设置，并在 allowBuilds 下包含 pnpm 打印的键。若 pnpm 打印 了其他键，不要猜测。

3. 重新执行同一条锁定 commit 的安装命令：

   dsh plugin --profile web add -w github:toolclub/dsh-agent-team-gui#<commit-sha>
   

   预期：pnpm 获准运行 prepare，完成构建并报告包已加入。

4. 验证组合包层：

   dsh --profile web --dump-config
   

   预期：dump 中包含 dsh-agent-team-gui 层与 agent-team-gui 行。

[!CAUTION] allowBuilds 表示授权该包在安装时于你的机器上执行代码。这些代码运行在所有 dsh agent 沙箱 之外。只放行源码可信的包，审查所选 revision，并用 github:owner/repo#<sha> 锁定 commit， 防止后续 push 静默改变实际执行内容。使用已构建 tarball 可避免此构建授权。

配置

组合包会插入以下宿主行：

- id: agent-team-gui
  name: dsh-agent-team-gui
  config:
    defaultProvider: spawn
    defaultExecutionMode: serial
    defaultContextMode: spawn

字段	类型	默认值	含义
defaultProvider	string	spawn	派单/上下文没有选择其他 provider 时使用的已注册 dsh subagent provider。
defaultExecutionMode	serial | parallel	serial	默认成员调度方式。
defaultContextMode	spawn | fork | chain	spawn	spawn 启动无父上下文的新子 Agent；fork 包含父会话已完成 turn 的前缀；chain 把每个串行成员的文本传给下一位。

若要覆盖某个 profile，请编辑 $DSH_HOME/profiles/<name>/cordis.patch.yml：

- id: agent-team-gui
  config:
    defaultProvider: fork
    defaultExecutionMode: parallel
    defaultContextMode: fork

dsh patch 行会整体替换 config，不会深合并。覆盖该行时请重写所有需要的字段。chain 只能与 串行执行搭配。

Agent 记录字段：

字段	必填	含义
name	是	显示名称。
systemPrompt	是	传给子 Agent 的角色/persona。
provider	是	已存在的 dsh provider 路由名。
model	是	该 provider 下已有的 model id。
maxTokens	否	单 Agent token 上限。
toolScope.allow / toolScope.deny	否	应用于该子 Agent 的 dsh 工具名限制。

小队记录字段：

字段	必填	含义
name	是	Settings 与对话选择器使用的全局显示名称。
members	是	小队可用且不重复的 Agent ID。
collabNote	否	加入成员 prompt 的协作说明。
executionOrder	否	包含全部成员的固定完整顺序；省略时由主模型规划。
executionMode	否	小队默认值：serial 或 parallel；省略时回退到插件配置。
contextMode	否	小队默认值：spawn、fork 或串行专用 chain；省略时回退到插件配置。

小队记录包含 name、可选协作说明、成员列表、可选 executionOrder，以及可选的 executionMode/contextMode 默认值。一个 Agent 可以属于多个小队。Settings → 小队通过仅 loopback 可用的宿主 RPC 编辑这些全局记录。固定的 executionOrder 必须恰好包含所有成员且不重复； 未固定时，主模型规划分工，并在派单时给出完整 memberOrder。插件只保存路由名称，不保存或复制 provider 密钥。

同进程 Service API

插件作者也可以在同进程直接使用该注册表：

const agentId = await ctx.agentTeamGui.createAgent({
  name: 'Reviewer',
  systemPrompt: 'Review for correctness and cite concrete evidence.',
  provider: 'your-configured-provider',
  model: 'your-configured-model',
  toolScope: { allow: ['bash', 'str_replace_editor'] },
})

const squad = await ctx.agentTeamGui.createSquad({
  name: 'Release review',
  collabNote: 'Run independent checks, then consolidate findings.',
  members: [agentId],
})

Service 还提供两类记录的 get/list/update/delete 方法、addMemberToSquad、 removeMemberFromSquad、exportDefinitions/importDefinitions 与可编程 dispatch 方法。准确 TypeScript 签名以包导出的声明文件为准。

使用示例

自然语言派单（已有小队后可用）

用户：把这个任务交给发布审查小队：检查补丁是否引入回归。
      让 reviewer 查正确性，test agent 并行运行重点测试。

助手：[调用 dispatch_to_squad，传入 squadId、task、
      assignments=[...]、executionMode="parallel"、contextMode="spawn"]

助手：小队返回了两个成员结果。Reviewer 发现……，重点测试……。
      任何失败成员都会被明确列出，而不会被省略。

由模型选择是否调用 dispatch_to_squad；本插件不会用正则解析用户文本。squadId 可以是持久化 ID，也可以是小队准确名称（不区分大小写）；若名称重复，必须使用持久化 ID。工具参数为 squadId、task，以及可选的 assignments: [{ agentId, task }]、executionMode 和 contextMode。 当小队没有固定 executionOrder 时，还可传 memberOrder；一旦传入，它必须完整、无重复地排列 所有成员。小队已有固定顺序时，单次调用不能覆盖它。工具会把完整 canonical JSON 结果渲染为文本， 其中包含每个成员的 runId、childId、状态、错误、stop reason 和输出，供主模型生成最终汇总。

对话协作开关

1. 启动 dsh --profile web，打开 Settings → 小队。
2. 创建 Agent，从 dsh 已配置路由中选择 provider/model；可选填写 max tokens 与逗号分隔的 允许/禁用工具。
3. 创建全局小队、勾选成员、可选填写协作说明，并可选固定成员顺序。不设置顺序时由模型规划分工 与顺序。
4. 打开任意对话，在小队选择器中选择发布审查小队，并开启小队协作。
5. 在普通输入框填写任务后点击发送。关闭开关后，该对话恢复普通单 Agent 发送。

用户输入：检查这次修改并给出发布建议。
对话控制：发布审查小队 -> 开启协作
用户选择：发送

助手：[选中的小队以当前对话为 parent 开始协作]
助手：发布审查小队建议…… Reviewer：…… Test agent：……

小队选择属于当前对话，且模式会持久化；逐 session 模式和全局 Agent/小队定义都会在重启后保留。 删除已选小队时，受影响的 session 模式会自动关闭。发送时不需要第二个任务框或单独的“派单”按钮。 内部会注入动态 system prompt，指示主模型调用一次 dispatch_to_squad，再把结果汇总为正常 assistant 回复。这属于 best-effort 模型指令，而不是 API 层硬性强制的工具调用；详见“已知限制”。

定义导出/导入

Settings → 小队可以把全部持久化定义导出/恢复为一个 JSON 文档。

• 导出下载 agent-team-gui-<日期>.json，内容为 { "format": "agent-team-gui/definitions", "version": 1, "agents": [...], "squads": [...] }——每条记录携带持久化 id 与模型路由（绝不包含 API key）。
• 导入读取该文件并按 merge 语义应用：文档中的行按 id upsert；文档未提及但已存在的行会 保留；小队可以引用存储中已有的 agent。整个文档先做完整校验（结构、重复 id、模型路由、小队 成员引用），因此被拒绝的导入不会写入任何数据。（持久化写入本身不是单一事务：中途存储失败可能 留下部分应用的结果。）

进程内同样可用 exportDefinitions() 与 importDefinitions(document, mode)；mode 为 merge （默认）或 replace。replace 让文档成为整个存储，此时小队只能引用文档内的 agent。

可观测性与失败行为

父会话的常规 tool/call 与持久化文本 tool/result 事件会保留请求和完整 canonical JSON 聚合结果。 若成员已经启动，其结果 会包含 provider 所有的 child session/run ID，可通过 dsh 现有 subagent/session 视图检查 trajectory。 宿主日志也会记录成员的开始/结束/失败。结果会区分完成、部分完成与失败成员。单个成员失败会连同 错误一起进入聚合结果，不会静默停止无关成员。插件不创建长驻子进程；Cordis 负责工具/监听器清理， 插件卸载时会关闭 storage domain。

卸载

通用形式是 dsh plugin --profile <name> remove <pkg>。本 Web 组合包执行：

dsh plugin --profile web remove dsh-agent-team-gui

预期：pnpm 移除依赖，dsh 从 profile 的组合包列表中移除 dsh-agent-team-gui。dsh 存储后端中的 持久化记录不会自动删除。

已知限制

• 仅支持 Web profile；本组合包依赖 dsh Web 的 storage、Connection RPC 与 browser module 服务， 不支持 headless 或裸自定义 profile。
• 没有独立的 shell CLI/YAML 记录编辑器；请使用 Settings 或同进程 Service API。
• 尚无自定义 squad/* 会话事件类型：当前树外插件 API 无法把它们注册到 dsh known-event catalog。 可观测性依赖标准工具事件、子会话和宿主日志。
• storage domain 版本为 0；developer-preview 版本可能拒绝旧磁盘数据或要求迁移。
• dsh 在子 Agent 运行时验证模型路由名；provider/model 被删除或拼写错误时会形成明确的成员失败。
• 小队模式属于 best-effort 模型编排：动态 system prompt 会要求恰好调用一次 dispatch_to_squad，但当前 Harness generation API 没有 toolChoice，插件无法在 API 层硬性强制。
• 大规模 fan-out 尚未使用 workflow engine 的并发控制。
• dsh API 尚未稳定，因此兼容范围有意限定为 >=0.1.0-rc.5 <0.2.0。

Roadmap

• 为 Settings 增加批量编辑和更丰富的逐 Agent 分工控制。
• 为持久化定义增加 schema migration。
• 为大规模小队增加有界并发与更丰富的 trajectory projection。

贡献指南

1. 创建 issue，说明行为与 dsh 版本。
2. 用 pnpm install 安装依赖，用 pnpm run build 构建。
3. 添加针对性测试，并按适用范围运行 pnpm test、pnpm run typecheck 和 pnpm pack。
4. 保持 RPC 仅限 loopback；绝不存储 API key；只使用在匹配源码版本中确认过的 dsh API。
5. 提交范围集中的 pull request，commit message 使用英文。

许可证

本项目按 MIT License 发布。