dsh-router-core 0.3.10 → 0.3.12

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

@@ -36,12 +36,129 @@ test('选号：某模型冷却中的号对该模型跳过，全冷却返回 unde
   assert.equal(p.pick(list, [], 'fallback', 'm1'), undefined)
 })
 
-test('round-robin 在健康号间轮转（带 model）', () => {
+test('round-robin 是块轮询：块内粘住不换号（带 model）', () => {
   const p = pool()
   const list = accs(['a', 'b'])
+  // 块没满 → 一直粘在 a（这就是缓存命中的来源）
   assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+})
+
+// ============ 块轮询（docs/pool-sticky-block.md） ============
+
+/** 连打 n 次成功请求，全部命中缓存。 */
+const serveHits = (p: AccountPool, uid: string, n: number, model = 'm1'): void => {
+  for (let i = 0; i < n; i++) p.noteCache(uid, model, 1000)
+}
+/** 连打 n 次成功请求，全部未命中（cold miss）。 */
+const serveMiss = (p: AccountPool, uid: string, n: number, model = 'm1'): void => {
+  for (let i = 0; i < n; i++) p.noteCache(uid, model, 0)
+}
+
+test('【块】OR：计数<N(最短驻留)且没达标 → 留守，哪怕缓存已热', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  // 计数 15 < N(16)，命中率 100% >= M → 留守（最短驻留没走完，不因热度提前跳）
+  serveHits(p, 'a', 15)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+})
+
+test('【块】OR：计数到 N 且命中率达标 → 换号（下一号也冷启动，让位均衡）', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  // 计数 16 >= N 且命中率 100% >= 85% → 换号
+  serveHits(p, 'a', 16)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+})
+
+test('【块】OR：命中率没达标 → 计数到 N 仍留守（继续热，不急换）', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  // 计数 20 全 miss → 命中率 0% < 85% → 留守（OR 语义：ratio<M 时留守）
+  serveMiss(p, 'a', 20)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+})
+
+test('【块】N_max 兜底：命中率一直不达标 → 到 N_max(48) 必换', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  // 一直 miss，命中率 0% 永不达标 → 不靠 N 换，靠 N_max 兜底
+  serveMiss(p, 'a', 48)
+  // 47 次后仍在 a；第 48 次触发 noteCache 的降权，随后 pick 跳过 a
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+})
+
+test('【块】驻留满 N_max 仍不达标 → 该号降权，后续轮转跳过', () => {
+  const p = pool()
+  const list = accs(['a', 'b', 'c'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  serveMiss(p, 'a', 48) // a 判定缓存无效（降权）
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b') // 跳过 a
+  // b 正常服务并达标 → 切走后轮转也应跳过 a
+  serveHits(p, 'b', 16)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'c')
+})
+
+test('【块】降权不是永久判决：全池都降权时退回健康池兜底', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  serveMiss(p, 'a', 48)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+  serveMiss(p, 'b', 48)
+  // 两个都降权 → 不能返回 undefined（那等于服务挂了），退回健康池
+  const uid = p.pick(list, [], 'round-robin', 'm1')
+  assert.equal(uid !== undefined, true)
+})
+
+test('【块】故障切走作废块：dropBlock 后重新选号', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  serveHits(p, 'a', 3) // 块才 3 次，本来会留守
+  p.dropBlock('m1')
+  // 块作废 → 从 a 之后前进，选到 b（而不是带着旧计数继续粘 a）
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+})
+
+test('【块】失败请求不入块统计（失败没产生缓存，计入会污染命中率）', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  // 16 次全命中 → 达标切走（失败不算，否则比例被稀释永不达标）
+  serveHits(p, 'a', 16)
   assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+})
+
+test('【块】块状态按模型隔离：m1 的驻留不影响 m2', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
   assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  serveHits(p, 'a', 16) // m1 上 a 已达标
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+  // m2 是独立的块 → 从头开始，选 a
+  assert.equal(p.pick(list, [], 'round-robin', 'm2'), 'a')
+})
+
+test('【块】多号间长期均衡：块大小有界 → 请求数均分', () => {
+  const p = pool()
+  const list = accs(['a', 'b', 'c'])
+  const count: Record<string, number> = { a: 0, b: 0, c: 0 }
+  // 每个块 16 次（全命中达标），跑 12 个块
+  for (let block = 0; block < 12; block++) {
+    const uid = p.pick(list, [], 'round-robin', 'm1')!
+    count[uid]! += 1
+    serveHits(p, uid, 16)
+  }
+  // 12 块 / 3 号 → 每号 4 块
+  assert.equal(count['a'], 4)
+  assert.equal(count['b'], 4)
+  assert.equal(count['c'], 4)
 })
 
 // ============ 核心新语义：冷却按 (模型, 连接) 分号 ============

package/src/router/account-pool.ts

@@ -86,6 +86,15 @@ const ERR_THRESHOLD = 3
 /** 攒够后的冷却时长。 */
 const ERR_COOLDOWN_MS = 5 * MINUTE
 
+/** 块轮询：命中率达标就放行（`留守 = 计数<N OR 命中率<M`）。见 stickyBlock 说明。 */
+const BLOCK_HIT_RATIO = 0.85
+/** 块轮询：最短驻留。新接到这个号的最少连续服务次数（防冷启动误切）。 */
+const BLOCK_MIN = 16
+/** 块轮询：绝对兜底。轮次过多(max)无论命中率如何都让位，防死守 + 保均衡下限。 */
+const BLOCK_MAX = 48
+/** 块轮询：判定「缓存无效」后的跳过时长。 */
+const BLOCK_DEMOTE_MS = 10 * MINUTE
+
 /** 冷却记录（键 = (supplier, model, uid)）。 */
 interface CooldownEntry {
   until: number
@@ -100,6 +109,26 @@ interface UidEntry {
   reason: string
 }
 
+/**
+ * 块轮询的驻留状态（键 = (supplier, model)，与冷却同粒度）。
+ *
+ * 为什么按 (供应商, 模型) 而不是按号：块是「当前这一轮由谁服务」的概念，
+ * 一个模型上只有一个号在驻留；换模型意味着换前缀，块自然作废。
+ */
+interface BlockState {
+  /** 当前驻留的号。 */
+  uid: string
+  /** 本块已服务的成功请求数。 */
+  served: number
+  /** 本块命中缓存（cachedTokens > 0）的请求数。 */
+  hits: number
+}
+
+/** 「缓存无效」降权记录（键 = (supplier, model, uid)）。 */
+interface DemoteEntry {
+  until: number
+}
+
 /** 指数退避：等级 1 = BACKOFF_BASE_MS，每级翻倍，封顶 BACKOFF_MAX_MS。 */
 function backoffMs(level: number): number {
   return Math.min(BACKOFF_BASE_MS * 2 ** Math.max(0, level - 1), BACKOFF_MAX_MS)
@@ -116,6 +145,10 @@ export class AccountPool {
   /** uid → 连接级禁用 / 手动暂停。 */
   private byUid = new Map<string, UidEntry>()
   private rrCursor = 0
+  /** (supplier, model) → 块轮询驻留状态。 */
+  private blocks = new Map<string, BlockState>()
+  /** (supplier, model, uid) → 缓存无效降权。 */
+  private demoted = new Map<string, DemoteEntry>()
 
   constructor(supplierId = '') {
     this.supplierId = supplierId
@@ -169,9 +202,19 @@ export class AccountPool {
 
   /**
    * 按策略为「某个模型」选一个健康账号。
+   *
+   * round-robin 走**块轮询**：一次轮转内连续服务若干请求，而不是每请求换号。
+   * 设计见 docs/pool-sticky-block.md。要点：
+   *  - 留守 = `计数 < N OR 命中率 < M`(OR,用户拍板):
+   *    命中率达标（缓存热了）→ 换号保均衡；计数到 N → 换号止损。
+   *    单号最多连续服务 N 次，不会因命中率低而死守到 N_max（打架场景关键）。
+   *  - 切号因子的思路：命中率是**留守**条件不是切号条件。反接会正反馈死锁
+   *    （切→cold miss→命中率 0%→触发切号→…），见文档 §3。
+   *  - `N_max` 绝对兜底：命中率永远不达标的号不能无限驻留（防死锁 + 防均衡归零）。
+   *
    * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
    * @param poolOrder 用户在面板拖出来的顺序（核心管）
-   * @param strategy fallback 取第一个健康 / round-robin 轮转健康号
+   * @param strategy fallback 取第一个健康 / round-robin 块轮转健康号
    * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
    * @returns 选中的 uid；无健康账号返回 undefined
    */
@@ -186,11 +229,80 @@ export class AccountPool {
     const healthy = ordered.filter((uid) => this.healthy(uid, modelId, now))
     if (healthy.length === 0) return undefined
     if (strategy !== 'round-robin') return healthy[0]
-    const uid = healthy[this.rrCursor % healthy.length]
-    this.rrCursor = (this.rrCursor + 1) % healthy.length
+    // 缓存无效降权：驻留满 N_max 命中率仍不达标的号，跳过它（可到期恢复）
+    const usable = healthy.filter((uid) => !this.isDemoted(uid, modelId, now))
+    const pool = usable.length > 0 ? usable : healthy
+    const block = this.blocks.get(this.blockKey(modelId))
+    if (block !== undefined && pool.includes(block.uid) && this.blockKeeps(block)) {
+      return block.uid
+    }
+    // 块满/块达标/块不存在 → 前进游标。从当前号之后开始找，保证轮转顺序稳定。
+    const from = block === undefined ? this.rrCursor : Math.max(0, pool.indexOf(block.uid) + 1)
+    const uid = pool[from % pool.length]!
+    this.rrCursor = (pool.indexOf(uid) + 1) % pool.length
+    this.blocks.set(this.blockKey(modelId), { uid, served: 0, hits: 0 })
     return uid
   }
 
+  /** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
+  private isDemoted(uid: string, modelId: string, now: number): boolean {
+    const e = this.demoted.get(this.key(modelId, uid))
+    return e !== undefined && e.until > now
+  }
+
+  /**
+   * 块是否还应驻留在当前号上。
+   *
+   * OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
+   * 单一账号内部：一个号先被轮到（冷启动/热），然后
+   *   - 命中率**爬上去**（>= M，缓存热了）→ 让位，轮到下一个号（均衡）
+   *   - 命中率**没上去**（冷启动/短块）→ 留守，继续热（不急着跳）
+   *   - 轮次**实在太多**（计数 >= N_max）→ 也换（防死守 + 保均衡下限）
+   *
+   * 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
+   * 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
+   *
+   * 每个号各自守着「这个会话在自己账号上的那段前缀」，轮流热；
+   * 命中率 = 块的命中占比。单会话下每个号块都从冷到热各付一次,
+   * 收益来自块内连续驻留(缺了它就跟每请求轮询一样)。
+   */
+  private blockKeeps(block: BlockState): boolean {
+    if (block.served >= BLOCK_MAX) return false // 轮次过多 → 让位（兜底）
+    const ratio = block.served === 0 ? 0 : block.hits / block.served
+    return block.served < BLOCK_MIN || ratio < BLOCK_HIT_RATIO // 计数<N OR 命中率<M
+  }
+
+  /**
+   * 记录一次成功请求的缓存命中情况（块轮询的反馈信号）。
+   *
+   * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错切。
+   * @param uid 实际服务的号
+   * @param modelId 模型（块粒度）
+   * @param cachedTokens 上游报的命中 token 数；0 = 全量重算
+   */
+  noteCache(uid: string, modelId: string, cachedTokens: number): void {
+    const k = this.blockKey(modelId)
+    const block = this.blocks.get(k)
+    // 块已被别处重置/换号（如故障切走）→ 这次结果不属于当前块，忽略
+    if (block === undefined || block.uid !== uid) return
+    block.served += 1
+    if (cachedTokens > 0) block.hits += 1
+    // 驻留满 N_max 仍不达标 → 判定缓存无效，降权一段时间（可恢复）
+    if (block.served >= BLOCK_MAX && block.hits / block.served < BLOCK_HIT_RATIO) {
+      this.demoted.set(this.key(modelId, uid), { until: Date.now() + BLOCK_DEMOTE_MS })
+    }
+  }
+
+  /** 故障切走时作废当前块：换号后前缀归属变了，块计数不能沿用。 */
+  dropBlock(modelId: string): void {
+    this.blocks.delete(this.blockKey(modelId))
+  }
+
+  /** 块状态键：与冷却同粒度 (supplier, model)，不含 uid。 */
+  private blockKey(modelId: string): string {
+    return `${this.supplierId}${SEP}${modelId}`
+  }
+
   /** 记录一次失败：按状态处置（冷却/禁用/退避），落在「(模型, 连接)」这个冷却单元上。 */
   noteFailure(uid: string, modelId: string, state: AccountState, message: string): void {
     const rule = RULES[state]

package/src/router/index.ts

@@ -615,6 +615,38 @@ export class Router {
    * 只有两种情况会真的等:`force`(用户主动刷新)和**从来没有过缓存值**
    * (冷启动,没有旧值可给)。后者只发生一次。
    */
+  /**
+   * 组合的上下文窗口(token):组合内各模型窗口的**最小值**,拿不到就 undefined。
+   *
+   * 只读缓存、绝不打上游:调用方是 llm adapter 的 `resolveModel`,它在每次
+   * 请求前后都可能被调用,不能为了报一个容量去触发按供应商的网络往返。
+   * 冷启动(还没缓存)时给 undefined —— 自动压缩会因此跳过这一轮,下次就
+   * 有了,比撒谎说一个窗口值安全。
+   *
+   * 单位:`ModelInfo.context_length` 存的是 **K**(供应商插件统一
+   * `Math.round(tokens / 1000)`,见 codebuddy plugin),这里换算回 token。
+   *
+   * 取最小而不是最大:组合会按策略 fallback 到任意一个模型,按最窄的声明
+   * 才能让「快满了」这件事在任何一条分支上都成立。
+   */
+  comboContextWindow(combo: Combo): number | undefined {
+    let min: number | undefined
+    for (const ref of combo.models) {
+      const at = ref.indexOf(',')
+      if (at < 0) continue
+      const supplierId = ref.slice(0, at)
+      const modelId = ref.slice(at + 1)
+      const hit = this.modelsCache.get(supplierId)
+      if (hit === undefined) return undefined // 这家还没缓存过,不猜
+      const m = hit.models.find((x) => x.id === modelId)
+      const k = m?.context_length
+      if (typeof k !== 'number' || !Number.isFinite(k) || k <= 0) continue
+      const tokens = Math.round(k * 1000)
+      if (min === undefined || tokens < min) min = tokens
+    }
+    return min
+  }
+
   async modelsOf(supplierId: string, force = false): Promise<ModelWithEnabled[]> {
     const s = this.suppliers.find((x) => x.id === supplierId)
     if (s === undefined) return []
@@ -813,6 +845,8 @@ export class Router {
         ok,
         durationMs: Date.now() - probe.startedAt,
         ttfbMs: probe.ttfbMs,
+        // 只有真被服务过才记 uid：失败请求的 uid 可能是空或上一次的残留
+        ...(ok && probe.uid !== '' ? { uid: probe.uid } : {}),
         ...(error === undefined ? {} : { error }),
       }, usage)
     }
@@ -986,6 +1020,8 @@ export class Router {
           return false
         }
         pool.noteFailure(uid, req.model, r.state, r.message)
+        // 故障切走：下次选号会换号，旧块的驻留计数不再适用（前缀归属变了）
+        pool.dropBlock(req.model)
         if (trace !== undefined) {
           trace.attempts += 1
           trace.lastState = r.state
@@ -1004,8 +1040,12 @@ export class Router {
         probe.uid = uid
       }
       const committed = await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0)
+      if (committed) {
+        // 块轮询反馈：只有成功请求才计入（失败没产生缓存，计入会污染命中率）
+        pool.noteCache(uid, req.model, probe?.tokens?.cachedTokens ?? 0)
+        return true
+      }
       // 一个字节都没写（上游刚连上就断）→ 这个号不算数，换下一个重试
-      if (committed) return true
       pool.noteFailure(uid, req.model, 'transport', 'stream failed before first byte')
       if (trace !== undefined) {
         trace.attempts += 1

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

@@ -671,3 +671,41 @@ test('流式：剥掉上游多发一次的空白 tool_call name/id', async () =>
   assert.equal(callId, 'chatcmpl-tool-a7ee5a0d3c361c7f', 'callId 也不能被空串冲掉')
   assert.deepEqual(JSON.parse(args), { command: 'echo hello' }, 'arguments 正常累积')
 })
+
+/**
+ * 组合上下文窗口 —— dsh 的自动压缩靠它算阈值（默认窗口用到 80% 触发）。
+ * adapter 报不出 contextWindow 时，dsh-compaction-basic 直接抛错并**静默
+ * 关闭自动压缩**，上下文于是一路涨到模型硬上限才炸。
+ */
+test('组合窗口：取组合内模型的最小值，单位 K → token', async () => {
+  const router = new Router('')
+  addSupplier(router, supplier('a', [
+    { id: 'a-1', context_length: 128 },   // 128K
+    { id: 'a-2', context_length: 1000 },  // 1M
+  ]).s)
+  await router.modelsOf('a') // 填缓存
+  const w = router.comboContextWindow({ id: 'x', name: 'x', strategy: 'fallback', models: ['a,a-1', 'a,a-2'] })
+  assert.equal(w, 128_000, '取最小的那个（fallback 到任意一条分支都得成立）')
+})
+
+test('组合窗口：供应商还没缓存过 → undefined（不猜，绝不打上游）', () => {
+  const router = new Router('')
+  addSupplier(router, supplier('a', [{ id: 'a-1', context_length: 128 }]).s)
+  // 故意不调 modelsOf：模拟冷启动
+  assert.equal(
+    router.comboContextWindow({ id: 'x', name: 'x', strategy: 'fallback', models: ['a,a-1'] }),
+    undefined,
+    '没缓存就报 undefined —— 压缩这轮跳过，下次就有，比撒谎安全',
+  )
+})
+
+test('组合窗口：模型都没报 context_length → undefined', async () => {
+  const router = new Router('')
+  addSupplier(router, supplier('a', [{ id: 'a-1' }]).s)
+  await router.modelsOf('a')
+  assert.equal(
+    router.comboContextWindow({ id: 'x', name: 'x', strategy: 'fallback', models: ['a,a-1'] }),
+    undefined,
+    '一家都没报就别编一个数（traework/nvidia 目前就是如此）',
+  )
+})

package/src/router/types.ts

@@ -70,6 +70,8 @@ export interface Supplier {
   readonly priority: number
   /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
   readonly icon?: string
+  /** 「添加 API key」弹窗提示文案（缺省前端用通用文案）。可选。 */
+  readonly apiKeyHint?: string
   status(): SupplierStatus
   listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[]
   /** 面板展示的模型（含启用/自定义标记）。 */

package/src/router/usage-store.ts

@@ -44,6 +44,14 @@ export interface UsageRecord {
   durationMs: number
   /** 首字节延迟（ms）；非流式为 0。 */
   ttfbMs: number
+  /**
+   * 实际服务的账号 uid（成功时回填）。
+   *
+   * 有了它才能把命中率按**号**下钻——prompt cache 是 per-account 命名空间，
+   * 只看供应商/模型无法判断「是某个号的缓存没热，还是策略在乱切号」。
+   * 块轮询（docs/pool-sticky-block.md）的调参完全依赖这个归因。
+   */
+  uid?: string
   /** 失败原因（ok=false 时）。 */
   error?: string
 }

package/src/shared.ts

@@ -70,6 +70,8 @@ export interface RouterHealthResponse {
     name: string
     /** 图标（URL 或 SVG data URI）。 */
     icon?: string
+    /** 「添加 API key」弹窗提示文案（缺省前端用通用文案）。 */
+    apiKeyHint?: string
     /** 面板能力集合（登录/签到/连接池/模型管理等，按存在性）。 */
     capabilities?: string[]
     /** 来源：内置 / 用户目录 / 外部插件。 */
@@ -137,6 +139,26 @@ export interface RouterSettingsResponse {
   requireApiKey?: boolean
 }
 
+/** 一条扩展器（`/router/api/ext`）。 */
+export interface RouterExtItem {
+  id: string
+  name: string
+  description?: string
+  /** 是否启用改写（面板开关）。 */
+  enabled?: boolean
+  /** 运行时是否就绪（如 RTK 二进制是否可用）。 */
+  ready?: boolean
+  /** 一句话状态说明（如「本机未装 rtk」）。 */
+  detail?: string
+}
+
+/** `/router/api/ext` response（扩展插件列表 + 开关）。 */
+export interface RouterExtResponse {
+  ok: boolean
+  error?: string
+  enhancers?: RouterExtItem[]
+}
+
 /** 供应商模型（含启用状态）。 */
 export interface RouterSupplierModel {
   id: string

package/src/suppliers/contract.ts

@@ -23,6 +23,21 @@ export interface SupplierEnv {
   store: SupplierConfigStore
   /** 通用凭证存储（账号凭证，核心统一管）。 */
   credentials: CredentialStore
+  /**
+   * 迟到的失败上报（可选）——**只在响应已提交之后**才用。
+   *
+   * 流式请求一旦写出第一个字节就绑死（HTTP 语义），此时上游再报错已经换不了
+   * 号、也改不了状态码。但「这个号坏了」这件事对**后续**请求仍然有价值：
+   * 不报上来，它就会继续留在池里被轮转选中，每次都白撞一次同一个错误。
+   *
+   * 核心实现 = `pool.noteFailure(uid, model, state, message)`，按该状态的规则
+   * 冷却/禁用。真实案例：TRAE 免费通道对某账号拒绝某模型时发 HTTP 200 +
+   * 流内 `code=4008`，三个号里两个如此，round-robin 下 2/3 请求直接失败
+   * （2026-09-08 实测）——有了这条通道，坏号被冷一次就退出轮转。
+   *
+   * 插件拿不到也不用兜底：不调用就退化成今天的行为，不影响正确性。
+   */
+  onLateFailure?: (uid: string, model: string, state: AccountState, message: string) => void
 }
 
 /** 通用供应商工厂：一个 js 模块 export 它（或 default export 它），loader 调用得到实例。 */
@@ -97,6 +112,13 @@ export interface SupplierModule {
   /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
   readonly icon?: string
 
+  /**
+   * 「添加 API key」弹窗的提示文案（HTML 未转义前是纯文本）。可选。
+   * 缺省时前端用通用文案。供应商若走 `addApiKey` 且有自己的 key 获取方式，
+   * 应提供它——否则所有供应商弹窗都显示同一句通用提示（如默认会写 OpenRouter）。
+   */
+  readonly apiKeyHint?: string
+
   // ---- 核心（必须） ----
   /** 报账号「现在状态」。冷却/禁用/错误累计由核心叠加，插件不算这些。 */
   status(): SupplierStatusNow

package/src/suppliers/loader.test.ts

@@ -15,7 +15,7 @@ import { join } from 'node:path'
 import { wrapModule } from './loader.ts'
 import { SupplierConfigStore } from '../supplier-config.ts'
 import type { CredentialStore } from '../credential-store.ts'
-import type { SupplierModule, SupplierAccountNow, ChatOnceResult } from './contract.ts'
+import type { SupplierEnv, SupplierModule, SupplierAccountNow, ChatOnceResult } from './contract.ts'
 import type { ChatRequest } from '../router/types.ts'
 
 const UNKNOWN = -1
@@ -116,3 +116,68 @@ test('不持久化（store fp 为空）时也不炸', async () => {
   const loaded = wrapModule(plugin('codebuddy', [[acct('cb-1', 50)]]), e, 'test')
   assert.equal(loaded.supplier.status().accounts[0]?.credits, 50)
 })
+
+// ---------------------------------------------------------------------------
+// onLateFailure：流式响应已提交后才发现的失败，要落回本供应商的池
+// ---------------------------------------------------------------------------
+
+/**
+ * 造一个会调用 env.onLateFailure 的插件（模拟 traework 的流式 4008 上报）。
+ * 记录它拿到的 env —— 用于验证「factory 先跑、回调后挂」这个顺序下插件仍能用。
+ */
+function latePlugin(id: string, seen: SupplierEnv[]): SupplierModule {
+  let captured: SupplierEnv | undefined
+  return {
+    id,
+    name: id,
+    status: () => ({ id, name: id, accounts: [acct('u1', 0), acct('u2', 0)] }),
+    listModels: () => [],
+    getAlias: () => id,
+    chatOnce: async (_uid: string, _req: ChatRequest): Promise<ChatOnceResult> => ({ ok: true, status: 200, body: '{}' }),
+    dispose: () => {},
+    // 真实插件（traework）在 factory 里存下 env，调用时才读 onLateFailure
+    __capture: (env: SupplierEnv) => { captured = env; seen.push(env) },
+    __report: (uid: string, model: string) => captured?.onLateFailure?.(uid, model, 'quota', 'boom'),
+  } as unknown as SupplierModule
+}
+
+test('onLateFailure 挂到 env 上，且冷却作用于本供应商的池（坏号退出选号）', () => {
+  const { env: e } = env()
+  const seen: SupplierEnv[] = []
+  const p = latePlugin('supA', seen)
+  const loaded = wrapModule(p, e, 'test')
+  assert.notEqual(e.onLateFailure, undefined, 'wrapModule 之后回调已挂上（插件必须调用时才读）')
+  // 模拟插件在 factory 里存下 env —— 此刻再读 onLateFailure 才有值
+  ;(p as unknown as { __capture(env: SupplierEnv): void }).__capture(e)
+
+  // 上报前：两个号都健康
+  const before = loaded.supplier.status().accounts.map((a) => a.cooling)
+  assert.deepEqual(before, [false, false])
+  // 上报 u1 在模型 m1 上的配额失败
+  ;(p as unknown as { __report(uid: string, model: string): void }).__report('u1', 'm1')
+  const after = new Map(loaded.supplier.status().accounts.map((a) => [a.uid, a.cooling]))
+  assert.equal(after.get('u1'), true, '上报后该号应进入冷却')
+  assert.equal(after.get('u2'), false, '冷却是 (模型,号) 粒度，不能连坐同供应商其它号')
+  // 且真的退出选号：只剩 u2
+  assert.equal(loaded.supplier.pool.pick(loaded.supplier.accounts(), [], 'fallback', 'm1'), 'u2')
+  assert.equal(loaded.supplier.pool.pick(loaded.supplier.accounts(), [], 'fallback', 'm2'), 'u1', '换个模型不受影响')
+})
+
+test('onLateFailure 不串供应商：各自落到自己的池', () => {
+  const { env: ea } = env()
+  const { env: eb } = env()
+  const loadedA = wrapModule(latePlugin('supA', []), ea, 'testA')
+  const loadedB = wrapModule(latePlugin('supB', []), eb, 'testB')
+  ea.onLateFailure?.('u1', 'm1', 'quota', 'boom')
+  const coolA = new Map(loadedA.supplier.status().accounts.map((a) => [a.uid, a.cooling]))
+  const coolB = new Map(loadedB.supplier.status().accounts.map((a) => [a.uid, a.cooling]))
+  assert.equal(coolA.get('u1'), true)
+  assert.equal(coolB.get('u1'), false, 'A 的失败不能冷到 B 的号')
+})
+
+test('onLateFailure 空 uid（无账号供应商）→ 不记，不炸', () => {
+  const { env: e } = env()
+  const loaded = wrapModule(latePlugin('supA', []), e, 'test')
+  assert.doesNotThrow(() => e.onLateFailure?.('', 'm1', 'quota', 'boom'))
+  assert.deepEqual(loaded.supplier.status().accounts.map((a) => a.cooling), [false, false])
+})

package/src/suppliers/loader.ts

@@ -83,13 +83,23 @@ const DIFF_CAPS = [
   'checkinNow',
 ] as const
 
+/**
+ * 每个供应商一份 env 副本：`onLateFailure` 是**按供应商**绑到本供应商的池上
+ * 的（见 wrapModule），共用一个 env 对象会让所有插件的上报都落到最后一个
+ * 供应商的池里。副本是浅拷贝，store/credentials 仍是同一实例。
+ */
+function ownEnv(env: SupplierEnv): SupplierEnv {
+  return { ...env }
+}
+
 /** 从文件构造 LoadedSupplier。 */
 async function loadOne(file: string, env: SupplierEnv, source: 'builtin' | 'user'): Promise<LoadedSupplier> {
   const mod = await importSupplierFile(file)
+  const mine = ownEnv(env)
   // 支持 factory: 模块本身就是工厂函数
   let instance: SupplierModule
   if (typeof mod === 'function') {
-    instance = (mod as unknown as SupplierFactory)(env)
+    instance = (mod as unknown as SupplierFactory)(mine)
     if (typeof instance !== 'object' || instance === null || typeof instance.id !== 'string' || instance.id === '') {
       throw new Error(`供应商 factory 返回无效: ${file}`)
     }
@@ -97,7 +107,7 @@ async function loadOne(file: string, env: SupplierEnv, source: 'builtin' | 'user
   } else {
     instance = mod
   }
-  return wrapModule(instance, env, file, source)
+  return wrapModule(instance, mine, file, source)
 }
 
 /**
@@ -119,11 +129,21 @@ export function wrapModule(instance: SupplierModule, env: SupplierEnv, source: s
   // 冷却键带 supplierId（跨供应商同名模型不串），故构造时注入本供应商 id。
   const pool = new AccountPool(instance.id)
 
+  // 迟到失败的上报通道：流式响应已提交后插件才发现的错误，经它落回同一个池。
+  // **直接挂在插件持有的那个 env 对象上**（不新建副本）——factory 在建 pool
+  // 之前就跑完了，插件若构造时读了 env 就永远拿不到这个字段。插件必须在
+  // **调用时**读 `env.onLateFailure`（见契约注释），此刻它已经挂好。
+  env.onLateFailure = (uid, model, state, message): void => {
+    if (uid === '') return // 无账号供应商（如 opencode）没号可记
+    pool.noteFailure(uid, model, state, message)
+  }
+
   const supplier: Supplier = {
     id: instance.id,
     name: instance.name,
     priority: instance.priority ?? 0,
     icon: (instance as { icon?: string }).icon,
+    apiKeyHint: (instance as { apiKeyHint?: string }).apiKeyHint,
     status: (): SupplierStatus => {
       const now = instance.status()
       // 连接池显示别名覆盖：uid 不变，只改面板展示名