dsh-agent-team
在 DeepSeek Harness (DSH) 中启用 Agent Teams 的一套配置方案与配套工具。
在V0.2.2-rc.5版本之后DSH已经修复了这个插件,如果版本是随着官方更新的不需要理会。已经诊断为是dsh官方在rc3版本时候将team从插件放到session中
目录
动机
DSH 0.2.2 重构了 Agent Teams,将其从「安装即启用」改为每会话开关。这次重构带来两个后果:
- 默认关闭。 Team 包随
@deepseek-ai/dsh-base安装,任务板工具也存在,但新会话不会启用它们。用户必须显式配置才能使用。 - 配置分散。 启用 Team 需要改 profile 补丁,而 DSH 的补丁语法有易错点(
- id:是修改而非新增),缺少文档。
本项目提供一份经过验证的最小配置,以及两个用于验证的脚本。目标读者是需要在其他 DSH 安装上复现同一套配置的开发者。
核心概念
理解以下三者的关系,是正确使用本项目的前提。
子代理 ≠ 智能体团队
子代理(subagent) = 创建方式 智能体团队(Team) = 协作层
子代理负责创建和委派任务,始终可用,无需任何配置。
Team 不创建 Agent。 它只在已有的 subagent 树上增加一块共享任务板。
没有 Team 时子代理照样工作,只是成员之间互不知情,可能重复修改同一文件。
Team 提供的协作能力
| 能力 | 说明 |
|---|---|
| 任务依赖 | 任务 B 必须等任务 A 完成才能被认领 |
| CAS 归属 | 认领/完成/释放使用 compare-and-set,旧更新不覆盖新工作 |
| 写作用域提示 | 两个进行中任务路径重叠时警告,但不阻塞 |
| 根可重分配 | 主智能体可把任务改派给任意可达后代 |
| 跨深度可见 | list_agents 列出整棵树 |
Team 不提供:隔离工作目录、跨进程协调、自动释放任务归属。
三个正交的开关
| 开关 | 作用 | 默认 |
|---|---|---|
agent-team.defaultEnabled | 是否提供任务板 | 关闭 |
subagent 工具 | 能否创建子代理 | 始终可用 |
subagent-model-selection-settings | 队友能否用非父模型 | 关闭 |
三者互不依赖,可任意组合。
功能
- 一行配置启用 Team 模式,无需安装插件或修改
app.asar - 队友默认跟随主智能体模型,零维护,适用于任何 provider 配置
- 支持为队友指定不同模型(含第三方厂商),需维护模型清单
- 附带验证脚本,可确认配置生效、路由正确
架构
模型继承链路
主智能体会话(当前路由)
│
│ subagent({ description, prompt }) ← 不带路由字段
▼
resolveChildAgentOptions(parent, undefined, depth)
│ 继承 provider / model / reasoningEffort / maxTokens
▼
子会话运行在主智能体的路由
为何默认路径无需授权
subagent 接受 provider、model、reasoning_effort,但都是可选的。授权校验只在显式指定路由时执行:
function requestedAgentOptions(configured, request, enabled, policy, parentOptions) {
if (!hasDelegationModelRequest(request)) return configured; // ← 提前返回,不检查 policy
if (!enabled) throw new Error("child model selection is disabled for this tool instance");
assertNonEmpty(request.provider, "provider");
assertNonEmpty(request.model, "model");
assertAllowedModelSelection(policy, parentOptions, { provider, model });
…
}
hasDelegationModelRequest() 仅在三个字段之一存在时为真。因此裸调用 subagent({ description, prompt }) 完全跳过白名单,直接继承父路由。
这就是「跟随主智能体」不需要模型清单的原因——它是工具的默认路径,且本就已授权。
会话策略的生命周期
会话创建 ──► 写入 subagent/model-selection-policy ──► 该会话终身使用
(不追溯更新)
策略在 agent/created 时写入一次。修改 allowedModels 后,已有会话仍用旧策略。
前置要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| DSH | ≥ 0.2.2-rc.3 | 重命名 Team 包的版本 |
| Profile | Web 或 Desktop | TUI profile 按进程组合,不使用 preset |
| Node.js | ≥ 20 | 仅运行配套脚本时需要 |
安装
1. 定位 profile 补丁
# macOS / Linux cd ~/.dsh/profiles/desktop # Windows cd "$USERPROFILE/.dsh/profiles/desktop"
要编辑的文件是 cordis.patch.yml,它在所有 bundle 层之后应用。
2. 备份
cp cordis.patch.yml "cordis.patch.yml.bak-$(date +%Y%m%d-%H%M%S)"
3. 追加配置
在文件末尾追加:
# --- Agent Team: 为新会话启用共享任务板 ---
- id: agent-team
config:
maxTasks: 256
defaultEnabled: true
保存后 DSH 会在数秒内热加载(profile 默认 patchReload: live)。
补丁语法注意 只写
- id:是修改已有行,不会创建新行。agent-team已存在于@deepseek-ai/dsh-base,所以这里用裸- id:是正确的。新增插件才需要- insert:。
4. 验证
node scripts/verify-setup.mjs --profile desktop --home ~/.dsh \ --asar "<DSH安装目录>/resources/app.asar"
使用
方案 A:队友跟随主智能体
安装完成即可使用。调用时不传路由字段:
subagent({ description: "审查 diff", prompt: "..." })
队友使用主智能体的当前模型。
适用:大多数场景。零维护,任何安装都能用。
限制:所有队友与主智能体用同一模型。
方案 B:为队友指定模型
配置
- id: subagent-model-selection-settings
name: "@deepseek-ai/dsh-tool-subagent/model-selection-settings"
config:
enabled: true
allowedModels:
- provider: <provider-id>
model: <model-id>
也可用 GUI:设置 → 子智能体 → 允许 Agent 为子智能体选择模型,勾选后保存。
调用
subagent({ description: "...", prompt: "...",
provider: "<provider-id>", model: "<model-id>" })
| 传入参数 | 结果 |
|---|---|
| 都不传 | 跟随主智能体 |
只传 provider 或只传 model | 报错,必须成对 |
provider + model | 使用指定路由 |
再加 reasoning_effort | 使用指定推理强度 |
验证
node scripts/inspect-session.mjs <child-session-id>
期望输出:
origin subagent (parent <lead-session-id>) descriptor <provider>/<model> last req <provider>/<model> · descriptor and request header agree
last req 是实际发送的路由。descriptor 是解析后的路由(含继承值),每个本地子代理都有,不反映调用方是否显式指定。
配置参考
agent-team
| 字段 | 类型 | 默认 | 含义 |
|---|---|---|---|
maxTasks | 整数 ≥ 1 | 256 | 一个 Team 保留的未删除任务上限 |
defaultEnabled | 布尔 | false | 新根会话首个模型步骤前启用 Team |
defaultEnabled: true 会在 agent/created 时为 origin 不是 subagent 的会话写入 team/mode { enabled: true }。已保存的选择总是优先,恢复会话时不会重新应用默认值。
已移除字段(加载时报错而非忽略):maxMembers、maxMessageBytes、disposalTimeoutMs。
subagent-model-selection-settings
| 字段 | 类型 | 默认 | 含义 |
|---|---|---|---|
enabled | 布尔 | false | 为新会话授权面向模型的路由选择 |
allowedModels | {provider, model}[] | [] | 提供给新顶层会话的精确路由 |
两个字段都是 volatile,编辑时不会重挂插件。
警告
enabled: true且allowedModels为空会让会话创建抛错:enabled subagent model selection requires at least one allowed model。 始终填充列表,或保持enabled: false。
tool-subagent(通常不需要)
Web/Desktop preset 已为 subagent 设置 modelSelection: true 和 modelDiscovery: true。不要往补丁里加 tool-subagent 行:dsh-web-app bundle 会禁用宿主平面的行,由 preset 持有该工具。补丁里的 tool-subagent 行静默无效。
subagent_fork 有意不带路由字段,以保留 provider 端 KV-cache 前缀复用。
配套工具
scripts/ 下有两个可选的验证脚本。它们不参与运行,DSH 不读取它们。
verify-setup.mjs
检查配置是否正确,以及 DSH 是否包含所需的 Team 包。
node scripts/verify-setup.mjs --profile desktop --home ~/.dsh \ --asar "<DSH>/resources/app.asar"
| 参数 | 说明 |
|---|---|
--profile | profile 名称,省略时用脚本所在目录 |
--home | DSH 主目录,默认 ~/.dsh |
--asar | app.asar 路径,用于校验 DSH 版本 |
输出示例:
✓ agent-team.defaultEnabled = true ✓ profile patchReload = "live" ✓ DSH ships dsh-agent-team ✓ DSH ships dsh-tool-agent-team all 6 check(s) passed
inspect-session.mjs
解码会话的 zstd JSONL 日志,显示真实请求路由与策略。
node scripts/inspect-session.mjs <session-id> node scripts/inspect-session.mjs <session-id> --policy node scripts/inspect-session.mjs <session-id> --json
| 参数 | 说明 |
|---|---|
--policy | 额外显示模型选择策略及每条路由 |
--json | 输出 JSON,便于脚本处理 |
--dir | 直接指定会话目录 |
设计决策
为何方案 A 不提供模型清单
白名单用于授权显式选择,不是让委派工作。队友默认跟随主智能体路由,常见场景不需要 policy。
要求清单会让每个安装枚举自己的模型——这恰好破坏了可移植性,而可移植性正是本项目的主要目标。
为何用 defaultEnabled 而非安装 bundle
Team 包已在 @deepseek-ai/dsh-base 内,只有会话开关是关的。启用它是一个字段的改动,不是安装步骤。
为何主智能体当前路由优先于部署默认值
parentAgentOptionsForDelegation() 先读 parent.session.requestHeader()?.config,再回退到 parent.options。请求头反映会话实际在做什么,这正是队友应该继承的。
为何不用运行时插件自动维护清单
实测不可行,原因有二:
- HMR 事务嵌套。 插件加载期间已处于 HMR 事务中,写入配置报
HMR transactions cannot be nested。用setTimeout延迟无效(AsyncLocalStorage上下文会继承)。 - 整份 YAML 往返丢数据。 用
hmr.executing.exit()逃逸事务后,写配置必须整份往返,实测在并发编辑时丢失 provider 条目(发生过两次)。
方案 A 从根上避免这个问题:不写配置。
为何队友是快照而非实时跟随
resolveChildAgentOptions() 在 spawn 时解析并固化路由。这是有意的:队友运行期间切换模型会破坏 provider 端的 KV-cache 前缀复用。
项目结构
dsh-agent-team/
├── README.md 本文档
├── CHANGELOG.md 版本历史
├── CONTRIBUTING.md 贡献指南
├── LICENSE MIT
└── scripts/
├── verify-setup.mjs 配置与版本校验
└── inspect-session.mjs 会话日志解码与路由检查
已知限制
- 策略不追溯。 修改
allowedModels后需新建会话才生效。 - 队友模型固定于 spawn 时。 主智能体后换模型不影响已创建的队友。
agent-default-model只影响新会话。 运行中的会话保留其请求头里的路由。- provider 模型可能被静默丢弃。 DSH 加载时会归一化配置,丢弃它认为无效的模型(如
qoder-cn/qfmodel、hy3系列)。方案 A 不受影响,方案 B 需重新勾选。 - 第三方模型需各自凭证。 每个 provider 使用自己的
apiKeyEnv。
贡献
见 CONTRIBUTING.md。核心要求:
- 每条命令必须在真实 DSH 安装上验证过
- 不要假设特定 provider 或模型数量
- 脚本不引入
yaml之外的依赖
兼容性
| DSH | 状态 |
|---|---|
| 0.2.2-rc.3 | 已验证 — Electron 44.7.0、Node 24.21.0、Windows 11、Desktop profile |
| 0.2.2-rc.1 及更早 | 不支持 — Team 包名称不同且有独立 bundle |

评论区
评论加载中...