dsh-router-core 0.3.11 → 0.3.13

package/src/router/account-pool.ts

@@ -23,6 +23,7 @@
  * 得落盘，届时加 stateFile 即可，接口不用变。
  */
 import type { AccountState, SupplierAccountNow } from '../suppliers/contract.ts'
+import { prefixFingerprint } from './prefix-affinity.ts'
 
 /** 各 AccountState 的处置：冷却策略 / 是否禁用 / 是否计入连续错误。 */
 interface Rule {
@@ -86,6 +87,24 @@ 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
+
+/**
+ * 前缀亲和：指纹 → 号 的绑定记忆上限。
+ *
+ * 会话指纹是无限集合（每个新会话一个），不封顶就是内存泄漏。超过了就丢掉
+ * **最久没用**的那条：活跃会话的指纹每请求都在刷新，不会被误删。
+ * 单号池（<= 几十个会话）绰绰有余。
+ */
+const AFFINITY_MAX = 512
+
 /** 冷却记录（键 = (supplier, model, uid)）。 */
 interface CooldownEntry {
   until: number
@@ -100,6 +119,40 @@ interface UidEntry {
   reason: string
 }
 
+/**
+ * 块轮询的驻留状态（键 = (supplier, model)，与冷却同粒度）。
+ *
+ * 为什么按 (供应商, 模型) 而不是按号：块是「当前这一轮由谁服务」的概念，
+ * 一个模型上只有一个号在驻留；换模型意味着换前缀，块自然作废。
+ */
+interface BlockState {
+  /** 当前驻留的号。 */
+  uid: string
+  /** 本块已服务的成功请求数。 */
+  served: number
+  /** 本块命中缓存（cachedTokens > 0）的请求数。 */
+  hits: number
+}
+
+/**
+ * 某号在某模型上的缓存质量样本（键 = (supplier, model, uid)）。
+ *
+ * 与「驻留」解耦：开启前缀亲和后多个会话各绑各的号交错服务，驻留概念只在
+ * 无亲和的回退路径上存在；而「这个号的缓存到底热不热」是**号本身的属性**，
+ * 必须跨驻留累计——否则每次换驻留就清零，永远攒不到 BLOCK_MAX 次判据。
+ */
+interface Sample {
+  /** 已服务的成功请求数。 */
+  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 +169,14 @@ export class AccountPool {
   /** uid → 连接级禁用 / 手动暂停。 */
   private byUid = new Map<string, UidEntry>()
   private rrCursor = 0
+  /** (supplier, model) → 当前驻留的号（只有**无亲和**的回退路径用它）。 */
+  private blocks = new Map<string, string>()
+  /** (supplier, model, uid) → 该号的缓存质量样本（降权判据，跨驻留累计）。 */
+  private samples = new Map<string, Sample>()
+  /** (supplier, model, uid) → 缓存无效降权。 */
+  private demoted = new Map<string, DemoteEntry>()
+  /** (supplier, model) → Map<前缀指纹, uid>：前缀亲和的选号记忆（LRU 封顶）。 */
+  private affinity = new Map<string, Map<string, string>>()
 
   constructor(supplierId = '') {
     this.supplierId = supplierId
@@ -169,13 +230,29 @@ export class AccountPool {
 
   /**
    * 按策略为「某个模型」选一个健康账号。
+   *
+   * round-robin = **前缀亲和定号 + 块统计只用来判定缓存无效**：
+   *
+   *  1. 算请求的前缀指纹（messages 前几条），查绑定表 → 命中且该号健康 → 用它。
+   *     这是第一优先：同一个会话的连续请求**永远落回同一个号**，前缀在该号的
+   *     缓存里只写一份。块轮询治不了跨会话驱逐（多会话大前缀在同一号互踩，
+   *     实测 3 会话 3.8% vs 单会话 82.5%），亲和才是根治。
+   *  2. 新指纹（或绑定的号不健康）→ 按游标挑一个号并**记下绑定**，之后就固定。
+   *     新会话用游标分发，所以不同会话天然散到不同号上（均衡）。
+   *  3. 块统计不再驱动轮转（亲和已经保证驻留，再轮转只会把会话踢出已热前缀），
+   *     只保留 `BLOCK_MAX` 次不达标 → 降权该号（缓存无效，可恢复）。
+   *
+   * 亲和失效（拿不到 messages / 指纹算不出）时**回退到块轮询**，行为与之前一致。
+   * 设计见 docs/pool-sticky-block.md §8。
+   *
    * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
    * @param poolOrder 用户在面板拖出来的顺序（核心管）
-   * @param strategy fallback 取第一个健康 / round-robin 轮转健康号
+   * @param strategy fallback 取第一个健康 / round-robin 前缀亲和
    * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
+   * @param messages 请求体的 messages（可选；给了才能算前缀指纹）
    * @returns 选中的 uid；无健康账号返回 undefined
    */
-  pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string): string | undefined {
+  pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string, messages?: unknown): string | undefined {
     const now = Date.now()
     const byUid = new Map(accounts.map((a) => [a.uid, a]))
     // 池顺序优先，未配置的按插件自然顺序追加
@@ -186,11 +263,110 @@ 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
+    // 缓存无效降权：该号缓存质量样本长期不达标 → 跳过它（可到期恢复）
+    const usable = healthy.filter((uid) => !this.isDemoted(uid, modelId, now))
+    const pool = usable.length > 0 ? usable : healthy
+    // 前缀亲和：指纹有绑定且该号仍可用 → 直接复用（不进驻留逻辑）
+    const fp = messages === undefined ? '' : prefixFingerprint(messages)
+    if (fp !== '' && pool.includes(this.affinity.get(this.blockKey(modelId))?.get(fp) ?? '')) {
+      return this.affinity.get(this.blockKey(modelId))!.get(fp)!
+    }
+    const block = this.blocks.get(this.blockKey(modelId))
+    if (fp === '' && block !== undefined && pool.includes(block) && this.blockKeeps(modelId, block)) {
+      return block
+    }
+    // 无亲和（或块满/块达标）→ 前进游标。从当前号之后开始找，保证轮转顺序稳定。
+    const from = block === undefined ? this.rrCursor : Math.max(0, pool.indexOf(block) + 1)
+    const uid = pool[from % pool.length]!
+    this.rrCursor = (pool.indexOf(uid) + 1) % pool.length
+    this.blocks.set(this.blockKey(modelId), uid)
+    if (fp !== '') {
+      this.bind(modelId, fp, uid)
+    } else {
+      // 新驻留 = 新观察窗口（旧行为：块计数从 0 开始）。样本是跨驻留累计的，
+      // 不清的话上一个大样本会立刻把新驻留判走。
+      this.samples.delete(this.key(modelId, uid))
+    }
     return uid
   }
 
+  /** 记下「前缀指纹 → 号」的绑定（LRU：超上限丢最久未用的）。 */
+  private bind(modelId: string, fp: string, uid: string): void {
+    const k = this.blockKey(modelId)
+    let m = this.affinity.get(k)
+    if (m === undefined) {
+      m = new Map()
+      this.affinity.set(k, m)
+    }
+    // 已存在则先删再 set：Map 的插入序即 LRU 序，重插等于刷新到最新
+    m.delete(fp)
+    m.set(fp, uid)
+    if (m.size > AFFINITY_MAX) {
+      const oldest = m.keys().next().value
+      if (oldest !== undefined) m.delete(oldest)
+    }
+  }
+
+  /** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
+  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(modelId: string, uid: string): boolean {
+    const s = this.samples.get(this.key(modelId, uid))
+    const served = s?.served ?? 0
+    if (served >= BLOCK_MAX) return false // 轮次过多 → 让位（兜底）
+    const ratio = served === 0 ? 0 : (s?.hits ?? 0) / served
+    return served < BLOCK_MIN || ratio < BLOCK_HIT_RATIO // 计数<N OR 命中率<M
+  }
+
+  /**
+   * 记录一次成功请求的缓存命中情况（降权判据的反馈信号）。
+   *
+   * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错降权。
+   * 统计按 (model, uid) 记，**不管这个号是不是「当前驻留」**——亲和开启后
+   * 多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
+   * @param uid 实际服务的号
+   * @param modelId 模型（块粒度）
+   * @param cachedTokens 上游报的命中 token 数；0 = 全量重算
+   */
+  noteCache(uid: string, modelId: string, cachedTokens: number): void {
+    const k = this.key(modelId, uid)
+    const s = this.samples.get(k) ?? { served: 0, hits: 0 }
+    s.served += 1
+    if (cachedTokens > 0) s.hits += 1
+    this.samples.set(k, s)
+    // 累计满 N_max 仍不达标 → 判定缓存无效，降权一段时间（可恢复）
+    if (s.served >= BLOCK_MAX && s.hits / s.served < BLOCK_HIT_RATIO) {
+      this.demoted.set(k, { until: Date.now() + BLOCK_DEMOTE_MS })
+      // 降权后样本重置：冷却结束重新观察，而不是带着旧判决立刻再降
+      this.samples.delete(k)
+    }
+  }
+
+  /** 故障切走时作废当前驻留：换号后前缀归属变了，驻留计数不能沿用。 */
+  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

@@ -78,6 +78,18 @@ function isTransient(state: AccountState): boolean {
   return state === 'transport' || state === 'unavailable'
 }
 
+/**
+ * 从请求体里取 `messages`（前缀亲和的指纹输入）。解析失败/字段缺失返回
+ * undefined —— 亲和拿不到输入就自动回退到块轮询，不影响路由本身。
+ */
+function reqMessages(rawBody: string): unknown {
+  try {
+    return (JSON.parse(rawBody) as { messages?: unknown }).messages
+  } catch {
+    return undefined
+  }
+}
+
 /** 丢弃响应的假 ServerResponse（测试模型用：记录状态+内容，用于判定成败）。 */
 function sinkRes(): ServerResponse & { status(): number; body(): string } {
   let status = 200
@@ -845,6 +857,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)
     }
@@ -1004,9 +1018,12 @@ export class Router {
     }
     // 试过的号不再选：某些失败状态既不冷却也不计数（如模型不属于本供应商），
     // 不排除试过的就会原地打转——死循环等于整个服务挂住。
+    // messages 只取一次：前缀亲和用它算指纹（重试换号时指纹必须一致，
+    // 否则同一会话的两次尝试会绑到不同的号上）。
+    const messages = reqMessages(req.rawBody)
     const tried = new Set<string>()
     for (;;) {
-      const uid = pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, cfg.poolStrategy, req.model)
+      const uid = pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, cfg.poolStrategy, req.model, messages)
       if (uid === undefined) return false
       tried.add(uid)
       const r = await s.chatOnce(uid, req.lv ?? 'auto', req)
@@ -1018,6 +1035,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
@@ -1036,8 +1055,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/prefix-affinity.ts

@@ -0,0 +1,80 @@
+/**
+ * 前缀指纹 —— 把一次请求的**消息前缀**压成一个短字符串，用于「同一个会话
+ * 粘在同一个账号上」。
+ *
+ * ## 为什么要这个
+ *
+ * 上游 prompt cache 是 **per-account × per-conversation** 的命名空间。块轮询
+ * 保证的是「单会话内连续驻留」，但多个会话被轮到同一个号时，各自十几万的大
+ * 前缀会在该号的缓存里**互相驱逐**（实测 3 会话并发 → 命中 3.8%，单会话独占
+ * → 82.5%，见 docs/pool-sticky-block.md §2.1）。
+ *
+ * 破法是让每个会话固定落到一个号：前缀指纹 → 选号。指纹相同的请求（= 同一
+ * 会话的连续请求，前缀逐轮增长但开头不变）落在同一个号，各自有独立的缓存
+ * 空间。
+ *
+ * ## 为什么按「前几条消息」而不是整个 body
+ *
+ * - 整个 body 每次都不一样（会话越跑越长）→ 指纹漂移 → 同一会话换号，正好
+ *   是要避免的事。
+ * - 请求体前 N 字节也不行：system prompt 动辄几 KB，同源会话（同一个 agent）
+ *   在这 N 字节里完全一样，多个会话会撞到同一个号。
+ * - 条数取 **2**（system + 首条用户消息）是刻意的：这两个槽位在会话整个
+ *   生命周期里**永不变化**（新消息只往后追加），所以从第 1 个请求起指纹
+ *   就稳定。取 3 条会在第一条 assistant 回复落进槽位 2 时变一次指纹 →
+ *   会话开局多付一次全量重算。而「system + 首条消息逐字相同」的会话，
+ *   缓存前缀本来就相同，共享一个号的缓存是收益不是冲突。
+ *
+ * 天花板：若某个客户端的前 3 条消息在所有会话里都逐字相同（无状态短请求），
+ * 指纹会退化成一个值 → 全部压到一个号。此时退化行为 = fallback，可接受；
+ * 真要区分得等 DSH 透传会话 id（不为此改契约）。
+ */
+import { createHash } from 'node:crypto'
+
+/** 取前几条消息：system + 首条用户消息。会话里这两个槽位永不变化 → 指纹从第 1 个请求起稳定。 */
+const FP_MSGS = 2
+/** 每条消息取前多少字符。缓存前缀的区分度集中在开头，全量哈希只增成本。 */
+const FP_CHARS = 512
+
+/**
+ * 消息 content 可能是字符串，也可能是多模态分片数组
+ * （`[{ type: 'text', text: '...' }]`）。只取文本部分：图片是 base64，
+ * 既大又不参与前缀匹配的语义（同一张图每轮都是同一串）。
+ */
+function textOf(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  let s = ''
+  for (const part of content) {
+    if (typeof part === 'string') {
+      s += part
+      continue
+    }
+    if (part !== null && typeof part === 'object') {
+      const t = (part as { text?: unknown }).text
+      if (typeof t === 'string') s += t
+    }
+  }
+  return s
+}
+
+/**
+ * 算请求的前缀指纹。
+ * @param messages OpenAI 请求体的 `messages` 字段（未校验，来自外部输入）
+ * @returns 指纹字符串；**空串 = 算不出来（无亲和，回退到块轮询）**
+ */
+export function prefixFingerprint(messages: unknown): string {
+  if (!Array.isArray(messages) || messages.length === 0) return ''
+  let buf = ''
+  const n = Math.min(messages.length, FP_MSGS)
+  for (let i = 0; i < n; i++) {
+    const m = messages[i]
+    if (m === null || typeof m !== 'object') continue
+    const { role, content } = m as { role?: unknown; content?: unknown }
+    const text = textOf(content)
+    if (typeof role !== 'string' && text === '') continue
+    buf += `${typeof role === 'string' ? role : ''}\u0000${text.slice(0, FP_CHARS)}\u0001`
+  }
+  if (buf === '') return ''
+  return createHash('sha1').update(buf).digest('base64url').slice(0, 12)
+}

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

@@ -139,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