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/PROJECT.md) · [工程设计与算法文章 → docs/blog-quota-router-engineering.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](./docs/configuration.md) for every editable policy field, [docs/strategy.md](./docs/strategy.md) for multi-source/task-decomposition recommendations, [docs/task-aware-routing-plan.md](./docs/task-aware-routing-plan.md) for the task-aware API, and [examples/quota-router.example.yaml](./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](./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](./docs/RELEASE-1.0.0.md) for the community-facing update.