dsh-router-core 0.3.21 → 0.4.1

package/src/router/index.ts

@@ -1,7 +1,7 @@
 /**
  * dsh-router 路由器本体：供应商注册表 + OpenAI 兼容 /v1/* 处理。
- * 仿 9router：组合 = 一组模型，请求 model 命中组合名时，按策略
- * （fallback 顺序尝试 / round-robin 轮转）选中一个模型路由。
+ * 仿 9router：组合 = 一组模型，请求 model 命中组合名时，作为降级链
+ * 按序尝试选中一个模型路由（无策略旋钮，见 docs/pool-sticky-block.md §10）。
  */
 import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
 import { dirname, join } from 'node:path'
@@ -24,6 +24,8 @@ interface ChatTrace {
   lastError?: string
   /** 最后一次失败的状态（组合据此判断要不要「喘口气」再降级）。 */
   lastState?: AccountState
+  /** 本次选号的理由（诊断「为什么没粘住原号」）。 */
+  pickWhy?: string
 }
 
 /**
@@ -79,6 +81,103 @@ function isTransient(state: AccountState): boolean {
   return state === 'transport' || state === 'unavailable'
 }
 
+/**
+ * **每条降级腿的首字节预算**：从进入这条腿起，多久内上游必须吐出第一个字节。
+ *
+ * 为什么必须有（2026-09-24 夜里 money 组合实测）：上游（codebuddy 系）额度用完 /
+ * 过载时，连接照常建立、HTTP 200 响应头照常回来，**body 却一个字节都不吐**。
+ * 这既不是成功也不是失败，于是
+ *   - `chatOnce` 的 120s 只守「连接+响应头」，`fetch` 一返回就撤表 → 守不到 body
+ *   - 核心写响应的路径也没有任何计时器 → 组合链卡在这一条腿上不动
+ *   - 客户端（dsh-router 自己的 adapter）有 300s 流空闲超时，但那是「整条请求」
+ *     的兜底，与降级无关
+ * 实测用户干等 200 多秒手动暂停：ttfb 84s / 122s / 151s / 244s / 246s / 250s /
+ * 254s / 255s，8 次全部 `ok: true`——**全都最终成功了**，只是晚了四分钟。同一批
+ * 账号因为「没失败」也不冷却，下一次请求继续挑它（cb-8 连吃 248s + 155s）。
+ *
+ * 60s 的来历（本机 500 条真实请求的 ttfb 分布）：p50 4.1s / p95 14.9s，
+ * 最大的**非停滞**值 47.7s，停滞簇从 84.5s 起 —— 60s 正落在两簇之间的空档，
+ * 砍得动停滞、砍不到真实慢请求。首个字节之后**不再计时**：长生成可以跑很久。
+ *
+ * 为什么按「腿」而不是按「账号」计：停滞是上游级的（同一供应商的所有号一起
+ * 挂）。按账号计的话，codebuddy 有 11 个号，一次请求能 11×60s = 11 分钟才轮到
+ * 下一个模型；按腿计，最坏 3 条腿 × 60s ≈ 3 分钟，且期间一定会走到下一个模型。
+ */
+const FIRST_BYTE_BUDGET_MS = 60_000
+
+/**
+ * 给上游流套一层**首字节截止**：截止前一个字节都没来，就把这条流判失败
+ * （error 出去，调用方看到「一个字节都没写」→ 换号/换模型）。
+ * 第一个字节到手后立刻撤表，之后多久都不管。
+ *
+ * 为什么套在核心而不是插件：首字节迟迟不来时，**只有核心**能做「还没提交响应
+ * → 换一条腿」的决定（插件在 `fetch` 拿到响应头那一刻就把流交出去了，
+ * 谁也没法再改结果）。核心也是所有供应商唯一的收口点，套一次全都受益。
+ */
+export function withFirstByteDeadline(stream: ReadableStream<Uint8Array>, ms: number): ReadableStream<Uint8Array> {
+  const reader = stream.getReader()
+  let first = true
+  /** 消费方已取消：这之后任何 ctrl.* 都会抛（流已死），必须全部跳过。 */
+  let cancelled = false
+  /**
+   * 上游 reader 只解绑一次。wrapper 替核心持有了这个 reader，所以**必须由
+   * wrapper 负责收尾**：上游正常读完 / 上游自己 error / 被取消时都解锁，
+   * 否则流永久锁着，上层想 cancel 会抛 `Invalid state: ReadableStream is locked`
+   * （disconnect-leak 那条判据守的就是这个；历史上由 aggregateSSE 的 finally 解锁，
+   * 现在读的是 wrapper，解绑责任跟着搬过来）。
+   */
+  let released = false
+  const release = (): void => {
+    if (released) return
+    released = true
+    try { reader.releaseLock() } catch { /* 有待定 read 时会抛，忽略 */ }
+  }
+  /** 取消要传到底下的上游（cancel 本身会顺带解锁）。 */
+  const cancelUpstream = (reason: unknown): Promise<void> => {
+    if (released) return Promise.resolve()
+    released = true
+    return reader.cancel(reason).then(() => {}, () => {})
+  }
+  return new ReadableStream<Uint8Array>({
+    async pull(ctrl) {
+      // 超时标志由计时器置位：置位后**不再碰 ctrl**（流已经 error 掉了，
+      // 再 close/enqueue 会抛 ERR_INVALID_STATE，把真正的失败原因盖掉）。
+      let expired = false
+      const timer = first
+        ? setTimeout(() => {
+            expired = true
+            void cancelUpstream(new Error('first byte timeout'))
+            try { ctrl.error(new Error(`no first byte within ${ms}ms`)) } catch { /* 已被取消 */ }
+          }, ms)
+        : undefined
+      try {
+        const { done, value } = await reader.read()
+        if (expired || cancelled) return
+        if (done) {
+          release()
+          ctrl.close()
+          return
+        }
+        first = false
+        ctrl.enqueue(value)
+      } catch (e) {
+        release()
+        if (!expired && !cancelled) {
+          try { ctrl.error(e) } catch { /* 已被取消 */ }
+        }
+      } finally {
+        if (timer !== undefined) clearTimeout(timer)
+      }
+    },
+    // 消费方取消必须穿过这层 wrapper 传到上游（与 normalizeSSEStream 同理，
+    // 不实现就等于每次客户端放弃都漏一条上游连接）。
+    cancel: (reason) => {
+      cancelled = true
+      return cancelUpstream(reason)
+    },
+  })
+}
+
 /**
  * 从请求体里取 `messages`（前缀亲和的指纹输入）。解析失败/字段缺失返回
  * undefined —— 亲和拿不到输入就自动回退到块轮询，不影响路由本身。
@@ -353,8 +452,18 @@ function fixFrame(frame: string): string {
  *
  * 天花板：一旦写出第一个字节就绑死（HTTP 语义），中途断流只能截断，
  * 不能回退。要彻底解决得在写头前缓冲判定，代价是首字节延迟——未做。
+ *
+ * @param firstByteTimeoutMs 上游多久内必须吐出第一个字节（见 FIRST_BYTE_BUDGET_MS）。
+ *   超时按「一个字节都没写」返回 false，调用方照常换号/换模型。
  */
-async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStream: boolean, probe?: UsageProbe, startedAt = 0): Promise<boolean> {
+async function writeChatResult(
+  res: ServerResponse,
+  r: ChatOnceResult,
+  wantsStream: boolean,
+  probe?: UsageProbe,
+  startedAt = 0,
+  firstByteTimeoutMs = FIRST_BYTE_BUDGET_MS,
+): Promise<boolean> {
   if (!r.ok) return false // 失败不该走到这里（核心先判 ok 才写）
   if (!('stream' in r)) {
     if (probe !== undefined) probe.tokens = usageFromJsonBody(r.body)
@@ -362,19 +471,21 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
     res.end(r.body)
     return true
   }
+  // 唯一收口：两条路径（聚合 / 透传）读的都是这层「套了首字节截止」的流。
+  const src = withFirstByteDeadline(r.stream, firstByteTimeoutMs)
   // 客户端要 JSON 但供应商只给流（如 codebuddy 强制 stream:true）→ 聚合成
   // 一次非流式响应。核心独占响应写入权，这个协议错配必须由核心吸收，
   // 否则客户端按 JSON 解析会在 SSE 的 delta 里找不到工具名。
   if (!wantsStream) {
     let body: string
     try {
-      body = await aggregateSSE(r.stream)
+      body = await aggregateSSE(src)
     } catch {
       // 聚合失败 = 一个字节都没写，调用方可以换号重试。
       // **但底层流必须 cancel**：aggregateSSE 内部 getReader() 消费到一半抛错时，
       // reader 只是 releaseLock()，传输层毫无察觉 —— 那条上游连接会一直挂着。
       // 不 cancel 就退化成「每次聚合失败漏一条连接」（issue #6 的路径 1）。
-      await r.stream.cancel().catch(() => {})
+      await src.cancel().catch(() => {})
       return false
     }
     if (probe !== undefined) probe.tokens = usageFromJsonBody(body)
@@ -384,7 +495,7 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
   }
 
   // 流式：边透传边统计（统计在 tee 之外的旁路做，首字节延迟不受影响）
-  const tapped = probe === undefined ? undefined : tapStreamUsage(r.stream, startedAt)
+  const tapped = probe === undefined ? undefined : tapStreamUsage(src, startedAt)
   let wroteAny = false
   /** 响应已死（客户端断开/res 已销毁）：等 drain 的写入要立刻放弃，别吊死。 */
   let dead = false
@@ -447,7 +558,7 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
     abort.abort()
   }
   res.once('close', onClose)
-  const norm = normalizeSSEStream(tapped?.stream ?? r.stream)
+  const norm = normalizeSSEStream(tapped?.stream ?? src)
   try {
     // signal 让 abort 时 pipeTo 立刻收尾（而不是等 drain）；其收尾路径会
     // cancel 源流，顺着 wrapper 的 cancel 一路传到上游 fetch body。
@@ -524,12 +635,16 @@ interface UsageProbe {
 
 /** 路由器。 */
 export class Router {
+  /**
+   * **已装载**的全部供应商（含被开关关掉的）。关掉的仍留在列表里 —— 否则用户关掉
+   * 之后它在 `/health`、面板、插件页里一起消失，开关就没有可指的对象、也没法再开。
+   *
+   * 真正参与路由的只有 `active` 那一份。
+   */
   private suppliers: Supplier[] = []
   private combosFp = ''
   private customCombos: Combo[] = []
-  /** round-robin 轮转游标（按组合 id 记忆）。 */
-  private rrCursors = new Map<string, number>()
-  /** 通用供应商配置（连接池顺序/策略、模型启用、别名）。 */
+  /** 通用供应商配置（连接池顺序、模型启用、别名）。 */
   private store: SupplierConfigStore
   /** 模型列表缓存（supplierId → 模型 + 拉取时间）。插件只管拉，不缓存。 */
   private modelsCache = new Map<string, { models: ModelWithEnabled[]; fetchedAt: number }>()
@@ -540,13 +655,21 @@ export class Router {
   private modelsInflight = new Map<string, Promise<ModelWithEnabled[]>>()
   /** 请求日志出口（面板/宿主 logger）。 */
   private log: (msg: string) => void
+  /** 每条降级腿的首字节预算（ms）。只给测试一个入口，生产恒为 FIRST_BYTE_BUDGET_MS。 */
+  private firstByteBudgetMs: number
   /** 用量统计（概览看板）。 */
   usage: UsageStore
 
-  constructor(stateFile = '', store?: SupplierConfigStore, log?: (msg: string) => void) {
+  constructor(
+    stateFile = '',
+    store?: SupplierConfigStore,
+    log?: (msg: string) => void,
+    opts?: { firstByteBudgetMs?: number },
+  ) {
     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.usage = new UsageStore(stateFile)
     this.loadCombos()
   }
@@ -565,7 +688,7 @@ export class Router {
     try {
       const f = JSON.parse(readFileSync(this.combosFp, 'utf8')) as { combos?: Combo[] }
       if (Array.isArray(f.combos)) {
-        // 兼容旧格式：steps(供应商) → models(模型)；无 strategy 默认 fallback。
+        // 兼容旧格式：steps(供应商) → models(模型)；旧 strategy 字段静默忽略。
         this.customCombos = f.combos
           .filter((c) => typeof c.id === 'string' && c.id !== '')
           .map((c) => {
@@ -589,13 +712,12 @@ export class Router {
               if (slash <= 0) return m // 裸 id：保持，路由降级为遍历
               const alias = m.slice(0, slash)
               const modelId = m.slice(slash + 1)
-              const s = this.suppliers.find((x) => x.getAlias() === alias)
+              const s = this.active.find((x) => x.getAlias() === alias)
               return s === undefined ? modelId : `${s.id},${modelId}`
             })
             return {
               id: c.id,
               name: typeof c.name === 'string' ? c.name : c.id,
-              strategy: c.strategy === 'round-robin' ? 'round-robin' as const : 'fallback' as const,
               models,
             }
           })
@@ -627,6 +749,22 @@ export class Router {
     this.store.sync(this.suppliers.map((s) => s.id))
   }
 
+  /**
+   * **参与路由的供应商** —— 装载清单里开关为开的那一份，按 priority 排好。
+   *
+   * 这是「供应商开关」唯一的收口点：请求分发、别名反查、模型列表、组合、面板状态
+   * 全部读它。关掉一个供应商 = 它从这里消失，而不是在每个调用点各写一遍判断 ——
+   * 后者一定会漏（本次实测路由有 15 处读 `this.suppliers`）。
+   */
+  private get active(): Supplier[] {
+    return this.suppliers.filter((s) => this.store.isEnabled(s.id))
+  }
+
+  /** 某供应商当前是否参与路由（面板与 API 用）。 */
+  isEnabled(supplierId: string): boolean {
+    return this.store.isEnabled(supplierId)
+  }
+
   /** 移除供应商（外部插件卸载时注销）。 */
   removeSupplier(id: string): boolean {
     const i = this.suppliers.findIndex((s) => s.id === id)
@@ -637,14 +775,20 @@ export class Router {
     return true
   }
 
-  /** 返回全部供应商状态（面板用）。 */
-  status(): { suppliers: SupplierStatus[] } {
-    return { suppliers: this.suppliers.map((s) => s.status()) }
+  /**
+   * 返回全部供应商状态（面板用）。**含被开关关掉的** —— 面板要能显示它们
+   * （「已关闭」），否则用户在面板上就再也看不到自己装过的供应商。
+   * 开关状态由 `enabled` 字段带出，调用方自己决定要不要只留开着的。
+   */
+  status(): { suppliers: (SupplierStatus & { enabled: boolean })[] } {
+    return {
+      suppliers: this.suppliers.map((s) => ({ ...s.status(), enabled: this.store.isEnabled(s.id) })),
+    }
   }
 
-  /** 供应商前缀信息（组合模型全名 = alias/id，展示时动态拼接）。 */
+  /** 供应商前缀信息（组合模型全名 = alias/id，展示时动态拼接）。只含开着的。 */
   aliases(): Array<{ id: string; name: string; alias: string }> {
-    return this.suppliers.map((s) => ({ id: s.id, name: s.name, alias: s.getAlias() }))
+    return this.active.map((s) => ({ id: s.id, name: s.name, alias: s.getAlias() }))
   }
 
   /**
@@ -661,7 +805,7 @@ export class Router {
         out.push({ id: c.name })
       }
     }
-    for (const s of this.suppliers) {
+    for (const s of this.active) {
       try {
         const ids = s.customModelIds?.()
         for (const id of ids ?? []) {
@@ -730,7 +874,7 @@ export class Router {
   }
 
   async modelsOf(supplierId: string, force = false): Promise<ModelWithEnabled[]> {
-    const s = this.suppliers.find((x) => x.id === supplierId)
+    const s = this.active.find((x) => x.id === supplierId)
     if (s === undefined) return []
     const hit = this.modelsCache.get(supplierId)
     const fresh = hit !== undefined && Date.now() - hit.fetchedAt < MODELS_TTL_MS
@@ -765,7 +909,14 @@ export class Router {
         enabled: !disabled.has(mm.id),
         custom: custom.has(mm.id) ? true : undefined,
       }))
-      // 自定义模型（listModels 之外的）并入显示
+      // 自定义模型（listModels 之外的）并入显示。
+      //
+      // 注意这里**刻意不**把「用户禁用过的模型」也补回来：插件的 listModels 只该报
+      // 「模型来源」，启用状态由核心合并（见 loader.ts 的 modelsWithEnabled）。
+      // 插件若在 listModels 里就把自己禁用的过滤掉，那是它违约 —— 该修的是插件，
+      // 核心不该反过来替它兜着。兜着的后果比表面症状更糟：面板看着正常了，
+      // 而体检的越权检测（probe.ts 的 hiddenDisabledIds）会因为模型已被补全而
+      // 永远报 OK，那个 bug 就再也没人发现了。
       const seen = new Set(models.map((mm) => mm.id))
       for (const id of custom) {
         if (!seen.has(id)) {
@@ -802,7 +953,7 @@ export class Router {
   /** 可用模型（按供应商分组，仅启用），面板加模型用。
    *  各供应商**并行**拉取——串行会把每个上游的延迟累加起来。 */
   async supplierModels(): Promise<Array<{ supplier: { id: string; name: string; alias: string }; models: ModelWithEnabled[] }>> {
-    const groups = await Promise.all(this.suppliers.map(async (s) => {
+    const groups = await Promise.all(this.active.map(async (s) => {
       try {
         const models = (await this.modelsOf(s.id)).filter((m) => m.enabled)
         return { supplier: { id: s.id, name: s.name, alias: s.getAlias() }, models }
@@ -819,10 +970,6 @@ export class Router {
       typeof m === 'string' && m !== '')
   }
 
-  private validStrategy(strategy: string | undefined): strategy is 'fallback' | 'round-robin' {
-    return strategy === 'fallback' || strategy === 'round-robin'
-  }
-
   /** 组合模型统一存裸 id：剥掉 alias/ 前缀（前缀随供应商动态变）。
    *  只剥「已知 alias + /」开头的前缀——模型 id 本身可以含斜杠
    *  （如 nvidia 的 `deepseek-ai/deepseek-v4-flash-0731`），用 lastIndexOf 会把
@@ -844,27 +991,26 @@ export class Router {
         if (slash <= 0) return m
         const alias = m.slice(0, slash)
         const modelId = m.slice(slash + 1)
-        const s = this.suppliers.find((x) => x.getAlias() === alias)
+        const s = this.active.find((x) => x.getAlias() === alias)
         return s === undefined ? modelId : `${s.id},${modelId}`
       })
   }
 
-  /** 创建组合（name 唯一，非 default）。 */
-  createCombo(name: string, strategy: string, models: string[]): { ok: boolean; error?: string; combo?: Combo } {
+  /** 创建组合（name 唯一，非 default）。选模型是降级链（按序尝试），无策略。 */
+  createCombo(name: string, models: string[]): { ok: boolean; error?: string; combo?: Combo } {
     const clean = name.trim()
     if (clean === '' || clean === 'default') return { ok: false, error: '组合名无效' }
     if (!/^[A-Za-z0-9._-]+$/.test(clean)) return { ok: false, error: '组合名只能含字母、数字、-、_ 和 .' }
     if (this.customCombos.some((c) => c.name === clean)) return { ok: false, error: `组合 ${clean} 已存在` }
     if (!this.validModels(models)) return { ok: false, error: '至少需要一个模型' }
-    if (!this.validStrategy(strategy)) return { ok: false, error: '策略无效' }
-    const combo: Combo = { id: clean, name: clean, strategy, models: this.normalizeModelIds(models) }
+    const combo: Combo = { id: clean, name: clean, models: this.normalizeModelIds(models) }
     this.customCombos.push(combo)
     this.saveCombos()
     return { ok: true, combo }
   }
 
   /** 更新组合（按 id）。 */
-  updateCombo(id: string, name: string, strategy: string, models: string[]): { ok: boolean; error?: string } {
+  updateCombo(id: string, name: string, models: string[]): { ok: boolean; error?: string } {
     const target = this.customCombos.find((c) => c.id === id)
     if (!target) return { ok: false, error: '组合不存在' }
     const clean = name.trim()
@@ -872,9 +1018,7 @@ export class Router {
     if (!/^[A-Za-z0-9._-]+$/.test(clean)) return { ok: false, error: '组合名只能含字母、数字、-、_ 和 .' }
     if (this.customCombos.some((c) => c.id !== id && c.name === clean)) return { ok: false, error: `组合 ${clean} 已存在` }
     if (!this.validModels(models)) return { ok: false, error: '至少需要一个模型' }
-    if (!this.validStrategy(strategy)) return { ok: false, error: '策略无效' }
     target.name = clean
-    target.strategy = strategy
     target.models = this.normalizeModelIds(models)
     this.saveCombos()
     return { ok: true }
@@ -929,22 +1073,24 @@ export class Router {
         ttfbMs: probe.ttfbMs,
         // 只有真被服务过才记 uid：失败请求的 uid 可能是空或上一次的残留
         ...(ok && probe.uid !== '' ? { uid: probe.uid } : {}),
+        ...(req.session === undefined ? {} : { session: req.session }),
         ...(error === undefined ? {} : { error }),
       }, usage)
     }
 
     const combo = this.comboByName(req.model)
     if (combo) {
-      // 组合：按策略选起点，然后按组合模型顺序回退
-      const start = combo.strategy === 'round-robin'
-        ? (this.rrCursors.get(combo.id) ?? 0) % combo.models.length
-        : 0
-      if (combo.strategy === 'round-robin') this.rrCursors.set(combo.id, (this.rrCursors.get(combo.id) ?? 0) + 1)
+      // 组合 = 降级链：从第一个模型起顺序尝试，谁先服务成功就停。
       for (let i = 0; i < combo.models.length; i++) {
-        const model = combo.models[(start + i) % combo.models.length]
+        const model = combo.models[i]
         if (model === undefined) continue
         const trace: ChatTrace = { attempts: 0 }
-        const served = await this.chatWithModel(req, res, model, probe, trace)
+        // 每条腿**独立**一份首字节预算：上一条腿已经等满 60s 也不该让下一条腿
+        // 只剩 0ms（否则组合越多越没法用），但同一条腿内的多个号共享一份
+        // （停滞是上游级的，按号各等一份会 11×60s）。
+        const served = await this.chatWithModel(
+          req, res, model, probe, trace, Date.now() + this.firstByteBudgetMs,
+        )
         if (served) {
           settle(true)
           return
@@ -1003,8 +1149,18 @@ export class Router {
    * @param outTrace 可选出参：把这次调用的追踪信息带回去（组合据此判断
    *   要不要「喘口气」再降级）。裸 id 遍历路径不填（多供应商混在一起，
    *   失败状态没有单一归属）。
+   * @param firstByteDeadlineAt 这条腿的首字节截止时刻（绝对 ms）。同一条腿内的
+   *   多个账号共享它——停滞是上游级的，按号各给一份会 11×60s 才轮到下一个模型。
+   *   缺省 = 此刻起一份全新预算（直接调用路径只有这一条腿）。
    */
-  private async chatWithModel(req: ChatRequest, res: ServerResponse, model: string, probe?: UsageProbe, outTrace?: ChatTrace): Promise<boolean> {
+  private async chatWithModel(
+    req: ChatRequest,
+    res: ServerResponse,
+    model: string,
+    probe?: UsageProbe,
+    outTrace?: ChatTrace,
+    firstByteDeadlineAt = Date.now() + this.firstByteBudgetMs,
+  ): Promise<boolean> {
     const comma = model.indexOf(',')
     const supplierId = comma > 0 ? model.slice(0, comma) : undefined
     // 组合存的是供应商 id，但插件认的是自己的模型 id
@@ -1028,28 +1184,33 @@ export class Router {
       return false
     }
     // 精准：只调这一个供应商。查不到就是配置错了，直接失败（不遍历兜底）
-    const s = this.suppliers.find((x) => x.id === supplierId)
+    const s = this.active.find((x) => x.id === supplierId)
     if (s === undefined) {
-      this.logChat(req.model, `supplier ${JSON.stringify(supplierId)} 不存在`, 0)
+      // 「被开关关掉」与「不存在」对请求是同一件事：都没有可用的上游。分开说
+      // 是为了日志能直接看出是用户关了它。
+      const reason = this.suppliers.some((x) => x.id === supplierId)
+        ? `supplier ${JSON.stringify(supplierId)} 已关闭`
+        : `supplier ${JSON.stringify(supplierId)} 不存在`
+      this.logChat(req.model, reason, 0)
       return false
     }
     const t0 = Date.now()
     const trace: ChatTrace = { attempts: 0 }
-    const served = await this.chatWithSupplier(s, clone, res, trace, probe)
+    const served = await this.chatWithSupplier(s, clone, res, trace, probe, firstByteDeadlineAt)
     if (outTrace !== undefined) {
       outTrace.attempts = trace.attempts
       outTrace.lastError = trace.lastError
       outTrace.lastState = trace.lastState
     }
     this.logChat(req.model, served
-      ? `${s.id}/${modelId} (${trace.uid ?? '?'}) ok${trace.attempts > 0 ? ` 重试${trace.attempts}次` : ''}`
+      ? `${s.id}/${modelId} (${trace.uid ?? '?'}) ok${trace.attempts > 0 ? ` 重试${trace.attempts}次` : ''}${trace.pickWhy !== undefined ? ` [选号: ${trace.pickWhy}]` : ''}`
       : `${s.id}/${modelId} 失败 ${trace.lastError ?? 'no account'}`, Date.now() - t0)
     return served
   }
 
   /** 按别名找供应商（对外模型全名 = alias/model）。别名唯一，故最多命中一个。 */
   supplierByAlias(alias: string): Supplier | undefined {
-    return this.suppliers.find((s) => s.getAlias() === alias)
+    return this.active.find((s) => s.getAlias() === alias)
   }
 
   /**
@@ -1060,8 +1221,24 @@ export class Router {
    * 还能换号重试；一旦写出第一个字节就绑死（HTTP 语义，9router 同样如此），
    * 之后出错不再换号——要彻底能回退就得在写头前缓冲判定，代价是首字节
    * 延迟，目前未做。
+   *
+   * @param firstByteDeadlineAt 这条腿的首字节截止时刻（见 chatWithModel）。
+   *   预算耗尽后不再调任何号：剩下的号大概率同样停滞（上游级故障），
+   *   挨个等下去只会把 60s 乘以号数，组合永远轮不到下一个模型。
    */
-  private async chatWithSupplier(s: Supplier, req: ChatRequest, res: ServerResponse, trace?: ChatTrace, probe?: UsageProbe): Promise<boolean> {
+  /**
+   * @param onlyUid - 只试这一个连接，**不做账号池回退**。给面板「指定连接」那档用
+   *   （诊断单个链接到底通不通）；正常请求与普通模型测试都不传，走账号池。
+   */
+  private async chatWithSupplier(
+    s: Supplier,
+    req: ChatRequest,
+    res: ServerResponse,
+    trace?: ChatTrace,
+    probe?: UsageProbe,
+    firstByteDeadlineAt = Date.now() + this.firstByteBudgetMs,
+    onlyUid?: string,
+  ): Promise<boolean> {
     const pool = s.pool
     const cfg = this.store.get(s.id)
     // 无账号供应商：直接调一次（uid 传空，插件忽略）
@@ -1085,7 +1262,9 @@ export class Router {
         probe.model = `${s.getAlias()}/${stripAlias(req.model, s.getAlias())}`
         probe.uid = ''
       }
-      return await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0)
+      return await writeChatResult(
+        res, r, req.stream, probe, probe?.startedAt ?? 0, firstByteDeadlineAt - Date.now(),
+      )
     }
     // 试过的号不再选：某些失败状态既不冷却也不计数（如模型不属于本供应商），
     // 不排除试过的就会原地打转——死循环等于整个服务挂住。
@@ -1093,9 +1272,35 @@ export class Router {
     // 否则同一会话的两次尝试会绑到不同的号上）。
     const messages = reqMessages(req.rawBody)
     const tried = new Set<string>()
+    let pickWhy = ''
     for (;;) {
-      const uid = pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, cfg.poolStrategy, req.model, messages)
-      if (uid === undefined) return false
+      // 指定连接：只试它。选不中就直接失败并说明原因（连接已不存在/不在池里），
+      // **不回退到别的号** —— 否则「测这个连接」测出来的是另一个号的结果，
+      // 诊断就变成了假话。
+      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) {
+          // 不给 AccountState 加「连接不存在」这个值：那是给**账号的失败**分类用的
+          // （决定要不要冷却），而链接不存在不是任何账号的错，混进去会让所有分类逻辑
+          // 都要认识它。具体原因放 lastError 就够。
+          trace.lastState = 'unknown'
+          trace.lastError = `连接 ${JSON.stringify(onlyUid)} 不存在（可能已被删除）`
+        }
+        return false
+      }
+      // 腿的首字节预算已经耗尽：不再调下一个号。停滞是上游级的，剩下那些号
+      // 挨个等下去 = 60s × 号数，组合永远轮不到下一个模型（2026-09-24 实测）。
+      const left = firstByteDeadlineAt - Date.now()
+      if (left <= 0) {
+        if (trace !== undefined) {
+          trace.lastState = 'transport'
+          trace.lastError = 'first-byte budget exhausted'
+        }
+        return false
+      }
+      pickWhy = pool.lastWhy
       tried.add(uid)
       const r = await s.chatOnce(uid, req.lv ?? 'auto', req)
       if (!r.ok) {
@@ -1121,7 +1326,10 @@ export class Router {
         continue
       }
       pool.noteSuccess(uid, req.model)
-      if (trace !== undefined) trace.uid = uid
+      if (trace !== undefined) {
+        trace.uid = uid
+        trace.pickWhy = pickWhy
+      }
       if (probe !== undefined) {
         probe.supplier = s.id
         // 记对外全名 alias/model：与直接调用路径一致。组合里存的是裸
@@ -1130,13 +1338,13 @@ export class Router {
         probe.model = `${s.getAlias()}/${stripAlias(req.model, s.getAlias())}`
         probe.uid = uid
       }
-      const committed = await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0)
+      const committed = await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0, firstByteDeadlineAt - Date.now())
       if (committed) {
         // 块轮询反馈：只有成功请求才计入（失败没产生缓存，计入会污染命中率）
-        pool.noteCache(uid, req.model, probe?.tokens?.cachedTokens ?? 0)
+        pool.noteCache(uid, req.model, probe?.tokens?.cachedTokens ?? 0, req.session)
         return true
       }
-      // 一个字节都没写（上游刚连上就断）→ 这个号不算数，换下一个重试
+      // 一个字节都没写（上游刚连上就断 / 首字节超时）→ 这个号不算数，换下一个重试
       pool.noteFailure(uid, req.model, 'transport', 'stream failed before first byte')
       if (trace !== undefined) {
         trace.attempts += 1
@@ -1146,11 +1354,17 @@ export class Router {
     }
   }
 
-  /** 测试某供应商的某模型是否可用。
-   *  走真实的账号遍历 + chatOnce 路径：账号池回退/冷却由核心实现，自动生效；
-   *  响应丢弃到 sink，限定单一供应商（不跨供应商回退）。 */
-  async testModel(supplierId: string, model: string): Promise<{ ok: boolean; error?: string }> {
-    const s = this.suppliers.find((x) => x.id === supplierId)
+  /**
+   * 测试某供应商的某模型是否可用。
+   *
+   * 走真实的账号遍历 + chatOnce 路径：账号池回退/冷却由核心实现，自动生效；
+   * 响应丢弃到 sink，限定单一供应商（不跨供应商回退）。
+   *
+   * @param onlyUid - 限定只测这一个连接（诊断单个链接），**不做账号池回退**。
+   *   不传 = 与面板「测试」按钮完全同一条路径（池内任选可用号，失败自动换号）。
+   */
+  async testModel(supplierId: string, model: string, onlyUid?: string): Promise<{ ok: boolean; error?: string }> {
+    const s = this.active.find((x) => x.id === supplierId)
     if (s === undefined) return { ok: false, error: `unknown supplier ${JSON.stringify(supplierId)}` }
     const sink = sinkRes()
     const req: ChatRequest = {
@@ -1161,7 +1375,7 @@ export class Router {
     let served = false
     const trace: ChatTrace = { attempts: 0 }
     try {
-      served = await this.chatWithSupplier(s, req, sink, trace)
+      served = await this.chatWithSupplier(s, req, sink, trace, undefined, Date.now() + this.firstByteBudgetMs, onlyUid)
     } catch (err) {
       return { ok: false, error: (err as Error).message }
     }