dsh-429-guard

DeepSeek Harness（DSH）插件 —— 429 / 配额不足错误自动无限重试守卫。

在 DSH Web UI 右上角挂一个精美浮窗（盾牌入口胶囊 + 展开卡片），带开关。开启后，模型请求遇到 429（含 DeepSeek 返回的 429 insufficient_quota，被官方归类为 QUOTA）会自动无限次重试，直至成功或你手动停止，避免任务中断。

它解决什么问题

使用 DSH 时，模型 API 经常返回：

429: {"message":"Allocated quota exceeded, please increase your quota limit.","type":"invalid_request_error","code":"insufficient_quota"}

官方 dsh-llm-retry 插件在 normal 模式下达到 maxRetries 即放弃 → 抛出 LlmError → 当前 turn 中断，长任务半途而废。本插件在重试链中接管官方插件放弃之后的 429 类错误，继续无限重试（退避等待，可被 agent 的 abort signal 取消）。

功能特性

• 右上角精美浮窗：玻璃拟态胶囊（盾牌 + 状态点 + 重试计数徽标），点击展开卡片（标题、说明、Toggle 开关、统计、正在重试呼吸灯、清零计数）。
• 开关即生效：开启 = 429 类无限重试；关闭 = 放行，恢复官方默认行为。
• 覆盖面广：判定 code ∈ {RATE_LIMIT, QUOTA} 或 status === 429 或文案命中 429/rate limit/quota/insufficient_quota，确保覆盖 insufficient_quota。
• 与官方 llm-retry 兼容共存：waterfall 链中排在官方之后接管，不冲突；若 provider 配了 always 模式，官方自身已无限重试，本插件不被触发。
• 可取消：退避等待监听 agent 的 abort signal，用户手动停止时立即放弃。
• 统计持久化：累计重试次数、最近拦截时间、最近错误，存于 $(DSH_HOME)/storages/dsh-429-guard.json。

安装

从 GitHub 安装（推荐）

dsh plugin --profile web add github:suufon/dsh-429-guard

安装后重启 / 重载 DSH 应用，右上角出现盾牌浮窗即安装成功。

想固定版本可加 tag：dsh plugin --profile web add github:suufon/dsh-429-guard#v0.1.0

从本地目录安装（插件开发）

dsh plugin --profile web add "file:<你克隆/解压到的路径>"

重启 DSH Web

插件在启动时加载，安装后需重启 dsh web：

# 仓库内自带脚本（自动探测 DSH_HOME / dsh CLI）
pwsh -File .\scripts\restart-web.ps1

参数：-Action stop|start|restart（默认 restart）、-ShowWindow（显示服务器日志窗口）。 脚本会自动探测 DSH_HOME 与 dsh CLI，也可用 -DshHome / -DshCmd 显式指定。

强制刷新安装：dsh plugin --profile web remove dsh-429-guard && 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. 不需要时关闭开关即可恢复默认行为；可点「清零」重置统计。

架构

DSH 是「主机平面 cordis 插件 + 客户端插件」双层架构，本插件对应两部分：

┌───────────────────────────── DSH Web（浏览器） ─────────────────────────────┐
│  lib/client.js（shell.overlay 浮窗，React）                                    │
│    └─ 轮询 /guard-api/state + POST /guard-api/enable                          │
└───────────────────────────┬──────────────────────────────────────────────────┘
                            │ 同源 fetch（loopback 可信）
┌───────────────────────────▼──────────────────────────────────────────────────┐
│  lib/index.js（主机端 cordis 插件，inject: ['webServer']）                     │
│    ├─ ctx.on('agent/request-error', …) → 429 类无限重试                        │
│    └─ ctx.webServer.register('/guard-api', …) → state / enable / reset        │
└──────────────────────────────────────────────────────────────────────────────┘

429 重试链路（agent loop）

模型请求 → 流式响应 → finish.kind === 'error'
  → dispatch.waterfall('agent/request-error', { failure, retryPolicy, signal, … }, fallback)
      ├─ dsh-llm-retry: normal 模式 previousRetry >= maxRetries → return next()（放弃）
      └─ dsh-429-guard（本插件）:
            开关关闭 / 非 429 类 → return next()（放行，抛出 LlmError，任务中断）
            开关开启 + 429 类     → 退避等待（signal 可取消）→ return { kind: 'retry' }
                                    agent loop continue → 重新发起请求（无限次）

failure 来自 LlmError.failure：{ message, code, status?, providerRetryAfterMs?, requestId? }。 DeepSeek 的 429 insufficient_quota 经 isQuotaExceededError 归类为 code = 'QUOTA'（QUOTA_EXCEEDED_CODE = 'QUOTA'），本插件据此接管。

REST API

方法	路径	说明
GET	/guard-api/state	读取开关状态 + 统计 + 当前活动重试
POST	/guard-api/enable	body { "enabled": true/false } 切换开关（持久化）
POST	/guard-api/reset	清零统计计数

所有路由仅 loopback 可信（同源、127.0.0.1/::1），防止远程 CSRF。

退避策略

• 优先使用 provider 返回的 retry-after（failure.providerRetryAfterMs），封顶 240s。
• 否则指数退避：initial 2s × 2^(retry-1)，封顶 60s，抖动 ±25%。
• 等待期间监听 agent 的 abort signal；用户手动停止时立即放弃。

License

MIT