前言¶
在使用 DeepSeek Harness Web 進行開發或部署時，錯誤處理是保證服務穩定性的關鍵環節。DSH 自帶 llm-retry 機制，但錯誤分類往往依賴於服務端返回的錯誤碼。如果某些速率限制錯誤被標記爲 PI_AI_ERROR 而非 RATE_LIMIT，重試機制可能無法生效。
dsh-better-retry 插件解決了這個問題。它通過將特定的 PI_AI_ERROR 重新分類爲 RATE_LIMIT，配合 DSH 的標準重試策略，讓開發者能夠更精細地控制哪些錯誤值得重試，以及如何匹配這些錯誤。
是什麼¶
這是一個面向 DeepSeek Harness Web 的錯誤分類與自動重試規則管理插件。
- 維護者：leolee9086
- 核心能力：將特定的錯誤消息模式（如
PI_AI_ERROR）識別並重新分類爲RATE_LIMIT，交由 DSH 的@deepseek-ai/dsh-llm-retry處理。 - 價值：通過規範化消息匹配和可視化規則管理，降低重試配置的門檻，避免因錯誤分類不當導致的請求失敗。
核心功能¶
錯誤重新分類¶
插件運行時攔截 PI_AI_ERROR，根據配置的規則將其歸類爲 RATE_LIMIT。DSH 會基於其內置的指數退避策略（包括抖動）決定是否重試，重試次數、延遲等參數由服務商的 DSH 策略決定，請求原文和診斷信息保持不變。
兩種消息匹配方式¶
- 規範化後完整匹配（默認）：移除
request、trace、correlation id和 UUID，統一大小寫與空白。這種方式要求消息在去除易變字段後完全一致，適合明確且較短的消息。 - 包含連續片段：支持更寬泛的匹配。片段必須是錯誤消息中連續存在的文本，且至少包含 24 個字符和 3 個空白分隔詞。
管理入口¶
插件在 Web 界面提供了兩個可見的管理入口：
1. 設置 → 自動重試：查看全部內置和自定義模式，進行啓用/停用、刪除和添加操作，並測試消息匹配。
2. 錯誤行 → 納入自動重試：在瀏覽錯誤日誌時，直接展開預覽表單，將當前錯誤快速納入自動重試規則。
智能建議與舊版遷移¶
- 相似樣本建議：插件會分析最近 100 種錯誤與已保存模式的樣本，按錯誤碼和服務商篩選，建議連續公共片段作爲匹配規則。
- 舊版遷移：支持將舊版的
rules: string[]遷移至新的patterns格式。
安裝與啓用¶
安裝前請確保你的 DSH Web profile 包含 llm、settings、connection 以及標準的 llm-retry 模塊。同時，需要較新的 DSH 接口支持（connection.rpc.handle/call、settings.section）。
使用官方命令安裝：
dsh plugin --profile web add github:leolee9086/dsh-better-retry
若需固定版本，可在命令末尾指定 commit SHA：
dsh plugin --profile web add github:leolee9086/dsh-better-retry#COMMIT_SHA
安裝後，刷新 Web 頁面。使用 dsh --profile web --dump-config 驗證配置中是否同時包含 llm-retry 和 dsh-better-retry，並打開管理頁確認 Host 能返回規則列表。
典型用法¶
納入一條錯誤¶
- 在錯誤日誌中點擊“納入自動重試”。
- 在展開的表單中，默認使用“規範化後完整匹配”。輸入服務商 ID（默認爲
*表示所有服務商）。 - 點擊“預覽匹配”，檢查規範化後的消息和命中的模式。
- 點擊“確認納入自動重試”。只有 Host 持久化成功，纔會顯示保存成功。
測試匹配¶
在管理頁的“測試消息是否命中”功能中，粘貼消息文本。Host 會使用與真實流處理相同的匹配器，顯示當前命中的啓用模式，用於調試規則配置。
內置模式¶
插件默認啓用了兩條針對常見速率限制錯誤的模式：
* Too many pending requests, please retry later
* Our servers are currently overloaded. Please try again later
適用場景與注意¶
適用場景¶
適用於需要精細化處理特定錯誤碼（如 PI_AI_ERROR）的場景，特別是當服務商返回的錯誤信息包含大量動態 ID 或格式不穩定，但核心錯誤含義明確時。
注意事項¶
- 不會恢復已結束的回合：保存規則僅影響後續請求。對於已經結束的對話，即使命中規則也不會自動重試。
- 權限與版本：插件以當前 DSH 進程權限運行。如果管理頁報錯或返回 404，通常意味着 Host 和 Client 版本不一致，需要重新加載 Host 插件而非僅刷新瀏覽器。
- 重試策略：實際的重試行爲由 DSH 的
maxRetries、backoff等參數決定。如果服務商關閉了重試或次數耗盡，命中模式也不會無限重試。 - 許可證：項目採用 MIT 許可證，可自由使用與修改。
總結¶
dsh-better-retry 提供了一個可視化的、基於消息模式的錯誤分類工具，它不替代 DSH 的重試引擎，而是作爲“翻譯器”將難以識別的錯誤轉化爲可重試的錯誤。通過規範化的匹配和直觀的管理界面，它降低了錯誤處理的複雜度。
- 項目目錄：https://www.skillhub.cn/plugins/leolee9086/dsh-better-retry
- GitHub 倉庫：https://github.com/leolee9086/dsh-better-retry
