前言¶
DeepSeek Harness（下面简称 DSH）里，subagent 工具创建的子 Agent 默认走与主 Agent 相同的模型路由。如果你想接一个第三方模型，常见做法是直接把主模型换掉——这样主对话和子代理都被绑到同一个模型上，做不到「主模型 A + 子模型 B」。
dsh-subagent-toolkit 补的就是这一层灵活度：不改 DSH 源码、不替换 DeepSeek Account、不影响主对话，只给子代理单独指定一个第三方模型。插件由 leotpp 维护，在社区目录里的分类是「模型推理」，当前版本 0.2.0，许可证 MIT。
下面介绍它的能力、安装方式和使用时要注意的点。
这是什么¶
一句话定位：DSH 的插件，提供「Settings → 子模型」设置页，把子模型从「跟随主模型」解耦为可固定的独立路由。
原生 DSH 有两条模型链路：
| 链路 | 用途 | 由什么决定 |
|---|---|---|
| 主模型 | 主对话、主 Agent | agent-default-model |
| 子模型 | subagent 创建的子 Agent |
tool-subagent 的默认值 / 父 Agent 路由；可选 subagent-model-selection-settings |
原生逻辑有两个限制：
- 子模型默认继承主模型，
subagent未显式传provider/model时子 Agent 与父 Agent 同路由。 subagent-model-selection-settings默认关闭，打开后也只是让主 Agent 在每次subagent调用里从名单里挑一个模型，不是固定默认值。原生的 Plugins → Subagent 页只能勾选授权，不能在同一个页面添加 OpenAI 兼容渠道、拉取模型或设置模型参数，也没有「固定子模型」这一项。
所以直接接第三方模型时，子模型机制实际上被写死在「跟随主模型」上。
核心功能¶
- Settings → 子模型 页面：添加 OpenAI 兼容渠道（Base URL、API Key）、获取模型列表、只选一个子模型；也可以保留「跟随主模型」。
- 写入官方设置：保存为
subagent-model-selection-settings = { enabled: true, allowedModels: [{ provider, model }] }，并同步写入llm-pi-ai.providers的渠道与模型参数（上下文窗口、最大输出、思考强度）。 - 系统提示词引导：当允许名单恰好只有一个路由时，向主 Agent 注入一条提醒，让它在派
subagent时显式带上provider、model和reasoning_effort。这样固定子模型在新会话里才真正生效，而不只是写在配置里。 - 可选的
subagent_pi：用官方 Pi CLI 一次性进程执行子任务，完全独立于 DSH 的 in-process 子 Agent；不加载 PI Desktop 的 Maker，也不触发codex exec。
插件不改 DSH 内核，使用的是 DSH 官方的 bundle / 配置扩展机制。原生的 Plugins → Subagent 页（递归深度、并发、模型授权）仍然可用，两者共存。
运行时路由优先级是：subagent 调用显式传入的 provider/model/reasoning_effort（必须在 Session allowlist 中）> tool-subagent.agentOptions 部署默认值 > 父 Agent 的主模型。
安装¶
先按团队习惯选择安装来源，再执行命令。安装命令来自 README，未使用发布到 npm 的写法（目前也还没有 npm 发布说明）时，用本地路径或打包好的 tgz。
本地路径：
dsh plugin --profile desktop add /absolute/path/to/dsh-subagent-toolkit
或使用仓库里已打好的 tgz：
dsh plugin --profile desktop add ./dist/dsh-subagent-toolkit-0.2.0.tgz
README 也给出了发布到 npm 后的写法：
dsh plugin --profile desktop add dsh-subagent-toolkit
安装后打开 Settings → 子模型。
兼容性：DSH 要求 >=0.2.1-rc.5 <0.3.0，README 说明在 0.2.1-rc.5 上验证过；Client 要求 Web 平台（dsh.client.platform: web），即桌面 App 的 Web GUI；Pi CLI 是可选项，pi 需在 PATH 中，或在 subagent-pi.binPath 配绝对路径。
典型用法¶
- 选择渠道：用已经存在的渠道，或点「添加 OpenAI 兼容渠道」，填 Base URL 和 API Key。
- 获取模型：点「获取模型」，从返回的模型列表里选一个。
- 只选一个模型并保存：保存后会写入
enabled=true+allowedModels=[该路由]；想恢复跟随主模型，就不选模型直接保存。 - 新开会话：设置只在 Agent 创建时采样，保存后请新开会话（或重启 DSH）。
- 可选 Pi CLI：在页面底部的 Advanced 区域配置
subagent_pi。
经过上面的步骤，主模型保持 A 不变，subagent 创建的子 Agent 走 B。验证方式是保存后检查 ~/.dsh/profiles/desktop/cordis.patch.yml 里的 subagent-model-selection-settings，再新开一个会话触发一次 subagent，确认子会话用的是指定模型。
工作原理¶
插件分两半：
| 文件 | 运行位置 | 作用 |
|---|---|---|
client.js |
浏览器（DSH Web GUI） | Settings → 子模型 页面：渠道、模型目录、唯一子模型、Pi CLI 高级项；通过 configForms 写官方配置命名空间 |
index.js |
Host | 注册 pi-cli 子代理提供方（subagent_pi）；读取 subagent-model-selection-settings，在恰好一个路由时注入系统提示词 |
cordis.patch.yml |
Host 启动层 | bundle patch：插入 subagent-pi 和 tool-subagent-pi 两个条目 |
package.json |
— | DSH bundle 清单，声明 engines.dsh 和 client 注入 |
DSH 侧有两个关键点，使用时要记住：
subagent-model-selection-settings是 Host 在 Agent 创建时采样的设置，保存后只对新会话生效，老会话不追溯。subagent工具只有在 Session 存在 allowlist 且调用显式传provider + model时才会切换子路由；未传参时仍按tool-subagent.agentOptions/ 父 Agent 路由走。
配置优先级方面，插件不会比官方优先：DSH 的加载顺序是内置 bundle 层 → 插件 bundle 层 → profile 的 cordis.patch.yml → home 级 cordis.patch.yml（最高）。插件只插入自己的两个条目，不覆盖官方条目。插件的设置页与官方的 Plugins → Subagent 页编辑的是同一个命名空间 subagent-model-selection-settings，谁后保存谁生效；页面内的 revision 校验只防同一页面的并发编辑。
适用场景与注意事项¶
适合这样的团队：主对话已经固定在惯用模型上，但想让子代理的批量化任务（检索、清理、格式化等）走另一个第三方模型来降低成本或改变行为；或者已经接入了 OpenAI 兼容渠道，需要一个不侵入主链路的子模型入口。
安装与使用前请确认以下几点：
- 插件以当前 dsh 进程的权限运行。 它保存的渠道、API Key（经 DSH credential service 存储，设置页不回显）和模型参数都会落到本机 DSH 配置里，安装前先读一遍
index.js/client.js/cordis.patch.yml，确认行为符合预期。许可证是 MIT。 - 固定子模型是软约束，不是内核强制。 它依靠系统提示词提醒主 Agent 传参，模型不遵守时仍可能退回主模型路由。若需要硬默认，请同时设置
tool-subagent.agentOptions，并验证它与模型自选的叠加效果。 - 只影响新会话。 老会话不会更新。
- 路由失效会报错。 删除或重命名渠道/模型后，已保存的 allowlist 会指向不存在的路由，
subagent调用失败；回设置页重新选择并保存即可。 - 升级可能失效。 插件依赖 DSH 扩展点
configForms、settings.section、llm-pi-ai.providers、subagent-model-selection-settings。DSH 升级到0.3.x后，bundle 可能因engines.dsh不匹配被跳过（设置页消失），或 client API 变化导致页面不可用。升级前保留旧版dist/*.tgz以便回滚；升级后按 README 的自检步骤验证设置页和一次 delegation。 - 条目 id 冲突。 插件插入的
subagent-pi/tool-subagent-pi若与未来官方条目重名，Loader 会报重复 id，届时需要改 id 或改用官方能力。 - Pi CLI 是外部进程。
subagent_pi会执行本机的pi二进制，不继承父会话上下文和 DSH Session 记录，只从可信来源安装。未安装pi时只有subagent_pi不可用，不影响原生subagent。
结尾¶
这个插件的价值在于把「主模型」和「子模型」这两条链路解耦，让子代理可以用独立的第三方模型，同时保留 DSH 原生设置页。安装方式是 dsh plugin --profile desktop add ./dist/dsh-subagent-toolkit-0.2.0.tgz，装完在 Settings → 子模型 里配一个唯一模型即可。
目录页：https://www.skillhub.cn/plugins/leotpp/dsh-subagent-toolkit
GitHub：https://github.com/leotpp/dsh-subagent-toolkit
