@apinggithub/mydsh-auto-model-router 0.2.0 → 0.2.1

package/README.md

@@ -116,6 +116,48 @@ npm install @apinggithub/mydsh-auto-model-router
 dsh plugin --profile web add @apinggithub/mydsh-auto-model-router
 ```
 
+## Host compatibility
+
+DSH treats a profile's plugin tree as one composition: a bundle whose patch
+fails can stop the whole Harness from starting, and a plugin entry that throws
+is reported as *did not activate* — the router simply disappears from the
+running session. This plugin is therefore written to **mount, degrade and
+log** rather than fail on a host whose surface moved.
+
+| Host line | Status |
+| --- | --- |
+| 0.1.x – 0.3.x | Tested (`0.2.1-rc.2` is the reference host) |
+| 0.4.x – 1.x | Allowed to mount, reported as *untested* in the log and in `GET /api/mydsh-auto-model-router/status` |
+
+At mount, `compat.mjs` probes every API the plugin touches
+(`llm.registerAdapter`, `llm.listModels`, `llm.stream`, scoped `ctx.inject`,
+`webServer.register`, the optional `tokenMeter`) and records the result in the
+status payload under `host.compat`. What that buys you on an unknown host:
+
+- **No hard dependency on `tokenMeter`** — it is looked up softly and token
+  spend falls back to the plugin's own estimator.
+- **No virtual-provider requirement** — without `llm.registerAdapter` the
+  plugin still mounts and logs one warning; the `Auto` model simply does not
+  appear in the picker.
+- **HTTP route aliases** — `webServer.register()`, `route()` or `addRoute()`
+  are all accepted; without any of them the settings page shows its "no report
+  yet" state instead of breaking.
+- **Payload tolerance** — event handlers accept the current `{ agent }` /
+  `(session, event)` shapes *and* a bare-agent / `{ session, event }` payload,
+  and a handler that throws hands the host's own proposal back untouched. A
+  router bug can no longer fail a user request.
+- **No process globals** — the adapter is created per mount and closes over
+  that mount's router, so several profiles in one process cannot overwrite
+  each other.
+- **Version report** — when the host exposes its version (environment, app
+  service, or a resolvable manifest), a host outside `>=0.1.0-0 <0.4.0` logs
+  one warning naming both versions. Capability probes run regardless, so a
+  host that hides its version still reports what it actually provides.
+
+The peer ranges (`>=0.1.0-0 <1.0.0`) and `engines.dsh` are deliberately wider
+than the tested range so an upgrade does not hard-block installation; the
+runtime warning is what tells you to file an issue.
+
 ## Configuration
 
 Add to your profile's `cordis.patch.yml`:
@@ -370,88 +412,111 @@ See [tier-cost/README.md](tier-cost/README.md) for details.
 ## License
 
 MIT
-
-### Context-window guard (contextGuard)
-
-A level may declare its model's `contextWindow`. When the session's live context
-(the input side of the last request, including cache reads/writes) exceeds
-`window × headroom` (default 0.85) the level is **skipped** and the router
-drifts up to the nearest level that fits; if no declared window fits, the
-original level stands (fail open) so the provider answers with a real error the
-fallback chain can handle. Each skip is recorded once per (level, session) and
-visible in `/status` under `contextGuard`. With no window declared anywhere the
-layer is inert.
-
-```yaml
-levels:
-  L0: { provider: bailian, model: qwen-max, contextWindow: 32768 }   # guard small windows
-contextGuard: { enabled: true, headroom: 0.85 }
+
+### Context-window guard (contextGuard)
+
+A level may declare its model's `contextWindow`. When the session's live context
+(the input side of the last request, including cache reads/writes) exceeds
+`window × headroom` (default 0.85) the level is **skipped** and the router
+drifts up to the nearest level that fits; if no declared window fits, the
+original level stands (fail open) so the provider answers with a real error the
+fallback chain can handle. Each skip is recorded once per (level, session) and
+visible in `/status` under `contextGuard`. With no window declared anywhere the
+layer is inert.
+
+```yaml
+levels:
+  L0: { provider: bailian, model: qwen-max, contextWindow: 32768 }   # guard small windows
+contextGuard: { enabled: true, headroom: 0.85 }
 ```
-
-## Deploying to another machine
-
-One machine = two commands (this repository ships both plugins):
-
-```powershell
-git clone https://github.com/apinggithub/mydsh-auto-model-router
-cd mydsh-auto-model-router; cd ..
-# On 0.2.x hosts the plugin's stale pinned peers make the installer refuse; grant the
-# exact-version exemption first (per new plugin version):
-dsh plugin --profile desktop allow-version '@apinggithub/mydsh-auto-model-router@0.1.1' --dsh-version 0.2.0-rc.2 --accept-risk
-dsh plugin --profile desktop add ./mydsh-auto-model-router
-dsh plugin --profile desktop add ./mydsh-auto-model-router/tier-cost   # optional: per-tier cost panel
-```
-
-Then write a full levels block into that machine's `profiles/<profile>/cordis.patch.yml` —
-provider/model must be routes **that machine** can actually use (do not copy ids across machines):
-
-```yaml
-- id: mydsh-auto-model-router-runtime
-  name: '@apinggithub/mydsh-auto-model-router'
-  config:
-    levels:
-      L0: { provider: ..., model: ..., reasoningEffort: off,  contextWindow: ..., freeQuota: true }
-      L1: { provider: ..., model: ..., reasoningEffort: low,   contextWindow: ..., freeQuota: true }
-      L2: { provider: ..., model: ..., reasoningEffort: high,  contextWindow: ..., freeQuota: true }
-      L3: { provider: ..., model: ..., reasoningEffort: max,   contextWindow: ... }
-    contextGuard: { enabled: true, headroom: 0.85 }
-    freeQuota:    { enabled: true, demoteOnError: true, notify: true }
-```
-
-⚠️ The built-in default levels carry legacy values (`deepseek-v4-flash` + `medium`) that are
-both invalid on 0.2.x hosts — a fresh machine must ship its own levels block or Auto fails
-outright. `tier-cost` has zero hard dependencies beyond the host: without the router every
-turn folds into manual/unknown, without the billing plugin tokens are counted and cost
+
+## Deploying to another machine
+
+One machine = two commands (this repository ships both plugins):
+
+```powershell
+git clone https://github.com/apinggithub/mydsh-auto-model-router
+cd mydsh-auto-model-router; cd ..
+# On 0.2.x hosts the plugin's stale pinned peers make the installer refuse; grant the
+# exact-version exemption first (per new plugin version):
+dsh plugin --profile desktop allow-version '@apinggithub/mydsh-auto-model-router@0.1.1' --dsh-version 0.2.0-rc.2 --accept-risk
+dsh plugin --profile desktop add ./mydsh-auto-model-router
+dsh plugin --profile desktop add ./mydsh-auto-model-router/tier-cost   # optional: per-tier cost panel
+```
+
+Then write a full levels block into that machine's `profiles/<profile>/cordis.patch.yml` —
+provider/model must be routes **that machine** can actually use (do not copy ids across machines):
+
+```yaml
+- id: mydsh-auto-model-router-runtime
+  name: '@apinggithub/mydsh-auto-model-router'
+  config:
+    levels:
+      L0: { provider: ..., model: ..., reasoningEffort: off,  contextWindow: ..., freeQuota: true }
+      L1: { provider: ..., model: ..., reasoningEffort: low,   contextWindow: ..., freeQuota: true }
+      L2: { provider: ..., model: ..., reasoningEffort: high,  contextWindow: ..., freeQuota: true }
+      L3: { provider: ..., model: ..., reasoningEffort: max,   contextWindow: ... }
+    contextGuard: { enabled: true, headroom: 0.85 }
+    freeQuota:    { enabled: true, demoteOnError: true, notify: true }
+```
+
+⚠️ The built-in default levels carry legacy values (`deepseek-v4-flash` + `medium`) that are
+both invalid on 0.2.x hosts — a fresh machine must ship its own levels block or Auto fails
+outright. `tier-cost` has zero hard dependencies beyond the host: without the router every
+turn folds into manual/unknown, without the billing plugin tokens are counted and cost
 stays 0 — both cases self-report in the panel notes.
-
-### Catalog freshness guard (modelsGuard)
-
-When a provider retires a model id, the level pointing at it goes stale. The
-guard reads what each provider actually advertises (`ctx.llm.listModels`) at
-activation and every `refreshMs` (default 10 min): a stale level's requests
-**drift to the nearest fresh level** instead of failing, and the status report
-names same-family candidate ids so the fix stays a one-line edit. Unreadable or
-empty catalogs fail open (never marked stale); environments without a catalog
-reader leave the layer inert.
-
-```yaml
-modelsGuard: { enabled: true, refreshMs: 600000 }
-```
-
-> The static list remains configuration (`cordis.patch.yml`) on purpose: the
-> plugin never decides *which* new model to adopt (windows, prices and
-> capabilities all change) — it guarantees a dead tier is not selected and
-> tells you what to switch to.
-
-## Publishing to npm
-
-Both plugins live in this repository and publish independently:
-
-```bash
-npm publish                 # @apinggithub/mydsh-auto-model-router (root)
-cd tier-cost && npm publish # @apinggithub/dsh-tier-cost
-```
-
-From 0.2.0 the peerDependencies are host-adaptive ranges, so fresh machines no
-longer need the allow-version exemption (only 0.1.1 and earlier did). Run
+
+### Catalog freshness guard (modelsGuard)
+
+When a provider retires a model id, the level pointing at it goes stale. The
+guard reads what each provider actually advertises (`ctx.llm.listModels`) at
+activation and every `refreshMs` (default 10 min): a stale level's requests
+**drift to the nearest fresh level** instead of failing, and the status report
+names same-family candidate ids so the fix stays a one-line edit. Unreadable or
+empty catalogs fail open (never marked stale); environments without a catalog
+reader leave the layer inert.
+
+```yaml
+modelsGuard: { enabled: true, refreshMs: 600000 }
+```
+
+> The static list remains configuration (`cordis.patch.yml`) on purpose: the
+> plugin never decides *which* new model to adopt (windows, prices and
+> capabilities all change) — it guarantees a dead tier is not selected and
+> tells you what to switch to.
+
+## Publishing to npm
+
+Both plugins live in this repository and publish independently:
+
+```bash
+npm publish                 # @apinggithub/mydsh-auto-model-router (root)
+cd tier-cost && npm publish # @apinggithub/dsh-tier-cost
+```
+
+From 0.2.0 the peerDependencies are host-adaptive ranges, so fresh machines no
+longer need the allow-version exemption (only 0.1.1 and earlier did). Run
 `npm login --scope=apinggithub` once per package account setup.
+
+## The silent-billing trap of free quota (real incident · rules)
+
+A true story from the author's machine: L1 pointed at the Bailian free model `glm-5.3`
+(`freeQuota: true`). When the quota ran out the provider did **not** return the promised
+403 (`stop-when-exhausted` had not actually taken effect for that model) — calls kept
+succeeding, now silently at pay-as-you-go rates, for a full day until a billing alert
+arrived. `demoteOnError` had no error to catch.
+
+Three rules, all required:
+
+1. **Verify "stop when exhausted" per model on the provider side** (make one over-quota
+   call and confirm a 403). The router can only switch lines on errors it can see;
+   a provider that silently converts a free route into paid billing is invisible to it.
+2. **Keep `costControl.defaultLevel` on a stable paid tier.** In this file's examples a
+   `defaultLevel: L1` where L1 is a free tier is exactly the incident shape. Prefer free
+   only at L0, or keep an explicit paid replacement for every free tier.
+3. **Watch the billing panel per tier.** A "free" tier whose cost line keeps growing and
+   never zeroes is burning money — drop it from the free routes immediately.
+
+> Another sharp edge: quota pools are counted per **provider+model**. The same id on two
+> providers (e.g. `qwen3.8-flash` on both `bailian` and `qianwen`) are **separate pools**;
+> quota and billing never cross over.

package/README.zh.md

@@ -99,6 +99,38 @@ npm install @apinggithub/mydsh-auto-model-router
 dsh plugin --profile web add @apinggithub/mydsh-auto-model-router
 ```
 
+## 宿主兼容性
+
+DSH 把 profile 的插件树当成一次组合：补丁失败的 bundle 可能让整个 Harness 起不来，
+而抛错的插件条目会被标记为「did not activate」——路由器从会话里直接消失。
+所以本插件的行为约定是**能挂载、能降级、能打日志**，而不是在接口变动时直接失败。
+
+| 宿主版本线 | 状态 |
+| --- | --- |
+| 0.1.x – 0.3.x | 已实测（`0.2.1-rc.2` 为基准宿主） |
+| 0.4.x – 1.x | 允许挂载，但在日志与 `GET /api/mydsh-auto-model-router/status` 中标记为「未实测」 |
+
+挂载时 `compat.mjs` 会探测插件用到的每个接口（`llm.registerAdapter`、
+`llm.listModels`、`llm.stream`、scoped `ctx.inject`、`webServer.register`、
+可选的 `tokenMeter`），结果记录在状态接口的 `host.compat` 字段里。在未知宿主上：
+
+- **`tokenMeter` 不再是硬依赖**——软查找，缺失时改用插件自带的估算器。
+- **没有 `registerAdapter` 也能挂载**——只记一条警告，模型选择框里不出现
+  `Auto`，路由逻辑本身不受影响。
+- **HTTP 路由方法适配**——`webServer.register()`、`route()`、`addRoute()`
+  都可接受；全都没有时设置页显示「暂无报告」，而不是报错。
+- **事件负载容错**——既接受当前的 `{ agent }` / `(session, event)` 形状，也接受
+  裸 agent / `{ session, event }` 形状；处理函数抛错时原样返回宿主自己的提案，
+  路由器的 bug 不会再让用户请求失败。
+- **不再使用进程级全局变量**——适配器按每次挂载创建并闭包引用该次挂载的
+  router，同进程多 profile 不会互相覆盖。
+- **版本报告**——当宿主愿意暴露版本（环境变量、app 服务或可解析的 manifest）时，
+  超出 `>=0.1.0-0 <0.4.0` 会打一条同时含宿主版本与实测范围的警告。能力探测始终
+  执行，因此即使宿主隐藏版本，也能从状态接口看到它实际提供了哪些接口。
+
+peer 范围（`>=0.1.0-0 <1.0.0`）和 `engines.dsh` 故意比实测范围宽，避免宿主升级后
+直接拒装；真正的提示是运行时那条警告——看到它就请提 issue。
+
 ## 配置
 
 在 profile 的 `cordis.patch.yml` 中添加：
@@ -336,78 +368,96 @@ dsh plugin --profile desktop add ./tier-cost
 ## License
 
 MIT
-
-### 上下文窗口守卫（contextGuard）
-
-档位可声明其模型的 `contextWindow`。会话实际上下文（最近一次请求的输入侧
-token，含缓存读写）超过 `window × headroom`（默认 0.85）时，**该档位被跳过**，
-路由向上漂到最近的装得下的档位；没有任何声明窗口装得下时保持原档（fail-open），
-让 provider 用真实错误说话、交给降级链处理。跳过每 (档位, 会话) 记录一次，
-`/status` 的 `contextGuard` 字段可见。未声明任何窗口时整层不生效。
-
-```yaml
-levels:
-  L0: { provider: bailian, model: qwen-max, contextWindow: 32768 }   # 小窗口模型的保护
-contextGuard: { enabled: true, headroom: 0.85 }
+
+### 上下文窗口守卫（contextGuard）
+
+档位可声明其模型的 `contextWindow`。会话实际上下文（最近一次请求的输入侧
+token，含缓存读写）超过 `window × headroom`（默认 0.85）时，**该档位被跳过**，
+路由向上漂到最近的装得下的档位；没有任何声明窗口装得下时保持原档（fail-open），
+让 provider 用真实错误说话、交给降级链处理。跳过每 (档位, 会话) 记录一次，
+`/status` 的 `contextGuard` 字段可见。未声明任何窗口时整层不生效。
+
+```yaml
+levels:
+  L0: { provider: bailian, model: qwen-max, contextWindow: 32768 }   # 小窗口模型的保护
+contextGuard: { enabled: true, headroom: 0.85 }
 ```
-
-## 部署到其它电脑
-
-一台机器 = 两条命令（本仓库含两个插件）：
-
-```powershell
-git clone https://github.com/apinggithub/mydsh-auto-model-router
-cd mydsh-auto-model-router; cd ..
-# 宿主 0.2.x 会因插件 peer 钉死旧版本而拒装，先授予精确版本豁免（每个新版本各授一次）：
-dsh plugin --profile desktop allow-version '@apinggithub/mydsh-auto-model-router@0.1.1' --dsh-version 0.2.0-rc.2 --accept-risk
-dsh plugin --profile desktop add ./mydsh-auto-model-router
-dsh plugin --profile desktop add ./mydsh-auto-model-router/tier-cost   # 可选：按档位拆账
-```
-
-然后在该机器的 `profiles/<profile>/cordis.patch.yml` 里写完整档位块，**provider/model 必须
-是那条机器自己能用的路由，别照抄 id**：
-
-```yaml
-- id: mydsh-auto-model-router-runtime
-  name: '@apinggithub/mydsh-auto-model-router'
-  config:
-    levels:
-      L0: { provider: ..., model: ..., reasoningEffort: off,  contextWindow: ..., freeQuota: true }
-      L1: { provider: ..., model: ..., reasoningEffort: low,   contextWindow: ..., freeQuota: true }
-      L2: { provider: ..., model: ..., reasoningEffort: high,  contextWindow: ..., freeQuota: true }
-      L3: { provider: ..., model: ..., reasoningEffort: max,   contextWindow: ... }
-    contextGuard: { enabled: true, headroom: 0.85 }
-    freeQuota:    { enabled: true, demoteOnError: true, notify: true }
-```
-
-⚠️ 内置默认 levels 是历史值（`deepseek-v4-flash` + `medium`），在 0.2.x 宿主上**两者都不是
-合法值**——新机器必须自带档位块，否则选 Auto 会直接失败。
-`tier-cost` 对宿主其余部分零依赖：缺路由插件时全部归 manual/unknown，缺计费插件时只统计
+
+## 部署到其它电脑
+
+一台机器 = 两条命令（本仓库含两个插件）：
+
+```powershell
+git clone https://github.com/apinggithub/mydsh-auto-model-router
+cd mydsh-auto-model-router; cd ..
+# 宿主 0.2.x 会因插件 peer 钉死旧版本而拒装，先授予精确版本豁免（每个新版本各授一次）：
+dsh plugin --profile desktop allow-version '@apinggithub/mydsh-auto-model-router@0.1.1' --dsh-version 0.2.0-rc.2 --accept-risk
+dsh plugin --profile desktop add ./mydsh-auto-model-router
+dsh plugin --profile desktop add ./mydsh-auto-model-router/tier-cost   # 可选：按档位拆账
+```
+
+然后在该机器的 `profiles/<profile>/cordis.patch.yml` 里写完整档位块，**provider/model 必须
+是那条机器自己能用的路由，别照抄 id**：
+
+```yaml
+- id: mydsh-auto-model-router-runtime
+  name: '@apinggithub/mydsh-auto-model-router'
+  config:
+    levels:
+      L0: { provider: ..., model: ..., reasoningEffort: off,  contextWindow: ..., freeQuota: true }
+      L1: { provider: ..., model: ..., reasoningEffort: low,   contextWindow: ..., freeQuota: true }
+      L2: { provider: ..., model: ..., reasoningEffort: high,  contextWindow: ..., freeQuota: true }
+      L3: { provider: ..., model: ..., reasoningEffort: max,   contextWindow: ... }
+    contextGuard: { enabled: true, headroom: 0.85 }
+    freeQuota:    { enabled: true, demoteOnError: true, notify: true }
+```
+
+⚠️ 内置默认 levels 是历史值（`deepseek-v4-flash` + `medium`），在 0.2.x 宿主上**两者都不是
+合法值**——新机器必须自带档位块，否则选 Auto 会直接失败。
+`tier-cost` 对宿主其余部分零依赖：缺路由插件时全部归 manual/unknown，缺计费插件时只统计
 token、费用记 0，均会在面板 notes 里说明。
-
-### 目录新鲜度守卫（modelsGuard）
-
-模型版本升级后，provider 不再公布的 id 会变成「过期路由」。守卫在激活时与每
-`refreshMs`（默认 10 分钟）用 `ctx.llm.listModels(provider)` 读取各 provider
-实际公布的模型：过期档位的请求**自动漂移到最近的鲜活档位**（绝不静默打死），
-状态报告列出过期档位与**同族候选 id**，改档位仍是一行编辑的事。目录读不到或
-为空时一律 fail-open（不判过期）。未注册 listModels 的环境整层惰性。
-
-```yaml
-modelsGuard: { enabled: true, refreshMs: 600000 }
-```
-
-> 静态列表本身仍是配置（`cordis.patch.yml`）——这是刻意的：插件不会替你决定
-> 换成哪个模型（窗口/单价/能力都变了），它只保证**坏档位不再被选中**并告诉你该换什么。
-
-## 发布到 npm
-
-两个插件同一仓库、各自独立发布（root 与本目录的 package.json 都可直接 publish）：
-
-```bash
-npm publish                 # @apinggithub/mydsh-auto-model-router（root）
-cd tier-cost && npm publish # @apinggithub/dsh-tier-cost
-```
-
-0.2.0 起 peerDependencies 已放宽为宿主自适应范围，新机器安装**不再需要**
+
+### 目录新鲜度守卫（modelsGuard）
+
+模型版本升级后，provider 不再公布的 id 会变成「过期路由」。守卫在激活时与每
+`refreshMs`（默认 10 分钟）用 `ctx.llm.listModels(provider)` 读取各 provider
+实际公布的模型：过期档位的请求**自动漂移到最近的鲜活档位**（绝不静默打死），
+状态报告列出过期档位与**同族候选 id**，改档位仍是一行编辑的事。目录读不到或
+为空时一律 fail-open（不判过期）。未注册 listModels 的环境整层惰性。
+
+```yaml
+modelsGuard: { enabled: true, refreshMs: 600000 }
+```
+
+> 静态列表本身仍是配置（`cordis.patch.yml`）——这是刻意的：插件不会替你决定
+> 换成哪个模型（窗口/单价/能力都变了），它只保证**坏档位不再被选中**并告诉你该换什么。
+
+## 发布到 npm
+
+两个插件同一仓库、各自独立发布（root 与本目录的 package.json 都可直接 publish）：
+
+```bash
+npm publish                 # @apinggithub/mydsh-auto-model-router（root）
+cd tier-cost && npm publish # @apinggithub/dsh-tier-cost
+```
+
+0.2.0 起 peerDependencies 已放宽为宿主自适应范围，新机器安装**不再需要**
 allow-version 豁免（豁免仅 0.1.1 及更早需要）。发布前各自 `npm login --scope=apinggithub`。
+
+## 免费额度的静默计费陷阱（真实事故 · 守则）
+
+本仓库作者机器上的实录事故：L1 指向百炼免费模型 `glm-5.3`（`freeQuota: true`），额度耗尽后
+服务商**没有按「用完即停」返回 403**（批量开关未覆盖到该模型/生效延迟），调用照常成功——
+于是 `demoteOnError` 无错可捕，**glm-5.3 静默转按量计费跑了一整天**，直到账单通知才被发现。
+
+三条守则，缺一不可：
+
+1. **先在服务商侧逐模型确认「用完即停」真的生效**（发一条超额调用看是否返回 403，别信批量开关）。
+   路由器只能在**看得见错误**时换线；额度耗尽若被服务商静默转按量，插件无从得知。
+2. **`costControl.defaultLevel` 指向稳定付费档**（本文各处示例的 `defaultLevel: L1` 若 L1 是免费档，
+   正是本次事故形态）。免费档只放最低层（L0），或至少每个免费档都有明确的付费替代。
+3. **用计费面板按档核账**：任何"免费"档的费用行持续大于 0 且不归零，立刻怀疑额度已尽、
+   在按量扣费——把该档从免费路由摘下来。
+
+> 另一个易错点：免费额度池按 **provider+model 独立**计数。同一个模型 id 出现在多个 provider
+> （如 `qwen3.8-flash` 同时在 bailian 与 qianwen）是**不同的池子**，额度与计费互不相干。