前言¶
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
