@apinggithub/mydsh-auto-model-router 0.3.1 → 0.3.2

package/README.md

@@ -432,39 +432,148 @@ contextGuard: { enabled: true, headroom: 0.85 }
 
 ## Deploying to another machine
 
-One machine = two commands (this repository ships both plugins):
+One machine = three 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
+# 1. Install from npm (peer ranges are host-adaptive; no allow-version exemption needed)
+dsh plugin --profile desktop add '@apinggithub/mydsh-auto-model-router@0.3.1'
+
+# 2. Optional: per-tier cost panel
+dsh plugin --profile desktop add '@apinggithub/dsh-tier-cost@0.1.0'
+
+# 3. Restart DSH once (bundles are composed at boot; config edits hot-reload)
 ```
 
-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):
+From source instead: `git clone …` then `dsh plugin --profile desktop add ./mydsh-auto-model-router`.
+
+### Every machine ships its own levels block
+
+The factory defaults are legacy routes that may not exist on that machine. Write your own
+block at the end of `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 }
+      # reasoningEffort: null = the model has no thinking mode (Qwen/GLM flash have none).
+      # Must be null, otherwise the host rejects the request with UNSUPPORTED_REASONING_EFFORT.
+      L0: { provider: zhipu, model: glm-4.7-flash, reasoningEffort: null, freeQuota: true }
+      L1: { provider: zhipu, model: glm-4.5-flash, reasoningEffort: null, freeQuota: true }
+      L2: { provider: zhipu, model: glm-4-flash,   reasoningEffort: null }
+      L3: { provider: deepseek-official, model: deepseek-flash, reasoningEffort: max }
     freeQuota:    { enabled: true, demoteOnError: true, notify: true }
+    contextGuard: { enabled: true, headroom: 0.85 }
+    quotaWatch:   { enabled: true, provider: bailian-dell-vostro, balanceFloorCny: 10 }
+```
+
+The providers themselves must already be configured in `cordis.patch.yml` (`llm-pi-ai`'s
+`providers:` section), with keys in the DSH credential store or an `apiKeyEnv`.
+
+`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.
+
+**Multi-machine, same account**: quotas and balances live on the provider's side, so nothing
+is accumulated locally — `quotaWatch` reads the cloud bill. But each machine configures its own
+credentials (the store does not sync).
+
+## Quota watchdog (quotaWatch)
+
+### What it fixes
+
+An exhausted free tier does not always produce an error: the provider may silently switch it to
+pay-as-you-go. `demoteOnError` has nothing to catch then, and the route keeps spending (see
+[the silent-billing trap](#the-silent-billing-trap-of-free-quota-real-incident--rules)). The
+watchdog reads the **bill** instead and retires a "free" model within one poll.
+
+### What it can see
+
+| Source | Gives | Limit |
+| --- | --- | --- |
+| `QueryAccountBalance` | available balance (CNY) | near real-time |
+| `DescribeInstanceBill` | spend per model for the cycle | **T+1** |
+| `QueryResourcePackageInstances` | resource-package remainder | empty when none exist |
+| DeepSeek `GET /user/balance` | platform balance | near real-time |
+
+There is **no** public "remaining free quota" API — that progress bar only exists in the
+provider console. So the semantics are *detect and demote*, not *block in advance*; the real
+guard against overspend is still the provider-side "stop when exhausted" switch.
+
+### Configuration
+
+```yaml
+quotaWatch:
+  enabled: true
+  provider: bailian-dell-vostro      # which configured provider the bill describes
+  productCode: sfm                   # 百炼's product code on the Aliyun bill
+  pollMs: 1800000                    # 30 min (minimum 60000)
+  balanceFloorCny: 10                # below this Aliyun balance, every paid level pauses; 0 = off
+  demoteOnSpend: true                # any spend on a guarded model retires its route
+  deepseekBalanceFloor: 10           # below this, only deepseek-official pauses; 0 = off
+  deepseekApiKeyRef: DEEPSEEK_API_KEY
+  accessKeyIdRef: ALIBABA_CLOUD_ACCESS_KEY_ID
+  accessKeySecretRef: ALIBABA_CLOUD_ACCESS_KEY_SECRET
+  timeoutMs: 20000
+```
+
+### Aliyun RAM: how to grant the least privilege
+
+**Never use the root account's AccessKey.** Instead:
+
+1. Console → **RAM** → Users → create a user with **programmatic access only**;
+2. Give it **read-only billing**: attach the system policy `AliyunBSSReadOnlyAccess`, or a custom
+   policy allowing just `bss:QueryAccountBalance`, `bss:DescribeInstanceBill`,
+   `bss:QueryResourcePackageInstances`;
+3. Create an **AccessKey** and store it in the DSH credential store — nothing else, no write scope;
+4. The plugin only ever issues two GETs per poll.
+
+> Never put the AccessKey **secret** in `cordis.patch.yml`, and never commit it. The config
+> carries reference names (`accessKeyIdRef` / `accessKeySecretRef`) only.
+
+### Where credentials live
+
+The watchdog resolves them through `ctx.credentials.resolve(ref)`, i.e. the **DSH credential
+store** (`$DSH_HOME/.credentials.yaml`, the same file that holds provider API keys):
+
+```yaml
+refs:
+  ALIBABA_CLOUD_ACCESS_KEY_ID: LTAI...
+  ALIBABA_CLOUD_ACCESS_KEY_SECRET: ...
+  DEEPSEEK_API_KEY: sk-...
+```
+
+Two ways to write it:
+
+- **GUI**: Plugins → built-in plugin settings → Models / credentials, using the ref names above;
+- **Command line** (keeps the secret out of shell history and out of any chat):
+
+```powershell
+$sec = Read-Host -AsSecureString 'Paste AccessKey Secret'
+$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
+  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec))
+# write it into $DSH_HOME/.credentials.yaml, then delete any temporary plaintext file
+```
+
+⚠️ **Multi-machine**: configure credentials once per machine. Quotas and balances live on the
+provider side, so every machine reads the same numbers.
+
+### Status
+
+`GET /api/mydsh-auto-model-router/status` → `quotaWatch`:
+
+```json
+{
+  "enabled": true, "lastCheckAt": "2026-10-22T09:57:18Z", "lastError": null,
+  "balanceCny": 28.21, "cycle": "2026-10",
+  "spendByModel": { "glm-5.3": 62.5611, "qwen3.8-flash": 8.0478 },
+  "totalCny": 70.67, "exhausted": [], "balanceLow": false,
+  "deepseekBalanceCny": 158.25, "deepseekBlocked": false, "deepseekError": null
+}
 ```
 
-⚠️ 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.
+Any step that fails lands in `lastError` / `deepseekError` and never breaks routing.
 
 ### Catalog freshness guard (modelsGuard)
 

package/README.zh.md

@@ -385,37 +385,155 @@ 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   # 可选：按档位拆账
+# 1. 从 npm 装（推荐；peer 范围已放宽为宿主自适应，不需要 allow-version 豁免）
+dsh plugin --profile desktop add '@apinggithub/mydsh-auto-model-router@0.3.1'
+
+# 2. 可选：按档位拆账
+dsh plugin --profile desktop add '@apinggithub/dsh-tier-cost@0.1.0'
+
+# 3. 重启 DSH（bundle 只在启动时组合；配置改动用热加载即可）
 ```
 
-然后在该机器的 `profiles/<profile>/cordis.patch.yml` 里写完整档位块，**provider/model 必须
-是那条机器自己能用的路由，别照抄 id**：
+也可以从源码装：`git clone …` 后 `dsh plugin --profile desktop add ./mydsh-auto-model-router`。
+
+### 每台机器必须自带档位块
+
+插件的出厂默认档位是**历史值**（`deepseek-official/deepseek-flash`），这台机器上不一定可用。
+装完在该机器 `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: ... }
+      # reasoningEffort: null = 该模型没有思考能力（Qwen/GLM flash 都是），必须写 null，
+      # 否则宿主会以 UNSUPPORTED_REASONING_EFFORT 拒绝请求。
+      L0: { provider: zhipu, model: glm-4.7-flash, reasoningEffort: null, freeQuota: true }
+      L1: { provider: zhipu, model: glm-4.5-flash, reasoningEffort: null, freeQuota: true }
+      L2: { provider: zhipu, model: glm-4-flash,   reasoningEffort: null }
+      L3: { provider: deepseek-official, model: deepseek-flash, reasoningEffort: max }
+    freeQuota:   { enabled: true, demoteOnError: true, notify: true }
     contextGuard: { enabled: true, headroom: 0.85 }
-    freeQuota:    { enabled: true, demoteOnError: true, notify: true }
+    quotaWatch:  { enabled: true, provider: bailian-dell-vostro, balanceFloorCny: 10 }
+```
+
+provider 本身要在 `cordis.patch.yml` 里先定义好（`llm-pi-ai` 的 `providers:` 段），
+密钥通过 DSH 凭据库或 `apiKeyEnv` 提供。
+
+**多机同账号的注意点**：额度与余额都在**服务端**，所以本机累计的 token 数不参与判断——
+`quotaWatch` 读的是云端账单/余额。但**每台机器都要各自配置一次**（凭据库不跨机同步）。
+
+## 额度看门狗（quotaWatch）
+
+### 它解决什么问题
+
+免费额度耗尽后，服务商**未必报错**——可能静默转按量计费。那时 `demoteOnError` 无错可捕，
+路由会一直烧钱（见文末「静默计费陷阱」）。看门狗改读**账单**，一旦某个"免费"模型出现花费，
+30 分钟内把它摘掉。
+
+### 它能看见什么
+
+| 数据源 | 能拿到 | 限制 |
+| --- | --- | --- |
+| `QueryAccountBalance` | 账户可用余额（¥） | 准实时 |
+| `DescribeInstanceBill` | 按模型拆分的当期花费 | **T+1 延迟** |
+| `QueryResourcePackageInstances` | 资源包余量 | 无资源包时为空 |
+| DeepSeek `GET /user/balance` | 开放平台余额 | 准实时 |
+
+**没有**"查询免费额度剩余"的公开接口——那个进度条只在服务商控制台里。
+所以看门狗的语义是**发现即降级**，不是提前拦截；真正的超前拦截仍要靠服务商侧的「用完即停」。
+
+### 配置
+
+```yaml
+quotaWatch:
+  enabled: true
+  provider: bailian-dell-vostro      # 账单描述的是哪个已配置 provider（要摘的路由）
+  productCode: sfm                   # 百炼在阿里云账单里的商品码
+  pollMs: 1800000                    # 轮询间隔，最小 60000
+  balanceFloorCny: 10                # 阿里云余额低于此值 → 暂停所有付费档；0 = 关闭
+  demoteOnSpend: true                # 某模型出现花费 → 摘掉它的路由
+  deepseekBalanceFloor: 10           # DeepSeek 平台余额低于此值 → 只暂停 deepseek-official；0 = 关闭
+  deepseekApiKeyRef: DEEPSEEK_API_KEY
+  accessKeyIdRef: ALIBABA_CLOUD_ACCESS_KEY_ID
+  accessKeySecretRef: ALIBABA_CLOUD_ACCESS_KEY_SECRET
+  timeoutMs: 20000
+```
+
+### 阿里云 RAM 子账号怎么开（重要）
+
+**不要用主账号 AccessKey。** 正确的做法：
+
+1. 阿里云控制台 → **RAM 访问控制** → 用户 → 创建用户，勾选**只允许编程访问**；
+2. 给它**只读账单权限**：直接附加系统策略 `AliyunBSSReadOnlyAccess`；
+   想更小可用自定义策略，只允许这几个 Action：
+   `bss:QueryAccountBalance`、`bss:DescribeInstanceBill`、`bss:QueryResourcePackageInstances`；
+3. 创建 **AccessKey**，把 ID/Secret 存进 DSH 凭据库（见下），**不要再给它任何写权限**；
+4. 验证（只读，不花钱）：
+
+```powershell
+$ak = (Resolve the ID);  $sk = (Resolve the secret)
+# 期望返回 {"Success":true,"Data":{"AvailableAmount":"..."}}
+```
+
+> AccessKey **Secret 不要写进 `cordis.patch.yml`，也不要提交进仓库**——配置文件里只有
+> `accessKeyIdRef` / `accessKeySecretRef` 这样的**引用名**。
+
+### 凭据放哪里
+
+看门狗通过 `ctx.credentials.resolve(ref)` 读取，所以密钥存在 **DSH 凭据库**
+（`$DSH_HOME/.credentials.yaml`，与 provider 的 API key 同一个文件），形如：
+
+```yaml
+refs:
+  ALIBABA_CLOUD_ACCESS_KEY_ID: LTAI...
+  ALIBABA_CLOUD_ACCESS_KEY_SECRET: ...
+  DEEPSEEK_API_KEY: sk-...
 ```
 
-⚠️ 内置默认 levels 是历史值（`deepseek-v4-flash` + `medium`），在 0.2.x 宿主上**两者都不是
-合法值**——新机器必须自带档位块，否则选 Auto 会直接失败。
-`tier-cost` 对宿主其余部分零依赖：缺路由插件时全部归 manual/unknown，缺计费插件时只统计
-token、费用记 0，均会在面板 notes 里说明。
+两种写入方式，任选：
+
+- **GUI**：插件 → 内置插件设置 → Models / 凭据，按 API key 的方式存（键名用上面的 ref 名）；
+- **命令行**（secret 不进 shell 历史，也不进对话）：
+
+```powershell
+$sec = Read-Host -AsSecureString 'Paste AccessKey Secret'
+$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
+  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec))
+# 写入 $DSH_HOME/.credentials.yaml 的 refs 段后，立即删除任何临时明文文件
+```
+
+⚠️ **多机部署**：每台机器都要各自配置一次凭据（凭据库不跨机同步）。
+额度/余额在服务端，所以多机读到的数字一致，不存在方案 A 那种"各机各算、互不知情"的偏差。
+
+### 状态接口
+
+`GET /api/mydsh-auto-model-router/status` 的 `quotaWatch` 字段：
+
+```json
+{
+  "enabled": true,
+  "lastCheckAt": "2026-10-22T09:57:18Z",
+  "lastError": null,
+  "balanceCny": 28.21,
+  "cycle": "2026-10",
+  "spendByModel": { "glm-5.3": 62.5611, "qwen3.8-flash": 8.0478 },
+  "totalCny": 70.67,
+  "exhausted": [],
+  "balanceLow": false,
+  "deepseekBalanceCny": 158.25,
+  "deepseekBlocked": false,
+  "deepseekError": null
+}
+```
+
+任何一环失败都只写进 `lastError` / `deepseekError`，**不会**影响路由本身。
+
+## 发布到 npm
 
 ### 目录新鲜度守卫（modelsGuard）
 

package/config.mjs

@@ -22,7 +22,7 @@
 //   fallbackChain:  [route, ...]  (model-level, appended with the default)
 //   maxRetries:     per-route retry budget on request-error
 
-export const PLUGIN_VERSION = '0.3.1'
+export const PLUGIN_VERSION = '0.3.2'
 
 export const LEVEL_IDS = Object.freeze(['L0', 'L1', 'L2', 'L3'])
 export const COST_MODES = Object.freeze(['cost-first', 'quality-first', 'balanced'])
@@ -48,6 +48,8 @@ const DEFAULT_CONFIG = Object.freeze({
   heuristic: {
     windowSize: 3,
     counting: 'cjk2',
+    // Ask before leaving the heuristic ladder; set false to route silently.
+    askAboveLock: true,
     thresholds: [
       { maxChars: 10, level: 'L0' },
       { maxChars: 100, level: 'L1' },
@@ -259,6 +261,9 @@ function normalizeHeuristic(heuristic) {
     ...(heuristic ?? {}),
   }
   h.windowSize = clampInt(h.windowSize, 1, 20, DEFAULT_CONFIG.heuristic.windowSize)
+  // `askAboveLock: false` removes the "this input crossed the ceiling" dialog:
+  // anything above the top threshold just rides the last threshold's level.
+  h.askAboveLock = h.askAboveLock !== false
   if (!COUNTING_MODES.includes(h.counting)) {
     throw new Error(
       `mydsh-auto-model-router: heuristic.counting must be one of ${COUNTING_MODES.join(', ')}, got "${h.counting}"`,

package/examples/README.md

@@ -0,0 +1,53 @@
+# Copy-paste examples
+
+These files are meant to be **copied into a profile**, not loaded from here.
+Each one is a fragment for `profiles/<profile>/cordis.patch.yml`; merge the entry
+into that file rather than replacing it.
+
+| File | What it gives you |
+| --- | --- |
+| [`levels-free-first.yml`](levels-free-first.yml) | L0–L2 on free Zhipu flash models, L3 on the DeepSeek platform API |
+| [`levels-deepseek-account.yml`](levels-deepseek-account.yml) | Everything on the logged-in DeepSeek account (no API key needed) |
+| [`quota-watch.yml`](quota-watch.yml) | The cloud-bill watchdog block, with the RAM notes inline |
+| [`add-credentials.ps1`](add-credentials.ps1) | Writes/updates/removes one credential in `$DSH_HOME/.credentials.yaml` |
+
+## Quick start on a fresh machine
+
+```powershell
+dsh plugin --profile desktop add '@apinggithub/mydsh-auto-model-router@0.3.1'
+
+# 1. store the keys the examples reference (secret is typed, never echoed)
+.\examples\add-credentials.ps1 -Name ZHIPU_API_KEY
+.\examples\add-credentials.ps1 -Name DEEPSEEK_API_KEY
+# only if you enable quotaWatch:
+.\examples\add-credentials.ps1 -Name ALIBABA_CLOUD_ACCESS_KEY_ID
+.\examples\add-credentials.ps1 -Name ALIBABA_CLOUD_ACCESS_KEY_SECRET
+
+# 2. append the levels block to the profile patch
+notepad $env:DSH_HOME\profiles\desktop\cordis.patch.yml
+
+# 3. restart DSH once (bundles compose at boot; later edits hot-reload)
+```
+
+Check what the plugin sees at any time:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:<port>/api/mydsh-auto-model-router/status
+```
+
+(the port is in the GUI URL; the route is unauthenticated by design)
+
+## Rules of thumb that cost us real time
+
+- **`reasoningEffort: null`** on any model without a thinking mode (Qwen/GLM
+  flash). Writing `off` makes the host reject the request with
+  `UNSUPPORTED_REASONING_EFFORT`.
+- **Never mark a route `freeQuota: true`** unless you verified the provider
+  stops at the quota instead of silently billing. If in doubt, leave it out and
+  let `quotaWatch` retire the route once the bill shows spend.
+- **Provider ids are per machine.** `zhipu`, `bailian-dell-vostro`,
+  `deepseek-account` only exist if that machine's `llm-pi-ai` `providers:` block
+  defines them.
+- **Keep `L3` on a model with a large context window** (or rely on
+  `contextGuard`), otherwise a long session gets its answer truncated to a
+  handful of tokens and reads as "reached the output token limit".

package/examples/add-credentials.ps1

@@ -0,0 +1,143 @@
+<#
+.SYNOPSIS
+  Store, update or remove one credential reference in the DSH credential store.
+
+.DESCRIPTION
+  DSH resolves provider keys (and the quota watchdog's cloud keys) from
+  $DSH_HOME/.credentials.yaml, under `refs:`. This script edits exactly one
+  entry and leaves every other line untouched.
+
+  The secret is read as a SecureString by default, so it never lands in the
+  shell history, in a log, or in a chat transcript. Pass -FromFile to import an
+  existing file and delete it afterwards.
+
+.PARAMETER Name
+  The reference name, e.g. ZHIPU_API_KEY, DEEPSEEK_API_KEY,
+  ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET.
+
+.PARAMETER Value
+  Optional literal value for non-interactive use (machine provisioning).
+  Prefer the prompt: a literal on the command line is recorded in history.
+
+.PARAMETER FromFile
+  Read the value from a file (trimmed), then delete that file.
+
+.PARAMETER Remove
+  Delete the reference instead of setting it.
+
+.PARAMETER DshHome
+  DSH home directory. Defaults to $env:DSH_HOME, then $HOME\.dsh.
+
+.EXAMPLE
+  .\add-credentials.ps1 -Name ZHIPU_API_KEY
+
+.EXAMPLE
+  .\add-credentials.ps1 -Name DEEPSEEK_API_KEY -FromFile C:\temp\key.txt
+
+.EXAMPLE
+  .\add-credentials.ps1 -Name ALIBABA_CLOUD_ACCESS_KEY_SECRET -Remove
+#>
+[CmdletBinding(DefaultParameterSetName = 'Prompt')]
+param(
+  [Parameter(Mandatory = $true)]
+  [ValidatePattern('^[A-Z][A-Z0-9_]*$')]
+  [string]$Name,
+
+  [Parameter(ParameterSetName = 'Value')]
+  [string]$Value,
+
+  [Parameter(ParameterSetName = 'File')]
+  [string]$FromFile,
+
+  [Parameter(ParameterSetName = 'Remove')]
+  [switch]$Remove,
+
+  [string]$DshHome
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Resolve-DshHome {
+  param([string]$Explicit)
+  if ($Explicit) { return $Explicit }
+  if ($env:DSH_HOME) { return $env:DSH_HOME }
+  return (Join-Path $HOME '.dsh')
+}
+
+function Read-SecretValue {
+  $secure = Read-Host -AsSecureString "Paste the secret for $Name"
+  $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+  try {
+    return [Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
+  } finally {
+    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) | Out-Null
+  }
+}
+
+function Quote-Yaml([string]$text) {
+  # Single-quoted YAML scalar: keys never contain quotes, but escape defensively.
+  return "'" + $text.Replace("'", "''") + "'"
+}
+
+$homeDir = Resolve-DshHome $DshHome
+$store = Join-Path $homeDir '.credentials.yaml'
+
+if (-not (Test-Path $store)) {
+  New-Item -ItemType Directory -Path $homeDir -Force | Out-Null
+  [IO.File]::WriteAllText($store, "version: 1`nrefs:`n", (New-Object System.Text.UTF8Encoding($false)))
+  Write-Host "created $store"
+}
+
+$raw = [IO.File]::ReadAllText($store, [Text.Encoding]::UTF8)
+$linePattern = "(?m)^[ \t]{2}" + [regex]::Escape($Name) + ":[^\r\n]*$"
+
+if ($Remove) {
+  if (-not [regex]::IsMatch($raw, $linePattern)) {
+    Write-Host "$Name is not present; nothing to remove."
+    return
+  }
+  $updated = [regex]::Replace($raw, $linePattern + "\r?\n?", '')
+  [IO.File]::WriteAllText($store, $updated, (New-Object System.Text.UTF8Encoding($false)))
+  Write-Host "removed $Name from $store"
+  return
+}
+
+if ($PSCmdlet.ParameterSetName -eq 'File') {
+  if (-not (Test-Path $FromFile)) { throw "file not found: $FromFile" }
+  $secret = ([IO.File]::ReadAllText($FromFile, [Text.Encoding]::UTF8)).Trim()
+  Remove-Item $FromFile -Force
+  Write-Host "imported and deleted $FromFile"
+} elseif ($PSCmdlet.ParameterSetName -eq 'Value') {
+  $secret = $Value.Trim()
+} else {
+  $secret = (Read-SecretValue).Trim()
+}
+
+if ([string]::IsNullOrWhiteSpace($secret)) { throw 'the secret is empty; nothing written' }
+
+$entry = "  ${Name}: " + (Quote-Yaml $secret)
+
+if ([regex]::IsMatch($raw, $linePattern)) {
+  $updated = [regex]::Replace($raw, $linePattern, { param($m) $entry })
+} elseif ([regex]::IsMatch($raw, '(?m)^refs:\s*$')) {
+  $updated = [regex]::Replace($raw, '(?m)^refs:\s*$', "refs:`n$entry", 1)
+} else {
+  $updated = $raw.TrimEnd() + "`nrefs:`n$entry`n"
+}
+
+[IO.File]::WriteAllText($store, $updated, (New-Object System.Text.UTF8Encoding($false)))
+
+# Restrict the file to the current user: it holds every provider key.
+try {
+  & icacls $store /inheritance:r /grant:r "$($env:USERNAME):(R,W)" | Out-Null
+} catch {
+  Write-Warning "could not tighten ACL on $store (non-fatal)"
+}
+
+$check = [IO.File]::ReadAllText($store, [Text.Encoding]::UTF8)
+$stored = [regex]::Match($check, "(?m)^[ \t]{2}" + [regex]::Escape($Name) + ":\s*(.+)$")
+if (-not $stored.Success) { throw "write failed: $Name not found after update" }
+
+Write-Host ("stored {0} in {1} (length {2}, suffix {3})" -f `
+  $Name, $store, $secret.Length, $secret.Substring([Math]::Max(0, $secret.Length - 4)))
+Write-Host 'Restart DSH only if the provider list changed; credentials are re-read per request.'

package/examples/levels-deepseek-account.yml

@@ -0,0 +1,39 @@
+# Everything on the logged-in DeepSeek account (OAuth), no API key needed.
+# Useful as a known-good baseline: if this routes, the plugin itself is fine and
+# any failure is in the provider/credential of the other example.
+#
+# `deepseek-account` comes from the host's own account login; the model must be
+# listed in that account's catalog (deepseek-flash on 0.2.x/0.3.x hosts).
+- id: mydsh-auto-model-router-runtime
+  name: '@apinggithub/mydsh-auto-model-router'
+  config:
+    levels:
+      L0:
+        provider: deepseek-account
+        model: deepseek-flash
+        reasoningEffort: off
+      L1:
+        provider: deepseek-account
+        model: deepseek-flash
+        reasoningEffort: low
+      L2:
+        provider: deepseek-account
+        model: deepseek-flash
+        reasoningEffort: high
+      L3:
+        provider: deepseek-account
+        model: deepseek-flash
+        reasoningEffort: max
+    heuristic:
+      windowSize: 3
+      counting: cjk2
+      askAboveLock: false
+      thresholds:
+        - { maxChars: 10, level: L0 }
+        - { maxChars: 100, level: L1 }
+        - { maxChars: 1000, level: L2 }
+        - { maxChars: null, level: L3 }
+    costControl:
+      enabled: true
+      mode: balanced
+      defaultLevel: L1

package/examples/levels-free-first.yml

@@ -0,0 +1,57 @@
+# Free-first ladder: L0–L2 on Zhipu flash (genuinely free), L3 on the DeepSeek
+# platform API. Requires the providers `zhipu` and `deepseek-official` to exist
+# in that machine's cordis.patch.yml (llm-pi-ai providers:) and their keys in the
+# credential store:
+#   ZHIPU_API_KEY       → https://open.bigmodel.cn  (glm flash tiers are free)
+#   DEEPSEEK_API_KEY    → https://platform.deepseek.com
+#
+# reasoningEffort: null is REQUIRED for the glm flash models: they have no
+# thinking mode, and any effort value makes the host reject the request with
+# UNSUPPORTED_REASONING_EFFORT.
+- id: mydsh-auto-model-router-runtime
+  name: '@apinggithub/mydsh-auto-model-router'
+  config:
+    levels:
+      L0:
+        provider: zhipu
+        model: glm-4.7-flash
+        reasoningEffort: null
+        freeQuota: true
+      L1:
+        provider: zhipu
+        model: glm-4.5-flash
+        reasoningEffort: null
+        freeQuota: true
+      L2:
+        provider: zhipu
+        model: glm-4-flash
+        reasoningEffort: null
+      L3:
+        provider: deepseek-official
+        model: deepseek-flash
+        reasoningEffort: max
+    # Long inputs ride the ladder silently instead of opening a dialog on every
+    # crossing of the heuristic ceiling.
+    heuristic:
+      windowSize: 3
+      counting: cjk2
+      askAboveLock: false
+      thresholds:
+        - { maxChars: 10, level: L0 }
+        - { maxChars: 100, level: L1 }
+        - { maxChars: 1000, level: L2 }
+        - { maxChars: null, level: L2 }
+    freeQuota:
+      enabled: true
+      demoteOnError: true
+      notify: true
+      routes: []
+    costControl:
+      enabled: true
+      mode: cost-first
+      defaultLevel: L1
+    fallbackChain:
+      - provider: deepseek-official
+        model: deepseek-flash
+    llmClassifier:
+      enabled: false

package/examples/quota-watch.yml

@@ -0,0 +1,42 @@
+# Cloud-bill watchdog. Read-only: two GETs per poll against the Aliyun BSS
+# OpenAPI, signed in-process. It exists because an exhausted free tier often
+# keeps answering instead of returning an error — the router cannot see that,
+# but the bill can.
+#
+# RAM setup (do this once, in the Aliyun console):
+#   1. RAM → Users → create a user with PROGRAMMATIC ACCESS ONLY.
+#   2. Attach the system policy `AliyunBSSReadOnlyAccess`, or a custom policy
+#      that allows exactly:
+#        bss:QueryAccountBalance
+#        bss:DescribeInstanceBill
+#        bss:QueryResourcePackageInstances
+#   3. Create an AccessKey for that user. Never use the root account's key and
+#      never give it write scope.
+#   4. Store the pair in the DSH credential store (examples/add-credentials.ps1):
+#        ALIBABA_CLOUD_ACCESS_KEY_ID
+#        ALIBABA_CLOUD_ACCESS_KEY_SECRET
+#
+# Secrets never appear in this file — only the reference names.
+- id: mydsh-auto-model-router-runtime
+  name: '@apinggithub/mydsh-auto-model-router'
+  config:
+    quotaWatch:
+      enabled: true
+      # Which configured provider the bill describes; only its routes are retired.
+      provider: bailian-dell-vostro
+      # 百炼's product code on the Aliyun bill.
+      productCode: sfm
+      # 30 minutes. Minimum 60000; billing data itself lags (T+1), so a faster
+      # poll buys nothing.
+      pollMs: 1800000
+      # Below this Aliyun balance every paid route pauses. 0 disables the floor.
+      balanceFloorCny: 10
+      # Any spend on a guarded model retires its route for the session.
+      demoteOnSpend: true
+      # DeepSeek bills its own platform account, which no cloud bill covers:
+      # give that provider a separate floor. 0 disables it.
+      deepseekBalanceFloor: 10
+      deepseekApiKeyRef: DEEPSEEK_API_KEY
+      accessKeyIdRef: ALIBABA_CLOUD_ACCESS_KEY_ID
+      accessKeySecretRef: ALIBABA_CLOUD_ACCESS_KEY_SECRET
+      timeoutMs: 20000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apinggithub/mydsh-auto-model-router",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Hybrid model router for DeepSeek Harness: declarative rules, user-configurable cost control (cost-first / quality-first / balanced), optional LLM task classifier, and failure fallback chains.",
   "type": "module",
   "main": "index.mjs",
@@ -25,6 +25,7 @@
     "scoring.mjs",
     "client.js",
     "cordis.patch.yml",
+    "examples",
     "README.md",
     "README.zh.md"
   ],

package/router.mjs

@@ -134,7 +134,9 @@ export class ModelRouter {
     // MODE A heuristic.
     const width = windowWidth(state.inputs, this.config.heuristic.windowSize, this.config.heuristic.counting)
     const ceiling = lockCeiling(this.config.heuristic.thresholds)
-    if (ceiling !== null && width > ceiling) {
+    // `askAboveLock: false` keeps the ladder silent: the last threshold's level
+    // simply takes the long input instead of interrupting with a question.
+    if (ceiling !== null && width > ceiling && this.config.heuristic.askAboveLock !== false) {
       return { needsAsk: 'above-lock', width }
     }
     const level = levelForWidth(this.config.heuristic.thresholds, width)

package/text-width.mjs

@@ -58,16 +58,14 @@ export function levelForWidth(thresholds, width) {
 }
 
 /**
- * The top finite threshold's maxChars, or null when every threshold is
- * unbounded. Used by the router to detect "above the heuristic lock".
+ * The heuristic ceiling: the top threshold's `maxChars`, or null when that
+ * threshold is unbounded (`maxChars: null`) — an open-ended ladder accepts every
+ * width, so the router never has to ask what to do.
  * @param {object[]} thresholds
  * @returns {number | null}
  */
 export function lockCeiling(thresholds) {
-  for (let i = thresholds.length - 1; i >= 0; i--) {
-    if (thresholds[i]?.maxChars !== null && thresholds[i]?.maxChars !== undefined) {
-      return thresholds[i].maxChars
-    }
-  }
-  return null
+  const last = thresholds[thresholds.length - 1]
+  if (last === undefined) return null
+  return last.maxChars === null || last.maxChars === undefined ? null : last.maxChars
 }