dsh-router-core 0.4.4 → 0.4.6

package/src/router/index.ts

@@ -657,6 +657,21 @@ export class Router {
   private log: (msg: string) => void
   /** 每条降级腿的首字节预算（ms）。只给测试一个入口，生产恒为 FIRST_BYTE_BUDGET_MS。 */
   private firstByteBudgetMs: number
+  /**
+   * 组合增删改**成功提交后**的通知出口。
+   *
+   * 为什么必须有：模型选择器（`ui-model-selection`）的目录是**客户端缓存**的，
+   * 只在宿主转发过来的事件上失效重载（`llm/adapters-updated` /
+   * `settings/document-updated` / 凭据事件 / 重连）。而组合只是本插件
+   * `combos.json` 里的一份状态：改完名字若不发通知，选择器会一直拿着旧快照 ——
+   * 用户能看到的症状是「面板里明明有这个名字，模型选择器里却找不到、切不过去」，
+   * 且新建的组合永远不出现（2026-10-14 实测）。
+   *
+   * 通知与落盘分开（{@link saveCombos} 先 {@link commitCombos} 落盘、再发通知）：
+   * 落盘失败、或 `stateFile` 为空（单测/独立运行时）时内存已经改了，客户端的
+   * 状态同样过期，所以这两条路径都必须照发。
+   */
+  private onCombosChanged: (() => void) | undefined
   /** 用量统计（概览看板）。 */
   usage: UsageStore
 
@@ -664,12 +679,13 @@ export class Router {
     stateFile = '',
     store?: SupplierConfigStore,
     log?: (msg: string) => void,
-    opts?: { firstByteBudgetMs?: number },
+    opts?: { firstByteBudgetMs?: number; onCombosChanged?: () => void },
   ) {
     this.combosFp = stateFile ? join(dirname(stateFile), 'combos.json') : ''
     this.store = store ?? new SupplierConfigStore(stateFile)
     this.log = log ?? ((): void => {})
     this.firstByteBudgetMs = opts?.firstByteBudgetMs ?? FIRST_BYTE_BUDGET_MS
+    this.onCombosChanged = opts?.onCombosChanged
     this.usage = new UsageStore(stateFile)
     this.loadCombos()
   }
@@ -728,7 +744,24 @@ export class Router {
     }
   }
 
+  /**
+   * 提交组合变更：落盘 + 通知拓扑观察者。
+   *
+   * `onCombosChanged` 的失败必须被吞掉：它是**通知**不是事务参与者，
+   * 监听方（宿主事件总线）出问题不能把一次已经生效的增删改报成失败 ——
+   * 那会让用户重试一个其实已经成功的操作（同 `schedule/changed` 的口径）。
+   */
   private saveCombos(): void {
+    this.commitCombos()
+    try {
+      this.onCombosChanged?.()
+    } catch (err) {
+      this.log(`combo change notification failed: ${(err as Error).message}`)
+    }
+  }
+
+  /** 组合落盘（通知由 {@link saveCombos} 单独发，落盘失败不阻断它）。 */
+  private commitCombos(): void {
     if (this.combosFp === '') return
     try {
       const dir = dirname(this.combosFp)
@@ -1276,12 +1309,19 @@ export class Router {
     for (;;) {
       // 指定连接：只试它。选不中就直接失败并说明原因（连接已不存在/不在池里），
       // **不回退到别的号** —— 否则「测这个连接」测出来的是另一个号的结果，
-      // 诊断就变成了假话。
+      // 诊断就变成了假话。注意「选不中」要区分「不在池里」和「这一轮试过了」：
+      // 后者是失败重试的收尾，必须保留上游给的真实错误（见下方 uid === undefined）。
       const uid = onlyUid !== undefined
         ? (s.accounts().some((a) => a.uid === onlyUid) && !tried.has(onlyUid) ? onlyUid : undefined)
         : pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, req.model, messages, req.session)
       if (uid === undefined) {
-        if (onlyUid !== undefined && trace !== undefined) {
+        // 指定连接却选不出来，有两种完全不同的原因，混为一谈就是假诊断：
+        //   - 这个 uid 根本不在账号池里 → 真「连接不存在（可能已被删除）」
+        //   - uid 在池里，只是这一轮被 `tried` 挡掉 → 它**刚才已经试过并失败**了，
+        //     trace 里正躺着上游给的真实原因（如 quota / 4008「额度已用完」）。
+        //     此处若照旧覆盖，会把「积分用完」说成「连接不存在」——2026-10-14
+        //     实测：0 积分号测出「连接不存在（可能已被删除）」，而它明明在面板上。
+        if (onlyUid !== undefined && !tried.has(onlyUid) && trace !== undefined) {
           // 不给 AccountState 加「连接不存在」这个值：那是给**账号的失败**分类用的
           // （决定要不要冷却），而链接不存在不是任何账号的错，混进去会让所有分类逻辑
           // 都要认识它。具体原因放 lastError 就够。
@@ -1315,7 +1355,7 @@ export class Router {
           }
           return false
         }
-        pool.noteFailure(uid, req.model, r.state, r.message)
+        pool.noteFailure(uid, req.model, r.state, r.message, r.resetAt)
         // 故障切走：下次选号会换号，旧块的驻留计数不再适用（前缀归属变了）
         pool.dropBlock(req.model)
         if (trace !== undefined) {

package/src/router/supplier-switch.test.ts

@@ -218,3 +218,94 @@ test('指定不存在的连接：明确报「连接不存在」，而不是静
   assert.equal(a.calls, 0, '一个号都不该被试')
   assert.match(r.error ?? '', /不存在/)
 })
+
+test('指定连接失败：报上游真实原因，不许说成「连接不存在」', async () => {
+  // 2026-10-14 实测：0 积分号（uid 在池里、面板上看得见）测出来是
+  // 「连接 "4135677434275728" 不存在（可能已被删除）」——真话是额度用完。
+  // 机制：失败后 `continue`，下一轮 onlyUid 被 `tried` 挡掉 → uid undefined，
+  // 旧代码在那里无条件覆盖 lastError，把上游原因冲掉。假诊断比没有诊断更坏：
+  // 用户会去删链接、重新登录，而正解是充值。
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  a.s.accounts = () => [
+    { uid: 'broke', credits: 0, state: 'ok' },
+    { uid: 'rich', credits: 100, state: 'ok' },
+  ]
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  const seen: string[] = []
+  a.s.chatOnce = async (uid) => {
+    seen.push(uid)
+    return { ok: false, state: 'quota', message: 'Your requests have exceeded the quota.' }
+  }
+  add(router, a.s)
+
+  const r = await router.testModel('supA', 'a-model', 'broke')
+  assert.equal(r.ok, false)
+  assert.deepEqual(seen, ['broke'], '钉死单连接，失败也不换号')
+  assert.match(r.error ?? '', /quota|exceeded/, `要报上游真因，实际: ${r.error}`)
+  assert.doesNotMatch(r.error ?? '', /不存在/, 'uid 在池里，绝不是「不存在」')
+})
+
+// ---- 积分用完的号必须退出路由（插件报 quota → 核心不选它） ----
+// 端到端串起来：traework 的 pool.list() 在 credits===0 时报 quota，核心 pick()
+// 据此跳过该号。这条走真实入口 chatCompletions，钉住「报出的事实真的改变了路由」，
+// 而不只是「状态字符串好看」。
+
+test('插件报 quota 的号：请求直接落到还有额度的号，不去撞死号', async () => {
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  const tried: string[] = []
+  a.s.accounts = () => [
+    { uid: 'broke', credits: 0, state: 'quota' },
+    { uid: 'rich', credits: 500, state: 'ok' },
+  ]
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  a.s.chatOnce = async (uid) => {
+    tried.push(uid)
+    return { ok: true, status: 200, body: '{"ok":1}' }
+  }
+  add(router, a.s)
+
+  await router.chatCompletions(reqWith('supA/a-model'), fakeRes())
+
+  assert.deepEqual(tried, ['rich'], '一次都不该撞到积分用完的号')
+})
+
+test('积分用完的号恢复（充值后报 ok）：立刻重新参与路由，无需重启', async () => {
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  let broke = true
+  const tried: string[] = []
+  a.s.accounts = () => (broke
+    ? [{ uid: 'was-broke', credits: 0, state: 'quota' }, { uid: 'other', credits: 10, state: 'ok' }]
+    : [{ uid: 'was-broke', credits: 900, state: 'ok' }])
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  a.s.chatOnce = async (uid) => {
+    tried.push(uid)
+    return { ok: true, status: 200, body: '{"ok":1}' }
+  }
+  add(router, a.s)
+
+  await router.chatCompletions(reqWith('supA/a-model'), fakeRes())
+  assert.deepEqual(tried, ['other'], '没额度时不选它')
+
+  broke = false
+  await router.chatCompletions(reqWith('supA/a-model'), fakeRes())
+  assert.equal(tried[1], 'was-broke', '充值后立刻回到候选')
+})
+
+test('全池都没额度：如实失败，不假装成功也不无限转圈', async () => {
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  a.s.accounts = () => [
+    { uid: 'b1', credits: 0, state: 'quota' },
+    { uid: 'b2', credits: 0, state: 'quota' },
+  ]
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  a.s.chatOnce = async () => ({ ok: true, status: 200, body: '{"ok":1}' })
+  add(router, a.s)
+
+  const r = await router.testModel('supA', 'a-model')
+  assert.equal(r.ok, false, '没号可选就是失败')
+  assert.equal(a.calls, 0, '不该去撞任何一个已知没额度的号')
+})

package/src/router/types.ts

@@ -3,7 +3,7 @@
  * 每个供应商提供 OpenAI 兼容的 chat/models，并暴露面板状态。
  * 仿 9router：供应商 = 一种"免费/付费"通道；dsh-router 在其上做路由。
  */
-import type { ChatOnceResult, SupplierAccountNow } from '../suppliers/contract.ts'
+import type { AccountState, ChatOnceResult, SupplierAccountNow } from '../suppliers/contract.ts'
 import type { AccountPool } from './account-pool.ts'
 
 /** 面板展示的账号状态（脱敏）。 */
@@ -11,6 +11,14 @@ export interface SupplierAccount {
   uid: string
   nickname?: string
   credits: number
+  /**
+   * 插件解读上游信号后的语义状态（`quota` = 额度/积分用完，`session_dead` = 凭证失效）。
+   *
+   * `decorate()` 一直原样带出插件报的状态，核心选号也读它（`quota`/`session_dead`
+   * 的号不进候选）——面板类型里缺了这一格就会自相矛盾：号明明已被排除在路由之外，
+   * 界面上却只看得到「0 积分」，看不出它为什么不参与。
+   */
+  state?: AccountState
   cooling: boolean
   until?: string
   reason?: string
@@ -53,9 +61,13 @@ export interface ChatRequest {
   /** 推理等级（reasoning effort），供应商各自决定怎么映射到上游。缺省 = 'auto'。 */
   lv?: string
   /**
-   * 宿主盖的会话身份（dsh-llm `GenerateOptions.sessionId`），由 adapter 转成
-   * 内部头带进来。用于把用量记录**按会话归因**（「最近命中」徽章要按当前会话
-   * 显示，而不是显示别的会话的命中）。缺省 = 非宿主调用（外部 OpenAI 客户端）。
+   * 调用方身份（归因键）。来源两种：
+   *   1. 宿主会话身份（dsh-llm `GenerateOptions.sessionId`，adapter 转成内部头
+   *      `x-dsh-router-session`）——形式 `session-<uuid>`；
+   *   2. 外部 OpenAI 兼容客户端的 `user` 字段（Zed/IDE 等多客户端场景）——形式
+   *      `ext:<user>`，前缀标明「这不是宿主会话」。
+   * 用途：把用量记录**按调用方归因**（「最近命中」徽章按当前会话显示；出事时
+   * 能反查是哪个客户端在打）。缺省 = 匿名外部客户端。
    */
   session?: string
 }

package/src/router/usage-store.ts

@@ -55,8 +55,10 @@ export interface UsageRecord {
   /** 失败原因（ok=false 时）。 */
   error?: string
   /**
-   * 宿主会话身份（有则记）。用于「最近命中」按当前会话归因 —— 徽章要显示
-   * 当前会话的命中，而不是全局最近（team 多会话下后者会张冠李戴）。
+   * 调用方身份（有则记）：宿主会话 id（`session-<uuid>`）或外部 OpenAI 客户端
+   * 标签（`ext/…`，见 shared.ts 的 clientIdentityOf）。用于「最近命中」按当前
+   * 会话归因（徽章要显示当前会话的命中，而不是全局最近），出事时也能反查
+   * 是哪个客户端在打。
    */
   session?: string
 }

package/src/shared.test.ts

@@ -0,0 +1,35 @@
+/**
+ * 外部 OpenAI 客户端归因标签（clientIdentityOf）的闸门。
+ *
+ * 2026-10-15 事故反查暴露的盲区：`/v1` 没有宿主内部头的请求全落成匿名
+ * usage 记录（296 条对不上任何会话）。这里锁住三级兜底的优先级与边界。
+ * 用 node --test 跑（Node 原生 TS 剥离，零新依赖）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { clientIdentityOf } from './shared.ts'
+
+test('归因优先级：user > prompt_cache_key > User-Agent', () => {
+  assert.equal(clientIdentityOf({ user: 'zed-thread-1', prompt_cache_key: 'k' }, 'Zed/0.2'), 'ext/user:zed-thread-1')
+  assert.equal(clientIdentityOf({ prompt_cache_key: 'k1' }, 'Zed/0.2'), 'ext/cache:k1')
+  assert.equal(clientIdentityOf({}, 'Zed/0.2'), 'ext/ua:Zed/0.2')
+  assert.equal(clientIdentityOf({}, undefined), undefined, '什么都没有 → 保持匿名')
+})
+
+test('空串/非字符串的 user 与 prompt_cache_key 当没有，落 UA 兜底', () => {
+  assert.equal(clientIdentityOf({ user: '' }, 'Zed/0.2'), 'ext/ua:Zed/0.2')
+  assert.equal(clientIdentityOf({ user: 123 }, 'Zed/0.2'), 'ext/ua:Zed/0.2')
+  assert.equal(clientIdentityOf({ user: '', prompt_cache_key: '' }, ''), undefined)
+})
+
+test('值截断到 64 字符（防超长标识灌进 usage 记录）', () => {
+  const long = 'x'.repeat(100)
+  assert.equal(clientIdentityOf({ user: long }, undefined), `ext/user:${'x'.repeat(64)}`)
+  assert.equal(clientIdentityOf({}, long), `ext/ua:${'x'.repeat(64)}`)
+})
+
+test('宿主会话 id 形态与外部标签形态不撞（lastHit 过滤互不误命中）', () => {
+  const host = 'session-72847baa-e309-42ad-aa6b-15107cdc6518'
+  const ext = clientIdentityOf({ user: '72847baa-e309-42ad-aa6b-15107cdc6518' }, undefined)
+  assert.notEqual(ext, host, '前缀区分宿主/外部，精确匹配过滤不会串')
+})

package/src/shared.ts

@@ -25,6 +25,12 @@ export interface RouterAccount {
   uid: string
   nickname?: string
   credits: number
+  /**
+   * 插件解读上游信号后的语义状态（`quota` = 额度/积分用完，`session_dead` = 凭证失效）。
+   * 核心选号会跳过这些号，所以面板必须显示出来——否则界面写着「健康」，而路由
+   * 永远不选它，用户无从知道为什么。
+   */
+  state?: string
   cooling: boolean
   until?: string
   reason?: string
@@ -315,3 +321,25 @@ export interface RouterChartResponse {
   error?: string
   chart?: RouterChartBucket[]
 }
+
+/**
+ * 外部 OpenAI 兼容客户端的归因标签（`/v1` 没有宿主内部头 `x-dsh-router-session`
+ * 时的兜底）——否则 usage 记录里全是匿名流量，出事反查不出是谁在打
+ * （2026-10-15 实测：296 条匿名记录对不上任何会话）。
+ *
+ * 取值优先级：`user`（OpenAI 标准终端用户字段）→ `prompt_cache_key`
+ * （Zed 等客户端的缓存键，常带线程粒度）→ `User-Agent`（保底到客户端粒度）。
+ * 值截断到 64 字符；三者皆无返回 undefined（保持匿名）。
+ */
+export function clientIdentityOf(
+  body: { user?: unknown; prompt_cache_key?: unknown },
+  userAgent: string | undefined,
+): string | undefined {
+  const tag = (kind: string, v: unknown): string | undefined =>
+    typeof v === 'string' && v !== '' ? `ext/${kind}:${v.slice(0, 64)}` : undefined
+  return (
+    tag('user', body.user)
+    ?? tag('cache', body.prompt_cache_key)
+    ?? (userAgent !== undefined && userAgent !== '' ? `ext/ua:${userAgent.slice(0, 64)}` : undefined)
+  )
+}

package/src/suppliers/contract.ts

@@ -117,8 +117,13 @@ export type ChatOnceResult =
   | { ok: true; stream: ReadableStream<Uint8Array> }
   /** 非流式：核心写 JSON。 */
   | { ok: true; status: number; body: string }
-  /** 失败：核心据此做冷却/换号。 */
-  | { ok: false; state: AccountState; message: string }
+  /**
+   * 失败：核心据此做冷却/换号。
+   * `resetAt` = 上游自己声明的重置时刻（epoch ms，可选）：限流类错误带它时
+   * 核心冷却到该点，而不是指数退避——频率配额的重置是小时级的，5min 上限的
+   * 退避只会到点回来再撞（2026-10-15 的 6004 事故：11 个号轮流被打冷）。
+   */
+  | { ok: false; state: AccountState; message: string; resetAt?: number }
 
 /** 供应商模块 —— 契约（核心必须，差异化可选）。 */
 export interface SupplierModule {

package/src/suppliers/loader.test.ts

@@ -215,3 +215,56 @@ test('用户目录只加载 *.js，且同 id 后者覆盖前者（按文件名
   assert.equal(suppliers[0]?.supplier.name, 'Second')
   assert.equal(suppliers[0]?.source, 'user')
 })
+
+// ---------------------------------------------------------------------------
+// 插件报的「额度用完」要真的进路由（end-to-end 的那一段线）
+// ---------------------------------------------------------------------------
+
+/**
+ * 造一个报 quota 的插件（模拟 traework 的 pool.list()：credits===0 → state quota）。
+ * 这条钉住 loader 的 `accounts()` 是**原样透传**插件状态（不带 decorate/hydrate）：
+ * 核心 pick() 读的就是它。哪天有人给它加一层加工，把 quota 抹成 ok，路由又会
+ * 去撞没额度的号，而面板还显示正常——所以这里必须红。
+ */
+function quotaPlugin(id: string): SupplierModule {
+  const accounts: SupplierAccountNow[] = [
+    { uid: 'u-broke', credits: 0, state: 'quota' },
+    { uid: 'u-rich', credits: 500, state: 'ok' },
+  ]
+  return {
+    id,
+    name: id,
+    status: () => ({ id, name: id, accounts }),
+    listModels: () => [],
+    getAlias: () => id,
+    chatOnce: async (_uid: string, _req: ChatRequest): Promise<ChatOnceResult> => ({ ok: true, status: 200, body: '{}' }),
+    dispose: () => {},
+  } as unknown as SupplierModule
+}
+
+test('插件报的 quota 原样到达核心 → 没额度的号不进选号', () => {
+  const { env: e } = env()
+  const { supplier } = wrapModule(quotaPlugin('traework'), e, 'test')
+  assert.equal(
+    supplier.accounts().find((a) => a.uid === 'u-broke')?.state,
+    'quota',
+    'accounts() 必须原样带出插件状态（核心 pick 读的就是它）',
+  )
+  assert.equal(supplier.pool.pick(supplier.accounts(), [], 'm1'), 'u-rich', '额度用完的号被跳过')
+})
+
+test('额度用完的号在面板上也能看出来（decorate 不吞掉插件报的 state）', () => {
+  const { env: e } = env()
+  const { supplier } = wrapModule(quotaPlugin('traework'), e, 'test')
+  const shown = supplier.status().accounts.find((a) => a.uid === 'u-broke')
+  assert.equal(shown?.state, 'quota', '面板要能区分「没额度」与「正常」')
+  assert.equal(shown?.cooling, false, '还没发生过失败，就不该标成冷却')
+})
+
+test('额度用完 ≠ -1：water 后积分真值 0 照旧落进核心缓存（不冲值、不误判）', () => {
+  const { env: e, store } = env()
+  const { supplier } = wrapModule(quotaPlugin('traework'), e, 'test')
+  supplier.status() // 触发 hydrateCredits
+  assert.equal(store.get('traework').credits['u-broke'], 0, '0 是真值，要落盘')
+  assert.equal(store.get('traework').credits['u-rich'], 500)
+})

package/src/suppliers/opencode/plugin.test.ts

@@ -1,17 +1,24 @@
 /**
- * opencode(Zen 免费档)握手契约测试 —— 锁住 2026-09-22 实测的那组硬门。
+ * opencode(OpenCode Zen 免费档)握手契约测试 —— 锁住 2026-10-15 实测的那组硬门。
  *
- * 为什么值得固化：这四条**都不是可选优化，缺一即 403**
+ * 为什么值得固化：这些**都不是可选优化，缺一即 403**
  * `FreeTierError: OpenCode's free tier can only be used from within OpenCode`。
- * 它们全是「看不出来」的那种约定——代码删掉一行 headers、或把 UA 改回
- * `opencode`，单测本该立刻变红，否则下次只能在真机对话里发现整个供应商死了。
+ * 它们全是「看不出来」的那种约定——代码删掉一行、或把端点/工具名改回去，
+ * 单测本该立刻变红，否则下次只能在真机对话里发现整个供应商死了。
  *
- * 实测依据（2026-09-22，逐项消融验证）：
- *   - UA 必须带版本且 ≥1.18：裸 `opencode`→403；`opencode/1.17.x`→426；1.18.0 起 200
- *   - 必须同时有 `x-opencode-session`/`x-opencode-request`，且形状是
- *     `ses_<12hex><14base62>` / `msg_<同形状>`——格式错也 403
- *   - tools 里必须**同时**有 bash 和 read，只给一个也 403
- *   - 非流式（`stream:false`）即使三样齐全也 403 → 必须恒发 stream:true
+ * 实测依据（2026-10-15，逐项消融 + 单因子隔离）：
+ *   - 端点必须是 `/inference/v1/chat/completions`：`/zen/v1` 已废弃，
+ *     对任何头部/工具组合一律 403（旧实现死在这里）
+ *   - `tools` 里必须存在**小写精确名为 `read`** 的工具：
+ *     `read` 单独→200；`bash`/`glob`/`write`/`shell` 单独→403；
+ *     `read` 改名 `READ`→403；但 `read` 的 `parameters` 完全不看
+ *     （`properties:{}`、无 `parameters`、`parameters:null` 全 200）
+ *   - session 的 12 位 hex 前缀必须是倒序时间戳且低 12 位 ∈ [0,63]：
+ *     纯随机 hex→403、sha256 派生→403、counter=64/300→403
+ *   - 非流式（`stream:false`）即使其余齐全也 403 → 必须恒发 stream:true
+ *
+ * 已实测**不敏感**（故不作为断言，改回旧值也不算错）：UA 具体版本、
+ * `x-opencode-client` 的 cli/desktop、工具 description。
  *
  * 用 node --test 跑（Node 原生剥 TS 类型）：
  *   node --test src/suppliers/opencode/plugin.test.ts
@@ -28,6 +35,19 @@ import type { ChatRequest } from '../../router/types.ts'
 const SES_RE = /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/
 const MSG_RE = /^msg_[0-9a-f]{12}[0-9A-Za-z]{14}$/
 
+/** 上游免费档的推理端点。`/zen/v1` 已废弃，出现即回归。 */
+const EXPECTED_CHAT_URL = 'https://opencode.ai/inference/v1/chat/completions'
+
+/**
+ * 从 session id 还原出 counter：12 位 hex 是 `~(ts * 0x1000 + counter)`，
+ * 故先取反还原 `ts * 0x1000 + counter`，再取低 12 位即 counter
+ * （`ts * 0x1000` 的低 12 位恒为 0）。
+ */
+function invertedCounter(id: string): bigint {
+  const time = BigInt('0x' + id.slice(4, 16))
+  return ~time & 0xffffffffffffn & 0xfffn
+}
+
 interface Captured {
   url: string
   headers: Record<string, string>
@@ -70,25 +90,38 @@ function request(over: Partial<ChatRequest> = {}): ChatRequest {
   }
 }
 
-test('chatOnce 必须带版本化 UA + 合法形状的 session/request 头', async () => {
+test('chat 必须打 /inference/v1（/zen/v1 已废弃，全组合 403）', async () => {
   const stub = stubFetch()
   try {
     const r = await makePlugin().chatOnce('', 'auto', request())
     assert.equal(r.ok, true, '握手齐全时应当成功')
-    const h = stub.captured[0]!.headers
+    assert.equal(stub.captured[0]!.url, EXPECTED_CHAT_URL, '/zen/v1 是本次故障根因，不得回退')
+  } finally {
+    stub.restore()
+  }
+})
 
-    // UA 必须带版本号（裸 'opencode' 会被上游按非 CLI 拒掉）
-    assert.match(h['User-Agent'] ?? '', /^opencode\/\d+\.\d+/, 'UA 必须带 opencode/ 版本号')
+test('session 的 12 位 hex 必须是倒序时间戳，低 12 位 counter ∈ [0,63]', async () => {
+  const stub = stubFetch()
+  try {
+    await makePlugin().chatOnce('', 'auto', request())
+    const h = stub.captured[0]!.headers
 
-    // session/request 形状不对上游是**拒绝**而不是忽略 —— 形状必须严格
+    // 形状不对上游是**拒绝**而不是忽略 —— 形状必须严格
     assert.match(h['x-opencode-session'] ?? '', SES_RE, 'x-opencode-session 形状不对会被 403')
     assert.match(h['x-opencode-request'] ?? '', MSG_RE, 'x-opencode-request 形状不对会被 403')
+
+    // 纯随机 hex 与 sha256 派生 hex 都落不进 [0,63] 窗口 → 必然 403
+    for (const key of ['x-opencode-session', 'x-opencode-request'] as const) {
+      const counter = invertedCounter(h[key]!)
+      assert.ok(counter <= 63n, `${key} 的 counter 必须 ∈ [0,63]（实测 64/300 会 403），得到 ${counter}`)
+    }
   } finally {
     stub.restore()
   }
 })
 
-test('请求体恒为流式，且 tools 同时含 bash 与 read', async () => {
+test('tools 必须含小写 read；bash 不是门，且不得被注入（旧实现的回归点）', async () => {
   const stub = stubFetch()
   try {
     // 调用方明确要非流式 —— 上游免费档对非流式一律 403，插件必须翻成流式
@@ -96,32 +129,53 @@ test('请求体恒为流式，且 tools 同时含 bash 与 read', async () => {
     const body = stub.captured[0]!.body
     assert.equal(body.stream, true, '免费档只支持流式，非流式必须翻成 stream:true')
 
-    const names = (body.tools as Array<{ function?: { name?: string } }>).map((t) => t.function?.name)
-    assert.ok(names.includes('bash'), 'tools 缺 bash 会被 403')
+    const tools = body.tools as Array<{ function?: { name?: string } }>
+    const names = tools.map((t) => t.function?.name)
     assert.ok(names.includes('read'), 'tools 缺 read 会被 403')
+    // 实测：bash 不是门（bash 单独 → 403），注入它只会污染调用方的工具表
+    assert.equal(names.includes('bash'), false, 'bash 不是免费档的门，不该被注入')
+    assert.equal(tools.length, 1, '无调用方工具时只应补 read 一个占位')
+  } finally {
+    stub.restore()
+  }
+})
+
+test('read 的 parameters 不被检查（空 schema 即可通过）', async () => {
+  const stub = stubFetch()
+  try {
+    await makePlugin().chatOnce('', 'auto', request())
+    const tools = stub.captured[0]!.body.tools as Array<{ function: { name: string; parameters?: unknown } }>
+    const read = tools.find((t) => t.function.name === 'read')!
+    // 上游只看名字，故占位用空 properties 是对的（别"补"成真 schema 增加噪音）
+    assert.deepEqual(read.function.parameters, { type: 'object', properties: {} })
   } finally {
     stub.restore()
   }
 })
 
-test('调用方自带的同名工具不被占位工具覆盖（bash/read 只补缺）', async () => {
+test('调用方自带的同名工具不被占位工具覆盖（read 只补缺）', async () => {
   const stub = stubFetch()
   try {
+    const realRead = {
+      type: 'function',
+      function: { name: 'read', description: 'REAL READ', parameters: { type: 'object', properties: { filePath: { type: 'string' } } } },
+    }
     const realBash = {
       type: 'function',
       function: { name: 'bash', description: 'REAL BASH', parameters: { type: 'object', properties: { command: { type: 'string' } } } },
     }
     await makePlugin().chatOnce('', 'auto', request({
-      rawBody: JSON.stringify({ model: 'big-pickle', messages: [], stream: true, tools: [realBash] }),
+      rawBody: JSON.stringify({ model: 'big-pickle', messages: [], stream: true, tools: [realRead, realBash] }),
     }))
     const tools = stub.captured[0]!.body.tools as Array<{ function: { name: string; description?: string } }>
 
-    const bash = tools.filter((t) => t.function.name === 'bash')
-    assert.equal(bash.length, 1, 'bash 不能被注入成两条（否则真实工具签名被挤掉）')
-    assert.equal(bash[0]!.function.description, 'REAL BASH', '调用方自己的定义必须原样保留')
+    const read = tools.filter((t) => t.function.name === 'read')
+    assert.equal(read.length, 1, 'read 不能被注入成两条（否则真实工具签名被挤掉）')
+    assert.equal(read[0]!.function.description, 'REAL READ', '调用方自己的定义必须原样保留')
+    assert.equal(tools.length, 2, '已有 read 时不该再补任何占位')
 
-    // read 缺失 → 补上；bash 已有 → 不重复
-    assert.ok(tools.some((t) => t.function.name === 'read'), '缺的 read 要补上')
+    // 调用方的 bash 必须原样留着（它不是门，但也绝不能被删）
+    assert.equal(tools.filter((t) => t.function.name === 'bash').length, 1, '调用方的 bash 不得被动')
   } finally {
     stub.restore()
   }