dsh-router-core 0.3.2 → 0.3.3

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

@@ -1,5 +1,11 @@
 /**
- * 账号池（核心策略）测试 —— 选号/冷却/禁用/错误累计/遍历回退。
+ * 账号池（核心策略）测试 —— 选号/冷却/禁用/遍历回退。
+ *
+ * 关键语义（v2）：
+ *   - 冷却单元 = (supplierId, modelId, uid)。某连接在模型 A 上失败，只冷
+ *     (A, 该连接)，该连接调模型 B 不受影响。
+ *   - 禁用(session_dead) = 连接级(uid)：该号所有模型都不可用。
+ *   - no_such_model 不惩罚账号（模型不属于本供应商不是号的错）。
  * 用 node --test 跑（Node 原生 TS 剥离，零新依赖）。
  */
 import { test } from 'node:test'
@@ -9,112 +15,208 @@ import type { SupplierAccountNow } from '../suppliers/contract.ts'
 
 const accs = (uids: string[]): SupplierAccountNow[] => uids.map((uid) => ({ uid, credits: 0, state: 'ok' }))
 
-test('选号：无冷却时按 poolOrder 优先，未配置的追加在后', () => {
-  const p = new AccountPool()
+/** 构造带供应商的池，与 loader 一致（真实使用会传 supplierId）。 */
+const pool = (sid = 'supA'): AccountPool => new AccountPool(sid)
+
+test('选号：无冷却时按 poolOrder 优先，未配置的追加在后（带 model）', () => {
+  const p = pool()
   const list = accs(['a', 'b', 'c'])
-  assert.equal(p.pick(list, ['c', 'a'], 'fallback'), 'c')
-  assert.equal(p.pick(list, ['b'], 'fallback'), 'b')
+  assert.equal(p.pick(list, ['c', 'a'], 'fallback', 'm1'), 'c')
+  assert.equal(p.pick(list, ['b'], 'fallback', 'm1'), 'b')
   // 未配置顺序的按自然顺序补上
-  assert.equal(p.pick(list, [], 'fallback'), 'a')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), 'a')
 })
 
-test('选号：冷却中的号跳过，全冷却返回 undefined', () => {
-  const p = new AccountPool()
+test('选号：某模型冷却中的号对该模型跳过，全冷却返回 undefined', () => {
+  const p = pool()
   const list = accs(['a', 'b'])
-  p.noteFailure('a', 'rate_limit', '429')
-  assert.equal(p.pick(list, [], 'fallback'), 'b')
-  p.noteFailure('b', 'rate_limit', '429')
-  assert.equal(p.pick(list, [], 'fallback'), undefined)
+  p.noteFailure('a', 'm1', 'rate_limit', '429')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), 'b')
+  p.noteFailure('b', 'm1', 'rate_limit', '429')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), undefined)
 })
 
-test('选号：round-robin 在健康号间轮转', () => {
-  const p = new AccountPool()
+test('round-robin 在健康号间轮转（带 model）', () => {
+  const p = pool()
   const list = accs(['a', 'b'])
-  assert.equal(p.pick(list, [], 'round-robin'), 'a')
-  assert.equal(p.pick(list, [], 'round-robin'), 'b')
-  assert.equal(p.pick(list, [], 'round-robin'), 'a')
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
 })
 
-test('处置：session_dead 永久禁用（不再被选中）', () => {
-  const p = new AccountPool()
-  const list = accs(['a'])
-  p.noteFailure('a', 'session_dead', '凭证失效')
-  assert.equal(p.pick(list, [], 'fallback'), undefined)
-  assert.equal(p.decorate(list)[0]?.disabled, true)
+// ============ 核心新语义：冷却按 (模型, 连接) 分号 ============
+
+test('【颗粒度】连接在模型 A 失败，只冷 (A, 该连接)，不影响它调模型 B', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  // a 在 m1 上限流失败 → 只冷 (m1, a)
+  p.noteFailure('a', 'm1', 'rate_limit', '429')
+  // m1 上 a 被冷 → 选 b
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), 'b')
+  // m2 上 a 完全健康 → 应选 a（不被 m1 的失败殃及）
+  assert.equal(p.pick(list, [], 'fallback', 'm2'), 'a')
+  // m1 只剩 a 一个号 → undefined（a 在 m1 上被冷）
+  assert.equal(p.pick(list.filter((x) => x.uid === 'a'), [], 'fallback', 'm1'), undefined)
+})
+
+test('【颗粒度】多号里只有一冷在 m1，其它号在 m2 仍可用', () => {
+  const p = pool()
+  const list = accs(['a', 'b', 'c'])
+  p.noteFailure('a', 'm1', 'transport', 'boom')
+  p.noteFailure('b', 'm1', 'transport', 'boom')
+  // m1：a、b 被冷 → 只剩 c
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), 'c')
+  // m2：a、b 健康 → 应选 a（poolOrder 顺序第一个健康）
+  assert.equal(p.pick(list, [], 'fallback', 'm2'), 'a')
 })
 
-test('处置：连续错误攒够阈值才冷却（前两次仍可服务）', () => {
-  const p = new AccountPool()
+test('【颗粒度】同一连接对不同模型的退避独立累加/清零', () => {
+  const p = pool()
   const list = accs(['a'])
-  p.noteFailure('a', 'unknown', 'e1')
-  assert.equal(p.pick(list, [], 'fallback'), 'a')
-  p.noteFailure('a', 'unknown', 'e2')
-  assert.equal(p.pick(list, [], 'fallback'), 'a')
-  // 第三次触发冷却
-  p.noteFailure('a', 'unknown', 'e3')
-  assert.equal(p.pick(list, [], 'fallback'), undefined)
+  p.noteFailure('a', 'm1', 'rate_limit', '429')
+  p.noteFailure('a', 'm1', 'rate_limit', '429')
+  // m1 退避等级 2
+  assert.equal(p.decorate(list, 'm1')[0]?.err_count, 2)
+  // m2 没被 m1 影响 → 等级 0
+  assert.equal(p.decorate(list, 'm2')[0]?.err_count, 0)
+  // m1 成功 → 清零 m1 的退避
+  p.noteSuccess('a', 'm1')
+  assert.equal(p.decorate(list, 'm1')[0]?.err_count, 0)
 })
 
-test('处置：成功清零连续错误，避免之前累积的错误把好号冷却掉', () => {
-  const p = new AccountPool()
+// ============ 连接级禁用(跨模型) ============
+
+test('【颗粒度】session_dead 是连接级禁用：跨该号所有模型', () => {
+  const p = pool()
   const list = accs(['a'])
-  p.noteFailure('a', 'unknown', 'e1')
-  p.noteFailure('a', 'unknown', 'e2')
-  p.noteSuccess('a')
-  p.noteFailure('a', 'unknown', 'e3')
-  assert.equal(p.pick(list, [], 'fallback'), 'a')
+  p.noteFailure('a', 'm1', 'session_dead', '凭证失效')
+  // 该号在 m1、m2 上都不可用（登录态问题，不是模型问题）
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), undefined)
+  assert.equal(p.pick(list, [], 'fallback', 'm2'), undefined)
+  assert.equal(p.decorate(list)[0]?.disabled, true)
+})
+
+test('处置：未知错误第一次就冷却（坏号不留在池里等下一次撞）', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  p.noteFailure('a', 'm1', 'unknown', 'e1')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), 'b')
+  assert.equal(p.pick(list.filter((x) => x.uid === 'a'), [], 'fallback', 'm1'), undefined)
 })
 
-test('decorate：把冷却/禁用/错误累计叠加到插件报的「现在状态」上', () => {
-  const p = new AccountPool()
+test('decorate：把冷却/禁用叠加到插件报的「现在状态」上（聚合展示）', () => {
+  const p = pool()
   const list: SupplierAccountNow[] = [
     { uid: 'ok', credits: 5, state: 'ok' },
     { uid: 'cool', credits: 5, state: 'ok' },
     { uid: 'dead', credits: 5, state: 'ok' },
   ]
-  p.noteFailure('cool', 'rate_limit', '429')
-  p.noteFailure('dead', 'session_dead', '凭证失效')
+  p.noteFailure('cool', 'm1', 'rate_limit', '429')
+  p.noteFailure('dead', 'm1', 'session_dead', '凭证失效')
   const out = p.decorate(list)
   const by = new Map(out.map((a) => [a.uid, a]))
   assert.equal(by.get('ok')?.cooling, false)
   assert.equal(by.get('ok')?.disabled, false)
   assert.equal(by.get('cool')?.cooling, true)
   assert.equal(by.get('cool')?.until !== undefined, true)
-  assert.equal(by.get('cool')?.reason, '429')
   assert.equal(by.get('dead')?.disabled, true)
   // 插件报的字段要原样透出（不能被 decorate 吃掉）
   assert.equal(by.get('ok')?.credits, 5)
 })
 
 test('no_such_model 不惩罚账号：不冷却、不计数', () => {
-  const p = new AccountPool()
+  const p = pool()
   const list = accs(['a'])
   // 攒够阈值次也不该冷却——模型不属于本供应商不是账号的错
-  for (let i = 0; i < 10; i++) p.noteFailure('a', 'no_such_model', 'unknown model "x"')
-  assert.equal(p.pick(list, [], 'fallback'), 'a')
-  const out = p.decorate(list)[0]
+  for (let i = 0; i < 10; i++) p.noteFailure('a', 'm1', 'no_such_model', 'unknown model "x"')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), 'a')
+  const out = p.decorate(list, 'm1')[0]
   assert.equal(out?.cooling, false)
   assert.equal(out?.disabled, false)
   assert.equal(out?.err_count, 0)
 })
 
 test('状态表：各 AccountState 的处置符合预期', () => {
-  const p = new AccountPool()
+  const p = pool()
   const list = accs(['rate', 'quota', 'dead', 'unavail'])
-  p.noteFailure('rate', 'rate_limit', 'x')
-  p.noteFailure('quota', 'quota', 'x')
-  p.noteFailure('dead', 'session_dead', 'x')
-  p.noteFailure('unavail', 'unavailable', 'x')
-  // rate_limit/quota 立刻冷却；session_dead 禁用；unavailable 只计错误不冷却
-  assert.equal(p.pick(list, [], 'fallback'), 'unavail')
+  p.noteFailure('rate', 'm1', 'rate_limit', 'x')
+  p.noteFailure('quota', 'm1', 'quota', 'x')
+  p.noteFailure('dead', 'm1', 'session_dead', 'x')
+  p.noteFailure('unavail', 'm1', 'unavailable', 'x')
   const by = new Map(p.decorate(list).map((a) => [a.uid, a]))
   assert.equal(by.get('rate')?.cooling, true)
   assert.equal(by.get('quota')?.cooling, true)
   assert.equal(by.get('dead')?.disabled, true)
-  assert.equal(by.get('unavail')?.cooling, false)
-  assert.equal(by.get('unavail')?.err_count, 1)
-  // 攒够阈值后才冷却（与 unknown/transport 同一条路径）
-  p.noteFailure('unavail', 'unavailable', 'x')
-  p.noteFailure('unavail', 'unavailable', 'x')
-  assert.equal(p.pick(list, [], 'fallback'), undefined)
+  assert.equal(by.get('unavail')?.cooling, true, '瞬时错误第一次就冷却')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), undefined, '四个号都不可服务')
+})
+
+/**
+ * 处置对齐 9router：未知/瞬时错误**每次**短冷却（不再攒够 3 次）。
+ */
+test('处置：未知/瞬时错误第一次就短冷却（对齐 9router 瞬时冷却）', () => {
+  const p = pool()
+  const list = accs(['a'])
+  p.noteFailure('a', 'm1', 'unknown', 'e1')
+  assert.equal(p.pick(list, [], 'fallback', 'm1'), undefined, '第一次失败就该冻结，不该留在池里')
+  const d = p.decorate(list, 'm1')[0]
+  assert.equal(d?.cooling, true)
+  assert.equal(d?.err_count, 0)
+})
+
+test('处置：瞬时冷却是短冷却（30s 量级），不是攒够后的 5 分钟', () => {
+  const p = pool()
+  const list = accs(['a'])
+  p.noteFailure('a', 'm1', 'transport', 'boom')
+  const d = p.decorate(list, 'm1')[0]
+  const until = d?.until === undefined ? 0 : new Date(d.until).getTime()
+  const span = until - Date.now()
+  assert.ok(span > 0 && span <= 60_000, `瞬时冷却应在 60s 内，实际 ${span}ms`)
+})
+
+test('处置：限流越频繁冷却越久（指数退避，对齐 9router backoff）', () => {
+  const p = pool()
+  const list = accs(['a'])
+  const spanOf = (m: string): number => {
+    const d = p.decorate(list, m)[0]
+    const until = d?.until === undefined ? 0 : new Date(d.until).getTime()
+    return until - Date.now()
+  }
+  p.noteFailure('a', 'm1', 'rate_limit', '429-1')
+  const first = spanOf('m1')
+  assert.ok(first > 0 && first <= 60_000, `首次限流应短冷（≤60s），实际 ${first}ms`)
+  assert.equal(p.decorate(list, 'm1')[0]?.err_count, 1, '退避等级 1')
+
+  // 连着再限流：等级递进 → 冷却变长。
+  p.noteFailure('a', 'm1', 'rate_limit', '429-2')
+  const second = spanOf('m1')
+  assert.equal(p.decorate(list, 'm1')[0]?.err_count, 2, '退避等级 2')
+  assert.ok(second > first, `第二次限流冷却应更久：${second}ms 应 > ${first}ms`)
+  p.noteFailure('a', 'm1', 'rate_limit', '429-3')
+  assert.ok(spanOf('m1') > second, '第三次更久')
+})
+
+test('处置：成功后限流退避等级归零（好号不再背历史惩罚）', () => {
+  const p = pool()
+  const list = accs(['a'])
+  p.noteFailure('a', 'm1', 'rate_limit', '429')
+  p.noteSuccess('a', 'm1')
+  p.cooldown('a', -1, 'reset')
+  p.noteFailure('a', 'm1', 'rate_limit', '429')
+  const after = p.decorate(list, 'm1')[0]
+  const until = after?.until === undefined ? 0 : new Date(after.until).getTime()
+  assert.ok(until - Date.now() <= 60_000, '成功清零后应从最短退避重新开始')
+})
+
+// ============ 跨供应商同名模型不串（键带 supplierId） ============
+
+test('【隔离】不同供应商的同名模型，各自独立冷却', () => {
+  const pa = pool('supA') // 供应商 A
+  const pb = pool('supB') // 供应商 B
+  const list = accs(['acc']) // 同一 uid 名出现在两个供应商池里（真实是不同账号）
+  // A 供应商的 acc 在 deepseek-v4-flash 上限流
+  pa.noteFailure('acc', 'deepseek-v4-flash', 'rate_limit', '429')
+  assert.equal(pa.pick(list, [], 'fallback', 'deepseek-v4-flash'), undefined, 'A 池该模型已冷')
+  // B 供应商同名模型不受影响
+  assert.equal(pb.pick(list, [], 'fallback', 'deepseek-v4-flash'), 'acc', 'B 池同名模型照常可用')
 })

package/src/router/account-pool.ts

@@ -1,21 +1,39 @@
 /**
- * 账号池 —— dsh-router 核心策略：选号、冷却、禁用、错误累计、遍历回退。
+ * 账号池 —— dsh-router 核心策略：选号、冷却、禁用、遍历回退。
  *
- * 供应商插件只管「对单个账号调通上游」，账号层面的策略全在这里：
- *   - 按 poolOrder 排序（未配置的按插件报告顺序追加）
- *   - 按 poolStrategy 选号：fallback = 取第一个健康；round-robin = 轮转健康号
- *   - 失败按插件报的 AccountState 处置（冷却/禁用/错误累计），攒够阈值自动冷却
+ * 供应商插件只管「对单个账号调通上游」，账号层面的策略全在这里。
  *
- * 天花板：冷却/禁用/错误计数都是**内存态**，重启归零（与旧插件行为一致，
- * 插件的持久化只存凭证与积分，不存健康）。要跨重启保留得落盘，届时加一个
- * stateFile 即可，接口不用变。
+ * ## 冷却颗粒度 = (供应商, 模型, 连接) 三元组
+ *
+ * 冷却**不按连接整体记**，而是按「哪家供应商 × 哪个模型 × 哪个连接」单独记。
+ * 理由：一个连接可以服务多个模型。若某连接调模型 A 时被限流/瞬时抖动而把
+ * **整个连接**冷掉，那它调模型 B 也被殃及——一个付费连接会因一个模型的瞬时
+ * 失败而对其它模型也不可用，这是错的。
+ *
+ *   - 冷却/限流退避/瞬时 → 键 = (supplierId, modelId, uid)，只冷「这个号 × 这个模型」
+ *   - 禁用(session_dead)     → 键 = uid（登录态问题，该号所有模型都不可用）
+ *   - 手动冷却(面板)         → 键 = uid（管理员整连接暂停）
+ *
+ * 为什么键里要带 supplierId：不同供应商**会有同名的模型 id**（如 traework 与
+ * codebuddy 都有 `deepseek-v4-flash`），它们是不同的实体，单靠 (modelId, uid)
+ * 会把跨供应商的同名模型串到一起。尽管本池实例当前是单供应商（loader 每供应商
+ * 一个 AccountPool），键仍显式带 supplierId，语义自明且将来若池合并也安全。
+ *
+ * 天花板：冷却/禁用都是**内存态**，重启归零（与旧插件行为一致）。要跨重启保留
+ * 得落盘，届时加 stateFile 即可，接口不用变。
  */
 import type { AccountState, SupplierAccountNow } from '../suppliers/contract.ts'
 
-/** 各 AccountState 的处置：冷却时长 / 是否禁用 / 是否计入连续错误。 */
+/** 各 AccountState 的处置：冷却策略 / 是否禁用 / 是否计入连续错误。 */
 interface Rule {
-  /** 冷却时长（ms）；0 = 不冷却。 */
-  cooldownMs: number
+  /**
+   * 冷却策略：
+   *  - `number` 固定时长（ms）
+   *  - `'transient'` 瞬时短冷却（每次都冷，30s 量级）
+   *  - `'backoff'` 指数退避（反复限流越退越久）
+   *  - `0` 不冷却
+   */
+  cooldown: number | 'transient' | 'backoff'
   /** 是否永久禁用（需重新登录才能恢复）。 */
   disable: boolean
   /** 是否计入连续错误（攒够阈值自动冷却）。 */
@@ -26,62 +44,138 @@ const MINUTE = 60_000
 
 /**
  * 状态 → 处置表。**核心策略就在这一张表里**，插件只报状态不做决策。
- * 时长参考 9router 的 errorConfig（限流类短冷却、额度类长冷却），
- * 但 9router 按文本/状态匹配，这里按插件解读后的语义状态匹配，更准。
+ *
+ * 冷却策略对齐 9router 的 accountFallback / errorConfig：
+ *  - `rate_limit` 用**指数退避**（9router 的 `backoff: true`）：偶发限流只
+ *    短冷，持续限流越退越久，比固定 1 分钟两头不讨好要准。
+ *  - 未知/瞬时错误用**瞬时短冷却**（9router 默认分支 TRANSIENT_COOLDOWN_MS）：
+ *    每次失败都冻结，坏号不会留在池里被下一个请求再选中。
+ *
+ * 与 9router 的差别：9router 按错误文本/HTTP 状态匹配，这里按插件解读后的
+ * 语义状态匹配 —— 插件已经把 11133/11134 这类网关噪声归成 `rate_limit`，
+ * 核心不必再猜文本，更准。
  */
 const RULES: Record<AccountState, Rule> = {
-  ok: { cooldownMs: 0, disable: false, counts: false },
-  rate_limit: { cooldownMs: 1 * MINUTE, disable: false, counts: false },
-  quota: { cooldownMs: 10 * MINUTE, disable: false, counts: false },
-  session_dead: { cooldownMs: 0, disable: true, counts: false },
-  // 404/服务下线：只计错误不立刻冷却——偶发的自己恢复，真挂了攒够阈值再冷却
-  unavailable: { cooldownMs: 0, disable: false, counts: true },
-  transport: { cooldownMs: 0, disable: false, counts: true },
-  unknown: { cooldownMs: 0, disable: false, counts: true },
+  ok: { cooldown: 0, disable: false, counts: false },
+  rate_limit: { cooldown: 'backoff', disable: false, counts: false },
+  quota: { cooldown: 10 * MINUTE, disable: false, counts: false },
+  session_dead: { cooldown: 0, disable: true, counts: false },
+  // 404/服务下线、传输中断、未知：每次都瞬时短冷却（见上方 9router 对齐说明）
+  unavailable: { cooldown: 'transient', disable: false, counts: false },
+  transport: { cooldown: 'transient', disable: false, counts: false },
+  unknown: { cooldown: 'transient', disable: false, counts: false },
   // 模型不属于本供应商：不是账号的错，不冷却也不计数（核心据此换下一个供应商）
-  no_such_model: { cooldownMs: 0, disable: false, counts: false },
+  no_such_model: { cooldown: 0, disable: false, counts: false },
 }
 
+/**
+ * 瞬时/未知错误的冷却时长 —— 对齐 9router 的 TRANSIENT_COOLDOWN_MS。
+ * 取短值：这类错误大多是偶发的上游抖动，冷太久会把好号白白关掉；
+ * 但**必须冷**，否则坏号留在池里，每个请求都要先撞一次才知道它坏了。
+ * （现在按 (模型, 号) 记，只关这一个号在这个模型上的可用性。）
+ */
+const TRANSIENT_COOLDOWN_MS = 30_000
+
+/** 限流退避：首次 2s，每次翻倍，上限 5 分钟（对齐 9router BACKOFF_CONFIG）。 */
+const BACKOFF_BASE_MS = 2_000
+const BACKOFF_MAX_MS = 5 * MINUTE
+const BACKOFF_MAX_LEVEL = 15
+
 /** 连续错误攒够这么多次就自动冷却（防止坏号被反复重试）。 */
 const ERR_THRESHOLD = 3
 /** 攒够后的冷却时长。 */
-const ERR_COOLDOWN_MS = 10 * MINUTE
+const ERR_COOLDOWN_MS = 5 * MINUTE
+
+/** 冷却记录（键 = (supplier, model, uid)）。 */
+interface CooldownEntry {
+  until: number
+  backoffLevel: number
+  reason: string
+}
 
-interface Entry {
+/** 连接级禁用/手动暂停记录（键 = uid）。 */
+interface UidEntry {
   until: number
   disabled: boolean
-  errCount: number
   reason: string
 }
 
+/** 指数退避：等级 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)
+}
+
+/** 冷却键分隔符：模型 id 本身可含 `/` `,`，用不可见控制符隔离最稳。 */
+const SEP = '\u0000'
+
 export class AccountPool {
-  private entries = new Map<string, Entry>()
+  /** 本池所属供应商（loader 每供应商一个实例；键里带上，跨供应商同名模型不串）。 */
+  private supplierId: string
+  /** (supplier, model, uid) → 冷却/退避。 */
+  private cooldowns = new Map<string, CooldownEntry>()
+  /** uid → 连接级禁用 / 手动暂停。 */
+  private byUid = new Map<string, UidEntry>()
   private rrCursor = 0
 
-  private entry(uid: string): Entry {
-    let e = this.entries.get(uid)
+  constructor(supplierId = '') {
+    this.supplierId = supplierId
+  }
+
+  private key(model: string, uid: string): string {
+    return `${this.supplierId}${SEP}${model}${SEP}${uid}`
+  }
+
+  private entry(model: string, uid: string): CooldownEntry {
+    const k = this.key(model, uid)
+    let e = this.cooldowns.get(k)
+    if (!e) {
+      e = { until: 0, backoffLevel: 0, reason: '' }
+      this.cooldowns.set(k, e)
+    }
+    return e
+  }
+
+  /** 某连接整体状态（禁用/手动暂停）。 */
+  private uidState(uid: string): UidEntry {
+    let e = this.byUid.get(uid)
     if (!e) {
-      e = { until: 0, disabled: false, errCount: 0, reason: '' }
-      this.entries.set(uid, e)
+      e = { until: 0, disabled: false, reason: '' }
+      this.byUid.set(uid, e)
     }
     return e
   }
 
-  /** 是否可服务：未禁用且不在冷却中。 */
-  private healthy(uid: string, now: number): boolean {
-    const e = this.entries.get(uid)
-    if (!e) return true
-    if (e.disabled) return false
-    return e.until <= now
+  /** 该连接是否被禁用 / 手动整连接暂停中（跨模型生效）。 */
+  private uidBlocked(uid: string, now: number): { blocked: boolean; disabled: boolean } {
+    const e = this.byUid.get(uid)
+    if (!e) return { blocked: false, disabled: false }
+    if (e.disabled) return { blocked: true, disabled: true }
+    if (e.until > now) return { blocked: true, disabled: false }
+    return { blocked: false, disabled: false }
+  }
+
+  /**
+   * 给定要试的模型，该连接是否可服务：
+   *  - 未被连接级禁用/手动暂停（跨模型）；
+   *  - 且此 (supplier, model, uid) 冷却单元不在冷却中。
+   */
+  private healthy(uid: string, model: string, now: number): boolean {
+    const b = this.uidBlocked(uid, now)
+    if (b.blocked) return false
+    const c = this.cooldowns.get(this.key(model, uid))
+    if (!c) return true
+    return c.until <= now
   }
 
   /**
-   * 按策略选一个健康账号。
+   * 按策略为「某个模型」选一个健康账号。
    * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
    * @param poolOrder 用户在面板拖出来的顺序（核心管）
+   * @param strategy fallback 取第一个健康 / round-robin 轮转健康号
+   * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
    * @returns 选中的 uid；无健康账号返回 undefined
    */
-  pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string): string | undefined {
+  pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string): string | undefined {
     const now = Date.now()
     const byUid = new Map(accounts.map((a) => [a.uid, a]))
     // 池顺序优先，未配置的按插件自然顺序追加
@@ -89,7 +183,7 @@ 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, now))
+    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]
@@ -97,47 +191,61 @@ export class AccountPool {
     return uid
   }
 
-  /** 记录一次失败：按状态处置（冷却/禁用/错误累计）。 */
-  noteFailure(uid: string, state: AccountState, message: string): void {
+  /** 记录一次失败：按状态处置（冷却/禁用/退避），落在「(模型, 连接)」这个冷却单元上。 */
+  noteFailure(uid: string, modelId: string, state: AccountState, message: string): void {
     const rule = RULES[state]
-    const e = this.entry(uid)
+    // 禁用 / 手动暂停是连接级（登录态问题，跨模型）——但这里只处理规则本身
     if (rule.disable) {
+      // session_dead：整个连接禁用（跨该号所有模型）
+      const e = this.uidState(uid)
       e.disabled = true
       e.reason = message
       return
     }
-    if (rule.cooldownMs > 0) {
-      e.until = Math.max(e.until, Date.now() + rule.cooldownMs)
-      e.reason = message
-      e.errCount = 0
+    if (rule.cooldown === 0) return // no_such_model 等：不冷不记
+    // 冷却/退避：记在 (model, uid) 单元上，不动该号其它模型
+    const e = this.entry(modelId, uid)
+    e.reason = message
+    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))
       return
     }
-    if (rule.counts) {
-      e.errCount += 1
-      e.reason = message
-      if (e.errCount >= ERR_THRESHOLD) {
-        e.until = Date.now() + ERR_COOLDOWN_MS
-        e.errCount = 0
-      }
+    if (rule.cooldown === 'transient') {
+      // 每次都冷（不再攒次数）：坏号不该留在池里等下一次撞
+      e.until = Math.max(e.until, Date.now() + TRANSIENT_COOLDOWN_MS)
+      return
     }
+    e.until = Math.max(e.until, Date.now() + rule.cooldown)
   }
 
-  /** 记录一次成功：清零连续错误。 */
-  noteSuccess(uid: string): void {
-    const e = this.entries.get(uid)
-    if (e) e.errCount = 0
+  /** 记录一次成功：清零「该模型」的限流退避等级（好号不背历史惩罚）。不解除禁用。 */
+  noteSuccess(uid: string, modelId: string): void {
+    const e = this.cooldowns.get(this.key(modelId, uid))
+    if (e) e.backoffLevel = 0
   }
 
-  /** 手动冷却（面板/管理用途）。 */
+  /** 手动暂停整连接（面板/管理用途，跨模型）。ms<=0 表示解除。 */
   cooldown(uid: string, ms: number, reason: string): void {
-    const e = this.entry(uid)
+    const e = this.uidState(uid)
     e.until = Date.now() + ms
     e.reason = reason
-    e.errCount = 0
+    // 手动暂停通常是想清掉这个号上的累积惩罚：把它的退避等级清零
+    // （disabled 不可由此解除——需重新登录）
+    for (const [k, ce] of this.cooldowns) {
+      if (k.endsWith(`${SEP}${uid}`)) ce.backoffLevel = 0
+    }
   }
 
-  /** 把核心的冷却/禁用/错误累计叠加到插件报告的「现在状态」上，产出面板态。 */
-  decorate(accounts: SupplierAccountNow[]): Array<SupplierAccountNow & {
+  /** 把核心的冷却/禁用叠加到插件报的「现在状态」上，产出面板态。
+   *
+   * 冷却现在是 (模型, 连接) 粒度的，而面板状态没有「当前模型」上下文，
+   * 这里默认**聚合**：只要该连接在任一模型上有活跃冷却，就显示 cooling=true
+   * （reason 带上具体模型），并在 `until` 给最长者。真实路由用 `pick` 的
+   * 模型级判定，不受此展示聚合影响。传 modelId 可只按该模型判定。
+   */
+  decorate(accounts: SupplierAccountNow[], modelId?: string): Array<SupplierAccountNow & {
     cooling: boolean
     disabled: boolean
     err_count: number
@@ -146,15 +254,39 @@ export class AccountPool {
   }> {
     const now = Date.now()
     return accounts.map((a) => {
-      const e = this.entries.get(a.uid)
-      const cooling = e !== undefined && !e.disabled && e.until > now
+      const u = this.byUid.get(a.uid)
+      const disabled = u?.disabled ?? false
+      // 连接级手动暂停或禁用也算不可服务；但 disabled 单列，冷却不算它
+      const manualCooling = u !== undefined && !u.disabled && u.until > now
+
+      let cooling = manualCooling
+      let maxUntil = manualCooling ? u!.until : 0
+      let reason = manualCooling ? u!.reason : undefined
+      let err = 0
+      // 遍历本连接在所有模型上的冷却单元（或仅指定模型）
+      for (const [k, ce] of this.cooldowns) {
+        if (!k.endsWith(`${SEP}${a.uid}`)) continue
+        if (modelId !== undefined) {
+          // 键形如 supplier\u0000model\u0000uid —— 只在键开头含该 model 时命中
+          const prefix = `${this.supplierId}${SEP}${modelId}${SEP}`
+          if (!k.startsWith(prefix)) continue
+        }
+        if (ce.until > now) {
+          cooling = true
+          if (ce.until > maxUntil) {
+            maxUntil = ce.until
+            reason = ce.reason
+          }
+        }
+        if (ce.backoffLevel > err) err = ce.backoffLevel
+      }
       return {
         ...a,
         cooling,
-        disabled: e?.disabled ?? false,
-        err_count: e?.errCount ?? 0,
-        until: cooling && e ? new Date(e.until).toISOString() : undefined,
-        reason: e?.reason !== '' ? e?.reason : undefined,
+        disabled,
+        err_count: err,
+        until: cooling && maxUntil > 0 ? new Date(maxUntil).toISOString() : undefined,
+        reason: reason !== undefined && reason !== '' ? reason : undefined,
       }
     })
   }