前言¶
在使用共享 LLM 網關（如校園網代理、自建網關、提供商池）時，網關經常返回 429 狀態碼，並在響應體中附帶明確的 retry_after_seconds 提示，例如：“所有上游提供商正在冷卻中，請在 28 秒後重試”。
DeepSeek Harness 的內置 llm-retry 機制雖然支持 failure.providerRetryAfterMs，但該字段通常由適配器解析 HTTP 頭填充。當提示僅存在於響應體文本中（如 llm-pi-ai 適配器不解析頭），llm-retry 會回退到本地退避策略（500ms → 1s，共 2 次），導致請求在冷卻窗口內失敗，而實際上等待 28 秒即可成功。這個插件旨在填補這一空白。
插件介紹¶
dsh-cooldown-retry 是一個 DeepSeek Harness 插件，提供耐心的自動重試機制。它從上游 429 容量冷卻消息中讀取重試延遲，而不是在兩次快速嘗試後放棄。
- 所有者: dboycht
- 分類: 工作流
- 許可證: MIT
核心功能¶
- 耐心重試: 對 DeepSeek Harness 進行自動重試，而非在兩次快速嘗試後放棄。
- 讀取上游延遲: 從上游 429 容量冷卻消息中讀取重試延遲（
retry_after_seconds等）。 - 吸收誤標 400: 吸收網關飽和時誤標爲“不支持音頻模態”的 400 錯誤。
- 預算管理: 按輪次和提供商管理重試預算。
- 中止感知等待: 支持在輪次被取消時立即結束等待。
安裝與啓用¶
推薦使用官方安裝命令添加插件。
dsh plugin --profile web add github:dboycht/dsh-cooldown-retry
前置條件: 安裝命令需要 git 在系統 PATH 中（用於 github: 指定符）。
安裝後，需要重新加載配置以生效，無需重啓進程。
驗證安裝是否成功：
dsh --profile web --dump-config | grep -A2 'cooldown-retry'
注意: 插件行必須出現在內置 llm-retry 行之後。agent/request-error 是一個瀑布流，後註冊的監聽器作爲內層監聽器，因此該插件能優先攔截失敗。
配置與用法¶
默認配置如下：
* maxRetries: 5
* minDelayMs: 1000
* maxDelayMs: 300000
* acrossSteps: true
* mislabeledClientError: true
可通過自定義配置覆蓋默認值。由於非 insert 補丁會替換整行配置，修改時需重申所有保留的鍵。
- id: cooldown-retry
config:
maxRetries: 10
maxDelayMs: 600000
主要配置項說明：
* maxRetries: 每輪次/每個提供商在將失敗傳遞給下游之前的耐心重試次數。
* minDelayMs / maxDelayMs: 每次等待的窗口限制（1s - 300s）。
* acrossSteps: 默認爲 true，表示在輪次的所有步驟中共享一個預算；設爲 false 則恢復每步獨立預算。
* mislabeledClientError: 默認爲 true。當同一提供商在短時間內出現過容量冷卻，且網關返回聲稱“不支持模態”的 400 錯誤時，插件會將其視爲電路重放並等待，而非直接報錯。
* mislabeledMaxRetries: 專門用於處理“誤標 400”的獨立重試預算，與 maxRetries 分離。
* mislabeledEvidenceMs: 容量冷卻作爲“證據”的有效時間窗口。
限制:
* maxRetries 和 mislabeledMaxRetries 上限爲 100。
* 非插入（非 insert）的補丁會替換整行配置，因此必須重申所有希望保留的鍵。
觀察性¶
每次等待和放棄都會通過 ctx.logger 記錄，標籤爲 cooldown-retry。這有助於在日誌中追蹤具體的重試行爲和延遲時間。
結語¶
該插件通過解析上游響應體中的冷卻提示，解決了共享網關環境下常見但被內置重試策略忽略的 429 處理問題，並提供了針對網關誤標錯誤的容錯機制。對於依賴不穩定網關或需要高可用性的 DSH 工作流，這是一個實用的增強。
