前言¶

在 DeepSeek Harness（DSH）裏跑智能體時，模型請求可能因爲限流、服務異常、超時或配額耗盡而失敗。DSH 自帶的 @deepseek-ai/dsh-llm-retry 會在一定次數內對同一模型重試；重試用盡後，這一輪往往以錯誤結束，後續步驟無法繼續。若你手上有多個已配置好的 provider 與模型，更自然的期望是：當前模型扛不住時，按預定順序換下一個模型接着做同一件事，而不是立刻停轉。

下面介紹社區插件 dsh-fallback-models（維護者 soffits，分類：模型推理）。它在 DSH 重試耗盡之後介入，按你配置的列表嘗試備用模型，並在會話裏給出可讀的切換說明。

這是什麼¶

dsh-fallback-models 是 DSH 的一個插件（當前 package 版本 0.1.1，許可證 MIT），爲 Harness 增加一條有序的 fallback 模型鏈。當某次模型請求在 DSH 自身重試仍失敗後，插件在條件允許時切換到鏈中的下一個模型繼續該輪工作，而不是直接以原始錯誤結束。

要點如下：

• 全局可配一條 chain；也可在 presets 裏爲不同 agent preset 覆蓋或關閉備用鏈。
• 在 @deepseek-ai/dsh-llm-retry 用盡次數、且該失敗類型允許切換時纔會換模型；對單次失敗，每個候選模型最多嘗試一次，避免循環。
• 默認 scope: turn：用完備用的那一輪結束後，會話會回到本輪開始時的模型；也可設爲 session 在會話結束前保持備用模型。
• chain 爲空（默認）時行爲與未安裝插件一致。

核心功能¶

配置項¶

設置頁從 DSH 模型目錄選型（與 Composer 裏模型選擇器同源），可排序。同等配置也可寫在 profile 的插件 patch 中，例如：

- id: fallback-models
  name: 'dsh-fallback-models'
  config:
    chain:
      - provider: deepseek
        model: deepseek-reasoner
      - provider: openrouter
        model: qwen/qwen3-coder
        reasoningEffort: high
    presets:
      reviewer:
        - provider: openrouter
          model: anthropic/claude-sonnet-4.5
      quick: []            # no fallback for this preset
    scope: turn            # or: session
    # codes: [...]         # optional, see below

修改後在下一次失敗時生效，無需重啓 DSH。

默認會觸發切換的失敗碼¶

適配器會爲失敗打上與 provider 無關的 code。默認會切換的包括：

默認不因 AUTH、INVALID_REQUEST、CONTEXT_WINDOW_EXCEEDED 換模型（避免掩蓋配置或上下文問題）；可在 codes 或設置頁中顯式開啓。用戶取消的請求（ABORTED 等）不會切換。

若在發請求之前就失敗（模型 id 不存在、缺少 API Key 等），請求不會發出，輪次結束，不會走 fallback。

與 DSH 恢復鏈路的配合¶

插件掛在 agent/request-error 瀑布流上：先執行 next()，讓 DSH 重試、上下文壓縮、圖片 offload 等既有恢復邏輯優先；只有沒有獲得重試時，才按鏈選下一個在 llm.resolveCallConfig 下可用的模型，通過 agent.model.select() 選定下一模型，以插件 cancel 結束失敗輪次並排隊一條簡短通知，再開新輪繼續。會話中可見類似 deepseek/deepseek-chat failed (RATE_LIMIT); switched to openrouter/qwen3 的提示行；發給模型的用戶側通知示例：

[model fallback: the request to deepseek/deepseek-chat failed (RATE_LIMIT: Too many requests). Continuing on openrouter/qwen/qwen3-coder: resume the interrupted work where it stopped.]

鏈耗盡時，仍以原始錯誤結束該輪。

安裝與啓用¶

環境要求：DSH 0.2.2-rc.1 及以上（0.2.x 系列），Node.js 22 及以上。

1. 將插件加入 profile（示例 profile 名爲 web）：

dsh plugin --profile web add github:soffits/dsh-fallback-models

也可通過 DSH 的 Plugins 頁面或插件管理器（install_bundle 使用 github:soffits/dsh-fallback-models 或本地 bundle 路徑）安裝。

2. 打開 Plugins > dsh-fallback-models，在 fallback-models 行點擊 Configure，或在 profile 中寫入上文 YAML。

3. 按需配置 chain、presets、scope 與可選的 codes。

典型用法¶

多 provider 容災：主模型用 deepseek/deepseek-chat，鏈中追加 openrouter 上另一模型，限流或短期故障時自動切換。

按 preset 分流：審查類 preset 單獨一條鏈指向更強模型；quick preset 設 quick: [] 關閉 fallback，避免輕量任務誤切昂貴模型。

會話級保持備用：將 scope 設爲 session，在長會話中持續使用已切換成功的模型，直到會話結束。

自定義失敗碼：需要在認證錯誤或非法請求時也換模型時，在 codes 中加入 AUTH、INVALID_REQUEST 等（需自行權衡是否會掩蓋配置問題）。

適用場景與注意¶

適合：已在 DSH 中配置多個 provider；希望重試之後仍有自動 failover；願意接受「一次切換佔用一輪邊界」（失敗輪顯示爲 stopped，新輪接續）。

不適合或需知侷限：

• 每次切換都會產生新的 turn；DSH 0.2.2 循環不允許在單個 agent/request 內改模型，這是當前公開 API 下的實現方式。
• Goal 自動回合中若因失敗被停止，Goal 會被關閉，工作可繼續但需稍後手動重啓 Goal。
• provider retryPolicy 爲 mode: always 時，下游恢復會先執行，可能在首次失敗就切換；鏈用盡後 always 模式可能對最後一個模型無限重試（依配置）。
• 鏈狀態在內存中；DSH 進程重啓後，若當時正使用備用模型，行爲以 README 說明爲準（會話可能仍保持該備用模型，除非手動改選）。

安全與權限：插件與當前 DSH 進程同權運行，可影響模型選擇與請求路由。安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認鏈中模型與 API 憑證符合你的合規要求。

結尾¶

dsh-fallback-models 在 DSH「重試之後」補上一段有序的模型備用鏈，把限流、 outage、配額等可切換的失敗轉成「換模型繼續」，並在對話裏留下可審計的切換記錄。社區插件目錄與 DeepSeek / 幻方無官方從屬關係；如需安裝與討論，可參考：

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