dsh-agent-team

dsh-agent-team

Deepseek Harness插件

dsh-agent-team

在 DeepSeek Harness (DSH) 中启用 Agent Teams 的一套配置方案与配套工具。

警告

在V0.2.2-rc.5版本之后DSH已经修复了这个插件,如果版本是随着官方更新的不需要理会。已经诊断为是dsh官方在rc3版本时候将team从插件放到session中


目录


动机

DSH 0.2.2 重构了 Agent Teams,将其从「安装即启用」改为每会话开关。这次重构带来两个后果:

  1. 默认关闭。 Team 包随 @deepseek-ai/dsh-base 安装,任务板工具也存在,但新会话不会启用它们。用户必须显式配置才能使用。
  2. 配置分散。 启用 Team 需要改 profile 补丁,而 DSH 的补丁语法有易错点(- id: 是修改而非新增),缺少文档。

本项目提供一份经过验证的最小配置,以及两个用于验证的脚本。目标读者是需要在其他 DSH 安装上复现同一套配置的开发者。

核心概念

理解以下三者的关系,是正确使用本项目的前提。

子代理 ≠ 智能体团队

text
子代理(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 配置
  • 支持为队友指定不同模型(含第三方厂商),需维护模型清单
  • 附带验证脚本,可确认配置生效、路由正确

架构

模型继承链路

text
主智能体会话(当前路由)
        │
        │  subagent({ description, prompt })        ← 不带路由字段
        ▼
resolveChildAgentOptions(parent, undefined, depth)
        │  继承 provider / model / reasoningEffort / maxTokens
        ▼
子会话运行在主智能体的路由

为何默认路径无需授权

subagent 接受 provider、model、reasoning_effort,但都是可选的。授权校验只在显式指定路由时执行:

js
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 }) 完全跳过白名单,直接继承父路由。

这就是「跟随主智能体」不需要模型清单的原因——它是工具的默认路径,且本就已授权。

会话策略的生命周期

text
会话创建 ──► 写入 subagent/model-selection-policy ──► 该会话终身使用
                                                        (不追溯更新)

策略在 agent/created 时写入一次。修改 allowedModels 后,已有会话仍用旧策略。

前置要求

依赖版本说明
DSH≥ 0.2.2-rc.3重命名 Team 包的版本
ProfileWeb 或 DesktopTUI profile 按进程组合,不使用 preset
Node.js≥ 20仅运行配套脚本时需要

安装

1. 定位 profile 补丁

bash
# macOS / Linux
cd ~/.dsh/profiles/desktop

# Windows
cd "$USERPROFILE/.dsh/profiles/desktop"

要编辑的文件是 cordis.patch.yml,它在所有 bundle 层之后应用。

2. 备份

bash
cp cordis.patch.yml "cordis.patch.yml.bak-$(date +%Y%m%d-%H%M%S)"

3. 追加配置

在文件末尾追加:

yaml
# --- Agent Team: 为新会话启用共享任务板 ---
- id: agent-team
  config:
    maxTasks: 256
    defaultEnabled: true

保存后 DSH 会在数秒内热加载(profile 默认 patchReload: live)。

补丁语法注意 只写 - id: 是修改已有行,不会创建新行。agent-team 已存在于 @deepseek-ai/dsh-base,所以这里用裸 - id: 是正确的。新增插件才需要 - insert:。

4. 验证

bash
node scripts/verify-setup.mjs --profile desktop --home ~/.dsh \
  --asar "<DSH安装目录>/resources/app.asar"

使用

方案 A:队友跟随主智能体

安装完成即可使用。调用时不传路由字段:

text
subagent({ description: "审查 diff", prompt: "..." })

队友使用主智能体的当前模型。

适用:大多数场景。零维护,任何安装都能用。

限制:所有队友与主智能体用同一模型。

方案 B:为队友指定模型

配置

yaml
- 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 为子智能体选择模型,勾选后保存。

调用

text
subagent({ description: "...", prompt: "...",
           provider: "<provider-id>", model: "<model-id>" })
传入参数结果
都不传跟随主智能体
只传 provider 或只传 model报错,必须成对
provider + model使用指定路由
再加 reasoning_effort使用指定推理强度

验证

bash
node scripts/inspect-session.mjs <child-session-id>

期望输出:

text
origin      subagent (parent <lead-session-id>)
descriptor  <provider>/<model>
last req    <provider>/<model>

· descriptor and request header agree

last req 是实际发送的路由。descriptor 是解析后的路由(含继承值),每个本地子代理都有,不反映调用方是否显式指定。

配置参考

agent-team

字段类型默认含义
maxTasks整数 ≥ 1256一个 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 包。

bash
node scripts/verify-setup.mjs --profile desktop --home ~/.dsh \
  --asar "<DSH>/resources/app.asar"
参数说明
--profileprofile 名称,省略时用脚本所在目录
--homeDSH 主目录,默认 ~/.dsh
--asarapp.asar 路径,用于校验 DSH 版本

输出示例:

text
✓ 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 日志,显示真实请求路由与策略。

bash
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。请求头反映会话实际在做什么,这正是队友应该继承的。

为何不用运行时插件自动维护清单

实测不可行,原因有二:

  1. HMR 事务嵌套。 插件加载期间已处于 HMR 事务中,写入配置报 HMR transactions cannot be nested。用 setTimeout 延迟无效(AsyncLocalStorage 上下文会继承)。
  2. 整份 YAML 往返丢数据。 用 hmr.executing.exit() 逃逸事务后,写配置必须整份往返,实测在并发编辑时丢失 provider 条目(发生过两次)。

方案 A 从根上避免这个问题:不写配置。

为何队友是快照而非实时跟随

resolveChildAgentOptions() 在 spawn 时解析并固化路由。这是有意的:队友运行期间切换模型会破坏 provider 端的 KV-cache 前缀复用。

项目结构

text
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。核心要求:

  1. 每条命令必须在真实 DSH 安装上验证过
  2. 不要假设特定 provider 或模型数量
  3. 脚本不引入 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

许可证

MIT

Zcode并发子代理插件 Zcode-dispatch
Pwn-SROP

评论区

评论加载中...