前言¶
在 DeepSeek Harness（DSH）里跑长会话时，常见中断来自当前模型的配额用尽、限流或路由暂时不可用。同一路由上的退避重试可以由 dsh-llm-retry 处理，但若主模型本身已经不可用，仍需要换一条路由才能把对话接下去。手动在模型选择器里切换会打断节奏，也不便于事先排好优先级。
dsh-model-fallback-queue 面向这类场景：为当前会话维护 P1 → P2 → … 的队列，在命中熔断条件时自动切到下一个模型，开关、队列顺序和 P1 恢复策略都在 Web 设置页完成，无需命令行。维护者为 HelloQingTao，归类为模型推理；npm 包名为 dsh-model-fallback-queue（当前版本 0.2.5，MIT 许可证）。
这是什么¶
插件在请求路径上实现跨路由的故障转移：P1 默认跟随你在会话里选的当前模型，你在设置里添加的是后备 P2、P3 等。发生切换时，DSH 核心会给出「模型已切换」通知，输入框旁的芯片会同步显示当前生效路由。
它与 dsh-llm-retry 分工明确：非致命错误一律放行，同路由退避重试仍由 retry 插件负责；本插件只处理需要换路由的情况。与 dsh-client-auto-continue 兼容，自动续发走同一条请求链，同样享受队列切换。
核心功能¶
请求级熔断与切换¶
- 命中即时熔断错误码（如
QUOTA、ACCOUNT_QUOTA、RATE_LIMIT、AUTH、INVALID_CREDENTIAL、NO_ADAPTER）时，立刻熔断当前路由并尝试队列中的下一个可用项。 - 其他错误连续失败 2 次（默认阈值）也会熔断当前路由。
- 熔断冷却默认 60 秒（
cooldownMs）；熔断状态在内存中，进程重启后归零。
队列 P1 → Pn¶
- P1 跟随当前会话模型（
p1Follow默认为true）：在模型选择器里换模型，P1 跟着变；队列里配置的是后备项。 - 队列为空或只有一项时不会发生切换。
- 队列顺序即优先级，存在独立文件
~/.dsh/fallback-queue-state.json，不在 settings 文档里，避免频繁调序触发ui-theme重推导致深色模式闪白（README 中的设计说明）。
P1 恢复策略三档¶
| 档位 | 行为 |
|---|---|
粘滞（sticky，默认） |
切到 P2 后只要 P2 可用就一直用，P1 恢复也不自动切回；继续失败则按队列往后找，绕回 P1 是最后手段。 |
探测回切（probe） |
P1 冷却到期后，由下一个真实请求探测回 P1；成功则留在 P1，失败回到 P2（默认防抖 5 分钟，不发额外探测流量）。 |
手动回切（manual） |
不自动回 P1，在芯片展开面板里点「切回 P1」。 |
输入框芯片与全熔断降级¶
输入框右侧显示状态芯片，可展开查看队列与健康状态：
| 显示 | 含义 |
|---|---|
P1 + 绿点 |
正常走 P1 |
P2（黄点） |
已切到 P2；黄点表示半开探测中 |
P! + 红点 |
队列全部熔断，已按原配置降级放行 |
P（灰点） |
插件未启用 |
当所有路由都熔断时，插件按原配置放行请求，不拦截。界面文案跟随 DSH 语言设置，中英自动切换。
安装与启用¶
在 Web 配置对应的 profile 下安装（官方 README 命令）：
dsh plugin --profile web add dsh-model-fallback-queue
装完后重启 dsh 或刷新 Web GUI；包内 cordis.patch.yml 会自动注册 bundle。兼容范围以 package.json 的 engines.dsh 为准：>=0.2.0-rc.2 <0.3.0；README 记载在 dsh 0.2.0-rc.2、0.2.1-rc.2 上实测。需要 Node.js >=20。
插件以当前 dsh 进程权限运行，安装前建议查看 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。
典型用法¶
- 打开 设置 → 故障转移，开启「启用故障转移」。
- 点 + 添加模型，选择后备路由（P2、P3…），用 ↑ / ↓ 调整顺序，不需要的项可移除。
- 选择 P1 恢复策略：粘滞、探测回切或手动回切。
- 回到会话：输入框右侧芯片显示当前 P1 对应的路由；发生切换时留意会话内的模型切换通知与芯片变化。
日常用的 enabled、queue、failbackMode 均在设置页修改。高级项（如 immediateCodes、failureThreshold、cooldownMs、failbackDelayMs）默认可用；需要定制时写入 ~/.dsh/profiles/<profile>/cordis.patch.yml 中本插件行的 config。
注意：队列文件是插件私有数据，不在设置页的导出/备份范围内，换机器需重新配置队列；首次升级若 JSON 不存在，会从 settings 里的旧队列自动迁移。
适用场景与注意¶
适合谁
- 配置了多条模型路由、希望主模型限流或配额问题时自动落到后备模型的 DSH 用户。
- 已使用 Web GUI profile，并愿意在设置页维护队列顺序与恢复策略的场景。
兼容与分层
- 号池类 provider（如 workbuddy-xdpool）：单号限流由号池内部换号，整池到顶后才轮到本插件跨模型切换。
- 不要与其他故障转移类插件同时启用，避免争抢同一错误事件。
社区与目录
DSH 生态强调「一切皆插件」；插件目录站 SkillHub 条目 与 GitHub 由社区维护，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-model-fallback-queue 把跨路由切换、熔断策略和 P1 回切收成一套图形化配置：限额、限流或不可用时按队列继续会话，全熔断时仍降级放行原请求。进一步了解实现与 issue，见 GitHub：HelloQingTao/dsh-model-fallback-queue；浏览分类与简介见 SkillHub 插件页。
