@liyuk/dsh-quota-router

Readme

# dsh-quota-router

[![npm](https://img.shields.io/npm/v/%40liyuk%2Fdsh-quota-router)](https://www.npmjs.com/package/@liyuk/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.

```bash
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:

```text
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

```bash
pnpm install
pnpm test
pnpm run check
pnpm run build
```

Published on npm as [`@liyuk/dsh-quota-router`](https://www.npmjs.com/package/@liyuk/dsh-quota-router); source lives at [Liyuk/dsh-quota-router](https://github.com/Liyuk/dsh-quota-router). See [`docs/RELEASE-1.0.0.md`](./docs/RELEASE-1.0.0.md) for the community-facing update.