dsh-router-core 0.3.11 → 0.3.12

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/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

@@ -845,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)
     }
@@ -1018,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
@@ -1036,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/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