Visol-456/dsh-llm-fallback
50最近提交 2026年8月15日
dsh-llm-fallback DSH 插件
该插件为 DeepSeek Harness 提供 provider 回退链。当主 provider 因限流、服务端错误或超时而失败时，请求会自动按顺序在配置的备用 (provider, model) 上重试。它维护路由表，跟踪连续失败次数，并在达到阈值后切换到健康备用目标。
如何安装 dsh-llm-fallback DSH 插件
dsh plugin --profile web add @visol-456/dsh-llm-fallback复制不会执行命令。安装 dsh-llm-fallback DSH 插件前请核对仓库和版本。
dsh-llm-fallback DSH 插件数据来源
dsh-llm-fallback DSH 插件快照日期：2026年8月16日
discovered
dsh-llm-fallback DSH 插件能做什么
- 定义优先级排序的备用 (provider, model) 列表
- 可自定义触发切换的错误码（如 RATE_LIMIT、SERVER、TIMEOUT）
- 熔断器：可配置失败阈值和冷却时间
- 持久会话事件记录切换和路由情况
- 在 dsh web 的 Settings -> 回退链 页面提供 Web UI 配置
- 状态按 (provider, model) 隔离；成功响应会重置失败计数
dsh-llm-fallback DSH 插件适合哪些场景
- 应对主 provider 的限流或配额错误
- 缓解服务端错误和 5xx 抖动
- 处理网络超时和传输层故障
- 在单个 provider 不稳定时保持长程任务不中断
- 优雅降级到更便宜或更稳定的备用模型
dsh-llm-fallback DSH 插件适合谁
- 经常遇到 provider 故障的 DSH 用户
- 依赖不稳定免费/廉价 provider 的学生或开发者
- 需要稳定 LLM 访问的 DSH web profile 运维人员
dsh-llm-fallback DSH 插件的限制
- 单一全局备用列表，所有请求共享；失败按实际服务的 (provider, model) 归因
- 状态仅进程内，重启后计数和冷却清零
- 仅 agent-loop 请求参与，直接调用 `ctx.llm.stream()` 的消费者不受影响
- 重试策略为 `always` 的 provider 会内部重试，fallback 看不到其失败
dsh-llm-fallback DSH 插件的仓库 README 摘录
以下文字摘自 dsh-llm-fallback DSH 插件的上游仓库 Visol-456/dsh-llm-fallback 的 README，版权归原作者，仅作引用。
DeepSeek Harness 的 provider fallback chain 插件——当主 provider 失败时，同一请求会自动在下一个配置的 `(provider, model)` 条目上重试，限流、超时或临时不可用的 provider 不会直接终结一轮对话。 > DeepSeek Harness `dsh-plugin` 生态的社区插件，不属于官方仓库。 ## 开发原因 由于众所周知的原因，deepseek要涨价了，对于我一个学生直接用不起了，于是只能去投奔opencode-go。然而，opencode-go的海外链接非常不稳定，挂了代理都不行，在长程任务中经常出错暂停，单 provider 部署在服务不稳定时会直接失败： - 限流与配额错误 - 服务端错误、5xx 抖动 - 超时与传输层故障 本插件为每条链维护一份按优先级排序的 `(provider, model)` 路由表，跟踪连续可切换失败（熔断器），并自动把请求故障切换到下一个健康条目。后续请求会继续使用当前服务条目，直到冷却结束、对链头的一次探测成功为止。 ## 快速开始 ```bash npm i @visol-456/dsh-llm-fallback ``` 在 `cordis.yml` 中挂载插件： ```yaml - 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 ``` 请求本身永远是链头（你在 UI 里选的 provider/model，或部署默认值），永不被改写。`fallbacks` 列出请求失败后按顺序切换的备用目标。省略 `fallbacks` 键合法且插件保持休眠，所有请求原样放行；等你在 Web 界面的 Settings -> 回退链 页保存备用目标之后再生效。 ## 部署到 web profile（dsh web） ### A. `dsh plugin add`（推荐） 本包声明了 `dsh.bundle`，安装后会作为 profile 层自动激活（无需手写 patch 文件——随包附带的 `cordis.patch.yml` 会以无备用目标挂载插件，目标在 UI 里创建）： ```bash dsh plugin --profile web add @visol-456/dsh-llm-fallba
阅读完整 README仓库许可: MIT
dsh-llm-fallback DSH 插件常见问题
如何在 dsh-llm-fallback 中配置备用 provider？
有两种配置方式：一是在 `cordis.yml` 中通过 `fallbacks` 字段（一个 provider/model 对列表）配置；二是通过 dsh web 的 Web 界面（Settings -> 回退链）配置。Web 界面将值写入 `<DSH_HOME>/settings.yaml`，下一次请求时生效。如果省略 `fallbacks` 键，插件保持休眠状态，所有请求原样放行。
为什么我的 provider 失败后插件没有切换到备用目标？
请检查错误码是否在 `switchCodes` 列表中。默认只有 `EMPTY_RESPONSE`、`RATE_LIMIT`、`SERVER`、`UNKNOWN_MODEL`、`TIMEOUT` 和 `TRANSPORT` 会触发切换。如果 provider 返回的是其他错误码，请将其添加到 `switchCodes`。同时确保备用 provider/model 正确列出，并且插件已加载（可通过 `dsh plugin list` 检查）。
能否将 dsh-llm-fallback 与内置的重试插件一起使用？
可以，但注意不要重复加载重试插件。web profile 默认已经包含了 `@deepseek-ai/dsh-llm-retry`。你只需要加载 `llm-fallback` 即可；瀑布顺序（先重试后回退）是天然正确的。重复加载重试会导致额外一层重试，可能产生意外行为。
熔断器是如何工作的？
当链头（你在 UI 中选择的 provider）连续失败且失败码在 `switchCodes` 内时，失败计数递增。当达到 `failureThreshold`（默认1）时，该 provider 被认为熔断打开，下一个请求会直接跳到第一个 fallback。经过 `cooldownMs`（默认0毫秒）后，链头会通过一个请求被探测；如果探测成功，熔断重置；如果失败，provider 继续保持排除状态。
为什么重启后插件的状态没有保留？
插件状态（当前活动条目、失败计数、冷却标记）仅存储在内存中。当 Harness 进程重启时，所有计数器归零，链从头开始。这是有意为之的设计，避免复杂的持久化。会话事件（`llm/fallback`、`llm/fallback-route`）可用于事后审计，但无法恢复实时状态。