dsh-model-router

English | 中文

Tiered model routing for DeepSeek Harness (DSH) — use the cheapest model that can do the job, automatically.

A monorepo containing the DSH plugin and its admin UI.

📦 Packages

Package	Description
dsh-model-router	DSH plugin — routing protocol, delegate tool, escalation ladder, guardrails
dsh-model-router-admin	Admin web UI — configuration dashboard and activity monitoring

🚀 Quick Start

Prerequisites

• Node.js ≥ 20
• DeepSeek Harness ^0.1.1-rc.2

Install & Build

# Clone the repo
git clone https://github.com/zhuzhujunandy/dsh-model-router.git
cd dsh-model-router

# Install dependencies
npm install

# Build all packages
npm run build

Add to DSH

# Add the plugin to your DSH profile
dsh plugin --profile web add /path/to/dsh-model-router/dsh-model-router

Then add the plugin row to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: model-router
      name: 'dsh-model-router'

Restart DSH (dsh web), then run /tiers in the Web GUI to verify.

✨ Features

• Routing protocol injection — a compact protocol section injected into the orchestrator's system prompt with tier table, task taxonomy, and routing rules.
• delegate tool — one model-facing tool that routes work to the right tier automatically.
• Escalation ladder — failed attempts retry at the next tier automatically.
• Cross-provider fallback chains — every tier can declare alternate provider/model routes tried in order when the primary provider is unregistered or an attempt fails.
• Forced verification (DoD pipeline, hard blocking) — blocking enforcement runs a Definition-of-Done checklist and a grader PASS gate; FAIL re-grades, then hard-blocks and escalates.
• Plan annotations — every delegation result carries an annotated execution plan (tier/provider/model/cost per step and verification outcome).
• Background / continuable delegation — run_in_background: true returns a jobs jobId (one-shot) or a durable subagentId (continuable, continued via send_message).
• Transparent per-step model switching — the model-router adapter classifies requests by task type, forwards to the right tier model, and falls back across providers transparently.
• Reasoning-effort safe routing — a request's reasoning effort is only forwarded to a route whose model actually advertises it; unsupported levels are dropped so the provider's own default applies instead of failing with UNSUPPORTED_REASONING_EFFORT.
• Budget modes — normal / budget / quality / deep routing profiles; single pins every request and delegation to one fixed model (no routing).
• Guardrails — per-tier read-only tool-call caps and retry limits.
• Web settings card — manage router config directly in the DSH Web settings panel.
• Admin UI — React-based dashboard for configuration and monitoring.
• Token usage dashboard — durable per-request usage with per-tier/model/day statistics, live refresh, and one-click reset.

📖 Documentation

• Plugin README — detailed setup, configuration, and usage
• 中文文档
• User Guide (EN) — installation, settings card, commands, workflows, troubleshooting
• 用户使用说明
• Single-Model Mode — design of the one-fixed-model mode

🏗️ Project Structure

dsh-model-router/
├── dsh-model-router/          # DSH plugin (TypeScript)
│   ├── src/                   # TypeScript source
│   ├── lib/                   # Compiled output
│   ├── package.json
│   └── README.md
├── dsh-model-router-admin/    # Admin UI (React + Vite)
│   ├── src/                   # React components
│   ├── dist/                  # Built assets
│   └── package.json
├── package.json               # Workspace root
├── LICENSE
└── README.md

🛠️ Development

# Build the plugin
npm run build:plugin

# Build and serve admin UI
npm run build:admin
npm run dev:admin

# Run tests
npm run test

📋 Configuration

See the plugin README for full configuration reference.

- id: model-router
  name: 'dsh-model-router'
  config:
    tiers:
      fast:   { provider: ark-code, model: deepseek-v4-flash-ga-260731, costRatio: 1,  maxTokens: 8192  }
      medium: { provider: ark-code, model: glm-5.3,                     costRatio: 5,  maxTokens: 16384 }
      heavy:  { provider: ark-code, model: deepseek-v4-pro-ga-260813,  costRatio: 20, maxTokens: 32768 }
    defaultTier: medium
    modes:
      normal:  { defaultTier: medium }
      budget:  { defaultTier: fast    }
      quality: { defaultTier: medium }
      deep:    { defaultTier: heavy   }
      single:  { defaultTier: medium, single: { provider: ark-code, model: deepseek-v4-pro-ga-260813, maxTokens: 32768 } }

📜 License

GPL-3.0

---

Built for DeepSeek Harness