dsh-router-core 0.3.2 → 0.3.4

package/src/router/models-cache.test.ts

@@ -66,6 +66,21 @@ function addSupplier(router: Router, s: unknown): void {
   ;(router as unknown as { suppliers: unknown[] }).suppliers.push(s)
 }
 
+/**
+ * 把某供应商的缓存标记成「已过期」（TTL 现在 10 分钟，测试不能真等）。
+ * 白盒改 fetchedAt，模拟插件重启/TTL 到期的冷路径。
+ */
+function expire(router: Router, id: string): void {
+  const cache = (router as unknown as { modelsCache: Map<string, { fetchedAt: number }> }).modelsCache
+  const hit = cache.get(id)
+  if (hit !== undefined) hit.fetchedAt = 0
+}
+
+/** 等一轮 microtask/定时器，让 fire-and-forget 的后台刷新跑完。 */
+function tick(ms = 20): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}
+
 test('组合面板连开两次只拉一次上游（缓存生效）', async () => {
   const router = new Router('')
   const a = supplier('a', [{ id: 'a-1' }])
@@ -137,9 +152,129 @@ test('单个供应商拉模型失败不影响其它供应商', async () => {
   assert.equal(groups[0]?.supplier.id, 'good')
 })
 
-test('未知供应商返回空，不抛错', async () => {
+/**
+ * 冷启动慢的回归（2026-09-03 实测）：插件的 listModels 大多无条件打上游
+ * （0.3~1.0s/供应商），TTL 一过就穿透到插件，组合页取最慢那家 = 1s+ 白屏。
+ * 现在核心走 stale-while-revalidate：过期先返回旧值，后台刷新。
+ */
+test('过期后不等上游：立刻返回旧值，后台刷新', async () => {
+  const router = new Router('')
+  // 慢供应商：真等它就是 300ms
+  const a = supplier('a', [{ id: 'a-1' }], 300)
+  addSupplier(router, a.s)
+
+  await router.modelsOf('a')
+  assert.equal(a.state.calls, 1)
+  expire(router, 'a')
+
+  const t0 = Date.now()
+  const models = await router.modelsOf('a')
+  const dt = Date.now() - t0
+
+  assert.ok(dt < 100, `过期后不该同步等上游（实测 ${dt}ms）`)
+  assert.deepEqual(models.map((m) => m.id), ['a-1'], '旧值要立刻返回，面板不空')
+  await tick(400)
+  assert.equal(a.state.calls, 2, '后台要真的刷新一次')
+})
+
+test('后台刷新后缓存变新：再取不再触发拉取', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }])
+  addSupplier(router, a.s)
+
+  await router.modelsOf('a')
+  expire(router, 'a')
+  await router.modelsOf('a') // 触发后台刷新
+  await tick()
+  assert.equal(a.state.calls, 2)
+
+  await router.modelsOf('a') // 已刷新过，不该再拉
+  await tick()
+  assert.equal(a.state.calls, 2)
+})
+
+test('并发刷新共享一次上游请求（不去重会把上游按 N 倍打）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }], 50)
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+  expire(router, 'a')
+
+  // 组合页的实际情况：多个入口同时触发同一个供应商
+  await Promise.all([router.modelsOf('a'), router.modelsOf('a'), router.modelsOf('a')])
+  await tick(200)
+  assert.equal(a.state.calls, 2, `并发只应多拉一次，实测 ${a.state.calls}`)
+})
+
+test('force 仍然同步等（用户主动点「获取模型」，要看到结果）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }], 150)
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+  expire(router, 'a')
+
+  const t0 = Date.now()
+  await router.modelsOf('a', true)
+  assert.ok(Date.now() - t0 >= 100, 'force 必须等上游拉完')
+  assert.equal(a.state.calls, 2)
+})
+
+test('拉到空列表不覆盖旧值（上游抖一下不该清空面板）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }])
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+
+  a.s.listModels = async (): Promise<ModelInfo[]> => []
+  expire(router, 'a')
+  const models = await router.modelsOf('a', true)
+
+  assert.deepEqual(models.map((m) => m.id), ['a-1'], '空结果不该冲掉旧列表')
+})
+
+test('后台刷新失败 → 保留旧值，不抛（fire-and-forget 没人接异常）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }])
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+
+  a.s.listModels = async (): Promise<ModelInfo[]> => {
+    throw new Error('upstream down')
+  }
+  expire(router, 'a')
+  const models = await router.modelsOf('a')
+  assert.deepEqual(models.map((m) => m.id), ['a-1'], '失败也要保住旧值')
+})
+
+test('首次就失败且无旧值 → 抛错（让 supplierModels 剔除该供应商，别显示空壳）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [])
+  a.s.listModels = async (): Promise<ModelInfo[]> => {
+    throw new Error('upstream down')
+  }
+  addSupplier(router, a.s)
+
+  await assert.rejects(() => router.modelsOf('a'), /upstream down/)
+})
+
+/**
+ * 回归（2026-09-03 契约精简）：删了插件 lastError() 后，testModel 的失败原因
+ * 必须从 chatOnce 返回值的 message 取（经 trace.lastError 透传）。以前问插件
+ * 的 lastError() 是个「最后一次失败」的可变全局，可能串别的请求，也有插件
+ * 压根没实现照样能走到。锁住：chatOnce 报的 message 能作为诊断呈现。
+ */
+test('testModel 失败 → 用 chatOnce 返回的 message 作诊断，不依赖插件 lastError()', async () => {
   const router = new Router('')
-  assert.deepEqual(await router.modelsOf('nonexistent'), [])
+  const a = supplier('a', [{ id: 'a-1' }])
+  // 明确不实现 lastError()——合约删了它
+  a.s.chatOnce = async (): Promise<ChatOnceResult> =>
+    ({ ok: false, state: 'quota', message: 'no quota for this plan' })
+  addSupplier(router, a.s)
+
+  const r = await router.testModel('a', 'a-1')
+  assert.equal(r.ok, false)
+  assert.match(r.error ?? '', /no quota for this plan/, '失败原因要来自 chatOnce 的 message')
+  assert.match(r.error ?? '', /账号\/额度\/限流问题/, '要带上可诊断的归类提示')
 })
 
 /**
@@ -311,7 +446,15 @@ test('流在写出第一个字节前就断 → 组合回退到下一个模型',
   assert.equal(heads, 1, '响应头只应提交一次')
 })
 
-test('已写出字节后断流 → 诚实截断，不回退也不二次写头', async () => {
+/**
+ * 已写出字节后断流：诚实截断，不回退也不二次写头 —— 但要**补一个终止帧**。
+ *
+ * 客户端（dsh-llm adapter）严格等 `[DONE]` 才认为流正常结束；缺了就抛
+ * `SSE payload stream ended without [DONE]`，整轮判失败，已经吐出去的内容
+ * 全部作废。所以核心补终止帧：断流降级为「拿到截断内容并正常收尾」，
+ * 而不是「整轮白干」。
+ */
+test('已写出字节后断流 → 截断并补 [DONE]，不回退也不二次写头', async () => {
   const router = new Router('')
   const half = supplier('half', [{ id: 'half-m' }])
   half.s.chatOnce = async (): Promise<ChatOnceResult> => ({
@@ -351,10 +494,81 @@ test('已写出字节后断流 → 诚实截断，不回退也不二次写头',
   await router.chatCompletions({ model: 'c2', stream: true, rawBody: JSON.stringify({ model: 'c2', messages: [] }) }, res)
 
   assert.ok(out.includes('半截'), '已投递的字节要送达客户端')
-  assert.ok(!out.includes('[DONE]'), '已提交就不该再接第二个模型的内容（会串流）')
+  assert.ok(out.includes('data: [DONE]'), '断流要补终止帧，否则客户端整轮判失败')
+  assert.equal(out.match(/\[DONE\]/g)?.length ?? 0, 1, '终止帧只能有一个（重复会坑客户端）')
+  assert.ok(!out.includes('兜底'), '已提交就不该再接第二个模型的内容（会串流）')
   assert.equal(heads, 1, '响应头只能提交一次')
 })
 
+/** 上游自己发了终止帧就别再补一个（重复 [DONE] 同样坑客户端）。 */
+test('上游已发 [DONE] → 不重复补', async () => {
+  const router = new Router('')
+  const s = supplier('sup', [{ id: 'm' }])
+  s.s.chatOnce = async (): Promise<ChatOnceResult> => ({
+    ok: true,
+    stream: new ReadableStream<Uint8Array>({
+      start(c) {
+        c.enqueue(new TextEncoder().encode('data: {"choices":[{"delta":{"content":"完整"}}]}\n\ndata: [DONE]\n\n'))
+        c.close()
+      },
+    }),
+  })
+  addSupplier(router, s.s)
+
+  let out = ''
+  const res = {
+    writeHead: (): void => {},
+    write: (b: Uint8Array | string): boolean => { out += Buffer.from(b).toString(); return true },
+    end: (): void => {},
+    once: (): void => {},
+    removeListener: (): void => {},
+    destroy: (): void => {},
+  } as unknown as ServerResponse
+  await router.chatCompletions({ model: 'sup/m', stream: true, rawBody: JSON.stringify({ model: 'sup/m', messages: [] }) }, res)
+
+  assert.equal(out.match(/\[DONE\]/g)?.length ?? 0, 1, `终止帧不能重复，实际: ${JSON.stringify(out)}`)
+})
+
+/**
+ * 一个字节都没写出就断 → 绝不能补 [DONE]。
+ * 补了就等于把这次失败坐实成一个空响应，组合回退（换号/换模型）就废了。
+ */
+test('首字节前就断 → 不补 [DONE]，留给组合回退', async () => {
+  const router = new Router('')
+  const dead = supplier('dead', [{ id: 'dead-m' }])
+  dead.s.chatOnce = async (): Promise<ChatOnceResult> => ({
+    ok: true,
+    stream: new ReadableStream<Uint8Array>({ start(c) { c.error(new Error('上游刚连上就断')) } }),
+  })
+  const live = supplier('live', [{ id: 'live-m' }])
+  live.s.chatOnce = async (): Promise<ChatOnceResult> => ({
+    ok: true,
+    stream: new ReadableStream<Uint8Array>({
+      start(c) {
+        c.enqueue(new TextEncoder().encode('data: {"choices":[{"delta":{"content":"兜底"}}]}\n\ndata: [DONE]\n\n'))
+        c.close()
+      },
+    }),
+  })
+  addSupplier(router, dead.s)
+  addSupplier(router, live.s)
+  assert.equal(router.createCombo('c3', 'fallback', ['dead,dead-m', 'live,live-m']).ok, true)
+
+  let out = ''
+  const res = {
+    writeHead: (): void => {},
+    write: (b: Uint8Array | string): boolean => { out += Buffer.from(b).toString(); return true },
+    end: (): void => {},
+    once: (): void => {},
+    removeListener: (): void => {},
+    destroy: (): void => {},
+  } as unknown as ServerResponse
+  await router.chatCompletions({ model: 'c3', stream: true, rawBody: JSON.stringify({ model: 'c3', messages: [] }) }, res)
+
+  assert.equal(out.match(/\[DONE\]/g)?.length ?? 0, 1, '只有兜底那个流该有终止帧')
+  assert.ok(out.includes('兜底'), '必须回退到下一个模型')
+})
+
 /**
  * 对照组：插件若用 unavailable 表示「不是我的模型」就会污染账号——
  * 这正是当初把 no_such_model 加进契约的原因（unavailable 在 RULES 里计数）。
@@ -368,7 +582,9 @@ test('对照：用 unavailable 表示「不是我的模型」会污染账号', a
     ({ ok: false, state: 'unavailable', message: 'not my model' })
   addSupplier(router, other.s)
 
-  const req = { model: 'want-m', stream: false, rawBody: JSON.stringify({ model: 'want-m', messages: [] }) }
+  // 严格图6拓扑：路由必须带供应商前缀/别名，裸 model 不再遍历。
+  // 这里用 alias/model 精准命中 other（别名默认 = 供应商 id）。
+  const req = { model: 'other/other-m', stream: false, rawBody: JSON.stringify({ model: 'other/other-m', messages: [] }) }
   for (let i = 0; i < 5; i++) await router.chatCompletions(req, fakeRes())
 
   const acc = other.s.pool.decorate([{ uid: 'u1', credits: 0, state: 'ok' }])[0]
@@ -387,7 +603,9 @@ test('组合请求不污染无关供应商的账号（no_such_model 不记账）
   addSupplier(router, other.s)
   addSupplier(router, target.s)
 
-  const req = { model: 'want-m', stream: false, rawBody: JSON.stringify({ model: 'want-m', messages: [] }) }
+  // 严格图6拓扑：用 alias/model 精准命中 target（别名默认 = 供应商 id），
+  // other 完全不该被问到——这正是这条回归要守的。
+  const req = { model: 'target/want-m', stream: false, rawBody: JSON.stringify({ model: 'target/want-m', messages: [] }) }
   const res = fakeRes()
   // 连打 5 次（远超错误阈值 3）
   for (let i = 0; i < 5; i++) await router.chatCompletions(req, res)

package/src/router/precise-dispatch.test.ts

@@ -49,8 +49,11 @@ function spy(id: string, modelId: string, alias = id): Spy {
       chatOnce: async (_uid, req) => {
         calls.n += 1
         const m = (JSON.parse(req.rawBody) as { model?: string }).model ?? ''
-        seen.push(m)
-        if (m !== modelId) return { ok: false, state: 'no_such_model', message: `unknown model ${m}` }
+        seen.push(m) // 记核心传来的**原样**全名，剥前缀是插件内部的事
+        // 真实插件会先剥掉自己的 alias 再认模型（各 suppliers/*/plugin.ts
+        // 都有一份 stripAlias）；这里照做，否则直接调用路径永远匹配不上。
+        const base = m.startsWith(`${alias}/`) ? m.slice(alias.length + 1) : m
+        if (base !== modelId) return { ok: false, state: 'no_such_model', message: `unknown model ${m}` }
         return { ok: true, status: 200, body: '{"ok":1}' }
       },
       dispose: () => {},
@@ -131,19 +134,22 @@ test('模型 id 含斜杠时不被吃掉（如 deepseek-ai/xxx）', async () =>
   assert.deepEqual(a.seen, ['aaa/deepseek-ai/deepseek-v3'])
 })
 
-test('旧数据裸模型 id 仍能工作（降级为遍历）', async () => {
+test('组合存了缺供应商前缀的裸模型 id → 直接失败，不降级遍历（严格图6拓扑）', async () => {
   const router = new Router('')
   const a = spy('supA', 'a-model')
   const b = spy('supB', 'b-model')
   add(router, a.s); add(router, b.s)
-  // 模拟旧存储：裸 id，没有 supplierId 前缀
+  // 模拟旧存储：裸 id，没有 supplierId 前缀 —— 图6 下这是配置错误，不遍历兜底
   ;(router as unknown as { customCombos: Array<{ id: string; name: string; strategy: 'fallback'; models: string[] }> })
     .customCombos.push({ id: 'legacy', name: 'legacy', strategy: 'fallback', models: ['b-model'] })
 
-  await router.chatCompletions(reqWith('legacy'), fakeRes())
+  const errs: unknown[] = []
+  const res = { ...fakeRes(), end: (x?: string): unknown => { if (x) errs.push(x); return undefined } } as unknown as ServerResponse
+  await router.chatCompletions(reqWith('legacy'), res)
 
-  assert.equal(a.calls, 1, '降级路径会先问 supA（它报 no_such_model）')
-  assert.equal(b.calls, 1, '最终由 supB 服务')
+  assert.equal(a.calls, 0, '不降级遍历，不该问 supA')
+  assert.equal(b.calls, 0, '裸 id 无前缀，不该被 supB 认领')
+  assert.equal(errs.length, 1, '缺前缀的模型应判失败（组合 503）')
 })
 
 test('组合存了不存在的供应商 id → 调用失败，不静默落到别的供应商', async () => {
@@ -196,3 +202,100 @@ test('空别名 → 生效别名回落到供应商 id', () => {
   store.setAlias('supA', 'custom')
   assert.equal(store.effectiveAliases().get('supA'), 'custom')
 })
+
+/**
+ * 为什么要有这一组：用量统计记的 model 名曾把 alias 前缀套了两层
+ * （`tx/tx/hy4-preview`、`trae/trae/DeepSeek-V4-Flash-Official`）。
+ *
+ * 成因：直接调 `alias/model` 时核心**原样**把全名传给插件（剥前缀是插件
+ * 的活，见上面那条断言），但记 `probe.model` 时又拼了一次 `${alias}/`
+ * ——于是统计里出现双前缀。功能不受影响（插件拿到的名字是对的），但
+ * Top 榜会把同一个模型**分裂成两行**（`tx/hy4-preview` 和
+ * `tx/tx/hy4-preview` 各占一行），看板数据失真。
+ */
+test('用量统计：直接调 alias/model 时 model 名不重复套前缀', async () => {
+  const router = new Router('')
+  const b = spy('supB', 'b-model', 'bbb')
+  add(router, b.s)
+
+  await router.chatCompletions(reqWith('bbb/b-model'), fakeRes())
+
+  const rec = router.usage.recentList(1)[0]
+  assert.equal(rec?.model, 'bbb/b-model', '统计名必须是 alias/model，不能是 alias/alias/model')
+})
+
+test('直接调裸模型 id（无前缀）→ 判失败，不再遍历兜底（严格图6拓扑）', async () => {
+  const router = new Router('')
+  const b = spy('supB', 'b-model', 'bbb')
+  add(router, b.s)
+
+  const errs: unknown[] = []
+  const res = { ...fakeRes(), end: (x?: string): unknown => { if (x) errs.push(x); return undefined } } as unknown as ServerResponse
+  await router.chatCompletions(reqWith('b-model'), res)
+
+  assert.equal(b.calls, 0, '裸 id 不该遍历到 supB')
+  assert.equal(errs.length, 1, '无前缀的裸模型应判失败（503）')
+})
+
+/**
+ * 为什么要有这一组：学 9router combo.js 的「瞬时故障降级前先喘口气」
+ * （其注释原话：fixes: combo falls through on transient 503）。
+ *
+ * 过载的上游往往几百毫秒内就恢复。立刻换下一个模型，会让整个组合在几
+ * 毫秒内被依次打穿 —— 最后一个模型也失败时，用户看到的就是全灭 503。
+ * 等待只针对**瞬时**故障：模型不属于本供应商（no_such_model）不是故障，
+ * 等它纯属浪费时间。
+ */
+
+/** 造一个总是以指定状态失败的供应商（可记调用时刻，用于验证等待）。 */
+function failingSpy(id: string, modelId: string, state: 'transport' | 'unavailable' | 'no_such_model') {
+  const at: number[] = []
+  return {
+    calls: 0,
+    at,
+    s: {
+      id, name: id, priority: 0, pool: new AccountPool(),
+      status: () => ({ id, name: id, accounts: [{ uid: `${id}-u1`, credits: 0, state: 'ok' }] }),
+      listModels: async () => [{ id: modelId }],
+      modelsWithEnabled: async () => [{ id: modelId, enabled: true }],
+      getAlias: () => id,
+      accounts: () => [{ uid: `${id}-u1`, credits: 0, state: 'ok' }],
+      chatOnce: async (_uid: string, _req: { rawBody: string }) => {
+        at.push(Date.now())
+        return { ok: false, state, message: `${state} boom` } as ChatOnceResult
+      },
+      dispose: () => {},
+    },
+  }
+}
+
+test('组合：瞬时故障降级前会等一等，不是毫秒级打穿整个组合', async () => {
+  const router = new Router('')
+  const m1 = failingSpy('s1', 'm1', 'transport')
+  const m2 = failingSpy('s2', 'm2', 'unavailable')
+  add(router, m1.s); add(router, m2.s)
+  router.createCombo('combo', 'fallback', ['s1,m1', 's2,m2'])
+
+  const t0 = Date.now()
+  await router.chatCompletions(reqWith('combo'), fakeRes())
+  const elapsed = Date.now() - t0
+
+  // 两个都失败 → 全灭；但 s1 瞬时失败后应等一个窗口再试 s2
+  assert.equal(m1.at.length, 1)
+  assert.equal(m2.at.length, 1)
+  assert.ok(elapsed >= 1000, `瞬时故障降级前应等待（实际 ${elapsed}ms），否则组合会被瞬间打穿`)
+})
+
+test('组合：no_such_model 不是故障，降级不该等', async () => {
+  const router = new Router('')
+  const m1 = failingSpy('s1', 'm1', 'no_such_model')
+  const m2 = failingSpy('s2', 'm2', 'no_such_model')
+  add(router, m1.s); add(router, m2.s)
+  router.createCombo('combo', 'fallback', ['s1,m1', 's2,m2'])
+
+  const t0 = Date.now()
+  await router.chatCompletions(reqWith('combo'), fakeRes())
+  const elapsed = Date.now() - t0
+
+  assert.ok(elapsed < 1000, `模型不存在是配置问题不是故障，不该等（实际 ${elapsed}ms）`)
+})

package/src/router/types.ts

@@ -80,8 +80,6 @@ export interface Supplier {
   accounts(): SupplierAccountNow[]
   /** 对单个账号调一次上游。不遍历账号、不管冷却、不写 res。 */
   chatOnce(uid: string, req: ChatRequest): Promise<ChatOnceResult>
-  /** 上次 chatOnce 失败原因（诊断用，可选）。 */
-  lastError?(): string | undefined
   /** 删除链接（清理凭证；内部能力，js 契约不要求实现）。 */
   removeLink?(uid: string): Promise<boolean>
   dispose(): void