前言¶

在 DSH 裏跑 Agent 時，模型接口會因爲限流、5xx、鑑權或適配器缺失而失敗。若只依賴同一 provider 上反覆重試，整體掛掉時仍會在壞模型上空轉；若手改配置換模型，又容易打斷會話節奏。dsh-plugin-model-failover（倉庫 Gpan666/dsh-plugin）面向「跨輪、跨步」的模型可用性：當前候選不健康時，在下一次 preStep 之前通過 agent.model.select() 換到下一個健康候選，並對失敗模型做冷卻與可選後臺探活。維護者爲 Gpan666；npm 包名爲 dsh-plugin-model-failover，版本 1.0.0（見倉庫 package.json），許可證 MIT。

下文按「能力邊界 → 機制 → 安裝配置 → 運行時接口 → 注意點」說明，事實以倉庫 README 與 package.json 爲準。

這是什麼¶

一句話：DSH 的模型故障轉移插件——當前模型變得不可用時，下一步（或下一條消息）自動換到下一個健康的候選模型。

依賴 Cordis 的 agents 服務（DSH 默認提供），peer 依賴 @deepseek-ai/cordis（>=4.1.0-0 <5.0.0-0）。插件加載後向上下文註冊 modelFailover 服務。

能力邊界：能做與不能做的¶

README 結合 dsh-agent-loop 源碼說明了架構約束，避免錯誤預期。

不能：同一 step() 內失敗後換模型繼續¶

在 step() 的重試循環裏，decision.selection 在整個 step() 生命週期內固定；prepareRequest() 禁止在 agent/request 中直接改 provider/model（會要求先 agent.model.select()）。step() 拋錯後本輪以 error 結束。agent.model.select() 只對下一次 preStep() 生效，對已在 step() 內的 retry 無效。因此「本步失敗立刻換模型接着寫」需要改 agent loop 本身，不屬於本插件範圍。

能：跨輪/跨步故障轉移與配套能力¶

與 @deepseek-ai/dsh-llm-retry 互補：retry 負責同一模型在 step() 內的重試（限流、5xx、超時等）；本插件負責模型整體不可用時的換代，讓下一條/下一步用健康模型。本插件默認不搶 retry（claimRetry 默認爲 false），先 next() 交給下游，用盡 retry 預算失敗後才終止本輪。

安裝與啓用¶

在 profile 目錄安裝依賴：

pnpm add dsh-plugin-model-failover

在 profile 的 cordis.patch.yml 中插入插件聲明：

- insert:
    - id: model-failover
      name: 'dsh-plugin-model-failover'

安裝前應自行查閱倉庫源碼與 MIT 許可證；插件以當前 DSH 進程權限運行，探活與正常推理一樣走你已配置的 llm 服務。

配置項¶

候選寫法（三種等價）：

deepseek-official/deepseek-v4-flash
deepseek-official|deepseek-v4-flash
deepseek-official deepseek-v4-flash

若單條回覆不能丟，可同時安裝 dsh-llm-retry，與本插件分工如上。

典型用法：modelFailover 服務¶

插件加載後可通過 Cordis 上下文獲取服務並查詢或干預狀態：

const svc = ctx.get('modelFailover')
svc.status()          // { enabled, candidates: [{provider, model, ok, coolingDown, ...}], lastSwitch }
svc.probe()           // 立刻探活一遍
svc.reset()           // 清空健康記錄
svc.updateSettings({ candidates: '...' })   // 運行中改配置，不重啓

日常無需調用上述 API 時，只要在 candidates 中列出備用 provider/model，插件會在 pre-step 與 request-error 路徑上自動維護健康狀態與切換。

網絡與隱私¶

• 探活請求走 DSH 自帶的 llm 服務（你已配置的模型接口），不連接 README 未列出的第三方。
• 插件不寫盤、不讀 Cookie、不處理消息正文（健康狀態目前主要在內存，重啓後重置；restoreOnStart 爲後續持久化預留）。

適用場景與注意¶

適合：多模型候選、希望某條線路整體故障時自動讓後續步驟落到備用模型，並願意接受「切換僅在 step 邊界生效」的 DSH 架構。

注意：

1. 探活消耗 token：每次 1 token；默認 120 秒週期與 2 個候選時，README 估算約一天 1440 次調用。可調長 probeIntervalSec 或減少候選。
2. claimRetry 只改變誰處理重試次數，不會在單步內換模型。
3. 社區目錄頁 skillhub.cn/plugins/Gpan666/dsh-plugin 與 GitHub 倉庫便於檢索；DSH 生態強調「一切皆插件」，該目錄爲社區站點，與 DeepSeek / 幻方無 README 所載的官方從屬關係。

結尾¶

dsh-plugin-model-failover 把「壞模型冷卻 + 下一步選健康候選」做成可配置插件，並與 dsh-llm-retry 在同一輪內的重試分工明確。使用前請確認你接受 step 邊界切換與探活 token 成本，並在 profile 中按 README 完成 pnpm add 與 cordis.patch.yml 配置。

• 目錄頁：https://www.skillhub.cn/plugins/Gpan666/dsh-plugin
• 源碼與文檔：https://github.com/Gpan666/dsh-plugin