前言¶
DeepSeek Harness（DSH）在运行长任务时，经常因为上游限流、额度耗尽、5xx 错误或超时导致回合中断。内核的 dsh-llm-retry 只能在同一 provider 内重试，本地网关也没有跨模型切换能力，而错误往往发生在服务端。因此，唯一可行的方案是在本地这一跳失败时，改派到另一个模型。
dsh-model-fallback 为 DSH 的每个主模型配置一条有序候选列表：当请求失败且错误类别命中你勾选的触发条件时，由链上的下一个模型接替这次请求。回合不会中断，并在会话里记录改派原因。
插件定位与维护者¶
dsh-model-fallback 是一个为 DeepSeek Harness 提供模型回退链能力的插件，维护者为 yn2aa。它通过在内核的两条 waterfall 上挂载钩子（agent/request 和 agent/request-error），实现失败时的跨模型改派。
核心功能¶
- 按主模型配置多条有序候选链
- 支持限流（TPM/RPM）、额度耗尽、HTTP 5xx、超时与网络错误等多类触发条件
- 设置页可视化编排：拖拽排序候选模型、按计费倍率或上下文窗口排序候选、失败模型自动冷却
- 多条链集中管理，支持停用与启用
- 零依赖、无构建步骤、默认不介入任何请求（无链时完全静默）
- 回合不中断，失败原因在会话中标注
安装与启用¶
一键安装/卸载¶
使用 PowerShell 脚本安装或卸载插件：
pwsh -File .\install\install.ps1 # 复制真实目录 + 登记依赖与 bundle
pwsh -File .\install\uninstall.ps1 # 完整逆操作
脚本默认按 $DSH_HOME（未设置则 ~/.dsh）定位 profile，安装位置不同可传参 -ProfilePath。
命令行安装¶
dsh plugin 命令支持在自定义 profile 上安装：
dsh plugin --profile <profile-name> add dsh-model-fallback
桌面端 profile（--profile desktop）由 Electron 应用独占管理，CLI 无法写入，桌面端请使用上述脚本或应用内插件管理器。
从零开始的完整流程¶
假设 profile 目录为 <DSH_HOME>/profiles/desktop/：
- 将本包整个复制到
<DSH_HOME>/profiles/desktop/node_modules/dsh-model-fallback/，必须包含lib/、cordis.patch.yml、package.json。 - 编辑
<DSH_HOME>/profiles/desktop/package.json，在dependencies中加入"dsh-model-fallback": "0.1.0"（版本号跟随本包package.json）。 - 在同一
package.json的dsh.profile.bundles数组末尾追加"dsh-model-fallback"。 - 重启 DSH。重启后打开 设置 → 模型回退链 即可看到配置入口。
重启要求¶
- 装载/启用/禁用插件（host 侧）：无需重启，实时生效
- 替换已安装包的 JS（
lib/*.js）：必须重启 - 仅客户端 bundle（
lib/client.js）：无需重启，但需pnpm run dev:web在运行时才自动重建，否则刷新页面即可
典型用法¶
打开 设置 → 模型回退链，页面自上而下依次为回退链管理区、可用模型清单、候选编辑面板、冷却中的模型、最近改派记录。
建一条回退链¶
- 在可用模型清单中，勾选要作为主模型的行，点击「设为回退链主模型」。如果没有链，会提示「还没有配置任何回退链」，此时插件完全不会介入。
- 新建链后会进入编辑状态，可以点击「添加候选（勾选即加入）」在展开清单中勾选候选模型。勾选状态即链的内容，已勾选的候选会显示为已勾选状态。
- 通过拖动候选前的图标或
↑/↓按钮调整候选顺序。拖动只影响本链，顺序在拖放结束时写入。 - 根据需要调整触发条件（限流、服务端错误、超时与网络错误），取消勾选的类别不会触发改派。
- 设置「尝试深度」，一次失败最多尝试几个候选。用尽后不再重试，直接向用户报告主模型的原始失败原因。
管理回退链¶
在「回退链（N）」清单中：
- 编辑：展开该链的可用模型清单与候选编辑面板。
- 启用/停用：取消勾选后该链不参与改派，但配置保留；勾回即恢复。
- 重命名：双击链名进入编辑，按回车保存或 Esc 取消。
- 删除：第一次点击变「确认删除」，再次点击才真正删除。
链数据存储在 <DSH_HOME>/model-fallback/chains.json。界面不保存副本，每次读取回到同一份文件。
适用场景与注意¶
- 适合需要用多个渠道跑长任务、经常遇到限流或临时故障的场景。
- 插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。
- 桌面端安装必须使用真实目录，避免符号链接或 junction，否则会触发 profile 升级要求。
- 没有配置任何链时，插件不会介入请求，行为与安装前一致。
结语¶
dsh-model-fallback 通过可视化编排和明确的触发条件，让在 DSH 中配置跨模型回退链变得简单可控。它不改变 DSH 的核心架构，而是通过两条 hook 实现失败时的智能改派，适合需要在多个渠道间平滑切换的开发者。
- 目录页：https://www.skillhub.cn/plugins/yn2aa/dsh-model-fallback
- GitHub：https://github.com/yn2aa/dsh-model-fallback
