dsh-retry-boost：DSH 瞬时网关故障自动重试

前言¶

在接入商汤 SenseNova 或其他 LLM 网关时，常会遇到瞬时故障。当网关返回 429 insufficient_quota 时，DSH 的错误分类器会将其归为 QUOTA 码，而非通用的 RATE_LIMIT。默认情况下，DSH 的内置重试机制（dsh-llm-retry）不包含 QUOTA 错误码，导致这类请求在第一次失败时直接 fail-fast，无法通过重试恢复。这需要开发者手动干预或频繁使用“继续”功能。

dsh-retry-boost 插件旨在解决这个问题。它通过热注入加固版的 retryPolicy，覆盖所有 llm-pi-ai provider，利用指数退避机制自动重试直到任务完成。

是什么¶

这是一个 DeepSeek Harness (DSH) 工作流插件，由开发者 hhb1028 维护，采用 MIT 许可证。

它的核心作用是在 DSH 启动时，将一份包含 QUOTA 错误码的 retryPolicy 热注入到所有 llm-pi-ai provider 的配置中。由于是通过 DSH 的 settings provider 合并写入，修改会热生效，无需重启进程。

核心功能¶

启动时热注入：启动 DSH 后，插件会自动为所有已存在的 llm-pi-ai provider 填充或增强重试策略。
运行时自动补全：插件监听 llm/adapters-updated 事件。在 DSH 运行过程中新增的 provider，会自动补上受保护的 retryPolicy，无需重启。
变体路由检测：插件会自动检测不受保护的变体路由（如 vision-toolkit-*），并在日志中发出警告，提示这类路由可能仍会因 QUOTA 错误而中断。
灵活的策略配置：支持 fill、boost、force 三种策略，以及 normal（有界重试）和 always（无限重试）两种模式。
指数退避：采用 1s 到 60s 的指数退避策略，并加入 0.2 的抖动比例，以缓解网络拥塞。

安装与启用¶

通过官方 CLI 安装插件。确保你的 DSH 版本满足要求（>= 0.1.1-rc.1）。

dsh plugin --profile <你的profile名> add dsh-retry-boost

安装完成后，重启 DSH。日志中会显示注入成功的提示，例如：
dsh-retry-boost: injected retry policy for "sensenova" (mode=normal retries=50 backoff=1000ms->60000ms codes=8)

注入后的策略会直接写入 profile 的 settings.yaml 中的 llm-pi-ai.providers.*.retryPolicy 下段，你可以随时手动修改。

配置项¶

在 profile 的 cordis.patch.yml roster 行或 DSH 的插件配置界面调整参数：

键	默认值	含义
`strategy`	`fill`	`fill`：仅处理未显式配置 `retryPolicy` 的 provider；`boost`：合并缺失错误码并抬高上限；`force`：全部替换为插件策略
`mode`	`normal`	`normal`：有界重试；`always`：无限重试（慎用）
`maxRetries`	`50`	`normal` 模式下的重试次数上限
`initialDelayMs`	`1000`	首次退避延迟（毫秒）
`maxDelayMs`	`60000`	退避上限（毫秒）
`jitterRatio`	`0.2`	抖动比例（0-1）
`retryableCodes`	8个码	需要重试的失败码列表（包含 QUOTA）
`warnUnprotectedVariants`	`true`	检测到不受保护的变体路由时是否警告

覆盖范围与已知限制¶

本插件仅作用于 llm-pi-ai 命名空间下的 provider。以下路径不在射程内，不受本插件保护：

图片输入变体路由（如 vision-toolkit-*）：这些路由由视觉类插件通过 registerAdapter 注册，其 retryPolicy 在注册时捕获，不读取 llm-pi-ai 的 settings。插件会对此发出警告，但无法直接修复。
第三方 LLM adapter 插件：由其他插件注册的自有路由，同样不经过 llm-pi-ai 命名空间。

环境要求：
* DeepSeek Harness >= 0.1.1-rc.1
* Node.js >= 20

卸载注意事项：
卸载后，settings.yaml 中被注入的 retryPolicy 段不会自动删除。需要手动清理该段配置，才能恢复 DSH 的默认行为。

与 dsh-chat-continue 的区别¶

特性	dsh-retry-boost（本项目）	dsh-chat-continue
定位	第一道防线：让 DSH 内置重试生效	第二道防线：内置重试耗尽后的兜底重试
机制	热注入 `retryPolicy`，走官方重试链路	拦截 `agent/request-error`，自行重发
退避	指数退避（1s -> 60s + 抖动）	固定间隔
互补性	单独使用即可解决大部分瞬时故障	可叠加作为最后的保险

结语¶

dsh-retry-boost 通过将生产环境验证过的重试策略标准化，解决了商汤网关等场景下的 429 瞬时故障问题。安装后，DSH 的内置重试机制将具备处理 QUOTA 错误的能力，大幅减少因网络抖动导致的任务中断。

更多细节与源码，请访问 GitHub 仓库。