前言¶
DSH 的插件體系允許擴展 harness 的模型選擇、設置卡片和請求路由能力。dsh-model-router 是一個社區插件，用於解決一個具體場景：用戶已經配置了多個提供商和多個模型，希望在模型選擇器中統一看到全部模型，並在每次 LLM 請求發出時，把請求發到該模型當前激活的提供商。
它不在會話中保存真實提供商，而是讓會話始終使用虛擬提供商 model-router，請求發出時再解析當前激活提供商並委派給原有 adapter 管線。下面介紹它的能力、安裝方式和配置項。
這是什麼¶
dsh-model-router 由 fonlan 維護，許可證爲 MIT。
它向 DSH harness 註冊一個虛擬模型提供商：
model-router
該提供商會匯聚用戶已添加的所有提供商及其模型，並按 model id 嚴格歸併。每次 LLM 請求發出時，插件會把請求路由到該模型當前激活的提供商。
設置入口位於：
設置 → 插件 → 插件配置 → 模型路由
核心能力¶
虛擬 model-router 提供商¶
安裝後，model-router 會出現在輸入框下方的模型選擇器中，也會出現在默認模型設置等模型選擇入口中。
它列出全部已配置提供商的所有模型。模型條目會標註當前激活提供商，例如：
via OpenCode Go
這意味着用戶看到的不是分散在各個提供商下的模型，而是一個統一的模型入口。
模型選擇菜單中的提供商切換¶
噹噹前會話選擇的是 model-router 模型時，點擊輸入欄的模型選擇器，可以看到「模型 / 提供商 / 推理等級」三欄菜單。
其中「提供商」一欄會列出該模型當前激活的提供商，支持直接切換。切換後，該模型後續請求會使用新的激活提供商。
該入口顯示由 showQuickSwitch 控制。當 router 全局只有一個提供商，或當前模型僅由一個提供商服務時，提供商欄會自動隱藏。
嚴格按 model id 歸併¶
同一個模型如果出現在多個提供商中，會被歸併爲一條模型條目。
模型展示名、上下文窗口、推理檔位等參數會跟隨當前激活的提供商。請求時，插件會按該提供商的原始模型 ID 發給真實提供商。
匹配時忽略模型 ID 前綴¶
插件支持匹配時忽略模型 ID 前綴，默認開啓，可通過設置關閉。
例如配置示例中：
deepseek/deepseek-v4-flash
和：
deepseek-v4-flash
可以視爲同一模型，統一顯示不帶前綴的模型 ID。請求時傳入帶前綴的 ID 也能命中同一路由。
這裏只是配置示例，不表示這些模型一定可用。
請求時即時路由¶
會話中始終保存：
provider=model-router
每次 LLM 請求發出時，插件在進程內解析當前激活提供商，並委派給真實 adapter 管線處理。
這種方式對主 agent、子代理、工具 LLM 調用使用同一路由邏輯。
設置卡片¶
設置卡片位於：
設置 → 插件 → 插件配置 → 模型路由
在設置卡片中，每個模型下列出其全部提供商，並支持以下操作：
- 點擊提供商，切換當前實際使用的提供商。
- 拖拽提供商，調整優先級順序。
- 未配置 API 密鑰的提供商不可選，並會被標灰。
order 和 active 分開維護：
- 點擊切換隻改
active。 - 拖拽排序只改
order。
order 用於維護優先級順序，爲後續自動切換策略預留；當前版本在請求失敗時直接返回錯誤，不做自動切換。
模型顯示順序¶
模型選擇列表中的 model-router 分組支持三種顯示順序：
custom | name | recent
含義如下：
custom：自定義順序，可手動拖拽模型順序。name：按名稱排序。recent：最近使用排序，最近請求過的模型排最前，未用過的排最後。
切換顯示順序和拖拽模型順序後，全局即時生效。
自動同步配置¶
新增或刪除提供商、模型後，插件會自動同步配置：
- 消失的提供商從排序中清理。
- 激活提供商失效時，自動回落到剩餘第一位。
- 新提供商追加到排序末尾。
- 消失的模型從自定義順序中清理。
- 新模型追加到自定義順序末尾。
- 未配置過的模型自動選擇排序第一位。
modelOrder 和 recentlyUsed 由插件自動維護，無需手寫。
CLI 和 headless profile¶
插件不僅用於 web profile。CLI / headless profile 安裝後，同樣會按照配置進行路由。
這類場景下，可以直接手改 settings.yaml 中的 model-router 段。
安裝與啓用¶
從 npm 包安裝¶
使用官方安裝命令：
dsh plugin --profile web add @fonlan/dsh-model-router
本地源碼安裝¶
也可以從倉庫本地構建後安裝。在倉庫目錄下構建出 lib/ 產物後，以本地目錄方式添加：
pnpm build
dsh plugin --profile web add .
掛載與生效¶
安裝後，插件通過 cordis.patch.yml 自動掛載到目標 profile：
- 服務端註冊
model-router提供商與路由配置。 - web 端註冊
settings.plugin.item設置卡片。 - 重啓 profile 後生效。
web profile 重啓後，輸入框下方的模型選擇器中會出現 Model Router 分組。
注意：插件以當前 DSH 進程權限運行。安裝前應檢查源碼和許可證。該插件許可證爲 MIT。
配置示例¶
路由配置持久化在 settings 文檔的 model-router 命名空間中。下面給出一個配置示例；其中的模型 ID 僅作爲示例，不表示模型可用性。
model-router:
showQuickSwitch: true
ignoreModelIdPrefix: true
modelSort: custom
modelOrder:
- deepseek-v4-flash
- qwen3.7-max
recentlyUsed:
deepseek-v4-flash: 1787036509332
models:
deepseek-v4-flash:
order:
- opencode-go
- deepseek-official
active: opencode-go
各配置項含義如下：
showQuickSwitch
控制在模型選擇菜單中是否顯示提供商切換入口，默認開啓。
ignoreModelIdPrefix
控制匹配時是否忽略模型 ID 前綴，默認開啓。
modelSort
控制模型顯示順序，可選：
custom | name | recent
默認值爲：
custom
modelOrder
用於 custom 模式下的模型顯示順序，由插件自動維護。
recentlyUsed
用於 recent 模式，記錄模型 ID 與最後使用時間戳，由插件自動維護。
models.<model>.active
當前實際使用的提供商。
models.<model>.order
提供商優先級順序，用於後續自動切換策略。
典型用法¶
Web profile¶
1、安裝插件並重啓 profile。
dsh plugin --profile web add @fonlan/dsh-model-router
2、打開：
設置 → 插件 → 插件配置 → 模型路由
3、在某個模型下點擊提供商，切換當前實際使用的提供商。
4、如需調整優先級，可以拖拽提供商順序。
5、回到輸入框下方的模型選擇器，選擇 model-router 中的模型。發起請求時，會路由到當前激活提供商。
CLI / headless profile¶
1、安裝插件到目標 profile。
2、重啓 profile。
3、修改 settings.yaml 中的 model-router 段，例如調整：
models.<model>.active
models.<model>.order
modelSort
showQuickSwitch
ignoreModelIdPrefix
4、重啓後按配置路由。
適用場景與注意¶
適合以下 DSH 用戶：
- 已經配置多個提供商。
- 同一個模型可能來自多個提供商。
- 希望在一個模型選擇器中統一查看模型。
- 希望手動切換某個模型當前使用的提供商。
- 希望手動維護提供商優先級順序。
- 需要在 web、CLI 或 headless profile 中使用同一套路由配置。
需要注意以下幾點：
- 當前提供商請求失敗時，插件直接返回錯誤；自動切換是後續規劃功能。
order和active分開維護，點擊切換不會改變拖拽出來的優先級順序。- 未配置 API 密鑰的提供商在設置卡片中不可選。
- 配置示例中的模型 ID 只是示例，不表示這些模型可用。
- 插件以當前 DSH 進程權限運行，安裝前應檢查源碼和許可證。
- DSH 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係，不應視爲官方應用商店。
結尾¶
dsh-model-router 的價值，是把多個提供商的模型入口收斂到 model-router 這一個虛擬提供商下，並在每次請求發出時解析當前激活提供商。它適合需要統一管理多提供商模型入口、手動切換當前提供商並維護優先級的 DSH 用戶。
目錄頁：未提供已覈實 URL。
GitHub：
https://github.com/fonlan/dsh-model-router
