dsh-model-failover：DeepSeek Harness 兩級熔斷與故障轉移插件

前言¶

在 DeepSeek Harness (DSH) 的智能體開發中，模型或平臺層級的故障（如超時、限流、服務不可用）會導致智能體請求失敗。如果沒有自動切換機制，故障會持續累積。dsh-model-failover 插件通過兩級熔斷策略，在模型或平臺出現故障時自動切換到備用路由，保障服務連續性。

該插件爲 DeepSeek Harness 提供兩級模型熔斷和故障轉移能力。
* 維護者：Letter2025
* 類別：模型推理
* 許可證：MIT

兩級熔斷：支持模型級和平臺級熔斷。當 modelCircuitThreshold 次失敗發生在 burstWindowMs 窗口內時觸發模型熔斷；當 platformCircuitThreshold 個獨立模型熔斷時觸發平臺級熔斷。
故障轉移：主路由熔斷後，下一個請求會自動路由到 fallbacks 中配置的第一個健康備用路由。
恢復探測：熔斷開啓後，經過 modelCooldownMs 冷卻期會進行恢復探測。探測成功則關閉熔斷，失敗則延長冷卻時間。
與 llm-retry 協同：插件與 llm-retry 插件配合工作。llm-retry 負責請求重試，而本插件觀測逃逸的重試失敗，避免因瞬時抖動而誤觸發熔斷。

通過 DSH 的 CLI 安裝插件：

dsh plugin --profile web add dsh-model-failover

安裝後，需要在 cordis.patch.yml 中配置 fallbacks（這是必須設置的字段）。

# cordis.patch.yml 示例
fallbacks:
  - provider: "provider-name"
    model: "model-name"

此外，插件會自動安裝一個配套技能 configure-model-failover，該技能可以引導你通過對話設置備用模型配置，無需手動複製文件。

進程本地狀態：熔斷狀態保存在內存中，插件重載時會重置，不支持跨實例共享。
僅路由 agent-loop 調用：插件僅對 agent-loop 的主循環調用進行路由，session-title 等輔助調用不會經過熔斷邏輯。
無平臺探測：插件僅對模型級熔斷進行恢復探測，平臺級熔斷僅依靠冷卻時間恢復。
上下文窗口風險：如果備選模型的上下文窗口小於主模型，切換時可能觸發 CONTEXT_WINDOW_EXCEEDED 錯誤，需配置 stripReasoningEffort: true 並選擇兼容的備選模型。
特定重試模式：當 retryPolicy.mode 爲 always 時，插件處於閒置狀態（設計如此），因爲此時重試策略會處理所有失敗。

dsh-model-failover 插件通過兩級熔斷機制和故障轉移策略，爲 DeepSeek Harness 提供了基礎的容錯能力。它不修改核心代碼，僅通過插件形式介入，適合需要在模型層增加高可用保障的場景。