前言¶

在 DeepSeek Harness（DSH）里跑智能体时，模型请求偶尔会因网关抖动、限流或超时失败。中转站、聚合网关以及被限流的官方接口里，这类失败往往是一次性的：同一请求隔几秒再发就能成功。默认情况下，失败会直接冒到界面、整轮对话结束，需要手动再点一次。下面介绍社区插件 dsh-auto-retry（维护者 643048695），它在 DSH 的 agent/request-error 链路上拦截失败，按固定退避阶梯重跑当前 step，而不是从头再跑整轮对话。

这是什么¶

dsh-auto-retry 是 DSH 生态里的「模型推理」类插件：给 Harness 加一层模型请求自动重试。某个 step 因 503、429、upstream_error 等原因失败时，插件先拦住这次失败，等待一段时间后再把同一个 step 重跑一遍。

流程可以概括为：

provider 返回 503 / 429 / "upstream_error" …
        ↓  agent/request-error waterfall
   dsh-auto-retry（prepend，最先拿到这次失败）
        ↓  等待 2s → 重试；再失败等 5s → 重试 …
   重跑同一个 step

装上之后，常见抖动会在日志里体现为「第 1/4 次自动重试，等待 2 秒」之类信息，对话随后自行继续，而不必立刻人工重试。

核心功能¶

退避阶梯¶

默认最多重试 4 次，最坏情况下累计静默等待约 37 秒：

重试次数按 provider + turn + step 计数，因此重试的是「同一个 step」，不会把整轮对话从头再跑一遍。若 maxRetries 大于阶梯表长度，超出部分固定使用最后一档（20 秒）延迟。

错误处理策略¶

插件拦截全部请求错误，不做按状态码的分类。README 说明这是有意为之：中转站常把「额度用完」「模型不存在」包装成 upstream_error 或缺少明确状态码，按码分类容易漏拦。代价是不可恢复的错误也会被重试（例如密钥失效、请求体不合法），可能多等几十秒后才报同样的错。若需要避免，可将 maxRetries 调小或关闭插件。

其他边界：

• 用户按停止（signal.aborted）时立即放弃，不会在后台偷偷重试。
• 只重放当前 step，不改写请求内容、不换模型、不换 provider；换模型由路由类插件负责。
• 达到上限时，日志会写「已达到最大重试次数，停止重试」，不会静默吞掉失败。

配置¶

设置页中的字段均为 volatile（改完立即生效，无需重启 DSH）：

兼容性与实现依赖¶

插件依赖宿主暴露的 agent/request-error waterfall，以及处理函数返回 { kind: "retry" } 的契约。README 写明已与 DSH 0.2.1-rc.3（当前桌面版内置核心）逐项核对，0.1.7 线同样具备这两处接缝。若宿主改动契约，最坏情况是插件不生效（监听不到或返回值不被识别），不会让原本正常的请求变失败。

仓库内 npm test 运行 8 个用例，覆盖阶梯递增、次数上限后的回落、计数键隔离、开关关闭，以及「已中断 / 等待中中断」两条中断路径；CI 另校验市场要求的 dsh.bundle 清单与入口。许可证为 MIT（package.json 版本 1.0.0）。

安装与启用¶

先用官方命令把插件装进当前 DSH 环境：

dsh plugin add github:643048695/dsh-auto-retry

也可以在 profile 的 package.json 里声明依赖，把 dsh-auto-retry 加入 dsh.profile.bundles，再将目录链接进 node_modules。

DSH 的理念是「一切皆插件」；社区目录 SkillHub 插件页 是独立站点，与 DeepSeek / 幻方无官方从属关系。插件与宿主进程同权限运行，安装前建议自行查看 GitHub 源码与 LICENSE。

典型用法¶

无需单独 API：启用插件并保持默认配置后，当某 step 的模型请求失败，waterfall 会自动进入重试逻辑。若需观察行为，保持 log: true，在日志中查看第几次重试与等待秒数；若希望快速失败，将 enabled 设为 false 或减小 maxRetries。

适用场景与注意¶

适合：经常走中转/聚合网关、偶发 503/429/超时、希望对话在短暂抖动后自动续跑的场景。

注意：不可恢复错误也会被重试并占用等待时间；停止操作会立刻终止重试链；插件不负责换模型或改请求体。

结尾¶

dsh-auto-retry 用固定退避阶梯和 per-step 计数，把「一次性」的模型请求失败就地消化，同时尊重用户中断信号。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库。