前言¶
在 DeepSeek Harness（DSH）裏接入多個 LLM 服務商時，常見做法是分別配置渠道、在模型菜單裏來回切換。會話一旦跨渠道，前綴 KV cache 往往無法複用；某條線路限流或鑑權失敗後，又要手動改模型或改配置。若希望把多條真實渠道收成「一個虛擬服務商」，並在失敗時自動換路、同時儘量讓同一會話釘在同一條線路上，就需要在 Host 側做統一路由與能力合併。dsh-llm-pool 是 lyingloong 維護的 DSH 插件（分類：模型推理），在當前資料中面向 DSH 0.2.1-rc.5，用會話粘性加全局負載均衡和自動切換來應對上述問題。
這是什麼¶
dsh-llm-pool 爲 DSH 增加「統一服務商 / 模型池」：把多個真實模型渠道組合成一個虛擬 provider，在模型選擇器裏像普通渠道一樣選擇。倉庫與 npm 包名均爲 dsh-llm-pool，許可證 MIT，運行時要求 Node.js ^22.19 || >=24，純 JavaScript、無原生依賴；與 DSH 的版本約束爲 >=0.2.1-0 <0.3.0-0（package.json 當前版本 0.1.1）。
插件不單獨保存 provider 密鑰，真實請求仍走用戶已配置好的 provider route；只在 Host 內註冊虛擬路由，並通過設置裏的配置編輯器或 cordis.patch.yml 寫入池配置。
核心功能¶
下面按資料中已寫明的行爲歸納，不超出 README 範圍。
統一服務商與模型映射¶
- 可定義虛擬 provider（例如
pool-a），members列出有序的真實 provider（如provider-a、provider-b）。 - 在虛擬 provider 下定義統一模型 id（如
model-a），通過targets把「成員 → 實際模型 id」一一映射；省略映射時默認各成員使用與統一模型同名的實際 id。
會話粘性 + 全局均衡（默認 strategy: sticky）¶
- 新會話或子代理首次調用時，在候選成員中選當前綁定會話數最少者；相同時輪轉。
- 之後該會話對同一統一模型儘量固定在同一成員，減少換渠道導致的前綴緩存失效。
- 調用失敗且在尚未產生可見輸出前，靜默嘗試下一個候選；若切換後成功，會話綁定會改到成功的成員。
分配粒度爲「會話 + 統一服務商 + 統一模型」。進程重啓後內存中的綁定會重置，但會話已選的 provider/model 不受影響。
失敗切換與健康冷卻¶
- 首 token 前失敗（認證、配額、限流、5xx、超時等）：記錄失敗並進入冷卻，嘗試下一候選。
- 已有可見輸出後再失敗：不拼接兩個渠道的回覆，交給 DSH 自帶的
dsh-llm-retry按 step 重試。 - 認證/配額/限流/服務端/超時等失敗進入冷卻；全部成員冷卻時 fail-open，選最早恢復時間嘗試。
strategy 還可設爲 round-robin（每次調用輪詢）或 failover（固定第一個可用）。
能力合併¶
對統一模型聲明的能力會合並各成員：上下文窗口與最大輸出默認取可用成員的最小值（可手動覆蓋）；推理檔位默認取交集，可用 effortMap 做統一檔位到成員檔位的映射；圖片能力取並集。不支持當前請求能力的成員在調用時會被跳過。
配置界面與可觀測¶
安裝並在 設置 → 模型 頁面底部打開「統一服務商池」面板後，可查看狀態、編輯渠道與模型映射、測試模型；面板可顯示會話分配、路由成功/失敗、冷卻與最近調用等信息。高級字段（推理檔位映射、冷卻毫秒等）可通過「高級 JSON」或 cordis.patch.yml 編輯。
安裝與啓用¶
推薦從 npm 安裝（README 原文命令如下）。web 是 DSH 市場文檔裏的通用 profile 名；若 profile 名爲 desktop，將 --profile web 換成 --profile desktop。
dsh plugin --profile web add dsh-llm-pool
安裝後重啓或刷新客戶端，在 設置 → 模型 底部應出現「統一服務商池」。npm 包頁：https://www.npmjs.com/package/dsh-llm-pool。
從 GitHub 安裝源碼時，資料給出的命令爲：
dsh plugin --profile web add github:lyingloong/dsh-llm-pool
本地開發可將 --profile 與倉庫絕對路徑按 README 說明傳入插件管理器。若環境中存在已從 npm 撤包的老插件導致 pnpm install 失敗，README 建議可通過 registry 選項指定 https://registry.npmmirror.com 繞過，屬安裝環境問題而非本插件邏輯。
插件在帶 llm、Web server、configEditor 的 profile（desktop / web 均可）上工作。安裝前宜自行查看倉庫源碼與 MIT 許可證；插件以當前 DSH 進程權限運行，測試按鈕會發起真實、可能計費的 provider 請求。
典型配置與用法¶
配置保存在當前 profile 的 cordis.patch.yml，也可通過面板保存。完整示例見倉庫 examples/pool.yml。簡例結構如下（字段含義見 README 字段表）：
- id: llm-pool
name: dsh-llm-pool
config:
retryPolicy:
mode: normal
maxRetries: 2
providers:
pool-a:
displayName: Example Pool
strategy: sticky
members: [provider-a, provider-b, provider-c]
models:
- id: model-a
name: Model A
targets:
provider-a: model-a
provider-b: model-a-alt
provider-c: model-a
使用步驟（與 README 一致）：
- 在真實渠道里配好各自的 endpoint、key 與模型；本插件複用這些配置，不要求在池裏再配密鑰。
- 在 設置 → 模型 底部面板點「新增統一服務商」，選擇成員、聚合模型、調整映射後保存。
- 在會話
/model或輸入框模型菜單中選擇pool-a下統一模型；子代理、默認模型、AgentTeams 成員也可直接選該虛擬 provider。 - 在面板中對某模型行點「測試」，可做一次真實流式調用以確認映射與渠道可用。
可選 retryPolicy 將虛擬 provider 失敗後的重試交給 dsh-llm-retry；providers.<id>.cooldown 可覆蓋各類失敗的冷卻時長（毫秒）。
適用場景與注意¶
適合：已爲 DSH 配置多條 LLM 渠道，希望在模型菜單裏呈現一個邏輯上的「池」，在負載與故障之間做默認粘性均衡；需要按成員映射不同實際 model id，或合併多成員能力聲明的場景。
資料中的限制與注意：
- 已輸出內容後失敗無法在同一流上無縫續接，依賴
dsh-llm-retry重試整個 step。 - 會話綁定、健康狀態、最近調用在內存中，重啓或保存配置後相關運行時狀態會重置。
- 默認上下文取各成員最小值可能偏保守，可手動覆蓋
contextWindow/maxTokens。 - 不支持嵌套統一服務商（成員不能是另一個池）。
- 卸載插件後真實 provider 配置保持不變；插件不修改 DSH 核心安裝包。
CI 在 Node 22/24 上運行 npm run verify（27 個單元測試）；端到端與故障切換記錄見倉庫 docs/demo.md。
結尾¶
dsh-llm-pool 把多渠道路由、能力感知映射和失敗前靜默切換收到一個虛擬 provider 裏，默認策略優先保住會話級 KV cache 並做全局會話數均衡。查閱市場條目與源碼可分別訪問 SkillHub 目錄頁與 GitHub 倉庫：
