Letter2025/dsh-model-failover

dsh-model-failover

release
downloads
stars
license
docs
Awesome DSH Plugin

为 DeepSeek Harness 打造的两级模型熔断与回退插件。当某个模型（或整个平台）持续失败时，插件打开熔断并把下一个模型请求路由到配置好的备用模型——零核心改动，dsh plugin 即可安装。

功能

- 模型级熔断 — 某个 provider/model 在 burstWindowMs 内失败达到 modelCircuitThreshold 次即打开。
- 平台级熔断 — 同一 provider 下有 platformCircuitThreshold 个不同模型同时打开时，整个平台熔断（平台故障通常连带所有模型）。
- 自动回退 — 下一个请求路由到 fallbacks 里第一个健康的备用路由；切换由 loop 自身落库（request/header 变更），可选追加用户可见提示。
- 恢复探测 — 打开的模型熔断在 modelCooldownMs 后用一次极小的真实调用探测；探测成功关闭熔断，失败则顺延冷却。
- 与 llm-retry 协作 — 单次请求的重试仍归官方 llm-retry 策略负责，熔断器只观察逃逸出重试的失败；重试后恢复的瞬时抖动不会误触发熔断。

安装

dsh plugin --profile web add dsh-model-failover

然后按需在 profile 的 cordis.patch.yml 里配置 fallbacks（唯一必配项）和阈值——完整默认配置见 cordis.patch.yml 中的插件行。

配套引导技能 configure-model-failover：由 AI 探测当前模型配置、写入 fallback 覆盖配置、再请你确认。安装插件即自动注册：包内自带 skills/configure-model-failover/SKILL.md，只要 skills 服务存在，插件就会把它注册为捆绑技能，无需手动复制。独立安装（未装插件的 profile）时才需要复制到 ~/.dsh/skills/configure-model-failover/（用户级技能实时生效）。

工作原理

插件装饰两个 agent-loop 官方瀑布（均为官方扩展点，无核心改动）：

| 瀑布 | 职责 |
| --- | --- |
| agent/request-error | 把 tripCodes 内的失败记录进熔断器，然后 next() 委托，重试仍归 llm-retry。 |
| agent/request | await next() 拿到解析后的配置，返回健康的主路由；主路由熔断时返回第一个健康的备用路由。 |

请求 ──> agent/request ──> 主路由 (mock/m1) ──> 失败×2 ──> 熔断打开
│
下一个请求 ──> agent/request ──> 主路由熔断 ──> 备用 (mock2/m2) ✔
│
冷却后探测 ──> 成功 ──> 熔断关闭

配置项

| 字段 | 默认 | 含义 |
| --- | --- | --- |
| enabled | true | 总开关。 |
| fallbacks | [] | 有序备用路由 {provider, model}；必须指向已注册 adapter 的 provider。 |
| tripCodes | RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, QUOTA, EMPTY_RESPONSE | 计入熔断的失败码；如 AUTH/INVALID_CREDENTIAL 保持终态不计入。 |
| modelCircuitThreshold | 2 | 突发窗口内打开模型熔断的失败次数。 |
| modelCooldownMs | 60000 | 模型熔断打开后的探测冷却时长。 |
| platformCircuitThreshold | 2 | 打开平台熔断所需的不同打开模型数。 |
| platformCooldownMs | 120000 | 平台级冷却时长。 |
| burstWindowMs | 300000 | 超过此时间的失败视为新一轮突发。 |
| enableProbe | true | 冷却后探测打开的模型以恢复熔断。 |
| probeMaxTokens | 8 | 探测调用的输出上限。 |
| stripReasoningEffort | true | 回退时丢弃主路由的 reasoning effort（备用模型可能不支持）。 |
| notifyUser | true | 路由切换时追加用户可见消息。 |

事件

插件自定义（emit）事件，类型通过 src/types.ts 中的 @deepseek-ai/cordis 增强声明：

- model-failover/circuit-opened — {provider, model, level: 'model' | 'platform'}
- model-failover/circuit-closed — {provider, model, level: 'model'}
- model-failover/failover — {from, to, agentId}
- model-failover/probe — {provider, model, ok, message?}

已知限制与后续

- 进程内状态 — 熔断状态存内存，插件重载即重置（与所有 harness 注册表一致）。跨实例共享暂缓。
- 仅覆盖 agent-loop 主链路 — agent/request 只管主对话循环；辅助调用（session-title、compaction、手写 ctx.llm.stream）不做路由。
- retryPolicy.mode: 'always' — 该模式下官方 llm-retry 永不把失败委托给本熔断器，回退按设计保持空闲（运维已选择无限重试）。
- 无上下文窗口适配 — 备用模型窗口较小可能触发 CONTEXT_WINDOW_EXCEEDED；请设置 stripReasoningEffort 并选择兼容的备用模型。
- 无平台级探测 — 平台熔断靠冷却到期恢复，仅模型级熔断有探测。

License

MIT