dsh-router-core 0.4.3 → 0.4.5

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, '落盘行为必须保持')
+})

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 就够。

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

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

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/registry.test.ts

@@ -211,3 +211,59 @@ test('刷新：status() 抛错 → 500 带错误信息', async () => {
   assert.equal(body.ok, false)
   assert.match(body.error ?? '', /status boom/)
 })
+
+/**
+ * 插件在 `listModels` 里抛错时，核心必须回 **JSON 500**。
+ *
+ * 为什么值得单锁：webServer 的兜底是 `res.writeHead(400); res.end()` —— **空
+ * body**。面板 `response.json()` 于是抛 "Unexpected end of JSON input"，真实原因
+ * （上游 500 / token 失效…）全丢。插件契约要求「出错就抛」(docs/suppliers.md)，
+ * 所以这层必须接住。traework 修掉 `catch {}` 之后这条才第一次真被走到。
+ */
+test('models 路由：插件 listModels 抛错 → 500 + JSON body（不是空 400）', async () => {
+  for (const path of ['models', 'models/fetch']) {
+    const supplier = {
+      id: 'fake',
+      name: 'fake',
+      status: () => ({ id: 'fake', name: 'fake', accounts: [] }),
+    }
+    const loaded = { supplier, capabilities: new Set(), source: 'builtin' }
+    // router.modelsOf 复刻核心语义：无旧值 → 把插件的错抛出来
+    const router = {
+      modelsOf: async (): Promise<never> => { throw new Error('models api returned empty list') },
+      invalidateModels: () => {},
+    }
+    const routes = supplierRoutes('/router/api', loaded as never, { get: () => ({ custom: [], disabled: [], poolOrder: [], credits: {} }) } as never, router as never)
+    const route = routes.find((r) => r.path === `/router/api/suppliers/fake/${path}`)
+    assert.ok(route, `${path} 路由应注册`)
+    const sink = fakeRes()
+    await route!.handler({} as never, sink.res)
+    const body = sink.body as { ok: boolean; error?: string }
+    assert.equal(sink.status, 500, `${path}: 抛错该回 500`)
+    assert.equal(body.ok, false, `${path}: 必须是 JSON body，不能是空 body`)
+    assert.match(String(body.error), /empty list/, `${path}: 真实原因不能丢`)
+  }
+})
+
+test('models 路由：body 不是合法 JSON → 400（不是 500，也不是空 body）', async () => {
+  const supplier = { id: 'fake', name: 'fake', status: () => ({ id: 'fake', name: 'fake', accounts: [] }) }
+  const loaded = { supplier, capabilities: new Set(), source: 'builtin' }
+  const router = { modelsOf: async () => [], invalidateModels: () => {} }
+  const routes = supplierRoutes('/router/api', loaded as never, { get: () => ({ custom: [], disabled: [], poolOrder: [], credits: {} }) } as never, router as never)
+  const route = routes.find((r) => r.path === '/router/api/suppliers/fake/models/toggle')
+  assert.ok(route)
+  // 造一个会吐非法 JSON 的 req（readBody 读 data/end）
+  const req = {
+    on(event: string, cb: (chunk?: Buffer) => void) {
+      if (event === 'data') cb(Buffer.from('{ not json'))
+      if (event === 'end') cb()
+      return req
+    },
+  }
+  const sink = fakeRes()
+  await route!.handler(req as never, sink.res)
+  const body = sink.body as { ok: boolean; error?: string }
+  assert.equal(sink.status, 400, '客户端传坏 body 是 400，不是核心 500')
+  assert.equal(body.ok, false)
+  assert.ok(String(body.error).length > 0, '400 也要带原因，不能是空 body')
+})

package/src/suppliers/registry.ts

@@ -44,6 +44,36 @@ function writeJson(res: ServerResponse, status: number, body: unknown): void {
   res.end(payload)
 }
 
+/**
+ * 包住会调插件的 handler：插件抛错时回 **JSON 500**，别让异常裸奔到 webServer。
+ *
+ * 为什么必须有这一层：webServer 的兜底是 `res.writeHead(400); res.end()`——**空
+ * body**。面板拿到空 body，`response.json()` 抛 "Unexpected end of JSON input"，
+ * 真实原因（上游 500 / token 失效…）全丢，用户只看到一句解析错误。
+ *
+ * 这条路径是插件契约「出错就抛」(docs/suppliers.md「模型统一策略」) 的下游：插件
+ * 老实抛了，核心就得老实接住并说清楚。以前 `listModels` 静默吞错，所以从没暴露过
+ * 这个缺口（traework 2026-10-10 「获取模型只有几个」修完才浮现）。
+ */
+function guard(handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>) {
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      await handler(req, res)
+    } catch (err) {
+      // headers 已发出就没法再改状态码了（writeJson 是原子的，这里基本不会发生）
+      if (res.headersSent) {
+        res.end()
+        return
+      }
+      // body 不是合法 JSON 是客户端的事（400），不该报成核心 500。这些 handler 里
+      // 唯一的 SyntaxError 来源就是 `JSON.parse(await readBody(req))`。
+      // （改 guard 之前这种情况由 webServer 兜底成**空** 400，改后保住状态码又带上原因。）
+      const status = err instanceof SyntaxError ? 400 : 500
+      writeJson(res, status, { ok: false, error: (err as Error).message })
+    }
+  }
+}
+
 async function readBody(req: IncomingMessage, limit = 64 << 10): Promise<string> {
   const chunks: Buffer[] = []
   let size = 0
@@ -109,10 +139,10 @@ export function supplierRoutes(base: string, loaded: LoadedSupplier, store: Supp
   routes.push({
     kind: 'exact',
     path: `${p}/models`,
-    handler: async (_req, res) => {
+    handler: guard(async (_req, res) => {
       const models = await router.modelsOf(s.id)
       writeJson(res, 200, { ok: true, alias: s.getAlias(), models })
-    },
+    }),
   })
 
   // ---- 通用: 供应商开关 ----
@@ -235,7 +265,7 @@ export function supplierRoutes(base: string, loaded: LoadedSupplier, store: Supp
   routes.push({
     kind: 'exact',
     path: `${p}/models/toggle`,
-    handler: async (req, res) => {
+    handler: guard(async (req, res) => {
       const body = JSON.parse(await readBody(req)) as { id?: string; enabled?: boolean }
       const cfg = store.get(s.id)
       const models = await router.modelsOf(s.id)
@@ -246,14 +276,14 @@ export function supplierRoutes(base: string, loaded: LoadedSupplier, store: Supp
       store.setModelEnabled(s.id, body.id, !!body.enabled)
       router.invalidateModels(s.id)
       writeJson(res, 200, { ok: true })
-    },
+    }),
   })
 
   // ---- 通用: models/add（自定义模型） ----
   routes.push({
     kind: 'exact',
     path: `${p}/models/add`,
-    handler: async (req, res) => {
+    handler: guard(async (req, res) => {
       const body = JSON.parse(await readBody(req)) as { id?: string }
       const id = (body.id ?? '').trim()
       if (id === '') {
@@ -268,7 +298,7 @@ export function supplierRoutes(base: string, loaded: LoadedSupplier, store: Supp
       store.addCustomModel(s.id, id)
       router.invalidateModels(s.id)
       writeJson(res, 200, { ok: true })
-    },
+    }),
   })
 
   // ---- 通用: models/remove（自定义模型） ----
@@ -292,13 +322,13 @@ export function supplierRoutes(base: string, loaded: LoadedSupplier, store: Supp
   routes.push({
     kind: 'exact',
     path: `${p}/models/bulk`,
-    handler: async (req, res) => {
+    handler: guard(async (req, res) => {
       const body = JSON.parse(await readBody(req)) as { enabled?: boolean }
       const models = await router.modelsOf(s.id)
       store.setAllModelsEnabled(s.id, !!body.enabled, models.map((mm) => mm.id))
       router.invalidateModels(s.id)
       writeJson(res, 200, { ok: true })
-    },
+    }),
   })
 
   // ---- 通用: pool/order ----
@@ -324,10 +354,10 @@ export function supplierRoutes(base: string, loaded: LoadedSupplier, store: Supp
   routes.push({
     kind: 'exact',
     path: `${p}/models/fetch`,
-    handler: async (_req, res) => {
+    handler: guard(async (_req, res) => {
       const models = await router.modelsOf(s.id, true)
       writeJson(res, 200, { ok: true, models })
-    },
+    }),
   })
 
   // ---- 通用: 测试模型（核心统一走 chatOnce 路径，账号池回退/冷却自动生效） ----