DeepSeek Harness Retry 插件介绍

在 DeepSeek Harness（DSH）的开发过程中，模型故障（如服务器过载、网络波动或 PI_AI_ERROR）常导致请求中断或任务失败。deepseek-harness-retry 插件旨在解决这一问题，提供可配置的自动重试机制和中断会话恢复能力。

插件定位与架构¶

该插件由社区开发者 syncended 维护，属于 Host 插件。它位于 agent/request-error 水流中，在应用自身的回退预算之前，会优先委托给 DSH 内置的恢复策略。

核心价值：
* 处理通用瞬态模型故障（如 PI_AI_ERROR、UNKNOWN）。
* 在 DSH 崩溃或重启后，仅继续被证明未完成的工作。
* 提供精确的提供商路由控制。

安装与启用¶

安装插件时，DSH 会自动将其注册为 model-error-retry 插件条目，无需手动添加插件入口。

dsh plugin --profile web add @syncended/dsh-retry

安装或升级后，需要重启选定的 DSH Profile 以使配置生效。

核心功能¶

智能重试策略
- 处理 PI_AI_ERROR、UNKNOWN 等配置的瞬态错误。
- 默认在原始请求后重试 2 次。
- 针对 Codex 服务器明确的过载错误，重试 5 次并使用更长的延迟。
延迟控制
- 支持指数退避（Exponential Backoff）策略。
- 包含随机抖动（Jitter）以避免惊群效应。
- 支持 Provider 返回的 Retry-After 头。
恢复与中断处理
- 中止感知等待：在等待重试期间，如果检测到用户取消或插件销毁，会立即停止等待。
- 会话恢复：在 DSH 崩溃或重启后，通过持久化会话历史，安全地继续未完成的任务（默认保留 24 小时内的未完成任务）。
- 收件箱保护：插件永远不会移除、重新排序或替换现有的持久化收件箱项目。
事件与路由
- 发出标准的非表面会话事件（llm/retry、llm/retry-started）。
- 支持通过 providers（允许列表）和 excludeProviders（拒绝列表）精确控制重试的 Provider 路由。

配置方法¶

插件安装后默认配置即可生效。如需自定义，需编辑对应的 Profile 配置文件。

编辑路径：
$DSH_HOME/profiles/<profile>/cordis.patch.yml

配置示例：
找到 id: model-error-retry 的条目，修改 config 部分。

- id: model-error-retry
  config:
    maxRetries: 3
    overloadMaxRetries: 5
    retryableCodes:
      - PI_AI_ERROR
      - UNKNOWN
      - STREAM_CLOSED
      - EMPTY_RESPONSE
      - RATE_LIMIT
      - SERVER
      - TIMEOUT
      - TRANSPORT
    initialDelayMs: 750
    overloadInitialDelayMs: 2000
    maxDelayMs: 15000
    jitterRatio: 0.15
    respectRetryAfter: true
    resumeInterrupted: true
    resumeMaxAgeMs: 86400000
    providers:
      - openai
      - openrouter

主要配置项说明：
* maxRetries: 普通错误的重试次数，默认为 2。设为 0 可禁用请求错误重试。
* overloadMaxRetries: 针对过载错误的重试次数，默认为 5。
* resumeMaxAgeMs: 未完成任务的最大等待时间（毫秒），默认为 86400000（24 小时）。
* providers: 允许重试的提供商列表，留空则允许所有。

系统要求与注意事项¶

环境依赖：
- 需要 Node.js 20 或更高版本。
- 需要 DeepSeek Harness 0.1.0-rc.7+ 或 0.1.1-rc.2+。
- 需要内置插件 @deepseek-ai/dsh-llm-retry（插件依赖该插件而非替换它）。
行为限制：
- 成本：每次重试都是一次新的 Provider 请求，会产生额外的费用。
- 历史记录：重试的错误和延迟不会添加到模型可见的历史记录中。
- 权限：作为 Host 插件，它没有浏览器连接步骤，也不需要插件特定的环境变量。

总结¶

deepseek-harness-retry 插件通过自动化的重试和会话恢复机制，增强了 DSH 在处理不稳定网络或模型状态时的鲁棒性。开发者可以通过配置文件灵活调整重试策略，以平衡请求成功率和资源消耗。

资源链接：
* GitHub 仓库
* DSH 插件目录