前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，模型請求可能因爲賬戶額度或餘額耗盡而失敗。宿主默認的 @deepseek-ai/dsh-llm-retry 會在有限次數內快速重試，預算用完後這一輪（turn）往往就結束，會話裏未完成的步驟也會停在那裏。
若你配置了多條可互換的 provider/model 路由，或希望在同一路由上按固定間隔一直等到額度恢復，就需要在「快速重試耗盡之後」還有一層策略。社區插件 dsh-llm-quota-retry（維護者 windwhiterain，分類：模型推理）就是針對這一缺口：在額度類失敗被 earlier 恢復策略放棄之後接管，要麼切到池裏仍有額度的路由，要麼在同一輪內按間隔反覆重試同一請求，直到成功或用戶取消。
這是什麼¶
dsh-llm-quota-retry 是一個 DSH 宿主插件（Cordis bundle，含 Web composer 側能力）。當前 package 版本爲 0.2.0，許可證 MIT。
它解決的核心問題是：當模型請求因賬戶 allowance 用盡而失敗時，在基礎重試策略放棄之後，仍保持當前 agent step 存活——若會話綁定了 route pool（有序、可互換的 provider/model 列表）且某條路由仍有額度，則立即按各路由剩餘額度比例切過去；若池內都沒有額度，則在同一輪未關閉的前提下，按配置間隔（默認 一小時）重試同一請求，無嘗試次數上限，直到成功或 turn 被取消。
插件默認對所有會話開啓；可通過 composer chip 或 /quota-retry 按會話關閉，或在部署級設置 defaultEnabled: false 全局關閉。
核心功能¶
額度類失敗的識別範圍¶
除標準的 QUOTA 外，插件還處理部分 provider 用 AUTH 或 RATE_LIMIT 表達「用量上限已用盡」的情況，例如按滾動窗口計量的 403、或 Token Plan 觸頂時的 429（含中文提示「已達到 Token Plan 用量上限：…」）。只認 QUOTA 會漏掉這些 metered 場景，因此擴展識別是插件存在意義的一部分。
Route pool 與餘額來源¶
會話可通過 composer 第二個 chip 或 /quota-pool 手動加入某個 pool；若當前模型本身就在 pool 裏，也會自動跟隨該 pool。pool 的 minimumRemaining 決定會話起始落在哪些路由上，並按各路由剩餘額度比例抽取；會話運行中，只有 provider 自身報告 allowance 用盡纔會觸發遷移。
哪些路由「還有額度」來自 balance scripts 以及 provider 上報的 exhaustion 信息。
與 dsh-llm-retry 的分工¶
Compose 時 llm-quota-retry 行必須排在 @deepseek-ai/dsh-llm-retry 之後。這是契約：dsh-llm-retry 在 agent/request-error 瀑布流裏更早執行，先消耗自己的重試預算；額度失敗傳到本插件時，前面的恢復策略已全部拒絕——即「基礎快速重試之後」再進入長期策略。bundle 自帶的 cordis.patch.yml 會把行追加到 composition root，安裝 bundle 後一般已在正確位置。
注意：行順序不等於 listener 註冊順序；Cordis 按註冊順序跑 listener。若本插件先於其他策略激活，可能對 quota 失敗「先發聲」，導致本應走原生策略的失敗不再原生重試。對 nativeRetryFirstProviders 中列出的 provider，行爲在兩種順序下一致。
nativeRetryFirstProviders（指定 provider 先走原生快速重試）¶
部分 provider 會把普通限流報成「額度用盡」（例如 qwen 在 429 上帶 insufficient_quota）。若直接等一小時會誤傷。配置 nativeRetryFirstProviders 後，對該 provider 會先跑與 @deepseek-ai/dsh-llm-retry 相同的有限指數退避（來自失敗請求上的 retryPolicy：initialDelayMs、maxDelayMs、jitterRatio、maxRetries、providerRetryAfterMs 等），預算耗盡後才標記該 provider 額度用盡、再 failover 或進入 hourly wait。
快速重試發生在 exhaustion 標記和 failover 之前；僅被限流的 provider 仍保留 allowance。日誌示例：
llm-quota-retry: provider "qwen" returned QUOTA; native quick retry 2 in 4000ms
README 中的配置示例：
- id: llm-quota-retry
name: 'dsh-llm-quota-retry'
config:
nativeRetryFirstProviders: [qwen]
狀態對外可見¶
長期重試的進入、離開與當前狀態會通過 ctx.llmQuotaRetry 等機制發佈，供其他插件感知（package.json description 中亦有說明）。
邊界¶
對非額度用盡類失敗，插件嚴格只做加法、不改動原有行爲；README「What this plugin does not touch」一節說明了其餘失敗類型的處理方式（資料截斷處未展開全文，安裝前可在 GitHub README 覈對）。
安裝與啓用¶
插件爲 Cordis bundle，需在已 checkout 本倉庫的目錄的上一級（即包含 dsh-llm-quota-retry 文件夾的目錄）執行官方安裝命令：
dsh plugin --profile web add ./dsh-llm-quota-retry
安裝會把包鏈入 profile 並寫入 dsh.profile.bundles，bundle 層在後續每次啓動時加載。宿主行無需重啓即可生效：profile patch 熱加載、行激活、bundle 報告 enabled 並啓動 fiber。
Composer chip 首次需要重啓宿主一次。 dsh.client manifest 由 client-module 掃描讀取，且按包緩存終身；首次掃描時若尚未聲明 dsh.client，會一直緩存爲「非 client 包」。安裝後或給已安裝包補上 dsh.client 後，請重啓一次 dsh web，chip 纔會出現。
請確認 composition 中已安裝 @deepseek-ai/dsh-llm-retry，且本插件行在其後（bundle 安裝通常已自動追加）。
典型用法¶
- 安裝 bundle 並重啓
dsh web（首次顯示 composer chip）。 - 在 Cordis 配置中爲
llm-quota-retry按需設置nativeRetryFirstProviders、route pool 與 balance 腳本（詳見 README 的 route pools 章節）。 - 會話級：用 composer chip 或
/quota-retry開關長期重試；用第二個 chip 或/quota-pool指定路由池。 - 部署級：不需要默認全開時，設置
defaultEnabled: false。
適用場景與注意¶
適合誰： 多 provider/model 路由、或單路由但願意在同一 turn 內長時間等待額度刷新（例如按小時配額）的 DSH 智能體部署；常與 @deepseek-ai/dsh-llm-retry 搭配。
安全與權限： 插件以當前 dsh 進程權限運行，可訪問宿主配置的網絡與憑證。安裝前請閱讀 GitHub 源碼 與 MIT 許可證，自行評估是否納入你的環境。
生態說明： DSH 主張「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-llm-quota-retry 在快速重試預算用盡後，用路由池 failover 與無上限的間隔重試把 step 留在同一輪裏，並覆蓋多種 provider 的「額度用盡」表達方式。進一步瞭解與 issue：
- 目錄頁：https://www.skillhub.cn/plugins/windwhiterain/dsh-llm-quota-retry
- GitHub：https://github.com/windwhiterain/dsh-llm-quota-retry
