MistRain-1/dsh-reconnect

dsh-reconnect

为 DeepSeek Harness 提供安全的模型请求重试，具备指数退避、中继/代理故障恢复以及统一的设置面板。

版本： 2.0.0

- 中文文档 (Chinese README)

项目描述

dsh-reconnect 是 DeepSeek Harness (DSH) 的一个 Host 端插件。它会重试失败的模型请求，使临时网络故障不会中断 agent 回合或长时间运行的任务。

该插件监听 DSH 的 agent/request-error waterfall 事件。在内置的 normal Provider 重试策略放弃后，或者当 Provider 的 always 策略将恢复委托给下游时，Agent 循环会根据本插件的策略再次发送同一请求。

适用场景

- 不稳定的中继站、反向代理、API 网关或转发服务
- 断开连接、重置连接或返回不完整响应的中继节点
- 间歇性网络故障和传输错误
- 临时的 provider 中断、服务端 5xx 错误、速率限制和超时
- 应能在短暂的 provider 或网络故障中存活的长时间运行任务

重试策略

| 条件 | 行为 |
| --- | --- |
| EMPTY_RESPONSE / RATE_LIMIT / SERVER / STREAM_CLOSED / TIMEOUT / TRANSPORT | 无限重试（临时连接/服务故障） |
| 模型缺失或未配置（MODEL_NOT_FOUND、MODEL_NOT_CONFIGURED 或匹配的 Provider 文本） | 无限重试，等待模型/账户配置恢复 |
| QUOTA（余额不足或配额耗尽） | 默认不重试；当 retryQuota: true 时重试 |
| 未知错误，如 PI_AI_ERROR | 默认无限重试；禁用 retryUnknown 以应用可配置的连续失败上限 |
| 工具/参数/未知工具/认证/凭据/上下文溢出/中止 | 从不重试；步骤立即结束 |

关键设计要点：

- 仅重试"重新发送同一请求"即可修复的故障——连接断开、速率限制、超时、5xx。
- 工具执行错误（tool/result）不在本插件的重试边界内。错误路由使用来自 agent/request-error 的机器码，而非根据消息文本猜测；未知机器码使用配置的未知错误路径（仅在 retryUnknown 被禁用时受限）。
- 永久性错误（凭据、请求内容、上下文溢出）立即停止；模型缺失或未配置是刻意的例外，会在配置恢复期间持续重试。
- retryQuota 和 retryUnknown 控制本插件的回退链。Host 的 always 策略将恢复委托给下游 waterfall 监听器，因此本插件对可恢复的故障类别只处理一次，不会创建第二个并行的重试循环。

退避与取消

- 指数退避：1s -> 2s -> 4s -> ...，默认上限为 60s（设置面板提供 1/2/5/10/30/60/120 秒或自定义值；maxDelayMs 以毫秒为单位覆盖）
- 当存在正的 providerRetryAfterMs 时予以遵循。它是提供方的最小等待时间，不受本地指数退避上限的限制；仅适用 Node 定时器的最大值。
- 记录提供方、错误代码、轮次、步骤、重试次数和延迟
- 发出标准的 llm/retry 事件，以便 Harness 对话 UI 显示连续的重试次数和倒计时
- 在当前轮次被中止、插件被停止或插件被热重载时停止；活动中的等待会在清理期间被排空。

可视化配置

打开 设置 → 插件配置。ReConnect 在该页面中显示为一张插件卡片：

- 每次尝试的最大等待时间：下拉预设（1/2/5/10/30/60/120 秒）或自定义值
- 配额错误时重试：开关，默认关闭
- 未知错误无限重试：开关，默认开启
- 未知错误的最大重试次数：默认 3。模型缺失或未配置错误不受此上限约束，始终重试。

更改立即生效，无需重启 DSH。

YAML 配置

该插件在其 Cordis 行配置中接受可选值：

- maxDelayMs（整数毫秒，默认 60000）：限制本地指数退避延迟；例如 15000 会产生 1s -> 2s -> 4s -> 8s -> 15s -> 15s... 无限循环。正的提供方 Retry-After 仍然具有权威性。
- retryQuota（布尔值，默认 false）：是否也重试 QUOTA 错误。
- retryUnknown（布尔值，默认 true）：是否无限重试未知错误。
- unknownMaxRetries（整数，默认 3）：同一模型步骤中连续未知失败的有界上限；模型缺失或未配置错误不使用此上限。

设置服务会持久化插件卡片的值。恢复默认值 会移除用户覆盖并立即返回 schema/Cordis 默认值；无需重启。

该插件自身的重试策略是提供方 normal 和 always 策略的下游恢复机制。这两层不会使重试次数相乘：normal 仅在此插件之前调度其配置的错误代码，而 always 将决策委托给下游。

maxDelayMs 限制本地指数等待时间，而非 提供方 Retry-After 值，也非总重试持续时间。

- insert:
- id: reconnect
name: dsh-reconnect
config:
maxDelayMs: 15000
retryQuota: false
retryUnknown: true

无效或缺失的 maxDelayMs 值会回退到 60000。

下载

该包与平台无关。请选择以下方法之一。

方法 1：GitHub 网页下载

1. 打开 https://github.com/MistRain-1/dsh-reconnect。
2. 选择 Code，然后选择 Download ZIP。
3. 解压归档文件，并将解压出的 dsh-reconnect-main 目录用作插件包。

方法 2：Git Clone

Windows PowerShell：

git clone https://github.com/MistRain-1/dsh-reconnect.git "$HOME\dsh-reconnect"

macOS：

bash
git clone https://github.com/MistRain-1/dsh-reconnect.git "$HOME/dsh-reconnect"

Linux：
bash
git clone https://github.com/MistRain-1/dsh-reconnect.git "$HOME/dsh-reconnect"

方法 3：从终端下载 ZIP

Windows PowerShell：
powershell
Invoke-WebRequest -Uri https://github.com/MistRain-1/dsh-reconnect/archive/refs/heads/main.zip -OutFile dsh-reconnect.zip
Expand-Archive -Path dsh-reconnect.zip -DestinationPath .

macOS：
bash
curl -L https://github.com/MistRain-1/dsh-reconnect/archive/refs/heads/main.zip -o dsh-reconnect.zip
unzip dsh-reconnect.zip

Linux：
bash
wget https://github.com/MistRain-1/dsh-reconnect/archive/refs/heads/main.zip -O dsh-reconnect.zip
unzip dsh-reconnect.zip

下载完成后，在 DSH Cordis 组合中注册该包：
yaml
- insert:
- id: reconnect
name: dsh-reconnect

安装持久化插件包后需要重启 DSH。

要求

- DSH Host 插件
- 使用 agent/request-error 瀑布事件和 Host 设置服务
- 客户端提供统一格式的设置卡片，且从不读取凭据

许可证

MIT