The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” In real-world development, the same logical model ID (such as deepseek-v4-flash) often needs to be invoked across multiple providers or different Route Groups. Manually switching configurations is tedious and error-prone. The welsione/dsh-model-router plugin aggregates candidate models from multiple providers into a single logical entry point through unified ModelID routing, enabling Route Group-based three-tier classification, failover before the first token, and health-based selection.
Plugin Overview¶
welsione/dsh-model-router is a unified model routing plugin for DeepSeek Harness (DSH). It maps a single logical ModelID to a multi-provider candidate chain, supports tier1/2/3 classification by Route Group, and automatically switches over when a candidate fails before the first token. The plugin includes a built-in management panel for configuring reasoning levels, cooldown policies, and model capabilities, and it automatically persists settings.
Core Capabilities¶
The plugin mainly includes the following features:
* Multi-Route-Group routing: Supports multiple Route Groups coexisting, with each Route Group independently managing a three-tier candidate chain and custom tier names.
* Automatic failover: Automatically switches when the primary candidate fails before the first token (rate limiting/authentication/network/empty response, etc.); supports tiered cooldown (short for rate limiting, medium for server-side, long for authentication) and exponential backoff (capped at 30 minutes).
* Health-based selection: Rescores and reorders candidates using sliding-window time decay and error-code weighting; stable successful candidates are preferred, while frequently failing candidates are deferred.
* Three-tier classification and manual tier selection: tier1 lightweight, tier2 standard, tier3 powerful; the chat window supports session-level manual tier selection.
* Reasoning level: Each candidate can have a reasoningEffort configured, with a pre-check of host-supported levels on save.
* Model capability write-back: The management panel can edit custom provider model capabilities (contextWindow/maxTokens) and write them back to the host llm-pi-ai, with hot reload support.
* Management panel: The DSH settings page includes a built-in “Model Routing” card that displays routing statistics, cooldown status, and capability information in real time.
* UI language: Supports zh/en bilingual interfaces, switched via the model-router namespace registry.
* Session safety: Supports automatic sanitization of replayState across providers.
Installation and Enablement¶
The plugin is published to npm and can be installed via the DSH plugin command:
dsh plugin --profile web add @welsione/dsh-model-router
To uninstall it:
dsh plugin --profile web remove @welsione/dsh-model-router
After installation, a “Model Routing” card will appear on the DSH settings page, and the model selector in the chat window will become a “Route Group” selector.
Configuration and Usage¶
Open Settings → Model Routing, add a unified ModelID (for example, deepseek-v4-flash), and configure candidate models for tier1/2/3. Changes to the plugin are automatically saved and take effect immediately.
Permissions and Data¶
The plugin’s runtime state is in-memory, and manual tier selections are persisted to the host settings. It does not make outbound requests, does not read or write workspace files, does not report telemetry, and does not access API keys.
Compatibility¶
This plugin only supports DSH versions 0.1.0-rc.x through 0.1.5-rc.x, and requires a Node.js ≥ 22 runtime environment.
Conclusion¶
By unifying logical IDs and providing an automatic failover mechanism, this plugin reduces the complexity of managing models across multiple providers. See the GitHub repository for the complete configuration table and examples.