前言¶
在 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
