前言¶

在 DeepSeek Harness（DSH）裏，agent-loop 請求通常綁定一個 provider/model。單 provider 部署在限流、超時或服務端異常時，會讓當前請求直接失敗。

@visol-456/dsh-llm-fallback 是一個 DSH 社區插件，用來在主 provider 失敗時，讓同一請求按配置的 (provider, model) 備用目標自動重試。下面介紹它的定位、安裝方式、配置項和使用邊界。

這是什麼¶

• 包名：@visol-456/dsh-llm-fallback
• 類型：DeepSeek Harness dsh-plugin 生態社區插件，不屬於官方倉庫
• 許可證：MIT
• 倉庫：https://github.com/Visol-456/dsh-llm-fallback
• 包名與 GitHub 倉庫均指向 Visol-456

它解決的問題很直接：主 provider 失敗時，不直接終結當前請求，而是沿着按優先級排序的備用目標列表繼續嘗試。

核心功能¶

1、主 provider 失敗時，同一請求自動在下一個配置的 (provider, model) 條目上重試。

2、維護按優先級排序的 fallbacks 備用目標列表。

3、跟蹤連續可切換失敗並打開熔斷，故障切換到下一個健康條目。

4、按 switchCodes 允許觸發切換的失敗碼進行切換。

5、支持 Web UI Settings -> 回退鏈 頁面編輯備用目標。

6、保存的配置寫入 <DSH_HOME>/settings.yaml，並在下一次請求生效，無需重啓。

7、記錄 llm/fallback 與 llm/fallback-route 持久會話事件。

8、省略 fallbacks 時插件保持休眠，所有請求原樣放行。

安裝與啓用¶

插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。

下面以 dsh web 的 web profile 爲例。

使用 dsh plugin add¶

運行：

dsh plugin --profile web add @visol-456/dsh-llm-fallback

該命令將插件安裝到 web profile。

使用 npm¶

按部署方式也可能使用包管理器安裝：

npm i @visol-456/dsh-llm-fallback

安裝後仍需要在 DSH 配置中掛載插件。

在 cordis.yml 中掛載¶

創建或編輯 cordis.yml，掛載插件並配置備用目標：

- name: '@visol-456/dsh-llm-fallback'
  config:
    fallbacks:
      - provider: pi-ai
        model: glm-4.5
    switchCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, UNKNOWN_MODEL, TIMEOUT, TRANSPORT]
    failureThreshold: 1
    cooldownMs: 30000

這裏 fallbacks 是備用目標列表，switchCodes 是允許觸發切換的失敗碼，failureThreshold 與 cooldownMs 控制熔斷和冷卻。

如果省略 fallbacks，插件保持休眠，所有請求原樣放行；之後可在 Web UI Settings -> 回退鏈 頁面創建備用目標。

手動 patch 與診斷¶

手動 patch¶

如果不用 dsh plugin add，可創建 patch 覆蓋層：

# cordis.yml
- insert:
    - id: llm-fallback
      name: '@visol-456/dsh-llm-fallback'

然後運行：

dsh web --patch ./cordis.yml

這個 patch 條目需要包含 insert 和 id，再應用到 dsh web。

診斷組合配置¶

如果 patch 後行爲不符合預期，用組合配置樹檢查：

node --import tsx/esm apps/cli/src/bin.ts web --dump-config --patch <file>

該命令用於查看 patch 合併後的配置，便於確認插件掛載項是否生效。

Web UI 配置¶

插件加載到 web profile 後，可在 Settings -> 回退鏈 頁面編輯備用目標。

可用配置項包括：

• fallbacks：按優先級排列的 (provider, model) 備用目標
• switchCodes：允許觸發切換的失敗碼
• failureThreshold：連續可切換失敗閾值
• cooldownMs：切換後鏈頭冷卻時間

保存後，配置寫入：

<DSH_HOME>/settings.yaml

並在下一次請求生效，無需重啓。

瀏覽器通過插件提供的僅迴環端點 /llm-fallback/config 讀寫該配置段。該端點拒絕非迴環來源與跨站請求；它是防誤寫/防跨站圍欄，不是鑑權層。

工作邊界¶

下面是已覈實的使用邊界：

1、僅 agent-loop 請求參與。直接調用 ctx.llm.stream() 的消費者仍是單 provider。

2、fallbacks 是單一全局備用列表，所有請求共享一個 fallbacks 列表。

3、狀態僅進程內。重啓後活動條目、冷卻與連續計數歸零。

4、retry 策略爲 always 的 provider 會自己重試，fallback 看不到其失敗。

5、web profile base bundle 已自帶 @deepseek-ai/dsh-llm-retry，重複掛載會疊加重試。

6、非空配置非法時，插件加載或保存會直接報錯。

7、發佈不足 24 小時的包可能被 pnpm minimumReleaseAge 攔截。

8、舊 chains / match / providers 配置在 0.1.x 中棄用。

適用場景¶

這個插件適合：

• 希望給 dsh web / agent-loop 請求增加備用 provider/model 的部署
• 主 provider 出現限流、超時或服務端錯誤時，希望同一請求繼續嘗試下一個備用目標
• 需要事後通過 llm/fallback 和 llm/fallback-route 事件審計切換路徑

它不適合：

• 期望直接調用 ctx.llm.stream() 的消費者也自動 fallback
• 期望按多個 agent 或請求維度維護多套獨立備用列表
• 期望 fallback 狀態跨進程或重啓持久化

結尾¶

@visol-456/dsh-llm-fallback 的價值是把單 provider 請求鏈路擴展爲按優先級重試的 fallback chain，適合 DSH 社區插件環境下的備用路由需求。

GitHub 倉庫：https://github.com/Visol-456/dsh-llm-fallback。目錄頁地址本次材料未提供，可按包名 @visol-456/dsh-llm-fallback 在社區目錄檢索。