前言¶
DSH 裏給子代理選模型，原本只有三檔：工具實例的靜態 agentOptions、會話級的 subagent-model-selection 白名單、具名子代理庫的逐條目配置。這三檔都表達不了一件事：你在哪個項目目錄裏幹活，子代理就用那個項目配好的模型。結果是每次派活都要手動挑一遍，或者乾脆將就。
dsh-subagent-routes 就是補這一檔的插件。它由 zdt3476 維護，倉庫爲 zdt3476/dsh-subagent-routes，社區目錄分類歸在「模型推理」。插件按工作區的目錄做最長前綴匹配，把匹配到的 provider / model / 思考等級注入子代理的 agentOptions，並提供可視化設置頁。下面介紹它的能力與用法。
這是什麼¶
一句話定位：一個 DSH 插件，根據子代理派活時父會話所在的工作區目錄，爲子代理指定 provider、模型與思考等級。
它解決的痛點是「項目級路由」。前端項目想找強模型、長文檔研究想固定最大思考等級、臨時腳本想用便宜模型、一個倉庫裏不同子目錄用不同策略——這些都無法用現有三檔配置表達。插件用一張最長前綴匹配的路由表覆蓋這些場景，同時提供一個設置頁，避免手寫 YAML。
社區目錄頁的分類是「模型推理」，倉庫當前爲 1 stars，屬於小體量個人項目。
核心功能¶
路由只作用於新派活的子代理，對已經在跑的會話不做任何改動。
插件介入的位置很單一：所有創建子代理的入口（subagent、subagent_fork、workflow、agent-team、具名子代理庫的 delegate）最終都會調用 ctx.subagents.startActivation，插件只在這一處攔截。因此它天然覆蓋全部派活路徑，不需要改 DSH 本體。
處理流程是：
- 讀父會話的當前工作目錄（
workingDirectory投影優先，回落到會話頭cwd）； - 在路由表裏做最長前綴匹配；
- 把匹配到的 provider / model / reasoningEffort 合併進
request.agentOptions； - 按需調用
llm.resolveCallConfig()預檢，路由非法時在派活處直接失敗。
派活時不寫會話事件、不改 profile；只有用戶保存基礎配置時，才通過宿主 configEditor.edit 持久化到當前 profile，並校驗、重載插件。
設置頁提供三級聯動選擇：Provider、Model、思考等級全部從宿主已探測的列表裏選，不用背 ID。私有通道支持「手動輸入」。未選 Provider 時 Model 下拉按廠商分組列出全部模型，選項內部同時編碼 provider + model，不同廠商的同名模型不會互相覆蓋。思考等級跟隨所選模型的真實元數據：模型不支持推理時選項置灰並清空；支持時只列出該模型的專屬檔位；手動輸入的未知模型 ID 會保留已選等級，插件不擅自改寫。
項目規則裏的「項目根目錄」默認從宿主已登記的工作區裏挑（顯示爲「標題 — 路徑」），需要 ~/... 或更細的子目錄時可切「手動輸入」。偏好直接編輯時，右上角可切「原始 YAML 模式」，可視化表單與 YAML 雙向同步，保存時校驗結構。
此外，會話頁面輸入區有一個狀態藥丸（子 provider / model ▾），點擊可就地臨時切換本會話的 provider / model，用於臨時拔高或降配，而不必改規則。右側欄仍保留一個更接近配置表單形態的「子代理」tab，兩處共用同一份優先級判定與數據面。
安裝與啓用¶
安裝命令來自倉庫 README：
# 從本地目錄安裝
dsh plugin --profile desktop add /path/to/dsh-subagent-routes
# 或從 npm 安裝（發佈後）
dsh plugin --profile desktop add @zdt3476/dsh-subagent-routes
首次安裝、或從沒有 client 的舊實現升級後，需重載插件或重啓 DSH，確保宿主加載新的 client 能力；僅打開舊設置頁不會補載新入口。若重載後仍無設置入口，請重啓 DSH。
安裝後設置入口出現在「插件管理 → 本插件 → 設置」，bundle 卡片與 patch 插件行均提供入口。會話頁右側欄 tab 與輸入區藥丸由同一份 client 產物註冊；若右側欄沒出現「子代理」，同樣先重載插件，仍不行再重啓 DSH（客戶端插件的 Slot 註冊只在插件加載時進行）。
典型用法¶
三步即可跑起來，全程不需要手寫 YAML：
- 打開設置頁：插件管理 → 本插件 → 設置。
- （可選）設全局默認模型：沒匹配到任何項目時用它兜底，留空則繼承父會話模型。
- 添加項目規則：點「+ 添加項目規則」→ 從工作區下拉選項目 → 從模型下拉選模型 → 思考等級自動跟着模型聯動 → 「確認保存規則」→ 底部「保存所有更改」。
保存後下一次新派活立即生效，不需要重啓 DSH。
也可以直接手寫路由表。默認位置是 $DSH_HOME/subagent-routes.yaml（通常是 ~/.dsh/subagent-routes.yaml），可視化設置頁就是它的編輯器：
default:
provider: openai
model: gpt-4.1
reasoningEffort: medium
routes:
- path: ~/Code/frontend-app
provider: anthropic
model: claude-sonnet-4
reasoningEffort: high
- path: ~/Code/frontend-app/legacy # 更長前綴優先
provider: deepseek
model: deepseek-chat
- path: ~/Code/research
reasoningEffort: max # 只改等級，provider/model 繼承父會話
字段規則：path 必填，絕對路徑或以 ~ 開頭，尾部分隔符會被規範化掉；provider 與 model 必須同時出現或同時省略；reasoningEffort 使用適配器自有的等級 id（low / medium / high / max 等，取決於模型）；三者至少要有一個。
改路由表後，下一次新派活即生效，每次派活都會重讀文件，不需要重啓。
優先級規則¶
從高到低：
調用方顯式指定 > 本會話選擇 > 項目規則 > 全局兜底 > 全局默認策略
具體行爲：
- 調用方顯式給了
provider+model→ 插件完全讓位，連思考等級也不追加（這是給工作區模型配的等級，套到另一個模型上可能不被支持）。 - 調用方只給了
reasoningEffort→ 插件補 provider / model，保留其等級。 - 本會話選了「繼承主代理」→ 直接讓位，項目規則與全局策略都不介入。
- 本會話選了「指定一套」→ 覆蓋項目規則。
- 本會話未做選擇（界面默認態，存儲層記爲
follow）→ 繼續按上述層次判定。 - 全局策略是「繼承主代理」→ 讓位，不查路由表。
- 全局策略是「使用路由規則」→ 按目錄匹配項目規則，未命中時用全局兜底。
- 所有層都沒有內容 → 插件不注入任何字段，子代理保持 DSH 原生的繼承行爲。
會話級切換存在 $DSH_HOME/subagent-routes.overrides.json，與路由表同目錄，原子寫入、保留最近 100 個會話。注意「繼承主代理」沒有可寫入路由表的 provider / model，該狀態下「固化爲項目規則」按鈕會置灰；固化到某目錄時該目錄已有條目會被替換，不會追加成第二條。
插件配置項¶
在 profile 的 cordis.patch.yml 裏按 id 覆蓋。同 id 的 override 會替換整個 config，三個字段要寫全：
- id: subagent-routes
config:
routesFile: ~/.dsh/subagent-routes.yaml
enabled: true
preflight: true
fallbackPolicy: rules
| 字段 | 默認 | 說明 |
|---|---|---|
routesFile |
$DSH_HOME/subagent-routes.yaml |
路由表路徑，留空用默認位置 |
enabled |
true |
路由注入開關，false 時停止注入，設置入口仍保留 |
preflight |
true |
注入前用 llm.resolveCallConfig 校驗路由，關掉則把錯誤留到子會話首輪 |
fallbackPolicy |
rules |
inherit = 沒有更具體來源時繼承主代理模型；rules = 按路由表注入 |
這四項在設置頁裏分別對應「已啓用 / 已暫停」開關、「全局默認策略」卡片與摺疊的「高級選項」，改完點底部「保存所有更改」即可，無需手工編輯 profile。fallbackPolicy 寫了未知值時按 rules 處理，並在日誌裏保持可解釋。
適用場景與注意¶
適合需要項目級模型路由的 DSH 用戶，尤其是一個 profile 下同時維護多個項目、對成本與能力檔位有差異化要求的開發者，或想按目錄固定思考等級的長文檔研究場景。
使用時要清楚幾點：
- 插件隻影響新派活，正在運行中的子代理不會被重新路由。
fork同樣適用，但 fork 會繼承父會話的對話前綴，換模型會讓這段前綴的 provider 側緩存失效，屬於預期代價。- 前綴匹配是純字符串的，不做 realpath，符號鏈接和
..不會自動歸一。 - 工作區與模型列表來自宿主；宿主沒提供對應服務或該 profile 尚未登記工作區時，設置頁會自動退回手動輸入。
- 會話指定必須成對給模型，只指定 provider 或只指定思考等級會被拒絕。
- 路由表寫錯時日誌會給出行號級說明，該次派活按「無路由」繼續，不會阻塞工作。
還需要說明的是，插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證。倉庫聲明爲 MIT 許可（見 package.json 的 license），要求 Node ^22.19.0 || >=24.0.0、DSH >=0.2.1-0。
結尾¶
dsh-subagent-routes 做的事情很窄：把子代理的模型路由從「全局一個選擇」細化到「按工作區目錄一條路由」。它的價值在於不需要改 DSH 本體、原生覆蓋全部派活入口，並提供可視化設置頁降低維護成本。項目當前星標不多，功能邊界寫在「已知邊界」一節，是否有自己需要的行爲，建議對照後再看是否採用。
目錄頁：https://www.skillhub.cn/plugins/zdt3476/dsh-subagent-routes
GitHub：https://github.com/zdt3476/dsh-subagent-routes
