dsh-router-core 0.3.11 → 0.3.13

package/src/ext/store.ts

@@ -0,0 +1,125 @@
+/**
+ * 扩展存储 —— **开关状态与插件数据都归核心持久化**,插件不自己 file IO。
+ *
+ * 落盘 `<dataDir>/ext.json`,按扩展器 id 存:
+ *   `{ "rtk": { "enabled": true, "data": { ...插件自己的东西... } } }`
+ *
+ * 为什么归核心:跟 `supplier-config.json` 一个道理——开关是用户对**核心面板**的操作,
+ * 不该由扩展插件各自决定存哪、怎么存(否则每个插件长一份互相不一致的实现,核心也无
+ * 从统一裁决「能不能开」)。插件变薄:只报自己是否可用(`ready`)+ 做事。
+ *
+ * `data` 槽是给插件的通用抽屉(2026-09 加):插件不再为了存一点状态而自己开数据目录,
+ * 统一经 `router.extStore` service 读写,落盘位置仍由核心锚定(不跟 cwd 跑)。
+ *
+ * 写法与核心其他存储一致:先写 `.tmp` 再 `rename` 原子覆盖(避免写一半崩掉留坏文件),
+ * 权限 600;持久化失败不阻断。
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+interface ExtFile {
+  [extId: string]: { enabled: boolean; data?: unknown }
+}
+
+interface Entry {
+  enabled: boolean
+  data: unknown
+}
+
+/** 扩展开关 + 插件数据存储。 */
+export class ExtStore {
+  private fp = ''
+  private byId: Record<string, Entry> = {}
+
+  constructor(stateFile: string) {
+    this.fp = stateFile ? join(dirname(stateFile), 'ext.json') : ''
+    this.load()
+    // 一次性迁移:开关早期由扩展插件自己写在 `enhance.json`(单文件、无法按 id 区分),
+    // 现在归核心按 id 存 `ext.json`。把旧值搬过来,避免用户已开的开关掉回关。
+    // 旧文件保留不删(不可逆操作留给人工),迁移只发生在新文件还没有时。
+    this.migrateLegacy()
+  }
+
+  private migrateLegacy(): void {
+    if (this.fp === '') return
+    if (Object.keys(this.byId).length > 0) return // 已有新配置,不覆盖
+    const legacy = join(dirname(this.fp), 'enhance.json')
+    let enabled = false
+    try {
+      const f = JSON.parse(readFileSync(legacy, 'utf8')) as { enabled?: unknown }
+      enabled = f.enabled === true
+    } catch {
+      return // 没有旧文件 / 读不了 → 无需迁移
+    }
+    if (!enabled) return
+    // 旧格式只有一个开关,当时唯一的扩展器就是 rtk。
+    this.byId.rtk = { enabled: true, data: undefined }
+    this.save()
+  }
+
+  private load(): void {
+    if (this.fp === '') return
+    let raw: string
+    try {
+      raw = readFileSync(this.fp, 'utf8')
+    } catch {
+      return
+    }
+    try {
+      const f = JSON.parse(raw) as ExtFile
+      for (const [id, v] of Object.entries(f)) {
+        if (id === '' || v === null || typeof v !== 'object') continue
+        if (typeof v?.enabled !== 'boolean') continue
+        this.byId[id] = { enabled: v.enabled, data: v.data }
+      }
+    } catch {
+      // 损坏则用默认关
+    }
+  }
+
+  private save(): void {
+    if (this.fp === '') return
+    try {
+      const dir = dirname(this.fp)
+      if (dir !== '' && dir !== '.') mkdirSync(dir, { recursive: true })
+      const out: ExtFile = {}
+      for (const [id, e] of Object.entries(this.byId)) {
+        // 没数据的不写 data 键,保持文件干净(旧格式兼容)。
+        out[id] = e.data === undefined ? { enabled: e.enabled } : { enabled: e.enabled, data: e.data }
+      }
+      const raw = JSON.stringify(out, null, 2)
+      const tmp = this.fp + '.tmp'
+      writeFileSync(tmp, raw, { mode: 0o600 })
+      renameSync(tmp, this.fp)
+    } catch {
+      // 持久化失败不阻断
+    }
+  }
+
+  /** 是否开启(未记录过 = 默认关)。 */
+  isEnabled(id: string): boolean {
+    return this.byId[id]?.enabled === true
+  }
+
+  setEnabled(id: string, enabled: boolean): void {
+    if (id === '') return
+    const cur = this.byId[id]
+    if (cur?.enabled === enabled) return
+    this.byId[id] = { enabled, data: cur?.data }
+    this.save()
+  }
+
+  /** 读插件自己存的数据块(没存过 = undefined)。 */
+  readData<T = unknown>(id: string): T | undefined {
+    if (id === '') return undefined
+    return this.byId[id]?.data as T | undefined
+  }
+
+  /** 写插件自己的数据块(覆盖;与 enabled 同一文件落盘)。 */
+  writeData(id: string, value: unknown): void {
+    if (id === '') return
+    const cur = this.byId[id]
+    this.byId[id] = { enabled: cur?.enabled === true, data: value }
+    this.save()
+  }
+}

package/src/index.ts

@@ -41,6 +41,8 @@ import type { SupplierEnv, SupplierModule } from './suppliers/contract.ts'
 import { SupplierConfigStore } from './supplier-config.ts'
 import { CredentialStore } from './credential-store.ts'
 import { dataDirOf, profileDirOf } from './data-dir.ts'
+import { ExtStore } from './ext/store.ts'
+import type { ExtInfo, ExtStoreService, RouterExt, RouterExtService } from './ext/contract.ts'
 
 /**
  * Plugin identity for cordis.yml rows — 必须与 package.json 的 name 一致。
@@ -185,6 +187,17 @@ export function apply(rawContext: unknown): void {
   // 单装 dsh-router-codebuddy 时表永不出现，codebuddy 就一直不生效）。
   ctx.provide('router.suppliers', {})
 
+  // ---- 扩展 (Ext)：router.ext 注册表 + router.extStore 存储 ----
+  // 核心只做**管理面**：发现（注册表）、展示（面板/API）、代存开关与插件数据。
+  // 拦截 tools/execute / 裁决 enabled+ready / 短路执行全部归扩展插件自己 —— 见
+  // ext/contract.ts 文件头。同 router.suppliers 模式：核心持有空表，扩展插件经
+  // ctx.inject 追加进同一个 live 对象。
+  const exts: Record<string, unknown> = {}
+  ctx.provide('router.ext', exts)
+  // 开关 + 插件数据归核心持久化(<dataDir>/ext.json);插件经此 service 读写,不自己 file IO。
+  const extStore = new ExtStore(stateFile)
+  ctx.provide('router.extStore', extStore as unknown as ExtStoreService)
+
   // 内置 + 用户 + 外部插件供应商（异步加载，完成后注册路由 + 加入路由器）
   const registerLoaded = (loaded: LoadedSupplier): void => {
     loadedSuppliers.push(loaded)
@@ -447,6 +460,56 @@ export function apply(rawContext: unknown): void {
     writeJson(res, 200, { ok: true, requireApiKey: keys.requireApiKey })
   })
 
+  // ---- 扩展 (Ext)：扩展器列表 + 开关 ----
+  route(`${ROUTER_API_BASE}/ext`, async (req, res) => {
+    if (req.method === 'PATCH') {
+      let body: { id?: unknown; enabled?: unknown }
+      try {
+        body = JSON.parse(await readBody(req, 64 << 10)) as { id?: unknown; enabled?: unknown }
+      } catch {
+        writeJson(res, 400, { ok: false, error: 'invalid JSON body' })
+        return
+      }
+      const ext = typeof body.id === 'string' ? exts[body.id] as RouterExtService[string] : undefined
+      if (!ext) {
+        writeJson(res, 404, { ok: false, error: 'extension not found' })
+        return
+      }
+      if (typeof body.enabled !== 'boolean') {
+        writeJson(res, 400, { ok: false, error: 'enabled must be a boolean' })
+        return
+      }
+      const wantOn = body.enabled
+      // 开启自检：不可用(ready !== true)的扩展**不能开启成功**——即使绕过面板
+      // 直连 API 也会被拒。由扩展器报告就绪状态,核心据此裁决。
+      if (wantOn && typeof ext.getState === 'function') {
+        const st = ext.getState()
+        if (st?.ready !== true) {
+          writeJson(res, 409, { ok: false, error: st?.detail ?? 'extension not ready' })
+          return
+        }
+      }
+      // 开关归核心持久化。
+      extStore.setEnabled(ext.id, body.enabled)
+    }
+    const list: ExtInfo[] = Object.values(exts as RouterExtService)
+      .map((raw): ExtInfo | undefined => {
+        const e = raw as RouterExt
+        if (!e || typeof e.id !== 'string' || e.id === '') return undefined
+        const st = typeof e.getState === 'function' ? e.getState() : { ready: false }
+        return {
+          id: e.id,
+          name: e.name ?? e.id,
+          ...(e.description !== undefined ? { description: e.description } : {}),
+          enabled: extStore.isEnabled(e.id),
+          ready: st?.ready === true,
+          ...(st?.detail !== undefined ? { detail: st.detail } : {}),
+        }
+      })
+      .filter((e): e is ExtInfo => e !== undefined)
+    writeJson(res, 200, { ok: true, enhancers: list })
+  })
+
   // ---- 概览看板：用量统计 ----
 
   /** 解析并校验周期参数（不接受任意字符串）。 */
@@ -563,6 +626,14 @@ export function apply(rawContext: unknown): void {
 
   ctx.effect(
     () => () => {
+      // 注册表里的扩展器（插件自己 inject 的清理会摘键；这里兜底 dispose 仍在表里的）。
+      for (const raw of Object.values(exts as RouterExtService)) {
+        try {
+          ;(raw as RouterExt)?.dispose?.()
+        } catch {
+          // 卸载清理失败不影响其他清理
+        }
+      }
       for (const dispose of disposers.splice(0)) dispose()
       router.dispose() // 内部会 flush 用量统计（防抖中的计数不能丢）
     },

package/src/llm/adapter.ts

@@ -17,6 +17,7 @@ import {
   type LlmModelInfo,
   type LlmReasoningEffortInfo,
   type LlmResolvedModelInfo,
+  type ModelModality,
   type StreamChunk,
 } from '@deepseek-ai/dsh-llm'
 import { mergeUsage, normalizeUsage, toTokenUsage, type UsageTokens } from '../router/usage-tokens.ts'
@@ -35,11 +36,16 @@ export interface RouterAdapterSource {
 /**
  * 把 DSH 消息序列化成 openai 兼容 wire 消息（纯文本 + tool）。
  *
- * `system` 必须由调用方从 `options.system` 传进来：agent-loop 把系统提示词
- * 放在 **options.system 这个独立槽位**，不放进 messages（见 dsh-llm
- * types.d.ts 的 `system?: string` —— 注释原话 "adapters map to the
- * provider's system slot"）。不读这个槽位，模型每一轮都拿不到身份/规则/
- * 工具用法约束，且**不会报错**，只是行为悄悄降级。
+ * `system` 必须由调用方从 `options.system` 传进来：one-shot 调用方把系统提示词
+ * 放在 **options.system 这个独立槽位**，不放进 messages。不读这个槽位，
+ * one-shot 调用方（如 compaction / session-title）的模型每一轮都拿不到身份/
+ * 规则/工具用法约束，且**不会报错**，只是行为悄悄降级。
+ *
+ * 0.1.5 起 loop-built 请求反过来：`options.system` 为 undefined，系统提示词作为
+ * **messages 里的 system-role 消息**下发（dsh-agent-loop 的 SystemProjection，
+ * 可出现在任意位置以支持提示词热更新）。两条路径都必须支持 —— 与官方
+ * dsh-llm-deepseek 一致（serializeRequest 前置 options.system，再按位置序列化
+ * messages 里的 system 消息）。
  */
 function wireMessages(options: GenerateOptions, system?: string): Array<Record<string, unknown>> {
   const out: Array<Record<string, unknown>> = []
@@ -396,6 +402,16 @@ export class RouterAdapter extends LlmAdapter {
     return out
   }
 
+  /**
+   * 只收文本。`resolveModel` 声明 `inputModalities: ['text']` 是**必须**的：
+   * 0.1.5 的 runtime 只在 `inputModalities` 存在且不含 `image` 时才把 image 块
+   * 投影成占位文本（见 dsh-llm adapterStream 的 projectImagesForTextModel）。
+   * 不声明 = "unknown" = 不投影，而 wireMessages 只读 text 块 → 图片**静默
+   * 丢失**，模型看到一条没有图片的用户消息却毫无提示。声明后由 runtime 统一
+   * 投影，我们仍只处理文本。
+   */
+  private static readonly INPUT_MODALITIES: readonly ModelModality[] = ['text']
+
   async resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo> {
     const combos = await this.source.comboModels()
     const found = combos.find((m) => m.id === model || m.name === model)
@@ -407,6 +423,7 @@ export class RouterAdapter extends LlmAdapter {
       provider: 'router',
       id: model,
       name,
+      inputModalities: RouterAdapter.INPUT_MODALITIES,
       ...(found?.contextWindow !== undefined ? { context: { contextWindow: found.contextWindow } } : {}),
       reasoning: { efforts: ROUTER_REASONING_EFFORTS, defaultEffort: ReasoningEffortId('high') },
     }

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

@@ -36,14 +36,257 @@ 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)
+})
+
+// ============ 前缀亲和（docs/pool-sticky-block.md §8 的根治） ============
+
+/** 构造一次请求的 messages（前缀 = system + 首条用户消息）。 */
+const msgs = (sessionSeed: string, turns = 1): unknown => [
+  { role: 'system', content: `shared agent prompt` },
+  { role: 'user', content: `${sessionSeed} ${'x'.repeat(40)}` },
+  ...Array.from({ length: turns - 1 }, () => ({ role: 'assistant', content: 'ok' })),
+]
+
+test('【亲和】同会话粘同一号：指纹相同 → 每次都返回同一个号', () => {
+  const p = pool()
+  const list = accs(['a', 'b', 'c'])
+  const m = msgs('session-1')
+  const first = p.pick(list, [], 'round-robin', 'm1', m)
+  // 连续多轮（会话增长，但前缀不变）→ 永远是第一个号
+  for (let i = 0; i < 10; i++) {
+    assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('session-1', i + 2)), first)
+  }
+})
+
+test('【亲和】不同会话散到不同号：新指纹按游标分发', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  const s1 = p.pick(list, [], 'round-robin', 'm1', msgs('s1'))
+  const s2 = p.pick(list, [], 'round-robin', 'm1', msgs('s2'))
+  assert.notEqual(s1, s2, '两个会话应落到不同的号（缓存空间隔离）')
+  // 各自回访仍粘各自的号
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('s1', 5)), s1)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('s2', 5)), s2)
+})
+
+test('【亲和】会话增长指纹稳定：前缀相同、轮数不同 → 同一号', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  const s1 = p.pick(list, [], 'round-robin', 'm1', msgs('s1'))
+  // 真实会话每轮 messages 变长，但前 3 条不变 → 指纹不变
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('s1', 30)), s1)
+})
+
+test('【亲和】绑定的号冷却 → 会话让位，换健康号', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  const m = msgs('s1')
+  const first = p.pick(list, [], 'round-robin', 'm1', m)!
+  p.noteFailure(first, 'm1', 'rate_limit', '429')
+  // 绑定的号不可用 → 不能返回它（挂了），应落到别的号
+  const second = p.pick(list, [], 'round-robin', 'm1', m)
+  assert.notEqual(second, first)
+  // 且之后粘在新号上（绑定已更新）
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('s1', 9)), second)
+})
+
+test('【亲和】绑定的号降权（缓存无效）→ 跳过它', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  const m = msgs('s1')
+  const first = p.pick(list, [], 'round-robin', 'm1', m)!
+  // 该号累计 48 次全 miss → 判定缓存无效
+  serveMiss(p, first, 48)
+  const second = p.pick(list, [], 'round-robin', 'm1', m)
+  assert.notEqual(second, first, '降权中的号不应被亲和继续选中')
+})
+
+test('【亲和】messages 拿不到 → 回退块轮询（旧行为不破坏）', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  // 不传 messages → 走块驻留
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
   assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'a')
+  serveHits(p, 'a', 16)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1'), 'b')
+  // 传了但算不出指纹（空/坏结构）→ 同样回退
+  assert.equal(p.pick(list, [], 'round-robin', 'm2', []), 'a')
+  assert.equal(p.pick(list, [], 'round-robin', 'm2', [{ nope: 1 }]), 'a')
+})
+
+test('【亲和】绑定表按模型隔离：冷却是 (model, uid) 粒度，不串模型', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  const m = msgs('s1')
+  const m1 = p.pick(list, [], 'round-robin', 'm1', m)
+  // rrCursor 跨模型共享（与旧块轮询一致）：m1 的新会话消耗 a 后，m2 的新会话分到 b
+  const m2 = p.pick(list, [], 'round-robin', 'm2', m)
+  assert.equal(m1, 'a')
+  assert.equal(m2, 'b')
+  // 各自回访粘各自的号（绑定表按模型分开，m1 的 a 不会盖掉 m2 的 b）
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('s1', 9)), 'a')
+  assert.equal(p.pick(list, [], 'round-robin', 'm2', msgs('s1', 9)), 'b')
+  p.noteFailure('a', 'm1', 'rate_limit', '429') // 只冷 (m1, a)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', m), 'b', 'm1 上让位')
+  assert.equal(p.pick(list, [], 'round-robin', 'm2', m), 'b', 'm2 不受影响，仍粘 b')
 })
 
+test('【亲和】绑定表 LRU 封顶：超上限不泄漏，旧指纹被挤掉', () => {
+  const p = pool()
+  const list = accs(['a', 'b', 'c'])
+  const first = p.pick(list, [], 'round-robin', 'm1', msgs('s0'))!
+  // 灌 600 个新会话（> AFFINITY_MAX=512）→ 最老的 s0 被挤出
+  for (let i = 0; i < 600; i++) p.pick(list, [], 'round-robin', 'm1', msgs(`flood-${i}`))
+  const again = p.pick(list, [], 'round-robin', 'm1', msgs('s0'))
+  // 被挤掉后重新分发——只要不是内存无限增长即可（uid 合法性由 pool 保证）
+  assert.equal(list.some((a) => a.uid === again), true)
+  // 活跃会话（每次都访问）不被挤掉
+  const hot = p.pick(list, [], 'round-robin', 'm1', msgs('hot'))!
+  for (let i = 0; i < 600; i++) {
+    p.pick(list, [], 'round-robin', 'm1', msgs(`flood2-${i}`))
+    assert.equal(p.pick(list, [], 'round-robin', 'm1', msgs('hot')), hot, '活跃会话的绑定应被 LRU 刷新保留')
+  }
+})
+
+test('【亲和】多模态分片 content 也能算指纹（文本片段参与，base64 不炸）', () => {
+  const p = pool()
+  const list = accs(['a', 'b'])
+  const multi = [
+    { role: 'user', content: [{ type: 'text', text: 'look at this' }, { type: 'image_url', image_url: 'data:image/png;base64,AAAA' }] },
+  ]
+  const first = p.pick(list, [], 'round-robin', 'm1', multi)
+  assert.equal(p.pick(list, [], 'round-robin', 'm1', multi), first)
+  // 文本不同的另一个会话 → 不同指纹
+  const other = [
+    { role: 'user', content: [{ type: 'text', text: 'different' }] },
+  ]
+  assert.notEqual(p.pick(list, [], 'round-robin', 'm1', other), first, '文本不同应散开')
+})
+
+
 // ============ 核心新语义：冷却按 (模型, 连接) 分号 ============
 
 test('【颗粒度】连接在模型 A 失败，只冷 (A, 该连接)，不影响它调模型 B', () => {