dsh-model-fallback

Smart Model Fallback (@carl2003/dsh-model-fallback)

English | 中文

Primary and multi-level backup model failover router plugin for DeepSeek Harness (DSH), featuring cross-provider reasoning effort clamping, structured error classification, exponential backoff cooldown, per-turn recovery, pre-commit stream protection, and an interactive Settings panel with one-click Save & Apply.

Features

• Primary + Ordered Fallback Chain: Configure provider, model ID, 8-tier reasoning effort, maxTokens, and temperature for both the primary model and an ordered list of backup models (DSH registered providers or custom OpenAI-compatible endpoints).
• Cross-Provider Reasoning Effort Clamping (src/effort.js): Automatically maps requested efforts across provider dialects (e.g., off / minimal / low / light / medium / balanced / high / xhigh / deep / max / ultra) to the nearest compatible tier supported by the backup model, or safely omits reasoningEffort when a target model does not declare reasoning support.
• Error Classifier & Failover Policy (src/classifier.js): Distinguishes 8 failure categories (rate_limit, billing, server_error, auth_error, not_found, timeout, empty_response, region_blocked), respects fast rate-limit reset thresholds (minSwitchResetSeconds), and never fails over on user abort (ABORTED).
• Exponential Cooldown & Recovery Scopes (src/cooldown.js): Places failing routes into exponential cooldown (min(initialCooldownSec * 2^(streak - 1), maxCooldownSec)) and supports turn (per-turn restore), cooldown (cooldown expiry restore), and session (sticky session fallback) recovery modes.
• Pre-Commit Stream Protection (src/router.js): Buffers pre-commit reasoning-delta and usage chunks during llm/stream; if the primary model fails before emitting visible text-delta or tool-call-delta, it discards the uncommitted chunks and transparently switches to the next backup route.
• One-Click Save & Apply (Save & Apply): Persists settings to $DSH_HOME/model-fallback/config.json, updates agentDefaultModel, synchronizes active sessions, and broadcasts live SSE status & toast notifications via /api/model-fallback.

Installation

Option 1: Install from npm (Recommended)

dsh plugin --profile web add @carl2003/dsh-model-fallback

Option 2: Install from GitHub Release Tarball (No build script approval)

dsh plugin --profile web add https://github.com/CarlCN2003/dsh-model-fallback/releases/download/v1.0.0/dsh-model-fallback-1.0.0.tgz

Option 3: Install from GitHub Source

dsh plugin --profile web add github:CarlCN2003/dsh-model-fallback

Option 4: DSH Desktop / DSH Market

Open Plugins → Plugin Market (or Settings → Plugin Market on older hosts), search for @carl2003/dsh-model-fallback or CarlCN2003/dsh-model-fallback, and click Install.

Configuration

Open Settings → Model Fallback (主备模型路由) in DSH:

1. Select your Primary Model provider, model ID, and reasoning effort.
2. Add or reorder Fallback Nodes (registered DSH providers or custom OpenAI-compatible endpoints) and choose their effort strategy (Auto-Clamp from Primary, Explicit Effort Override for Backup, or Disable Thinking on Backup).
3. Customize Triggers, Recovery Scope, and Cooldown Policy, or run 🔍 Test Routes / 📊 Telemetry & Failover Drill.
4. Click ⚡ Save & Apply to DSH.

Verification

node ./tests/run-tests.mjs

License

MIT