前言¶

在 DeepSeek Harness（DSH）里，一次智能体请求通常会落到某一条 provider route 上。如果这条 route 返回 429、超时、传输异常，或凭证/配额状态异常，当前轮次可能直接失败。已有的重试策略往往围绕同一条 route 做有限恢复；如果用户已经有多条被授权访问同一模型的 route，就希望请求能切换到仍健康的 route，同时把坏凭证、坏配额或坏 route 隔离掉。

dsh-route-resilience 解决的是这个多路由可用性问题：它把用户已授权的 provider routes 组织成 model groups，在健康 route 之间分配请求，并在可重试错误发生时切换到下一条 route。下面介绍它的定位、功能、安装方式、典型用法和注意事项。

定位¶

dsh-route-resilience 是一个 DSH 插件，用于 multi-route high availability, fault isolation and observability。维护者是 lokic7123-star，许可证为 MIT。

它不是 quota workaround。它不绕过 quotas、rate limits 或 fair-use caps，也不支持多账号、多身份绕过 provider limits。它只使用用户已授权的 credentials 和 routes；每条 route 仍然受其 provider 的服务条款约束。插件通过名称引用 provider routes，不读取、写入或暴露 key material。

核心功能¶

多路由与故障切换¶

插件提供以下已核实能力：

• Model groups：将服务同一模型的多条 provider routes 组织成一个 group。
• Round-robin allocation：新请求在 active group 的健康 routes 间进行轮询分配。
• Retryable failover：遇到可重试错误时，请求可切换到下一条 route。
• 429 / Retry-After handling：对限流场景进行 429 / Retry-After 处理。
• Auth / quota isolation：对 auth / quota 异常进行隔离，避免异常 route 影响整个 group。
• Fallback：提供 fallback，避免所有 route 不可用时陷入死锁。

观测与管理¶

插件还提供以下入口：

• Observability：提供只读状态接口 GET /api/dsh-route-resilience/status。
• Web settings panel：在 Models 页面提供 Route resilience 面板，用于管理 groups、keys 和 quarantine parameters。

安装与启用¶

安装¶

文档给出的 npm 安装命令是：

npm install dsh-route-resilience

资料未确认 npm 发布状态。如果当前环境没有可安装的 npm 包，可以从 GitHub 仓库获取源码，并按 DSH profile 的插件方式接入。仓库地址：

https://github.com/lokic7123-star/dsh-route-resilience

在 profile 中启用¶

启用时，需要在 profile 的 package.json 中完成两步：

1、将 dsh-route-resilience 加入 dsh.profile.bundles。
2、添加一个 link: 依赖，指向本地插件目录。

可以写成类似下面的形式：

{
  "dsh": {
    "profile": {
      "bundles": ["dsh-route-resilience"]
    }
  },
  "dependencies": {
    "dsh-route-resilience": "link:/path/to/plugins/dsh-route-resilience"
  }
}

这里的 /path/to/plugins/dsh-route-resilience 应替换为实际存放插件的目录路径。经过上面的步骤后，插件进入 DSH profile 的加载路径。

典型用法¶

配置 settings namespace¶

插件从 dsh-route-resilience settings namespace 读取配置。下面是一个示例结构：

{
  "groups": [
    {
      "id": "deepseek",
      "targets": [
        { "provider": "route-a", "model": "deepseek-chat" },
        { "provider": "route-b", "model": "deepseek-chat" }
      ],
      "retryableCodes": ["RATE_LIMIT", "TIMEOUT", "TRANSPORT"],
      "quarantineBaseMs": 60000,
      "quarantineCapMs": 300000
    }
  ],
  "activeGroup": "deepseek"
}

其中：

• groups 定义一个或多个模型组。
• targets 列出组内 provider route 和 model。
• retryableCodes 指定可触发 failover 的错误代码。
• quarantineBaseMs 和 quarantineCapMs 用于 quarantine 参数。
• activeGroup 是可选字段；当 activeGroup 未设置时，插件处于 installed but idle 状态，routing passes through unchanged。

查看状态¶

插件提供只读状态接口：

GET /api/dsh-route-resilience/status

该接口用于查看当前路由健康状态。资料说明该状态路由是 read-only，与 served web UI 同域，并被 host trust fence 限制远程浏览器访问。

使用 Web 面板¶

在 Models 页面底部会出现 Route resilience 面板。可以在其中管理：

• groups
• keys
• quarantine parameters

该面板用于日常查看和调整多路由策略。插件侧仍只通过名称引用 provider routes，不暴露 key material。

适用场景与注意¶

这个插件适合以下场景：

• 已有多个被授权的 provider routes，希望同一模型在多路由之间保持可用。
• 希望把 429 / Retry-After、传输异常、auth / quota 异常等 route 级故障隔离。
• 希望有只读状态接口和 Web 面板来查看路由健康。
• 希望在不修改 DSH 核心源的前提下，以插件方式扩展路由行为。

需要注意：

• 它不绕过 quotas、rate limits 或 fair-use caps。
• 它不支持 multi-account 或 multi-identity circumvention of provider limits。
• 它只使用用户已授权的 credentials 和 routes；每条 route 仍受其 provider 的 terms of service 约束。
• 它不读取、写入或暴露 key material，只按名称引用 provider routes。
• 要求 DSH >= 0.1.0-rc.5，Cordis >= 4.0.1。
• 插件以当前 DSH 进程权限运行。安装前应检查源码、MIT 许可证、依赖版本和实际配置。

结尾¶

dsh-route-resilience 的价值在于：当某一条 provider route 出现限流、故障或授权异常时，让 DSH 仍能从其他已授权 route 继续提供服务，而不是让整个请求失败。它把多路由高可用、故障隔离和观测能力做成了一个 DSH 插件。

社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系；本文未确认目录页 URL。仓库地址为：

https://github.com/lokic7123-star/dsh-route-resilience