前言¶
在 DeepSeek Harness（DSH）里跑智能体时，模型选择往往是「一次选定、失败就报错」。官方 dsh-llm-retry 会在同一供应商内重试；若该供应商整体限流、配额耗尽或不可用，重试耗尽后这一轮仍会失败。多供应商、多模型并存时，需要一种在供应商之间按池轮询、失败即切、且不把真实错误掩盖掉的机制。下面介绍社区插件 qgg4588/dsh-model-failover（维护者 QGG4588，分类：模型推理）如何接入 DSH 扩展点实现上述行为。
这是什么¶
dsh-model-failover 是 Host-only bundle 插件：在模型请求因可配置失败码（如 RATE_LIMIT、QUOTA、TIMEOUT 等）失败时，从「所选供应商池」中挑选下一个未试过的模型重试；提供运行时工具 model_failover 与 Web 输入框旁的 ⇄ 故障转移 面板。池耗尽时交还原错误，不掩盖故障。
仓库：https://github.com/QGG4588/dsh-model-failover
社区目录页：https://www.skillhub.cn/plugins/QGG4588/dsh-model-failover（独立站点，与 DeepSeek / 幻方无官方从属关系）
当前 package.json 版本为 1.2.2，许可证 MIT，要求 DSH 引擎 >=0.2.1-rc.1 <0.3.0-0。
核心功能¶
供应商池与失败即切¶
- 池 = 所选供应商下的全部模型：只选一个供应商 → 该供应商内所有模型轮询；选多个 → 按顺序跨供应商池轮询。
- 触发转移：默认可路由失败码包括
RATE_LIMIT、QUOTA、ACCOUNT_QUOTA、SERVER、TIMEOUT、TRANSPORT、EMPTY_RESPONSE、NO_ADAPTER（可在配置中调整）；每个候选模型只试一次。 - 粘滞：
sticky: true时转移后该会话持续使用新模型；默认仅当次故障内转移。
与官方扩展点对齐¶
agent/request-error瀑布流：上游dsh-llm-retry同供应商重试耗尽后返回undefined，本插件接住失败 → 从池中挑下一个未试过的模型 → 返回{ kind: "retry" }，由 agent-loop 重新prepareRequest并重发。agent/request瀑布流：把待生效目标写入本次请求的 provider/model（与dsh-session-conductor成员模型切换同一模式）。- 失败分类只认
failure.code，不解析报错文本。 - 状态写在
<DSH_HOME>/model-failover/state.json（运行时池、粘滞目标、modelCatalog 快照、最近事件、熔断状态）。
熔断（抗抖动）¶
单模型偶发失败不立刻永久拉黑；在窗口内连续失败达阈值会进入冷却，池候选自动跳过；供应商级阈值可让整个供应商池一起冷却。preemptiveSwitch（默认开）可在请求前绕行已熔断路由。冷却到期自动恢复；llm/stream 成功终态会清除该路由熔断。全部候选熔断时仍按池顺序尝试。
运行时工具与界面¶
| action | 作用 |
|---|---|
status |
开关、池、触发码、最近 8 条转移事件 |
set |
设置运行时池（优先于 config.providers） |
clear |
清空运行时池与粘滞，回退配置池 |
enable / disable |
运行时总闸 |
Web 面板在输入框右下角、官方模型选择器左侧；数据走 GET /api/model-failover/status、POST /api/model-failover/{set,clear,toggle}。修改 Client 代码后需重启 DSH 并刷新页面。
安装与启用¶
本仓库无第三方依赖、无需构建，目录结构大致为：
dsh-model-failover/
├── index.js
├── cordis.patch.yml
├── package.json
├── locale/{en,zh}.json
└── icon.svg
方式一：通过 DSH Plugin Manager 的 install_bundle，target 传本目录绝对路径。
方式二：把目录放进 profile 的 node_modules/，并在 cordis.patch.yml 追加：
- insert:
- id: dsh-model-failover
name: dsh-model-failover
config: {}
重启 DSH 生效。插件以当前 DSH 进程权限运行，安装前请自行查看源码与 MIT 许可证。
配置项¶
在 cordis.patch.yml 对应行的 config 中设置（均有默认值）：
| 键 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关 |
providers |
[] |
默认供应商池；空则用 model_failover set |
retryableCodes |
见 README 列表 | 触发转移的失败码 |
sticky |
false |
转移后是否粘滞会话 |
maxFailoverAttempts |
0 |
单次故障最多转移几个候选（0 = 整个池） |
熔断相关阈值（failureThreshold、burstWindowMs、circuitCooldownMs、providerThreshold 等）见仓库 README「熔断」一节。
典型用法¶
先用运行时工具设定池（示例来自 README）：
model_failover set providers=["wb","agnes"]
含义：池 = wb 全部模型 + agnes 全部模型，按此顺序。
查看状态：
model_failover status
也可在 Web 面板勾选供应商并保存，与工具共用同一份状态。
与 dsh-llm-retry 协同时：先同供应商重试与退避，耗尽后由本插件做跨供应商转移。与 dsh-session-conductor 同在 agent/request 改写模型；有待生效转移或 sticky 时本插件生效，无 pending 时不干预显式成员模型。
适用场景与注意¶
适合：已配置多供应商、希望在限流/配额/超时/服务端错误时自动换模型继续同一轮任务，且需要运行时改池、不必改配置重启的场景。
边界（README 已说明）：
- 池成员来自
modelCatalog；目录不可用时用最近落盘快照。 - v1 不检查候选模型的输入模态；池内含纯文本模型时，图片消息可能被拒。
- 转移在同一步内可能增加耗时（每个候选一次完整尝试 + 官方退避）。
- 不做定时轮询，仅失败时转移。
单元测试：node --test test/unit.mjs。
结尾¶
dsh-model-failover 在 DSH「一切皆插件」的生态里，补上官方单点选模与同供应商重试之外的跨供应商池故障转移能力，并配合熔断与 Web/工具双通道控制。进一步了解与安装可参考 SkillHub 目录页 与 GitHub 仓库。
