Skip to main content

dsh-llm-fallbacks

13Stars2Forks0Issues0Watchers

Provides automatic LLM model fallback chain for DSH agents: automatically switches to the next backup model when requests trigger authentication, quota, or rate limit errors, ensuring uninterrupted task execution.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
MIT
Branch
main
deepseek-harnessdeepseek-harness-plugindshdsh-pluginfallbackssubagents

Install

cmdweb profile
$ dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin btspoony/dsh-llm-fallbacks for me: review the repository at https://github.com/btspoony/dsh-llm-fallbacks first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-line Summary

Adds automatic fallback chains for LLM requests in DSH (DeepSeek Harness) agents: when authentication fails, quota runs out, or rate limiting (429) occurs, the plugin automatically switches to the next available provider/model along a pre-configured sequence, allowing the current step to continue without interruption.

Core Capabilities

  • When requests from main or sub-agents fail, automatically falls back to the next provider/model in the chain, keeping the task uninterrupted
  • The new "FallbacksChain / Auto" virtual entry in the model selector allows using the entire chain as the primary choice, rather than only intervening on failure
  • Provides 7 built-in sub-agent roles (task / sonic / scout / designer / librarian / reviewer / security-reviewer) that can be directly referenced by rules
  • Supports switching effective root chains by time period (peak/valley windows): 4固化 UTC+8 presets + custom windows, the first matching row's chain replaces the all-day chain
  • During dispatch, intelligently locks sub-agent roles through three-stage parsing (explicit → rule → LLM auto-match), and injects the first specific model from that role chain into the initial request
  • Two safety valves: max switch count per step and always-mode retry cap, preventing chain loops from amplifying latency

Technical Implementation

  • Language: TypeScript (host-side + client-side React components), outputting ESM
  • Key Dependencies: @deepseek-ai/cordis ^4.0.1 (host service injection), @deepseek-ai/dsh-settings (settings namespace registration), @deepseek-ai/dsh-typert-protocol + dsh-typert-registry (self-built /api/fallbacks/* gateway channel), @deepseek-ai/schemastery ^3.18.1 (settings schema)
  • Architecture Pattern: mount-only cordis plugin——bundle/cordis.patch.yml only inserts one line id: llm-fallbacks, the host side intercepts requests through two cordis hooks agent/request-error and agent/request, the client side registers a settings card through settings.plugin.item slot + registers a virtual provider through llm.registerAdapter; the built-in typert gateway (/api/fallbacks/get|set|reset|revert-seed) is the only write path, does not modify dsh source code
  • Entry Files: src/index.ts (host-side apply()), src/client/index.ts (client-side apply()), respectively loaded by bundle patch and dsh.client.inject list

Applicable Scenarios

When DSH users use multiple models like DeepSeek / Anthropic / OpenAI, a single provider experiencing 429, quota exhaustion, or authentication failure can stall the entire task. After installing this plugin, configuring a chain like "preferred Anthropic, fallback DeepSeek V4 Flash, final fallback DeepSeek V4 Pro" ensures single-point failures no longer block tasks. Multi-model users, users with self-built/third-party multi-provider configurations, and users who want to switch different model pools for peak/valley periods are the best fit.

Prerequisites and Compatibility

DependencyMinimum VersionDescription
DSH^0.1.1-rc.1All @deepseek-ai/dsh-* peer dependencies are ^0.1.1-rc.1; dsh-tui settings panel requires ≥ v0.8.5 (README.md:145)
Node.js>=22package.json:56-58 declares engines.node: ">=22"; build uses pnpm ≥ 10 / project stack pnpm 11.21+
PlatformCross-platformpackage.json doesn't declare os / cpu, no native module dependencies
Native ModulesNoneNo native bindings like node-pty, node:sqlite introduced

Installation

dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks

Configuration Options

All plugin configurations fall under the dsh settings document's fallbacks: namespace and can be edited in Settings → Plugins → Fallbacks card, $DSH_HOME/settings.yaml file, or dsh-tui's /settings area. Description column is in plain language, full field constraints see docs/configuration.md.

ConfigTypeDescriptionDefault
enabledbooleanMaster switch; when closed the plugin is completely no-opfalse
triggerCodesstring arrayFailure codes that trigger fallback decision (5xx is retried first by llm-retry)['AUTH', 'QUOTA', 'RATE_LIMIT']
rootChainstring arrayAll-day fallback chain: preceding items are fallback chain, the last item must be an official V4 model (Flash or Pro) as final fallback[]
cooldownMsnumberHow many milliseconds a switched-out/failed model won't be selected again300000 (5 minutes)
revertPolicyenumWhether to automatically return to main model after cooldown expirescooldown-expiry
maxSwitchesPerStepnumberMax switches per step; exceeding stops switching8
alwaysModeRetryCapnumberSwitch after how many always mode retries; 0 disables5
presetsenumWhether to auto-declare 7 built-in sub-agent roles on applybundled
roleAutoMatchbooleanWhether to allow LLM auto-matching roles on sub-agent's first requesttrue
timeSlotsarrayTime slot rows (4固化 presets + custom windows); first matching row's chain replaces all-day chain[]
tzstringTimezone for time slot matching (standard Intl rules, DST-safe)Asia/Shanghai
roles.listarrayCustom sub-agent role list, each must have at least one chain entry[]
roles.rulesarrayRules mapping sub-agents to roles (match by provider/model pattern)[]

FAQ

Q: Will this plugin immediately change my model behavior after installation?

A: No. enabled defaults to false, and the config is no-op with no chains configured, just like not having it installed. You need to open the switch in the Fallbacks card and fill in rootChain, then restart the session for it to take effect.

Q: Will 5xx temporary errors be managed by the fallback chain?

A: 5xx is first retried with backoff by the host's llm-retry plugin; only after its budget is exhausted does this plugin's decision path run; no need to add 5xx to triggerCodes (docs/configuration.md:25).

Q: How should I set it up if I want the primary choice to directly use the "head" of the fallback chain?

A: Just select the FallbacksChain / Auto virtual entry in the web or dsh-tui model selector—it will use the first specific model of the current day's effective chain as the primary; selecting any real model preserves fallback-only behavior.

Q: After upgrading to 0.2.2+, historical sessions won't open. What should I do?

A: Versions before 0.2.2 wrote fallbacks/switch durable events to sessions, which new dsh refuses to load. First stop dsh, clone this repo, then run pnpm repair:fallbacks-switch-logs -- --apply --backup. The script will mark old events as ignorable to restore session loading.

Q: If I edit settings.yaml directly, will it take effect in real-time?

A: YAML is the shared source of truth; web card and TUI both read from here. You need to restart the current dsh session for config changes to be picked up by the plugin (README.md:70-74).

Q: What if there's no settings panel in my terminal profile?

A: Requires dsh-tui ≥ v0.8.5. Older dsh-tui versions won't see the Fallbacks editing area in /settings, only file editing; functionality still runs, just no GUI.

Q: Any extra operations needed when uninstalling?

A: Just run dsh plugin --profile web remove dsh-llm-fallbacks and restart the session. This plugin has no postinstall hooks and didn't modify dsh source code.

Learning Curve

Beginner — The plugin is completely no-op under default configuration; at minimum, just open enabled in the settings card and fill in one line of rootChain to get the fallback engine running. Complex time slot switching and role rules can be added as needed.

Known Issues and Limitations

  • Does not automatically rewrite old (two-era) chains / roles.default config; only prints warning at startup and shows migration banner at panel top, requires manual migration per docs/configuration.md migration table (src/index.ts:436-439, README.md:133).
  • Versions before 0.2.2 wrote durable fallbacks/switch session events, issue #52 (event type registration fails under different module instances on apply()) confirmed; from 0.2.2+ the plugin stops writing new events, but old sessions need the scripts/repair-fallbacks-switch-logs.ts script in the repo to mark as ignorable to reload (src/index.ts:672-678, README.md:46-58).
  • Time slot presets (liang-peak / liang-valley / glm-peak / glm-valley) windows are固化 UTC+8 code constants, preset rows in config cannot carry start/end/days/name fields; rejected by gateway on save, warned and skipped on load if present (src/time-slots.ts:106-152, src/config.ts:236-241).
  • When rootChain doesn't end with an official V4 model (Flash or Pro), there's a warning at startup; time slot rows are invalid at this time, and FallbacksChain / Auto in model selector also refuses to override (src/config.ts:236-241, src/virtual-adapter.ts:287-298).
  • agent/request-error hook must be ordered after host llm-retry; the plugin's bundle line is auto-appended to stack end via dsh plugin add, satisfying order; when manually modifying dsh.profile.bundles need to ensure @deepseek-ai/dsh-base is before this plugin (docs/install.md:31-37).

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/btspoony/dsh-llm-fallbacks)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory