# Quota Router 1.0：让 DSH 的模型路由可控、可解释、可衡量

> `@liyuk/dsh-quota-router@1.0.0` 是 DeepSeek Harness（DSH）的策略层插件。它不注册 provider、不保存凭据、不训练模型，也不接管工具或上下文压缩；它只在 DSH 已经知道的 provider/model 中，为每个任务选择路线，并在基础设施失败时按规则恢复。

## 一句话说明

Quota Router 把“这个任务应该用什么模型”和“哪个来源应该优先使用”分开配置，然后为每个任务生成一条有顺序的候选链。

例如：

```text
普通编码：订阅源 / fast-model → 免费源 / capable-model
高难编码：订阅源 / fast-model → 免费源 / strong-model
```

两个任务可以共享第一跳，但 fallback 不会混淆，因为 router 会在每个 DSH turn 内保留任务 Profile 和候选位置。

## 1. 现在有什么能力

### 任务匹配与模型选择

- 按关键词匹配任务 Profile，按 Profile 顺序执行 first-match；
- 为每个 Profile 配置关键词、默认 reasoning effort 和每个来源的模型；
- 依据全局 source priority 展开每个任务自己的候选链；
- 支持 subscription、free、unlimited、low-price、paid、manual、emergency 等来源标签；
- `paid` 默认不自动使用，`manual` 和 `emergency` 不自动选择；
- 只使用 DSH 已注册、且通过 DSH native provider/model validation 的候选。

### 失败恢复

| 失败 | Router 的行为 |
| --- | --- |
| 配额、余额、401/403 等稳定失败 | 立即沿当前任务候选链前进，并请求 DSH 在同一轮重建请求 |
| 429、5xx、超时、传输中断等暂态失败 | 先交给 DSH 的正常 adapter retry；达到配置阈值后进入 cooldown，再前进 |
| 上下文超限、语义质量不佳等非路由问题 | 不擅自换模型，保留 DSH 原始处理路径 |

恢复规则是 forward-only：候选只向后移动，不在坏路由之间来回震荡。所有候选都耗尽时，保留原始 DSH 错误。

### 稳定性与可观察性

- per-turn identity：同一轮沿用原始 Profile、candidate index 和 route fingerprint；
- bounded idempotent receipts：事件重放不会在保留窗口内重复记账；
- ledger 记录 selected、retried、fallback、cooldown、completed、failed 和按 tier 聚合的用量；
- `quota_router_status` 提供运行时状态；
- DSH Web 的 Settings → Quota Router 提供策略编辑、候选链预览和付费保护提示；
- Route Receipt 提供按 session 查看路由时间线。

### Task-aware API

`SubtaskRouter` 为已经拆好的 subtask 提供显式模型租约：

- 使用 `taskClass`、`complexity`、`precision` 等结构化约束，而不是每轮重新猜任务；
- 使用 `taskId + subtaskId + contractHash` 保持幂等；
- `allowedModels` 只收紧候选，不扩大权限；
- critical 任务在候选耗尽时要求人工介入，不静默降到不合适的模型；
- 语义质量失败交给上层验收器，不把它误判成 provider 故障。

它不是 Planner，也不负责拆任务、审核答案或重新规划。

## 2. 能节省什么

Quota Router 的直接节省来自“把请求放到合适的来源和模型上”，而不是来自减少每次请求的工具 schema。

可直接观察的收益包括：

- 订阅、免费或低价来源的使用比例提高；
- paid 来源保持显式 opt-in，避免故障时意外付费；
- 简单任务不必默认使用最贵或最强模型；
- 已知配额故障不再反复重试同一个不可用来源；
- fallback 恢复后不需要用户手工复制问题、切模型、重新发送。

不要把“选了便宜模型”直接称为“节省”。如果便宜模型导致更多返工，净成本可能更高。建议按以下口径评估：

```text
route_cost = input + output + cache + reasoning tokens，按来源和模型分组

fallback_recovery = fallback 后最终完成的 turns / fallback turns

net_saving = baseline 完成同等任务的资源
           - router 完成同等任务的资源
```

`net_saving` 只有在有可比 baseline，并且能关联 accepted / quality-failed / needs-replan 结果时才成立。插件自身可以记录路由和 token；任务是否完成、是否返工，需要上层提供。

## 3. 明确不包含什么

Quota Router 1.0 不包含以下能力：

- 不训练、微调或改善模型本身；
- 不负责 provider、凭据、模型目录和模型能力定义；
- 不负责 adapter retry 的具体实现，只与 DSH 的 retry 生命周期协作；
- 不负责工具按需加载、tool schema 隐藏、tool search/load 或 skill search/load；
- 不负责上下文压缩、摘要、检索、记忆或 compaction 后的工具重新注入；
- 不保证输出质量、低价模型一定成功或 fallback 一定恢复；
- 不提供跨进程持久化账本，不是永久账单系统；
- 不读取 prompt 全文来做成本推断，也不把上下文 token 节省冒充模型调用成本节省。

工具可见性和上下文 token 优化属于 DSH 或 `dsh-economizer` 一类的上下文层。Quota Router 可以与它们组合，但两者的指标必须分开：

```text
context_cost = 工具 schema、prompt、cache、compaction 相关观察
route_cost   = provider、model、input/output/reasoning token 和 fallback
```

本版本参考了 dsh-economizer 对稳定接口、幂等状态、fingerprint 和离线评估的做法，但没有复制它的工具延迟加载或 compaction 注入实现。

## 4. DSH、用户和插件各自负责什么

| 范围 | 负责人 | 说明 |
| --- | --- | --- |
| 来源顺序、Profile、关键词、模型映射 | 用户 | Settings → Quota Router |
| 付费保护、暂态阈值、cooldown、ledger 上限 | 用户 | 成本和风险策略 |
| first-match、native validation、forward-only、turn identity | Quota Router | 固定路由规则 |
| provider、凭据、模型目录、模型能力 | DSH | DSH Models |
| adapter retry、请求执行 | DSH | router 与其协作 |
| 上下文压缩和工具可见性 | DSH / 上下文插件 | `compaction-basic` 或相应插件 |
| 任务拆解、答案验收、质量返工 | 上层应用 | Planner / evaluator / workflow |

## 5. 1.0 的升级意义

从 0.2.x 到 1.0.0，重点不是声称增加了一个不存在的“自动省 token”功能，而是把已实现的路由契约正式稳定下来：

- source priority × task model mapping 的两层配置模型；
- stable / transient failure 的差异化恢复；
- forward-only、paid protection 和 native validation 安全边界；
- per-turn route identity、bounded idempotent receipt 和 session Route Receipt；
- `SubtaskRouter` 的显式能力约束和模型租约；
- Settings、status tool、receipt 和 ledger 的可观察性；
- 对 route cost、context cost、quality outcome 和 net saving 的清晰分账。

### 兼容说明

现有 `quota-router` 配置结构保持兼容：`sources`、`profiles`、`modelBySource`、`priority`、`allowPaidFallback`、`transientFailureThreshold`、`cooldownMs` 和 `ledgerLimit` 的语义不变。升级后仍需使用匹配 DSH rc.8 运行时的插件构建产物，并重启对应 DSH profile。

Receipt 和 ledger 是进程内 bounded 记录。session resume、进程重启后的历史恢复以及 durable cross-process ledger 不属于 1.0 的保证范围。

## 6. 快速开始

```bash
npm install @liyuk/dsh-quota-router
```

打开 DSH Web 的 Settings → Quota Router：

1. 添加已在 DSH Models 中注册的来源；
2. 设置来源 priority；
3. 创建任务 Profile 和关键词；
4. 为每个来源选择模型；
5. 默认保持 paid fallback 关闭；
6. 用展开后的候选链检查实际顺序；
7. 在新 session 中观察 Route Receipt，或使用 `quota_router_status` 查看运行状态。

完整配置见 [configuration.md](./configuration.md)，策略示例见 [strategy.md](./strategy.md)，task-aware API 见 [task-aware-routing-plan.md](./task-aware-routing-plan.md)。

## 7. 社区讨论时应如何描述

推荐说法：

> Quota Router 是 DSH 的多来源模型路由和故障恢复插件。它让用户按任务配置模型链，优先使用订阅/免费/低价来源，并在配额、权限、限流或传输故障时进行可控 fallback。它能衡量路由成本和恢复情况，但不把工具 schema 优化或上下文压缩节省冒充成模型调用节省。

不推荐说法：

- “自动让所有请求更便宜”；
- “保证省 token”；
- “自动提高模型质量”；
- “包含工具延迟加载和 compaction 优化”；
- “ledger 是永久账单”。