模型故障切换guangxiangwu6-cmd/dsh-llm-failover

dsh-llm-failover

当你的模型宕机时，你的任务不会。

DeepSeek Harness 的社区模型自动故障切换插件。当 Provider 出现 429 / 5xx / 超时 / 网络错误 / SSE 中断时，自动切换到健康模型继续执行，而不是让整个任务失败。

⚠️ DeepSeek Harness 的社区插件。与 DeepSeek 无关联，也未获其认可。

version
license MIT
node
tests
boot-safe

是什么 & 为什么

你在用 DeepSeek Harness 跑任务，突然当前模型挂了——429 限流、5xx 服务端错误、超时、网络断连、SSE 流中断。没有 failover 插件时，整个任务直接失败，你得手动重试。

本插件在 Provider 级别实现自动故障转移：

Provider A (DeepSeek V4)
│
├── 429 / 5xx / Timeout / Network Error
│
▼
Failure threshold reached (default: 5)
│
▼
Provider A → marked unhealthy, enters cooldown
│
▼
Switch to Provider B (next healthy model in priority pool)
│
▼
Task continues seamlessly — same session, same context
│
▼
Cooldown expires → Provider A automatically recovers

功能特性

- 自动 Retry + Failover — 基于 agent loop 的两个公开 waterfall 扩展点，零修改核心循环
- Provider 健康管理 — 按 provider 粒度跟踪连续失败次数
- 优先级池切换 — models 数组顺序即优先级
- 双通道恢复 — 冷却到期惰性恢复 + assistant message 主动证明恢复
- 最大切换保护 — 单回合切换上限防止死循环
- 错误分类 — 7 种可恢复错误 + 多种永久错误，精确决定是否切换
- 敏感信息日志脱敏 — URL 凭据 / Bearer token / key 参数自动掩码
- Session 安全设计 — 不写自定义事件类型，避免会话重载兼容问题
- 与 llm-retry 共存 — 阈值以下决策权归 llm-retry，达到阈值才由本插件接管

安装

三步手工操作，不联网、不 npm install：

1. 复制插件到 Harness（排除 node_modules）
$dst = "\\resources\\app.asar.unpacked\\node_modules\\@deepseek-ai\\dsh-llm-failover"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
Copy-Item "\\" $dst -Recurse -Force -Exclude node_modules

2. 把 patches/cordis.patch.snippet.yml 的内容追加到 DSH home 下的 profiles\\desktop\\cordis.patch.yml 末尾
DSH home 默认：Windows %USERPROFILE%\\.dsh / Linux·macOS ~/.dsh

3. 重启 DeepSeek Harness Desktop

启动日志出现 llm-failover active 即加载成功。详见 INSTALL.md。

完全可逆：删目录 + 删配置块 + 重启。

快速配置

models 数组的顺序就是故障切换优先级——排在第一位的是主模型，后面的依次作为备份。

- insert:
- id: llm-failover
name: '@deepseek-ai/dsh-llm-failover'
config:
enabled: true                  # 总开关
models:                        # 故障切换池（顺序 = 优先级）
- provider: deepseek-official
model: deepseek-v4-flash
- provider: my-siliconflow   # llm-pi-ai settings 里的 profile 名
model: deepseek-ai/DeepSeek-V3
maxConsecutiveFailures: 5      # 同一 provider 连续失败多少次后切换
cooldownSeconds: 60            # 冷却时长（必须 > 0）
autoRecover: true              # 冷却到期是否自动回池
maxSwitchesPerTurn: 8          # 单回合最大切换次数
未配置键取默认值；未知键不会导致报错，只记录警告后忽略。models 为空时插件保持惰性。

按类别故障转移开关

| 开关 | 默认值 | 控制范围 |
|--------|---------|----------|
| failoverOnRateLimit | ✅ true | HTTP 429 |
| failoverOnTimeout | ✅ true | 请求/连接/空闲超时 |
| failoverOnServerError | ✅ true | HTTP 5xx |
| failoverOnTransportError | ✅ true | 网络/代理链路异常 |
| failoverOnStreamInterrupted | ✅ true | SSE 流中断 |
| failoverOnEmptyResponse | ❌ false | 退化空补全 |
| failoverOnQuota | ❌ false | 配额耗尽 |

错误分类

| 错误 | 默认行为 | 原因 |
|-------|-----------------|-----|
| RATE_LIMIT (429) | 故障转移 | Provider 限流，切换可能绕过 |
| SERVER (5xx) | 故障转移 | 服务端瞬时故障 |
| TIMEOUT | 故障转移 | 请求/连接超时 |
| TRANSPORT | 故障转移 | DNS、连接重置/拒绝、代理异常 |
| STREAM_CLOSED | 故障转移 | SSE 流中途中断 |
| EMPTY_RESPONSE | 仅重试 | 可安全重复，不一定需要切模型 |
| QUOTA | 仅重试 | 配额问题，切模型不一定解决 |
| AUTH / INVALID_CREDENTIAL | 永不故障转移 | 凭证问题，切换无用 |
| INVALID_REQUEST / UNKNOWN_MODEL | 永不故障转移 | 请求本身有误 |
| CONTEXT_WINDOW_EXCEEDED | 永不故障转移 | 交给 compaction 处理 |
| ABORTED | 永不故障转移 | 用户主动取消 |

架构

agent/request-error (请求失败恢复点)
│
├── 可恢复错误 → 计数
│   ├── 未达阈值 → 交给下游栈（通常是 llm-retry）
│   └── 达到阈值 → 标记不可用 + 冷却 → 切换到下一健康目标
│
└── 永久错误 → 永不切换，让错误冒泡

agent/request (每次构建请求时)
│
└── 目标 provider 处于冷却期 → 自动改写到当前最优健康条目
└── 改写时丢弃继承的 reasoningEffort（属于失败路由的每模型设置）

恢复是双通道的：冷却到期后惰性放回池中；任何 assistant 消息证明某 provider 成功出活时立即主动恢复。

详见 docs/architecture.md。

项目状态

Release Candidate — 版本 0.1.1-rc.4

- ✅ 核心 failover 功能已实现并通过 19/19 测试
- ✅ 启动安全设计经真实加载器验证
- ✅ 已安装进真实 DSH Desktop 环境（2026-08-27）
- ✅ QA 彩排脚本 6 个（smoke / badconfig / disabled / doc-crosscheck / s0-session-compat / final-round）
- 🔄 当前生产配置：deepseek-official/deepseek-v4-flash，1 模型池（待扩展）

有意排除的范围

- 会话内可见切换提示 — DSH 当前未暴露注册自定义会话事件类型的扩展点，插件侧不存在受支持的实现通道。详见 docs/session-compatibility.md。
- 自动推导备份模型 — 切换目标必须显式列在 models 里，不会从适配器目录自动推导。
- 旁路调用保护 — 直接消费 ctx.llm.stream() 的调用（标题生成、compaction 摘要）不在保护范围内。

未来可能的扩展

- 若 DSH 提供事件词汇注册面或 ignorable 公开写入口，可重新评估恢复会话事件记录
- 与本地 AI 网关集成时的双层阈值错开策略

安全

本插件在设计上避免敏感信息泄露：

- URL 内嵌凭据掩码 — 日志中 URL 里的 key=、token= 参数自动替换为 **
- Bearer token 掩码 — Authorization header 中的 token 不会明文出现在日志
- 错误文本截断 — 错误信息截断至 200 字符，减少意外泄露窗口
- 不写会话事件 — 决策轨迹只存在于宿主日志，不追加任何会话事件

故障排查

| 问题 | 检查项 |
|---------|-------|
| 插件没有加载 | 启动日志搜索 llm-failover，确认目录复制位置正确 |
| models 没有配置 | models 为空时插件仅日志提示，不执行切换 |
| provider 名称配置错误 | 切换目标会跳过不存在的 provider，不影响原请求 |
| 模型切换没有发生 | 检查 maxConsecutiveFailures 是否达到；检查 per-class 开关 |
| 为什么 AUTH 不切换 | 凭证问题切换无用，设计行为 |
| 为什么某些错误只 retry | 参考错误分类表 |
| 为什么 session 中看不到 failover 消息 | 插件不写会话事件，见 docs/session-compatibility.md |
| 如何查看日志 | Host 日志面板过滤 llm-failover |
| 如何关闭插件 | config.enabled: false 或 patch 行块加 disabled: true |
详见 docs/troubleshooting.md。

演示

许可证

MIT