dsh-router-core 0.4.4 → 0.4.6

package/src/index.ts

@@ -33,7 +33,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { join } from 'node:path'
 import Schema from '@deepseek-ai/schemastery'
-import { ROUTER_API_BASE, type RouterPeriod } from './shared.ts'
+import { ROUTER_API_BASE, type RouterPeriod, clientIdentityOf } from './shared.ts'
 import { Router } from './router/index.ts'
 import { RouterAdapter, type RouterAttachmentStore } from './llm/adapter.ts'
 import { KeysStore } from './keys.ts'
@@ -162,6 +162,11 @@ export function apply(rawContext: unknown): void {
     get: (key: string) => unknown
     on: (name: string, listener: (...args: unknown[]) => void) => unknown
     provide: (name: string, value: unknown) => unknown
+    /**
+     * 广播宿主事件。组合增删改后必须用它发 `llm/adapters-updated`，
+     * 否则模型选择器一直拿着旧快照（见 `Router` 的 `onCombosChanged` 注释）。
+     */
+    emit: (name: string, ...args: unknown[]) => unknown
     webServer: WebServer
     llm?: Llm
     logger: { info: (message: string) => void; warn: (message: string) => void }
@@ -193,7 +198,13 @@ export function apply(rawContext: unknown): void {
   }
   const store = new SupplierConfigStore(stateFile)
   const credentials = new CredentialStore(join(dataDir, 'auths'))
-  const router = new Router(stateFile, store, log)
+  // 组合增删改后广播 `llm/adapters-updated`：模型选择器的目录是客户端缓存的，
+  // 只在这个（宿主已转发给客户端的）事件上失效重载。不发它就出现「面板里有、
+  // 选择器里找不到/切不过去」（2026-10-14 实测）。
+  // 该事件在宿主侧是纯通知（payload-free），监听方都是幂等的重读，重复发安全。
+  const router = new Router(stateFile, store, log, {
+    onCombosChanged: () => { ctx.emit('llm/adapters-updated') },
+  })
 
   const keys = new KeysStore(stateFile)
 
@@ -352,9 +363,9 @@ export function apply(rawContext: unknown): void {
       writeJson(res, 413, { error: { message: 'request body too large', type: 'api_error', code: 'request_too_large' } })
       return
     }
-    let peek: { stream?: boolean; model?: string; reasoning_effort?: unknown }
+    let peek: { stream?: boolean; model?: string; reasoning_effort?: unknown; user?: unknown; prompt_cache_key?: unknown }
     try {
-      peek = JSON.parse(body) as { stream?: boolean; model?: string; reasoning_effort?: unknown }
+      peek = JSON.parse(body) as { stream?: boolean; model?: string; reasoning_effort?: unknown; user?: unknown; prompt_cache_key?: unknown }
     } catch {
       writeJson(res, 400, { error: { message: 'invalid JSON body', type: 'api_error', code: 'invalid_request' } })
       return
@@ -362,9 +373,12 @@ export function apply(rawContext: unknown): void {
     const lv = typeof peek.reasoning_effort === 'string' && peek.reasoning_effort !== ''
       ? peek.reasoning_effort
       : 'auto'
-    // 宿主会话身份（adapter 从 GenerateOptions.sessionId 转来的内部头）；外部客户端没有。
+    // 调用方身份：宿主会话内部头（adapter 从 GenerateOptions.sessionId 转来）
+    // 优先；外部客户端没有内部头，用 user/prompt_cache_key/UA 兜底归因——
+    // 否则 usage 记录全是匿名，反查不出是哪个客户端在打。
     const sessionRaw = req.headers['x-dsh-router-session']
-    const session = typeof sessionRaw === 'string' && sessionRaw !== '' ? sessionRaw : undefined
+    const session = (typeof sessionRaw === 'string' && sessionRaw !== '' ? sessionRaw : undefined)
+      ?? clientIdentityOf(peek, req.headers['user-agent'])
     await router.chatCompletions(
       {
         rawBody: body,

package/src/llm/adapter.test.ts

@@ -156,6 +156,60 @@ test('出口：空的 finish_reason 不许冲掉后面那个真终止原因', as
   assert.deepEqual(reason, { kind: 'tool-calls' })
 })
 
+test('出口：上游报 stop 却发了完整工具调用时，必须以 tool-calls 收尾', async () => {
+  // 真实事故（2026-10-15，traework 上游 + Delta 客户端）：带 tools 的请求上，
+  // 上游正常发出完整的 tool_calls（参数逐片拼全），收尾帧却写
+  // `finish_reason: "stop"` —— 与 OpenAI 契约不符（有工具调用应为 tool_calls）。
+  //
+  // 修复前 mapFinishReason('stop') 直接给 kind='stop'，而「无内容」兜底又因
+  // 为有内容不触发，于是已攒好的工具块被静默丢弃；调用方据此认为「本轮结束、
+  // 没有工具要执行」，表现为「模型能对话但工具永远调不动」（Delta 侧即
+  // 「test 能访问但 tool 调用不了」）。
+  const reason = await finishOf(
+    frame({ choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', function: { name: 'bash', arguments: '{"command":"ls"}' } }] } }] }),
+    frame({ choices: [{ delta: {}, finish_reason: 'stop' }] }),
+    '[DONE]',
+  )
+  assert.deepEqual(reason, { kind: 'tool-calls' })
+})
+
+test('出口：stop + 工具调用时，工具块本身也要照常交出（不能只改收尾）', async () => {
+  const calls = await toolCallsOf(
+    frame({ choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', function: { name: 'bash', arguments: '{"command":"ls"}' } }] } }] }),
+    frame({ choices: [{ delta: {}, finish_reason: 'stop' }] }),
+    '[DONE]',
+  )
+  assert.deepEqual(calls, [{ type: 'tool-call', id: 'call_1', name: 'bash', arguments: '{"command":"ls"}' }])
+})
+
+test('出口：stop 且没有工具调用时，仍然收尾为 stop（不能误报 tool-calls）', async () => {
+  // 反向判据：修复不能把普通对话也标成 tool-calls，否则调用方会空等工具结果。
+  const reason = await finishOf(frame({ choices: [{ delta: { content: 'hello' }, finish_reason: 'stop' }] }), '[DONE]')
+  assert.deepEqual(reason, { kind: 'stop' })
+})
+
+test('出口：length 截断即使带了工具调用也不能改成 tool-calls', async () => {
+  // `length` 必须原样透传：dsh-llm 的 assembled() 靠 `finish.kind === 'max-tokens'`
+  // 丢弃被截断的工具调用，改成 tool-calls 等于把半截调用放出去执行。
+  const reason = await finishOf(
+    frame({ choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', function: { name: 'bash', arguments: '{"command":"ls"}' } }] } }] }),
+    frame({ choices: [{ delta: {}, finish_reason: 'length' }] }),
+    '[DONE]',
+  )
+  assert.deepEqual(reason, { kind: 'max-tokens' })
+})
+
+test('出口：stop + 参数残缺的工具调用时，仍判 error（半成品不许当有效调用）', async () => {
+  // 与上一条互补：`stop` 只在工具块**完整**时才提升为 tool-calls。
+  // 参数残缺时既有逻辑已把 pendingFinish 改成 error，不能被这条修复绕过去。
+  const reason = await finishOf(
+    frame({ choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', function: { name: 'bash', arguments: '{"command": "cd' } }] } }] }),
+    frame({ choices: [{ delta: {}, finish_reason: 'stop' }] }),
+    '[DONE]',
+  )
+  assert.equal(reason?.kind, 'error')
+})
+
 test('出口：未知终止原因必须带非空 code（agent-loop 会拿它重建 LlmError）', async () => {
   const reason = await finishOf(frame({ choices: [{ delta: { content: 'x' }, finish_reason: 'content_filter' }] }), '[DONE]')
   assert.equal(reason?.kind, 'error')

package/src/llm/adapter.ts

@@ -444,13 +444,35 @@ export async function* translateSse(payloads: AsyncIterable<string> | Iterable<s
         const usage = toTokenUsage(accumulated)
         if (usage !== null) yield { type: 'usage', usage }
       }
+      // 上游报 `stop` **却发了工具调用**时，必须以 tool-calls 收尾。
+      //
+      // 为什么（2026-10-15 实测）：traework 上游在带 tools 的请求上正常发出
+      // 完整的 tool_calls（参数逐片拼全），收尾帧却写 `finish_reason: "stop"`
+      // ——与 OpenAI 契约不符（有工具调用应为 `tool_calls`）。而 mapFinishReason
+      // 只看 reason 字面量，于是 kind='stop'，下面那个 `order.length === 0` 的
+      // 兜底又因为「有内容」不触发，最终以 stop 收尾 → **已攒好的工具块被静默
+      // 丢弃**，调用方（Delta 等）据此认为「本轮结束、没有工具要执行」，表现为
+      // 「模型能对话但工具永远调不动」。
+      //
+      // 判据用 `complete` 而不是 `order`：只有**参数拼全**的工具块才配提升为
+      // tool-calls。注意在当前逻辑下两者等价——参数残缺时上面的 `pendingFinish`
+      // 已经把它改成 error，`reason.kind` 就不是 'stop'，根本走不到这里；
+      // 仍写 `complete` 是因为语义直接（「完整的工具调用」），且不依赖那个
+      // 副作用：哪天 error 分支挪走或放宽，这里不会跟着把半成品放行。
+      //
+      // 只改 `stop`：`length`（截断）必须原样透传 —— dsh-llm 的 assembled()
+      // 正是靠 `finish.kind === 'max-tokens'` 去丢弃被截断的工具调用，
+      // 改掉它就等于把半截调用放出去执行。
+      const hasCompleteToolCall = complete.some((block) => block.kind === 'tool-call')
       const reason = pendingFinish ?? { kind: 'stop' }
+      const resolved =
+        reason.kind === 'stop' && hasCompleteToolCall ? { kind: 'tool-calls' } : reason
       yield {
         type: 'finish',
         reason:
-          reason.kind === 'stop' && order.length === 0
+          resolved.kind === 'stop' && order.length === 0
             ? { kind: 'error', failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE } }
-            : (reason as never),
+            : (resolved as never),
       }
       return
     }

package/src/router/account-pool.test.ts

@@ -517,6 +517,80 @@ test('状态表：各 AccountState 的处置符合预期', () => {
   assert.equal(p.pick(list, [], 'm1'), undefined, '四个号都不可服务')
 })
 
+// ---- 插件报的额度/凭证状态直接进选号 ----
+// 分工：插件报「现在怎么了」，核心决定「怎么办」。积分用完（quota）/凭证失效
+// （session_dead）要靠充值/重登才能恢复，选它必是白撞一次——而且 traework 的
+// 积分耗尽失败发生在流已提交之后（HTTP 200 + 流内 4008），这次请求救不回来。
+// 所以必须在**选号阶段**就排除，不能等失败后记账。
+
+test('报 quota 的号不进选号（额度用完，选它必白撞）', () => {
+  const p = pool()
+  const list: SupplierAccountNow[] = [
+    { uid: 'broke', credits: 0, state: 'quota' },
+    { uid: 'rich', credits: 100, state: 'ok' },
+  ]
+  assert.equal(p.pick(list, ['broke', 'rich'], 'm1'), 'rich', '池顺序在前也没用，用不了的号跳过')
+})
+
+test('报 session_dead 的号不进选号（凭证失效，要重登）', () => {
+  const p = pool()
+  const list: SupplierAccountNow[] = [
+    { uid: 'dead', credits: 100, state: 'session_dead' },
+    { uid: 'alive', credits: 1, state: 'ok' },
+  ]
+  assert.equal(p.pick(list, ['dead', 'alive'], 'm1'), 'alive')
+})
+
+test('全池都报 quota → 无号可选，且说明原因不是「都在冷却」', () => {
+  const p = pool()
+  const list: SupplierAccountNow[] = [
+    { uid: 'a', credits: 0, state: 'quota' },
+    { uid: 'b', credits: 0, state: 'quota' },
+  ]
+  assert.equal(p.pick(list, [], 'm1'), undefined)
+  assert.match(p.lastWhy, /额度|凭证/, '原因要能区分「没额度」和「冷却中」')
+})
+
+test('报 quota 的号恢复成 ok 后立刻回到候选（充值即自愈，无需重启）', () => {
+  const p = pool()
+  assert.equal(p.pick([{ uid: 'u', credits: 0, state: 'quota' }], [], 'm1'), undefined)
+  assert.equal(p.pick([{ uid: 'u', credits: 50, state: 'ok' }], [], 'm1'), 'u')
+})
+
+test('积分 0 但状态是 ok 的号照常可选（0 不等于「没额度」）', () => {
+  const p = pool()
+  // openrouter/nvidia 报的就是 credits: 0 + state: 'ok'（没有积分这个概念）。
+  // 核心不能自己拿 credits===0 当「用完了」，否则这些供应商会被整池排除。
+  const list: SupplierAccountNow[] = [{ uid: 'api-key', credits: 0, state: 'ok' }]
+  assert.equal(p.pick(list, [], 'm1'), 'api-key')
+})
+
+test('瞬时状态（transport/unknown/unavailable）不排除号：那是采样抖动，不是账号事实', () => {
+  const p = pool()
+  for (const state of ['transport', 'unknown', 'unavailable'] as const) {
+    const list: SupplierAccountNow[] = [{ uid: 'u', credits: 5, state }]
+    assert.equal(p.pick(list, [], 'm1'), 'u', `${state} 不该让号退出候选`)
+  }
+})
+
+test('会话绑定撞上报 quota 的号 → 换号，且 lastWhy 指出是额度问题', () => {
+  const p = pool()
+  const msgs = [{ role: 'user', content: 'hello' }]
+  const okList: SupplierAccountNow[] = [
+    { uid: 'bound', credits: 10, state: 'ok' },
+    { uid: 'other', credits: 10, state: 'ok' },
+  ]
+  assert.equal(p.pick(okList, [], 'm1', msgs), 'bound', '先绑到 bound')
+  // 该号积分耗尽后：同一会话必须换到别的号，不能继续钉在死号上
+  const brokeList: SupplierAccountNow[] = [
+    { uid: 'bound', credits: 0, state: 'quota' },
+    { uid: 'other', credits: 10, state: 'ok' },
+  ]
+  assert.equal(p.pick(brokeList, [], 'm1', msgs), 'other')
+  assert.match(p.lastWhy, /bound/, '要说清为什么没用原绑定')
+  assert.match(p.lastWhy, /额度|凭证/, '原因要指向额度/凭证，不是「冷却」')
+})
+
 /**
  * 处置对齐 9router：未知/瞬时错误**每次**短冷却（不再攒够 3 次）。
  */
@@ -586,3 +660,38 @@ test('【隔离】不同供应商的同名模型，各自独立冷却', () => {
   // B 供应商同名模型不受影响
   assert.equal(pb.pick(list, [], 'deepseek-v4-flash'), 'acc', 'B 池同名模型照常可用')
 })
+
+// ============ 限流冷却对齐上游声明的重置时刻（resetAt） ============
+
+/**
+ * 2026-10-15 事故：6004 文案自带「将在 … 重置」（小时级），但退避上限 5min →
+ * 到点回来再撞，11 个号轮流被打冷。锁住：带 resetAt 就冷到那个点；
+ * 过期/未带的 resetAt 退回指数退避（行为与改动前一致）。
+ */
+test('【resetAt】限流冷却到上游声明的重置时刻，而不是 5min 退避上限', () => {
+  const p = pool()
+  const list = accs(['a'])
+  const resetAt = Date.now() + 3 * 3600_000 // 3 小时后重置
+  p.noteFailure('a', 'm1', 'rate_limit', 'codebuddy 6004: 您的使用量已超出频率限制，将在 … 重置', resetAt)
+  const row = p.decorate(list, 'm1')[0]
+  assert.equal(row?.cooling, true)
+  assert.equal(row?.until === undefined ? 0 : new Date(row.until).getTime(), resetAt, '冷到上游重置点')
+  assert.equal(p.pick(list, [], 'm1'), undefined, '重置前不该再被选中')
+})
+
+test('【resetAt】过期的重置时刻退回指数退避；不带 resetAt 行为不变', () => {
+  const p = pool()
+  const list = accs(['a'])
+  // 上游报的重置时刻已过 → 退避（首档 2s 量级），不是「不冷」也不是冷很久
+  p.noteFailure('a', 'm1', 'rate_limit', '429', Date.now() - 1000)
+  const row = p.decorate(list, 'm1')[0]
+  const until = row?.until === undefined ? 0 : new Date(row.until).getTime()
+  assert.ok(until > Date.now(), '仍要冷')
+  assert.ok(until - Date.now() <= 60_000, '退回短退避，而不是按过期时刻冷')
+  // 不带 resetAt（其它供应商/文案没解析出）：同样短退避
+  const p2 = pool()
+  p2.noteFailure('b', 'm1', 'rate_limit', '429')
+  const row2 = p2.decorate(accs(['b']), 'm1')[0]
+  const until2 = row2?.until === undefined ? 0 : new Date(row2.until).getTime()
+  assert.ok(until2 > Date.now() && until2 - Date.now() <= 60_000)
+})

package/src/router/account-pool.ts

@@ -54,7 +54,9 @@ const SESSION_DEAD_COOLDOWN_MS = 30 * MINUTE
  *
  * 冷却策略对齐 9router 的 accountFallback / errorConfig：
  *  - `rate_limit` 用**指数退避**（9router 的 `backoff: true`）：偶发限流只
- *    短冷，持续限流越退越久，比固定 1 分钟两头不讨好要准。
+ *    短冷，持续限流越退越久，比固定 1 分钟两头不讨好要准。上游自己声明了
+ *    **重置时刻**（resetAt，如 6004「将在 … 重置」）时冷到该点——频率配额是
+ *    小时级的，退避上限（5min）只会到点回来再撞。
  *  - 未知/瞬时错误用**瞬时短冷却**（9router 默认分支 TRANSIENT_COOLDOWN_MS）：
  *    每次失败都冻结，坏号不会留在池里被下一个请求再选中。
  *
@@ -252,6 +254,25 @@ export class AccountPool {
     return c.until <= now
   }
 
+  /**
+   * 插件报的「现在状态」是否意味着这个号此刻不该被选中。
+   *
+   * 只认两种**账号级持久事实**（要靠外部动作才能恢复，不是抖动）：
+   *  - `quota` —— 额度/积分用完，充值才能恢复（traework 积分归零时报它）
+   *  - `session_dead` —— 凭证失效，重新登录才能恢复
+   *
+   * 其余一律不看：`transport`/`unknown`/`unavailable` 是插件某一次采样的瞬时
+   * 观察，拿它排除等于「一次抖动就踢号」，而且没有冷却计时器兜底；`rate_limit`
+   * 的指数退避由核心的冷却单元管，比状态采样准。
+   *
+   * 这是「插件只报现在怎么了、核心决定怎么办」的分工落地：插件报出它观察到
+   * 的事实，核心决定此刻不选它。恢复同样自动——充值/重登后插件报回 `ok`，
+   * 该号立刻回到候选（没有额外状态要清）。
+   */
+  private servableByReport(a: SupplierAccountNow | undefined): boolean {
+    return a?.state !== 'quota' && a?.state !== 'session_dead'
+  }
+
   /**
    * 为「某个模型」选一个健康账号 —— **会话亲和选号，无策略旋钮**。
    *
@@ -267,11 +288,17 @@ export class AccountPool {
    *     "策略"，是无会话身份时的替身。
    *  4. 块统计不驱动轮转（亲和已保证驻留），只保留 `BLOCK_MAX` 次不达标 →
    *     降权该号（缓存无效，可恢复）。
+   *  5. 插件报的 `quota`/`session_dead`（额度用完 / 凭证失效）→ **直接不选它**：
+   *     这类失败要靠充值/重登才能恢复，选它必是白撞一次（还有的供应商失败在
+   *     流已提交之后，这次请求根本救不回来）。见 `servableByReport`。
    *
    * 天花板：号数 < 并发会话数时必然有会话共用号 → 互踩，无法用选号手法消除
    * （缓存空间是账号侧物理限制）。见 docs/pool-sticky-block.md §10。
    *
-   * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
+   * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）。
+   *   `state` 会被读：`quota`/`session_dead` 的号不进候选（见 `servableByReport`）。
+   *   `credits` **不读** —— 不同供应商的 0 含义不同（openrouter/nvidia 的 0 是
+   *   「没有积分这个概念」），是否已用完由插件解读成 `state` 后报上来。
    * @param poolOrder 用户在面板拖出来的顺序（核心管）
    * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
    * @param messages 请求体的 messages（算亲和指纹的内容兜底）
@@ -286,9 +313,11 @@ export class AccountPool {
       ...poolOrder.filter((uid) => byUid.has(uid)),
       ...accounts.map((a) => a.uid).filter((uid) => !poolOrder.includes(uid)),
     ]
-    const healthy = ordered.filter((uid) => this.healthy(uid, modelId, now))
+    const healthy = ordered.filter(
+      (uid) => this.healthy(uid, modelId, now) && this.servableByReport(byUid.get(uid)),
+    )
     if (healthy.length === 0) {
-      this.lastWhy = '全池无健康号（都在冷却）'
+      this.lastWhy = '全池无健康号（都在冷却，或插件报的额度/凭证已不可用）'
       return undefined
     }
     // 缓存无效降权：该号缓存质量样本长期不达标 → 跳过它（可到期恢复）
@@ -309,8 +338,13 @@ export class AccountPool {
       why.push('该指纹无绑定（会话首次出现）')
     } else {
       if (!healthy.includes(bound)) {
-        const c = this.cooldowns.get(this.key(modelId, bound))
-        why.push(`原绑定 ${bound} 正在冷却${c?.reason ? `(${c.reason})` : ''}`)
+        const ba = byUid.get(bound)
+        if (!this.servableByReport(ba)) {
+          why.push(`原绑定 ${bound} 插件报额度/凭证不可用（${ba?.state}）`)
+        } else {
+          const c = this.cooldowns.get(this.key(modelId, bound))
+          why.push(`原绑定 ${bound} 正在冷却${c?.reason ? `(${c.reason})` : ''}`)
+        }
       } else if (!usable.includes(bound)) {
         why.push(`原绑定 ${bound} 被降权（本会话样本不达标）`)
       } else {
@@ -463,8 +497,13 @@ export class AccountPool {
     return `${this.supplierId}${SEP}${modelId}`
   }
 
-  /** 记录一次失败：按状态处置（冷却/退避），落在「(模型, 连接)」这个冷却单元上。 */
-  noteFailure(uid: string, modelId: string, state: AccountState, message: string): void {
+  /**
+   * 记录一次失败：按状态处置（冷却/退避），落在「(模型, 连接)」这个冷却单元上。
+   * `resetAt` = 上游声明的重置时刻（epoch ms）：限流退避优先冷到该点——
+   * 频率配额是小时级的，5min 上限的指数退避只会到点回来再撞 6004，
+   * 把号轮流打冷（2026-10-15 的 11 号全灭事故）。
+   */
+  noteFailure(uid: string, modelId: string, state: AccountState, message: string, resetAt?: number): void {
     const rule = RULES[state]
     if (rule.cooldown === 0) return // no_such_model 等：不冷不记
     // session_dead 是连接级冷却（登录态问题，跨该号所有模型），到期自愈——
@@ -482,7 +521,11 @@ export class AccountPool {
     if (rule.cooldown === 'backoff') {
       // 连续被限流 → 等级递进冷却；成功（noteSuccess）会清零等级
       e.backoffLevel = Math.min(e.backoffLevel + 1, BACKOFF_MAX_LEVEL)
-      e.until = Math.max(e.until, Date.now() + backoffMs(e.backoffLevel))
+      const backoffUntil = Date.now() + backoffMs(e.backoffLevel)
+      // 上游自己报了重置时刻就冷到那个点（且不低于已有的更长冷却）；过期/
+      // 未报的 resetAt 退回指数退避。
+      const until = resetAt !== undefined && resetAt > Date.now() ? resetAt : backoffUntil
+      e.until = Math.max(e.until, until)
       return
     }
     if (rule.cooldown === 'transient') {

package/src/router/combo-change.test.ts

@@ -0,0 +1,125 @@
+/**
+ * 组合变更必须通知拓扑观察者 —— `onCombosChanged` 的出口判据。
+ *
+ * ⚠️ 为什么需要它（2026-10-14 实测的「面板里有，模型选择器里找不到」）：
+ *   模型选择器（`ui-model-selection`）的模型目录是**客户端缓存**的：每个浏览器
+ *   连接只 `load()` 一次，之后只在宿主转发的事件上失效重载
+ *   （`llm/adapters-updated` / `settings/document-updated` / 凭据事件 / 重连）。
+ *   而组合只是本插件 `combos.json` 里的一份状态：
+ *     - `createCombo` 建了新组合 → 选择器永远看不到它
+ *     - `updateCombo` 改了名字 → 选择器还拿旧名字，用户切不过去
+ *     - `removeCombo` 删了组合 → 选择器里还留着，选中必然失败
+ *   实测现场：`combos.json` 里是 `buddy-models-flash`（22:19 改的名），
+ *   而选择器里显示的是**早已删除的** `NVIDIA-models` —— 整张表都过期了。
+ *
+ * 判据形态：直接守「提交成功后有没有发出通知」，而不是守客户端有没有刷新 ——
+ * 客户端刷新要靠宿主转发，单测里没有宿主。通知是这里唯一能守住的那一环。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Router } from './index.ts'
+
+/** 造一个空 stateFile 的临时目录（组合落在同目录的 combos.json）。 */
+function fixture(): { dir: string; stateFile: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-router-combo-'))
+  return { dir, stateFile: join(dir, 'state.json') }
+}
+
+test('★ createCombo 成功后通知一次（否则新组合在选择器里永不出现）', () => {
+  const { stateFile } = fixture()
+  let notified = 0
+  const router = new Router(stateFile, undefined, undefined, { onCombosChanged: () => { notified += 1 } })
+  assert.equal(router.createCombo('c1', ['supA,a-model']).ok, true)
+  assert.equal(notified, 1, '新建组合后没有通知 ⇒ 模型选择器看不到它')
+})
+
+test('★ updateCombo 成功后通知（否则选择器还拿旧名字，切不过去）', () => {
+  const { stateFile } = fixture()
+  let notified = 0
+  const router = new Router(stateFile, undefined, undefined, { onCombosChanged: () => { notified += 1 } })
+  router.createCombo('old-name', ['supA,a-model'])
+  notified = 0
+  assert.equal(router.updateCombo('old-name', 'new-name', ['supA,a-model']).ok, true)
+  assert.equal(notified, 1, '改名后没有通知 ⇒ 选择器里还留着旧名字')
+})
+
+test('★ removeCombo 成功后通知（否则选择器里留着已删的组合，选中必失败）', () => {
+  const { stateFile } = fixture()
+  let notified = 0
+  const router = new Router(stateFile, undefined, undefined, { onCombosChanged: () => { notified += 1 } })
+  router.createCombo('gone', ['supA,a-model'])
+  notified = 0
+  assert.equal(router.removeCombo('gone').ok, true)
+  assert.equal(notified, 1, '删除后没有通知 ⇒ 选择器里还留着它')
+})
+
+test('被拒绝的变更不通知（校验失败时组合根本没变）', () => {
+  const { stateFile } = fixture()
+  let notified = 0
+  const router = new Router(stateFile, undefined, undefined, { onCombosChanged: () => { notified += 1 } })
+  router.createCombo('keep', ['supA,a-model'])
+  notified = 0
+  // 空模型列表 / 非法名字 / 不存在的 id：三条都得原地不动
+  assert.equal(router.createCombo('bad-chars!', ['supA,a-model']).ok, false)
+  assert.equal(router.createCombo('no-models', []).ok, false)
+  assert.equal(router.updateCombo('missing-id', 'x', ['supA,a-model']).ok, false)
+  assert.equal(router.removeCombo('missing-id').ok, false)
+  assert.equal(notified, 0, '失败的变更不该通知（会让客户端做一次无意义的全量重拉）')
+})
+
+test('通知出口抛错不能把已提交的变更报成失败', async () => {
+  const { stateFile } = fixture()
+  const router = new Router(stateFile, undefined, undefined, {
+    // 监听方（宿主事件总线）出问题：这是通知不是事务参与者
+    onCombosChanged: () => { throw new Error('listener exploded') },
+  })
+  const result = router.createCombo('survivor', ['supA,a-model'])
+  assert.equal(result.ok, true, '通知失败不该让 createCombo 变红 —— 组合其实已经提交')
+  assert.equal((await router.combos()).some((c) => c.name === 'survivor'), true, '内存里的组合必须还在')
+})
+
+test('没装出口时不抛（单测/独立运行时）', () => {
+  const { stateFile } = fixture()
+  const router = new Router(stateFile)
+  assert.doesNotThrow(() => { router.createCombo('c1', ['supA,a-model']) })
+})
+
+test('通知发生在落盘之后 —— 监听方重读时能读到新组合', () => {
+  const { stateFile } = fixture()
+  let seen: string[] = []
+  const router = new Router(stateFile, undefined, undefined, {
+    onCombosChanged: () => {
+      // 监听方（宿主）会重新读一遍组合去刷客户端，此刻必须已经能读到新的
+      const onDisk = JSON.parse(readFileSync(join(stateFile, '..', 'combos.json'), 'utf8')) as {
+        combos: Array<{ name: string }>
+      }
+      seen = onDisk.combos.map((c) => c.name)
+    },
+  })
+  router.createCombo('persisted', ['supA,a-model'])
+  assert.deepEqual(seen, ['persisted'], '通知时组合还没落盘 ⇒ 监听方重读会拿到旧状态')
+})
+
+test('重复写同一个组合名不触发第二次落盘语义变化（幂等读取安全）', () => {
+  const { stateFile } = fixture()
+  let notified = 0
+  const router = new Router(stateFile, undefined, undefined, { onCombosChanged: () => { notified += 1 } })
+  router.createCombo('c1', ['supA,a-model'])
+  // 同 id 的 update 到等价内容仍然是合法提交（不是 no-op 语义），必须通知
+  assert.equal(router.updateCombo('c1', 'c1', ['supA,a-model']).ok, true)
+  assert.equal(notified, 2)
+})
+
+test('★ 注入：拿掉通知 ⇒ 上面几条会红（反向自检）', () => {
+  const { stateFile } = fixture()
+  // 等价于修复前的实现：没有 onCombosChanged
+  const router = new Router(stateFile)
+  router.createCombo('c1', ['supA,a-model'])
+  const combosFile = join(stateFile, '..', 'combos.json')
+  // 落盘仍然发生（这条路径没被改坏），但没有任何通知出口可发
+  const onDisk = JSON.parse(readFileSync(combosFile, 'utf8')) as { combos: unknown[] }
+  assert.equal(onDisk.combos.length, 1, '落盘行为必须保持')
+})