# dsh-quota-router 1.0.0：社区更新说明

`@liyuk/dsh-quota-router@1.0.0` 现已进入 1.0 产品线。

## 这是什么

Quota Router 是 DSH 的多来源模型路由和故障恢复插件。它根据任务 Profile 和来源优先级选择 DSH 已注册的模型，并在配额、权限、限流或传输故障时沿候选链进行可控 fallback。

它解决的是“这次请求应该走哪个 provider/model，以及失败后怎么安全切换”，不是 provider 管理器，也不是上下文压缩器。

## 1.0 包含的能力

- 关键词 Profile 的 first-match 任务匹配；
- 全局来源优先级 × 每任务模型映射的候选链；
- DSH native provider/model validation；
- paid opt-in、manual/emergency 不自动选择；
- stable failure 立即前进，transient failure 先交给 DSH retry；
- forward-only fallback 和 cooldown；
- per-turn route identity，避免 fallback 丢失原任务上下文；
- bounded idempotent ledger、route receipts、`quota_router_status`；
- DSH Web Settings → Quota Router 配置和候选链预览；
- `SubtaskRouter` 的显式能力约束和模型租约 API。

## 能节省什么

它可以帮助用户：

- 把简单任务优先放到免费、订阅或低价来源；
- 避免故障时意外切到付费来源；
- 避免持续重试已经确定不可用的 provider；
- 减少手工切换模型后重复发送同一请求的浪费。

但 1.0 不声称“保证省 token”或“保证降低总成本”。总成本还取决于模型质量、返工率、上下文大小和实际价格。建议用相同任务 baseline 对比 `route_cost`、`fallback_recovery`、accepted rate 和 rework rate。

## 和 dsh-economizer 的边界

本版本参考了 dsh-economizer 的接口纪律、稳定 fingerprint、幂等状态和离线评估思路，但没有复制其工具按需加载、tool/skill search-load 或 compaction 后重新注入能力。

两类成本应分开：

- `route_cost`：provider/model、input/output/cache/reasoning token、fallback；
- `context_cost`：工具 schema、prompt、cache、compaction 和上下文可见性。

Quota Router 负责前者；DSH 或上下文插件负责后者。

## 升级说明

0.2.x 的核心配置保持兼容。升级后请：

1. 安装 1.0.0；
2. 重启 DSH profile；
3. 在 DSH Models 中确认 provider/model 仍已注册；
4. 在 Settings → Quota Router 检查候选链；
5. 用新 session 验证 Route Receipt 和 `quota_router_status`。

需要注意：receipt 和 ledger 当前是进程内、有限容量的记录。它们不是跨重启恢复的永久账单。

欢迎在 DSH 社区反馈：

- 任务 Profile 和关键词匹配是否符合实际使用；
- fallback 后是否真正恢复；
- 各来源 token 和成本的可比 baseline；
- router 与上下文/工具优化插件组合时的行为。

完整项目说明见 [`docs/PROJECT.md`](./PROJECT.md)。