前言¶

在 DeepSeek Harness（DSH）里跑智能体时，模型请求难免遇到 429、超时或服务端错误。DSH 内置的重试由各 provider 适配器注册时的 retryPolicy 快照决定：默认有限重试 5 次，首次等待 500 ms、上限 10 000 ms，抖动 10%，运行期无法在设置里改次数或退避曲线。执行层 @deepseek-ai/dsh-llm-retry 也没有独立配置项。若你希望按场景调整重试预算、等待曲线或参与重试的失败码，并在保存后立即生效，社区插件 dsh-retry-policy（维护者 jinxiqinghuan）通过 bundle patch 禁用内置 llm-retry、由插件接管，同时沿用官方 llm/retry 事件与会话投影，上层界面无需改动。

这是什么¶

dsh-retry-policy 是 DSH 插件（npm 包名 dsh-retry-policy，当前资料中安装示例版本 0.1.1），用纯 JavaScript 实现，无构建步骤、无第三方运行时依赖、不访问外网。它在 MIT 许可证下发布，README 标明兼容 DSH 0.2.1-rc.3，运行环境要求 Node ≥ 22。

插件做的事可以概括为：读取自身配置（重试次数、等待策略、失败码集合等），在 agent loop 的 step 失败路径上决定是否重试、等待多久，再在同一 step 上重跑请求；配置经设置页或 cordis.patch.yml 写入 profile 用户补丁，保存即生效，无需重启应用（客户端设置页装完后需刷新页面一次）。

与默认行为的对比¶

bundle 层面的挂钩方式（README 原文）：

bundle patch:
  ├─ id: llm-retry      disabled: true          # 关掉内置执行器
  └─ insert: dsh-retry-policy                    # 挂上本插件，由它接管

核心功能¶

下面介绍 README 中已列出的能力，均可在仓库文档中核对。

重试预算

• maxRetries 取值 0 ~ 1000（不含首次请求）。
• mode: always 时可对提供方强制无限重试（永久性错误也会一直重试，需自行承担成本与延迟）。

等待曲线

• 三种策略：fixed（固定间隔）、linear（线性增长）、exponential（指数退避）。
• 可配 initialDelayMs、maxDelayMs、multiplier（指数用）、jitterRatio（对称抖动）。
• 设置页提供实时预览（例如第 1 次、第 2 次等待及累计时间）。

失败判定

• 从 10 种失败码中勾选参与重试的集合；默认与官方一致的五种：EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT。
• 可选码还包括：AUTH、QUOTA、INVALID_REQUEST、PROTOCOL、CONTEXT_OVERFLOW。
• respectRetryAfter: true 时优先采用提供方 Retry-After，且不超过 maxDelayMs。

透明性与运维

• 继续写入官方同款的 llm/retry、llm/retry-started 与 llmRetry 会话投影，会话气泡与轨迹视图无需区分执行器。
• enabled: false 时退回内置默认策略（normal / 5 次 / 500→10 000 / 抖动 10%）。

安装与启用¶

推荐从 npm 安装预构建包，不需要 allowBuilds；生产环境建议锁版本。

dsh plugin --profile desktop add dsh-retry-policy@0.1.1

也可从 GitHub 指定 tag 安装（仓库用户名为 jinxiqinghuan）：

dsh plugin --profile desktop add "github:jinxiqinghuan/dsh-retry-policy#v0.1.1"

本地开发可链接目录（将路径换成你的绝对路径）：

dsh plugin --profile desktop add "link:/绝对路径/dsh-retry-policy"

装完后按 README 建议做三步确认：

1. 打开 设置（左下角齿轮）→ 模型重试策略，应看到「接管中」及当前次数、策略摘要。
2. 在会话中发消息，确认正常；发生重试时会话里出现官方「模型重试」节点。
3. 若设置页未出现：检查 profile bundle 列表是否含 dsh-retry-policy，刷新页面（⌘R）；仍异常则查宿主日志中客户端 slot 报错。

卸载并回退内置重试：

dsh plugin --profile desktop remove dsh-retry-policy

移除后内置 llm-retry 恢复；若 ~/.dsh/profiles/desktop/cordis.patch.yml 仍留有本插件配置行，可一并删除。

典型用法¶

设置页（推荐）¶

路径：设置 → 模型重试策略。

1. 启用接管：关闭则使用内置默认策略。
2. 按需设置 无限重试、重试次数、等待策略及初始/最大等待、倍数、抖动。
3. 勾选 参与重试的失败码 与 优先听 Retry-After。
4. 查看 实时预览 后保存；经 configEditor 写入 profile 用户层补丁，即时生效。

README 中的场景预设可作为起点（改完保存即可）：

直接编辑补丁¶

不经 UI 时，可在 profile 用户补丁中写入（字段含义见 README「字段速查」）：

# ~/.dsh/profiles/desktop/cordis.patch.yml
- id: dsh-retry-policy
  name: dsh-retry-policy
  config:
    enabled: true
    mode: inherit          # inherit | always
    maxRetries: 10
    strategy: exponential  # exponential | linear | fixed
    initialDelayMs: 1000
    maxDelayMs: 60000
    multiplier: 2
    jitterRatio: 0.1
    retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
    respectRetryAfter: true

等待时间计算公式（README 第 4 节）：在 fixed / linear / exponential 上算出 base，再截断到 maxDelayMs，最后按 jitterRatio 加抖动并取整。

适用场景与注意¶

适合谁

• 经常遇到限流、超时或瞬时服务端错误，希望比默认 5 次更灵活地「多等一会儿再试」或「少试几次快速失败」的 DSH 桌面 profile 用户。
• 需要在不改 provider 适配器源码的前提下，统一在设置页调整重试策略的团队或个人。

边界与风险（资料原文）

• 只重试 agent loop step 边界上的模型请求；直接调用 ctx.llm.stream() 的路径仍是单次尝试，属官方架构限制。
• mode: always 会对鉴权、配额、非法参数等也持续重试，可能造成长时间阻塞与额外费用。
• 插件以 当前 DSH 进程权限运行；安装前请自行阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全与合规要求。社区目录 SkillHub 插件页 为独立生态站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-retry-policy 把「重试几次、每次等多久、哪些错误码值得重试」从适配器注册时的快照，挪到可保存、可预览的设置页与 YAML 补丁里，并在禁用内置 llm-retry 后保持与会话、轨迹兼容的官方事件语义。若你在 DSH 里调模型稳定性，可按上文命令安装 0.1.1（或按需锁定 GitHub tag），在 模型重试策略 页面试配后再用于日常会话。

• 目录页：https://www.skillhub.cn/plugins/jinxiqinghuan/dsh-retry-policy
• 源码与完整说明：https://github.com/jinxiqinghuan/dsh-retry-policy