dsh-retry-boost：DSH 瞬時網關故障自動重試

前言¶

在接入商湯 SenseNova 或其他 LLM 網關時，常會遇到瞬時故障。當網關返回 429 insufficient_quota 時，DSH 的錯誤分類器會將其歸爲 QUOTA 碼，而非通用的 RATE_LIMIT。默認情況下，DSH 的內置重試機制（dsh-llm-retry）不包含 QUOTA 錯誤碼，導致這類請求在第一次失敗時直接 fail-fast，無法通過重試恢復。這需要開發者手動干預或頻繁使用“繼續”功能。

dsh-retry-boost 插件旨在解決這個問題。它通過熱注入加固版的 retryPolicy，覆蓋所有 llm-pi-ai provider，利用指數退避機制自動重試直到任務完成。

是什麼¶

這是一個 DeepSeek Harness (DSH) 工作流插件，由開發者 hhb1028 維護，採用 MIT 許可證。

它的核心作用是在 DSH 啓動時，將一份包含 QUOTA 錯誤碼的 retryPolicy 熱注入到所有 llm-pi-ai provider 的配置中。由於是通過 DSH 的 settings provider 合併寫入，修改會熱生效，無需重啓進程。

核心功能¶

啓動時熱注入：啓動 DSH 後，插件會自動爲所有已存在的 llm-pi-ai provider 填充或增強重試策略。
運行時自動補全：插件監聽 llm/adapters-updated 事件。在 DSH 運行過程中新增的 provider，會自動補上受保護的 retryPolicy，無需重啓。
變體路由檢測：插件會自動檢測不受保護的變體路由（如 vision-toolkit-*），並在日誌中發出警告，提示這類路由可能仍會因 QUOTA 錯誤而中斷。
靈活的策略配置：支持 fill、boost、force 三種策略，以及 normal（有界重試）和 always（無限重試）兩種模式。
指數退避：採用 1s 到 60s 的指數退避策略，並加入 0.2 的抖動比例，以緩解網絡擁塞。

安裝與啓用¶

通過官方 CLI 安裝插件。確保你的 DSH 版本滿足要求（>= 0.1.1-rc.1）。

dsh plugin --profile <你的profile名> add dsh-retry-boost

安裝完成後，重啓 DSH。日誌中會顯示注入成功的提示，例如：
dsh-retry-boost: injected retry policy for "sensenova" (mode=normal retries=50 backoff=1000ms->60000ms codes=8)

注入後的策略會直接寫入 profile 的 settings.yaml 中的 llm-pi-ai.providers.*.retryPolicy 下段，你可以隨時手動修改。

配置項¶

在 profile 的 cordis.patch.yml roster 行或 DSH 的插件配置界面調整參數：

鍵	默認值	含義
`strategy`	`fill`	`fill`：僅處理未顯式配置 `retryPolicy` 的 provider；`boost`：合併缺失錯誤碼並抬高上限；`force`：全部替換爲插件策略
`mode`	`normal`	`normal`：有界重試；`always`：無限重試（慎用）
`maxRetries`	`50`	`normal` 模式下的重試次數上限
`initialDelayMs`	`1000`	首次退避延遲（毫秒）
`maxDelayMs`	`60000`	退避上限（毫秒）
`jitterRatio`	`0.2`	抖動比例（0-1）
`retryableCodes`	8個碼	需要重試的失敗碼列表（包含 QUOTA）
`warnUnprotectedVariants`	`true`	檢測到不受保護的變體路由時是否警告

覆蓋範圍與已知限制¶

本插件僅作用於 llm-pi-ai 命名空間下的 provider。以下路徑不在射程內，不受本插件保護：

圖片輸入變體路由（如 vision-toolkit-*）：這些路由由視覺類插件通過 registerAdapter 註冊，其 retryPolicy 在註冊時捕獲，不讀取 llm-pi-ai 的 settings。插件會對此發出警告，但無法直接修復。
第三方 LLM adapter 插件：由其他插件註冊的自有路由，同樣不經過 llm-pi-ai 命名空間。

環境要求：
* DeepSeek Harness >= 0.1.1-rc.1
* Node.js >= 20

卸載注意事項：
卸載後，settings.yaml 中被注入的 retryPolicy 段不會自動刪除。需要手動清理該段配置，才能恢復 DSH 的默認行爲。

與 dsh-chat-continue 的區別¶

特性	dsh-retry-boost（本項目）	dsh-chat-continue
定位	第一道防線：讓 DSH 內置重試生效	第二道防線：內置重試耗盡後的兜底重試
機制	熱注入 `retryPolicy`，走官方重試鏈路	攔截 `agent/request-error`，自行重發
退避	指數退避（1s -> 60s + 抖動）	固定間隔
互補性	單獨使用即可解決大部分瞬時故障	可疊加作爲最後的保險

結語¶

dsh-retry-boost 通過將生產環境驗證過的重試策略標準化，解決了商湯網關等場景下的 429 瞬時故障問題。安裝後，DSH 的內置重試機制將具備處理 QUOTA 錯誤的能力，大幅減少因網絡抖動導致的任務中斷。

更多細節與源碼，請訪問 GitHub 倉庫。