dsh-quota-router
A policy-only multi-source model router for DeepSeek Harness.
v1.0.0 makes the routing contract explicit: choose the right DSH-native model source for each task, recover from infrastructure failures in a bounded and explainable way, and measure route usage without claiming unproven token savings.
npm install @liyuk/dsh-quota-router
📖 项目详解（能力 / 边界 / 收益）→ docs/PROJECT.md · 工程设计与算法文章 → docs/blog-quota-router-engineering.md
It routes a user message to a named task profile, then selects the first healthy, auto-eligible source on that profile's candidate chain. The chain is built from a global source priority list (sources) combined with a per-task model mapping (profiles[].modelBySource) — two orthogonal dimensions. This is designed for a "cost-source 薅羊毛" workflow across mixed free / subscription / unlimited / low-price / manual emergency model sources.
Why it exists
A normal keyword → target + fallback Router cannot reliably express:
coding: opencode-go/mimo-v2.5 → token-share/gpt-5.6-luna
hard coding: opencode-go/mimo-v2.5 → token-share/gpt-5.6-terra
Both rules have the same primary route, so a fallback inferred only from the current session header loses the original task identity. quota-router retains profile + candidate identity per turn and moves along that exact chain.
Safety model
- Only DSH-native registered providers/models are used; no adapters or credentials are owned here.
- Global
sources.priority is the only source-order authority; sourceTier is explanatory metadata, never a hidden reorder rule.
manual and emergency candidates are never selected automatically; paid candidates require the explicit allowPaidFallback: true opt-in.- Stable quota/auth failures advance immediately; transient failures respect normal retries until a configurable threshold opens a cooldown.
- Context compaction is configured and triggered independently by DSH; this plugin never rewrites session history.
- If all candidates are exhausted, the original failure path remains intact.
See docs/configuration.md for every editable policy field, docs/strategy.md for multi-source/task-decomposition recommendations, docs/task-aware-routing-plan.md for the task-aware API, and examples/quota-router.example.yaml for a safe starting configuration. The task-aware layer narrows quota-router to model selection for already-split subtasks; it does not add a Planner, tool lazy-loading, context compaction, or cross-Harness orchestration. REQUIREMENTS.md is the implementation and state-machine reference.
Settings page
With the package enabled in a DSH Web profile, Settings → Quota Router opens the dedicated configuration page. It edits the live quota-router settings namespace and provides:
- global retry, cooldown, and ledger controls;
- global source priority editing;
- profile keyword and
modelBySource editing;
- an expanded source-chain/fallback preview.
The page previews configuration only. Native provider/model availability, active cooldowns, route decisions, and usage stay host-side; inspect runtime observability through the read-only quota_router_status tool.
Development
pnpm install
pnpm test
pnpm run check
pnpm run build
Published on npm as @liyuk/dsh-quota-router; source lives at Liyuk/dsh-quota-router. See docs/RELEASE-1.0.0.md for the community-facing update.
