安装

在 DeepSeek Harness 里通过 dsh-market 安装

dsh plugin --profile web add dshmarket

或使用命令行

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

装任何插件都等于在你的机器上跑第三方代码，权限和你本人一样大——能读你的文件、用你的凭据、访问网络。请先审阅源码，并尽量锁定 commit（github:owner/repo#sha）。

README

中文 | English

为 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 并选择兼容的备用模型。
无平台级探测 — 平台熔断靠冷却到期恢复，仅模型级熔断有探测。