前言¶

在 DeepSeek Harness（DSH）里跑智能体时，模型请求可能因为限流、服务异常、超时或配额耗尽而失败。DSH 自带的 @deepseek-ai/dsh-llm-retry 会在一定次数内对同一模型重试；重试用尽后，这一轮往往以错误结束，后续步骤无法继续。若你手上有多个已配置好的 provider 与模型，更自然的期望是：当前模型扛不住时，按预定顺序换下一个模型接着做同一件事，而不是立刻停转。

下面介绍社区插件 dsh-fallback-models（维护者 soffits，分类：模型推理）。它在 DSH 重试耗尽之后介入，按你配置的列表尝试备用模型，并在会话里给出可读的切换说明。

这是什么¶

dsh-fallback-models 是 DSH 的一个插件（当前 package 版本 0.1.1，许可证 MIT），为 Harness 增加一条有序的 fallback 模型链。当某次模型请求在 DSH 自身重试仍失败后，插件在条件允许时切换到链中的下一个模型继续该轮工作，而不是直接以原始错误结束。

要点如下：

• 全局可配一条 chain；也可在 presets 里为不同 agent preset 覆盖或关闭备用链。
• 在 @deepseek-ai/dsh-llm-retry 用尽次数、且该失败类型允许切换时才会换模型；对单次失败，每个候选模型最多尝试一次，避免循环。
• 默认 scope: turn：用完备用的那一轮结束后，会话会回到本轮开始时的模型；也可设为 session 在会话结束前保持备用模型。
• chain 为空（默认）时行为与未安装插件一致。

核心功能¶

配置项¶

设置页从 DSH 模型目录选型（与 Composer 里模型选择器同源），可排序。同等配置也可写在 profile 的插件 patch 中，例如：

- id: fallback-models
  name: 'dsh-fallback-models'
  config:
    chain:
      - provider: deepseek
        model: deepseek-reasoner
      - provider: openrouter
        model: qwen/qwen3-coder
        reasoningEffort: high
    presets:
      reviewer:
        - provider: openrouter
          model: anthropic/claude-sonnet-4.5
      quick: []            # no fallback for this preset
    scope: turn            # or: session
    # codes: [...]         # optional, see below

修改后在下一次失败时生效，无需重启 DSH。

默认会触发切换的失败码¶

适配器会为失败打上与 provider 无关的 code。默认会切换的包括：

默认不因 AUTH、INVALID_REQUEST、CONTEXT_WINDOW_EXCEEDED 换模型（避免掩盖配置或上下文问题）；可在 codes 或设置页中显式开启。用户取消的请求（ABORTED 等）不会切换。

若在发请求之前就失败（模型 id 不存在、缺少 API Key 等），请求不会发出，轮次结束，不会走 fallback。

与 DSH 恢复链路的配合¶

插件挂在 agent/request-error 瀑布流上：先执行 next()，让 DSH 重试、上下文压缩、图片 offload 等既有恢复逻辑优先；只有没有获得重试时，才按链选下一个在 llm.resolveCallConfig 下可用的模型，通过 agent.model.select() 选定下一模型，以插件 cancel 结束失败轮次并排队一条简短通知，再开新轮继续。会话中可见类似 deepseek/deepseek-chat failed (RATE_LIMIT); switched to openrouter/qwen3 的提示行；发给模型的用户侧通知示例：

[model fallback: the request to deepseek/deepseek-chat failed (RATE_LIMIT: Too many requests). Continuing on openrouter/qwen/qwen3-coder: resume the interrupted work where it stopped.]

链耗尽时，仍以原始错误结束该轮。

安装与启用¶

环境要求：DSH 0.2.2-rc.1 及以上（0.2.x 系列），Node.js 22 及以上。

1. 将插件加入 profile（示例 profile 名为 web）：

dsh plugin --profile web add github:soffits/dsh-fallback-models

也可通过 DSH 的 Plugins 页面或插件管理器（install_bundle 使用 github:soffits/dsh-fallback-models 或本地 bundle 路径）安装。

2. 打开 Plugins > dsh-fallback-models，在 fallback-models 行点击 Configure，或在 profile 中写入上文 YAML。

3. 按需配置 chain、presets、scope 与可选的 codes。

典型用法¶

多 provider 容灾：主模型用 deepseek/deepseek-chat，链中追加 openrouter 上另一模型，限流或短期故障时自动切换。

按 preset 分流：审查类 preset 单独一条链指向更强模型；quick preset 设 quick: [] 关闭 fallback，避免轻量任务误切昂贵模型。

会话级保持备用：将 scope 设为 session，在长会话中持续使用已切换成功的模型，直到会话结束。

自定义失败码：需要在认证错误或非法请求时也换模型时，在 codes 中加入 AUTH、INVALID_REQUEST 等（需自行权衡是否会掩盖配置问题）。

适用场景与注意¶

适合：已在 DSH 中配置多个 provider；希望重试之后仍有自动 failover；愿意接受「一次切换占用一轮边界」（失败轮显示为 stopped，新轮接续）。

不适合或需知局限：

• 每次切换都会产生新的 turn；DSH 0.2.2 循环不允许在单个 agent/request 内改模型，这是当前公开 API 下的实现方式。
• Goal 自动回合中若因失败被停止，Goal 会被关闭，工作可继续但需稍后手动重启 Goal。
• provider retryPolicy 为 mode: always 时，下游恢复会先执行，可能在首次失败就切换；链用尽后 always 模式可能对最后一个模型无限重试（依配置）。
• 链状态在内存中；DSH 进程重启后，若当时正使用备用模型，行为以 README 说明为准（会话可能仍保持该备用模型，除非手动改选）。

安全与权限：插件与当前 DSH 进程同权运行，可影响模型选择与请求路由。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认链中模型与 API 凭证符合你的合规要求。

结尾¶

dsh-fallback-models 在 DSH「重试之后」补上一段有序的模型备用链，把限流、 outage、配额等可切换的失败转成「换模型继续」，并在对话里留下可审计的切换记录。社区插件目录与 DeepSeek / 幻方无官方从属关系；如需安装与讨论，可参考：

• 目录页：https://www.skillhub.cn/plugins/soffits/dsh-fallback-models
• 源码与文档：https://github.com/soffits/dsh-fallback-models