dsh-model-failover：DeepSeek Harness 两级熔断与故障转移插件

前言¶

在 DeepSeek Harness (DSH) 的智能体开发中，模型或平台层级的故障（如超时、限流、服务不可用）会导致智能体请求失败。如果没有自动切换机制，故障会持续累积。dsh-model-failover 插件通过两级熔断策略，在模型或平台出现故障时自动切换到备用路由，保障服务连续性。

该插件为 DeepSeek Harness 提供两级模型熔断和故障转移能力。
* 维护者：Letter2025
* 类别：模型推理
* 许可证：MIT

两级熔断：支持模型级和平台级熔断。当 modelCircuitThreshold 次失败发生在 burstWindowMs 窗口内时触发模型熔断；当 platformCircuitThreshold 个独立模型熔断时触发平台级熔断。
故障转移：主路由熔断后，下一个请求会自动路由到 fallbacks 中配置的第一个健康备用路由。
恢复探测：熔断开启后，经过 modelCooldownMs 冷却期会进行恢复探测。探测成功则关闭熔断，失败则延长冷却时间。
与 llm-retry 协同：插件与 llm-retry 插件配合工作。llm-retry 负责请求重试，而本插件观测逃逸的重试失败，避免因瞬时抖动而误触发熔断。

通过 DSH 的 CLI 安装插件：

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

安装后，需要在 cordis.patch.yml 中配置 fallbacks（这是必须设置的字段）。

# cordis.patch.yml 示例
fallbacks:
  - provider: "provider-name"
    model: "model-name"

此外，插件会自动安装一个配套技能 configure-model-failover，该技能可以引导你通过对话设置备用模型配置，无需手动复制文件。

进程本地状态：熔断状态保存在内存中，插件重载时会重置，不支持跨实例共享。
仅路由 agent-loop 调用：插件仅对 agent-loop 的主循环调用进行路由，session-title 等辅助调用不会经过熔断逻辑。
无平台探测：插件仅对模型级熔断进行恢复探测，平台级熔断仅依靠冷却时间恢复。
上下文窗口风险：如果备选模型的上下文窗口小于主模型，切换时可能触发 CONTEXT_WINDOW_EXCEEDED 错误，需配置 stripReasoningEffort: true 并选择兼容的备选模型。
特定重试模式：当 retryPolicy.mode 为 always 时，插件处于闲置状态（设计如此），因为此时重试策略会处理所有失败。

dsh-model-failover 插件通过两级熔断机制和故障转移策略，为 DeepSeek Harness 提供了基础的容错能力。它不修改核心代码，仅通过插件形式介入，适合需要在模型层增加高可用保障的场景。