前言¶
DeepSeek Harness (DSH) 在處理模型請求時，默認的 llm-retry 插件在 normal 模式下達到 maxRetries 後會拋出 LlmError，導致當前任務中斷。針對這種情況，dsh-429-guard 插件接管了官方插件放棄後的 429 類錯誤（包含 DeepSeek 返回的 insufficient_quota），提供無限次自動重試能力，避免任務因臨時限流或配額問題而中斷。
核心功能¶
該插件通過 Web UI 右上角的浮窗與 DSH 主機端插件協同工作，主要提供以下能力：
- Web UI 交互：右上角顯示玻璃擬態風格的盾牌膠囊，展開卡片可查看開關狀態、重試計數和統計信息。卡片包含“自動無限重試”開關和“清零”按鈕。
- 錯誤攔截：覆蓋
code ∈ {RATE_LIMIT, QUOTA}、status === 429或包含429/rate limit/quota/insufficient_quota文案的所有錯誤。 - 無限重試：開啓開關後，遇到 429 類錯誤進入重試循環，直至成功或用戶手動停止。
- 共存機制：與官方
llm-retry插件兼容，位於重試鏈（waterfall）的下游，僅在官方插件放棄後接管。 - 可取消性：重試期間監聽 agent 的 abort signal，用戶手動停止任務時立即放棄當前重試。
- 持久化統計：累計重試次數、最近攔截時間等數據存儲於
$(DSH_HOME)/storages/dsh-429-guard.json。
安裝與啓用¶
安裝插件後需重啓 DSH Web 應用以加載組件。
dsh plugin --profile web add github:suufon/dsh-429-guard
安裝完成後，右上角應出現盾牌浮窗。如需卸載：
dsh plugin --profile web remove dsh-429-guard
使用方法¶
- 查看與控制：點擊右上角盾牌膠囊，展開卡片。卡片顯示當前開關狀態。
- 開啓重試：打開「自動無限重試」開關。
- 觀察重試：當模型請求遇到 429 或配額不足錯誤時，系統自動開始重試，卡片上的重試計數增加，顯示“正在重試”呼吸燈效果。
- 狀態警示：若錯誤類型爲
QUOTA（配額耗盡），卡片顯示醒目警示，膠囊狀態點變黃。 - 結束或重置：不需要自動重試時關閉開關即可恢復默認放行；可點擊「清零」重置統計計數。
技術實現與機制¶
- 架構設計：採用雙層架構。主機端（
lib/index.js）監聽agent/request-error事件並執行重試邏輯；客戶端（lib/client.js）提供浮窗 UI 與 REST API 通信。 - 重試鏈路：請求失敗觸發
agent/request-error事件，官方llm-retry插件放棄後，本插件接管。若開啓開關且判定爲 429 類錯誤，返回kind: 'retry'，Agent 循環重新發起請求。 - 退避策略：
- 優先使用 provider 返回的
retry-after（封頂 240s）。 - 否則使用指數退避（初始 2s，每次翻倍，封頂 60s，抖動 ±25%）。
- 優先使用 provider 返回的
- 安全限制：REST API 路由僅允許 loopback 可信來源（同源、127.0.0.1/::1）訪問，防止 CSRF 攻擊。
總結¶
dsh-429-guard 是一個爲 DSH 環境設計的輕量級守衛插件，通過 UI 交互與後端重試邏輯結合，解決了官方插件在處理 429 錯誤時過早放棄的問題。它遵循 MIT 許可證，適合需要在長任務中處理突發限流場景的開發者使用。
項目地址：https://github.com/suufon/dsh-429-guard
