Visol-456/dsh-llm-fallback
50Last commit Aug 15, 2026
dsh-llm-fallback DSH plugin
This plugin provides a fallback chain for DeepSeek Harness. When the primary provider fails due to rate limits, server errors, or timeouts, the request is automatically retried on the next configured (provider, model) entry. It maintains a route table, tracks consecutive failures, and switches to a healthy fallback after a configurable threshold.
How to install the dsh-llm-fallback DSH plugin
dsh plugin --profile web add @visol-456/dsh-llm-fallbackCopying does not run this command. Review the repository and version before installing the dsh-llm-fallback DSH plugin.
dsh-llm-fallback DSH plugin data source
dsh-llm-fallback DSH plugin snapshot date: Aug 16, 2026
discovered
What the dsh-llm-fallback DSH plugin can do
- Define a prioritized list of fallback (provider, model) entries
- Customizable error codes that trigger switching (e.g., RATE_LIMIT, SERVER, TIMEOUT)
- Circuit breaker with configurable failure threshold and cooldown period
- Persistent session events for fallback switches and routing
- Web UI configuration panel in dsh web (Settings -> Fallback)
- Isolated state per provider/model; successful request resets failure count
Where the dsh-llm-fallback DSH plugin fits
- Handle rate limits or quota errors from a primary provider
- Mitigate server-side errors and 5xx fluctuations
- Overcome network timeouts and transport layer failures
- Keep long-running tasks alive when a single provider is unstable
- Gracefully degrade to cheaper or more reliable fallback models
Who the dsh-llm-fallback DSH plugin is for
- DSH users who experience frequent provider failures
- Students or developers relying on unstable free/cheap providers
- Operators of DSH web profiles needing robust LLM access
dsh-llm-fallback DSH plugin limitations
- Single global fallback list shared by all requests; failure attribution is per (provider, model)
- State is in-memory only; restart resets counters and cooling
- Only agent-loop requests are covered; direct `ctx.llm.stream()` calls are not
- Providers with retry strategy `always` will retry internally and fallback won't see their failures
dsh-llm-fallback DSH plugin: from the repository README
Quoted from the Visol-456/dsh-llm-fallback README, the upstream source of the dsh-llm-fallback DSH plugin. Copyright remains with the original authors.
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
Read the full READMERepository license: MIT
dsh-llm-fallback DSH plugin questions
How do I configure fallback providers in dsh-llm-fallback?
You can configure fallbacks in two ways: either via `cordis.yml` with the `fallbacks` field (list of provider/model pairs), or through the Web UI in dsh web (Settings -> Fallback). The Web UI writes to `<DSH_HOME>/settings.yaml` and takes effect on the next request. If you omit the `fallbacks` key entirely, the plugin stays dormant and passes all requests through.
Why does the plugin not switch to the fallback when my provider fails?
Check that the error code is included in your `switchCodes` list. By default, only `EMPTY_RESPONSE`, `RATE_LIMIT`, `SERVER`, `UNKNOWN_MODEL`, `TIMEOUT`, and `TRANSPORT` trigger a switch. If your provider returns a different error code, add it to `switchCodes`. Also ensure the fallback provider/model is correctly listed and that the plugin is loaded (check `dsh plugin list`).
Can I use dsh-llm-fallback together with the built-in retry plugin?
Yes, but be careful not to double-load retry. The web profile already includes `@deepseek-ai/dsh-llm-retry` by default. You only need to load `llm-fallback`; the waterfall order (retry then fallback) is correct. Duplicating retry will cause an extra layer of retries, which may lead to unwanted behavior.
How does the circuit breaker work?
When the head provider (the one you selected in the UI) fails consecutively with a switchable error code, the failure count increments. Once it reaches `failureThreshold` (default 1), the provider is considered open and the next request will skip to the first fallback. After `cooldownMs` (default 0 ms), the head provider is probed again with a single request. If that probe succeeds, the circuit resets; if it fails, the provider stays excluded.
Why does the plugin not persist state across restarts?
The plugin's state (current active entry, failure counts, cooling) is stored in memory only. When the Harness process restarts, all counters reset to zero and the chain starts fresh from the head provider. This is a deliberate design choice to avoid complex persistence. The session events (`llm/fallback`, `llm/fallback-route`) can be used for post-hoc auditing but not for restoring live state.