dsh-429-guard：DeepSeek Harness 429 错误自动重试守卫

前言¶

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

使用方法¶

1. 查看与控制：点击右上角盾牌胶囊，展开卡片。卡片显示当前开关状态。
2. 开启重试：打开「自动无限重试」开关。
3. 观察重试：当模型请求遇到 429 或配额不足错误时，系统自动开始重试，卡片上的重试计数增加，显示“正在重试”呼吸灯效果。
4. 状态警示：若错误类型为 QUOTA（配额耗尽），卡片显示醒目警示，胶囊状态点变黄。
5. 结束或重置：不需要自动重试时关闭开关即可恢复默认放行；可点击「清零」重置统计计数。

技术实现与机制¶

• 架构设计：采用双层架构。主机端（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%）。
• 安全限制：REST API 路由仅允许 loopback 可信来源（同源、127.0.0.1/::1）访问，防止 CSRF 攻击。

总结¶

dsh-429-guard 是一个为 DSH 环境设计的轻量级守卫插件，通过 UI 交互与后端重试逻辑结合，解决了官方插件在处理 429 错误时过早放弃的问题。它遵循 MIT 许可证，适合需要在长任务中处理突发限流场景的开发者使用。

项目地址：https://github.com/suufon/dsh-429-guard