前言¶
在 DeepSeek Harness（DSH）里，当模型返回超时、传输失败或空响应时，整轮对话会直接红字报错。要避免这种情况，常见做法是手动切换模型、重试，或者依赖其它插件做全局重试。这些方案要么不够精细，要么会打断当前步骤。dsh-model-fallback 插件通过在模型无响应时自动切换到备用模型、并在同一步重试，把错误控制在当前轮次，不让用户看到报错。
是什么¶
dsh-model-fallback 是一个 DSH 插件，维护者为 ukakbdh091。它的核心功能是：当主模型在请求时发生“无响应”类错误（如 TIMEOUT、TRANSPORT、SERVER、EMPTY_RESPONSE）时，自动在同一轮对话里切换到备用模型并重试；只有所有备用模型都失败，才把原错误交回上层。插件通过挂载在 agent/request-error、agent/request、agent/pre-step 等扩展点上工作，不改动内核、不包装 adapter、不改变 session 日志格式。
核心能力¶
只在无响应时切换¶
默认只认“无响应”类错误：TIMEOUT、TRANSPORT、SERVER、EMPTY_RESPONSE。如果模型返回了错误但不是无响应（例如额度不足、鉴权失败、参数错误），插件不会切换。如需扩大触发范围，可在配置里调整 codes（见下文）。
在同一步内重试¶
插件在同一步内尝试备用模型，用户只看到回答，看不到报错。它不会打断当前轮次，也不会把错误信息透出给用户。
严格按列表顺序¶
备用模型列表按顺序尝试：设置页里的第一行先试，不行再第二行，同一 step 内每个备用模型只试一次；走到链尾才把原错误交回上层。
会话内生效¶
切换结果写入会话（model/selection），UI 的模型选择器会随之变化，重开会话也记得。它不会修改全局默认模型。
用户取消不算报错¶
当请求被用户中止（signal 已中止）或失败码为 ABORTED/CANCELLED 时，插件不做任何切换。
三处可配，改完即生效¶
配置支持设置页、~/.dsh/model-fallback.json、profile 的 cordis.patch.yml 三处。修改后无需重启 Harness 或 DSH 即可生效。
安装与启用¶
需要 DSH 的 desktop profile（或任意带 settings 服务的 profile）。
一键安装¶
在 DSH 插件市场/插件管理里输入包名：
dsh-model-fallback
或在终端执行：
dsh plugin --profile desktop add dsh-model-fallback
安装完成后重启 Harness（或等待 HMR 热重载），进入 设置 → 模型兜底 选择备用模型即可。
把
desktop换成你实际使用的 profile 名，例如web。
从源码安装¶
git clone https://github.com/ukakbdh091/dsh-model-fallback.git
dsh plugin --profile desktop add ./dsh-model-fallback
验证安装成功¶
dsh --profile desktop --dump-config | grep model-fallback
看到 id: model-fallback 即表示插件已挂载。
配置方式¶
A. 设置页（推荐）¶
进入 设置 → 模型兜底，一行一个下拉框，选项按 provider 分组，直接列出当前部署中可选的所有模型（与输入框上的模型选择器使用同一份数据）。至少可以放两个，不设上限。
B. ~/.dsh/model-fallback.json¶
文件不存在、格式损坏或 fallbacks 为空数组时，插件会退回插件配置里的链，不会报错。
{
"fallbacks": [
{ "provider": "workbuddy-ai", "model": "deepseek-v4.1-flash" },
{ "provider": "slate", "model": "glm-5.3-flash" }
],
"codes": ["TIMEOUT", "TRANSPORT", "SERVER", "EMPTY_RESPONSE"]
}
fallbacks：按顺序尝试。当前模型不在链里时从第一个开始；在链里时取它的下一个。codes：省略时只认无响应；["*"]表示任何失败都切换；也可自定义，例如只认额度：["QUOTA", "ACCOUNT_QUOTA"]。
C. profile 的 cordis.patch.yml¶
优先级：model-fallback.json 里的非空 fallbacks > 设置页 / YAML 配置。
- id: model-fallback
config:
fallbacks:
- provider: workbuddy-ai
model: deepseek-v4.1-flash
codes: ["*"]
两条路都可以用，但建议只填一处，避免冲突。
判定与切换逻辑¶
插件监听每一步的模型请求失败，按 codes 判断是否应该切换。默认只认“无响应”，用户取消不触发。同一 step 内按列表顺序从上到下挑下一个未试过的模型；通过 ctx.llm.resolveCallConfig 校验该模型在当前部署中是否存在，不存在则跳过。切换结果写入会话，让 loop 在同一步重试；备用模型也失败则继续沿链往下走；链尾都没有时把原错误交回上层。
一次普通的限流不会立刻切换模型：瞬态错误会先由 llm-retry 插件退避重试（默认对 RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT、EMPTY_RESPONSE 重试 5 次），只有它放弃之后，失败才会落到本插件手里。
一个容易踩的点¶
DSH 的模型选择是在 pre-step 的 system-prompt 组装时快照的，而失败发生在 step 进行中。只改 selection 的话，同一步的重试仍会用旧模型。因此插件在 agent/request 上做了一次一次性覆盖，等进入下一步就撤掉——这就是 agent/pre-step 那条监听的全部作用。
适用场景与注意事项¶
适合在需要避免整轮对话红字报错、希望在同一轮内尝试备用模型的场景使用。插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。已知限制包括：只在 desktop profile 上实测过，其它带 settings 服务的 profile 应也能用；设置页依赖 DSH 的 settings 服务，若字段改为非 volatile 保存会报错；不会自动切回主模型；备用模型必须能用 resolveCallConfig 解析出来，否则会被跳过。
生态背景¶
DSH 的理念是“一切皆插件”，社区目录（如 SkillHub）与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-model-fallback 通过在模型无响应时自动切换到备用模型并在同一步重试，避免整轮对话红字报错，同时保持会话内生效与用户无感知。如需了解安装与使用细节，可参考目录页与 GitHub 仓库。
