前言¶

在 DeepSeek Harness（DSH）里，agent-loop 请求通常绑定一个 provider/model。单 provider 部署在限流、超时或服务端异常时，会让当前请求直接失败。

@visol-456/dsh-llm-fallback 是一个 DSH 社区插件，用来在主 provider 失败时，让同一请求按配置的 (provider, model) 备用目标自动重试。下面介绍它的定位、安装方式、配置项和使用边界。

这是什么¶

• 包名：@visol-456/dsh-llm-fallback
• 类型：DeepSeek Harness dsh-plugin 生态社区插件，不属于官方仓库
• 许可证：MIT
• 仓库：https://github.com/Visol-456/dsh-llm-fallback
• 包名与 GitHub 仓库均指向 Visol-456

它解决的问题很直接：主 provider 失败时，不直接终结当前请求，而是沿着按优先级排序的备用目标列表继续尝试。

核心功能¶

1、主 provider 失败时，同一请求自动在下一个配置的 (provider, model) 条目上重试。

2、维护按优先级排序的 fallbacks 备用目标列表。

3、跟踪连续可切换失败并打开熔断，故障切换到下一个健康条目。

4、按 switchCodes 允许触发切换的失败码进行切换。

5、支持 Web UI Settings -> 回退链 页面编辑备用目标。

6、保存的配置写入 <DSH_HOME>/settings.yaml，并在下一次请求生效，无需重启。

7、记录 llm/fallback 与 llm/fallback-route 持久会话事件。

8、省略 fallbacks 时插件保持休眠，所有请求原样放行。

安装与启用¶

插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

下面以 dsh web 的 web profile 为例。

使用 dsh plugin add¶

运行：

dsh plugin --profile web add @visol-456/dsh-llm-fallback

该命令将插件安装到 web profile。

使用 npm¶

按部署方式也可能使用包管理器安装：

npm i @visol-456/dsh-llm-fallback

安装后仍需要在 DSH 配置中挂载插件。

在 cordis.yml 中挂载¶

创建或编辑 cordis.yml，挂载插件并配置备用目标：

- name: '@visol-456/dsh-llm-fallback'
  config:
    fallbacks:
      - provider: pi-ai
        model: glm-4.5
    switchCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, UNKNOWN_MODEL, TIMEOUT, TRANSPORT]
    failureThreshold: 1
    cooldownMs: 30000

这里 fallbacks 是备用目标列表，switchCodes 是允许触发切换的失败码，failureThreshold 与 cooldownMs 控制熔断和冷却。

如果省略 fallbacks，插件保持休眠，所有请求原样放行；之后可在 Web UI Settings -> 回退链 页面创建备用目标。

手动 patch 与诊断¶

手动 patch¶

如果不用 dsh plugin add，可创建 patch 覆盖层：

# cordis.yml
- insert:
    - id: llm-fallback
      name: '@visol-456/dsh-llm-fallback'

然后运行：

dsh web --patch ./cordis.yml

这个 patch 条目需要包含 insert 和 id，再应用到 dsh web。

诊断组合配置¶

如果 patch 后行为不符合预期，用组合配置树检查：

node --import tsx/esm apps/cli/src/bin.ts web --dump-config --patch <file>

该命令用于查看 patch 合并后的配置，便于确认插件挂载项是否生效。

Web UI 配置¶

插件加载到 web profile 后，可在 Settings -> 回退链 页面编辑备用目标。

可用配置项包括：

• fallbacks：按优先级排列的 (provider, model) 备用目标
• switchCodes：允许触发切换的失败码
• failureThreshold：连续可切换失败阈值
• cooldownMs：切换后链头冷却时间

保存后，配置写入：

<DSH_HOME>/settings.yaml

并在下一次请求生效，无需重启。

浏览器通过插件提供的仅回环端点 /llm-fallback/config 读写该配置段。该端点拒绝非回环来源与跨站请求；它是防误写/防跨站围栏，不是鉴权层。

工作边界¶

下面是已核实的使用边界：

1、仅 agent-loop 请求参与。直接调用 ctx.llm.stream() 的消费者仍是单 provider。

2、fallbacks 是单一全局备用列表，所有请求共享一个 fallbacks 列表。

3、状态仅进程内。重启后活动条目、冷却与连续计数归零。

4、retry 策略为 always 的 provider 会自己重试，fallback 看不到其失败。

5、web profile base bundle 已自带 @deepseek-ai/dsh-llm-retry，重复挂载会叠加重试。

6、非空配置非法时，插件加载或保存会直接报错。

7、发布不足 24 小时的包可能被 pnpm minimumReleaseAge 拦截。

8、旧 chains / match / providers 配置在 0.1.x 中弃用。

适用场景¶

这个插件适合：

• 希望给 dsh web / agent-loop 请求增加备用 provider/model 的部署
• 主 provider 出现限流、超时或服务端错误时，希望同一请求继续尝试下一个备用目标
• 需要事后通过 llm/fallback 和 llm/fallback-route 事件审计切换路径

它不适合：

• 期望直接调用 ctx.llm.stream() 的消费者也自动 fallback
• 期望按多个 agent 或请求维度维护多套独立备用列表
• 期望 fallback 状态跨进程或重启持久化

结尾¶

@visol-456/dsh-llm-fallback 的价值是把单 provider 请求链路扩展为按优先级重试的 fallback chain，适合 DSH 社区插件环境下的备用路由需求。

GitHub 仓库：https://github.com/Visol-456/dsh-llm-fallback。目录页地址本次材料未提供，可按包名 @visol-456/dsh-llm-fallback 在社区目录检索。