dsh-router-core 0.3.12 → 0.3.13

package/README.md

@@ -5,7 +5,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/dsh-router-core"><img src="https://img.shields.io/npm/v/dsh-router-core?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square" alt="MIT license"></a>
-  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本：0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a>
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本：0.1.5-rc.1+" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B-4d6bfe" /></a>
 </p>
 
 <p align="center">
@@ -25,7 +25,7 @@
 
 ## 快速安装
 
-需要支持 `dsh plugin` profile 插件机制的 DeepSeek Harness、Node.js `>= 20`,以及 `web` profile。
+需要 **DSH `0.1.5-rc.1` 及以上**(支持 `dsh plugin` profile 插件机制)、Node.js `>= 20`,以及 `web` profile。
 
 ```bash
 dsh plugin --profile web add dsh-router-core

package/docs/pool-sticky-block.md

@@ -3,6 +3,11 @@
 > 状态:设计定稿 + 已实现。目标:保留 round-robin 的**多账号均衡**,
 > 只把轮转的**触发方式**从「每请求」改成「满意才走」,从而大幅降低
 > prompt cache miss。
+>
+> **2026-09-09 后续:round-robin 已升级为前缀亲和**(§8 天花板落地,
+> 见文末 §9)。块轮转降级为**回退路径**——亲和拿不到 `messages`
+> (算不出指纹)时才走;块统计(`BLOCK_MIN/BLOCK_HIT_RATIO/BLOCK_MAX`)
+> 保留,从「驱动轮转」改为「判降权」(§9.3)。
 
 ## 1. 问题:每请求轮转把缓存打碎
 
@@ -204,3 +209,49 @@ pick():
   否则触发失真。当前未启用。
 - **TTL 仍未知**:87.5% 是保证下限,实际可能更高。要精确 N 需反推 TTL
   (同号相邻请求间隔 vs 命中率拟合驱逐拐点)。
+
+## 9. 前缀亲和(2026-09-09 落地,round-robin 的新语义)
+
+### 9.1 机制
+
+```
+pick(round-robin):
+  fp = hash(messages 前 2 条: role + content 前 512 字符)   ← src/router/prefix-affinity.ts
+  绑定表[model][fp] 存在且该号健康 → 返回它                  ← 亲和:同会话永远同号
+  否则 → 游标分一个号 + 记绑定(fp → uid)
+  块统计(样本按 (model, uid) 跨驻留累计)只用来判降权,不再驱动轮转
+  fp 算不出(无 messages/解析失败)→ 回退块轮转(§2 的旧行为)
+```
+
+- **会话标识 = 前缀指纹**:取前 **2** 条(system + 首条用户消息)是刻意的
+  ——这两个槽位在会话生命周期里永不变化(新消息只往后追加),指纹从第 1 个
+  请求起就稳定。取 3 条会在首条 assistant 回复落进槽位 2 时变一次指纹 →
+  会话开局多付一次全量重算。「system + 首条消息逐字相同」的会话,缓存前缀
+  本来就相同,共享一个号是收益不是冲突。
+- **新会话按游标分发** → 不同会话天然散到不同号,per-account 缓存空间互不
+  清(§2.1 的打架根治)。
+- **绑定失效即重绑**:绑定的号冷却/降权/被禁 → 会话让位换健康号,并更新绑定。
+
+### 9.2 为什么亲和负责选号、块不再负责轮转
+
+亲和本身已保证驻留(同会话永远粘同号),块轮转若继续驱动换号,会把会话
+踢出已热的前缀——两者叠加只会互相拆台。块统计保留的真实价值是**号的缓存
+质量判定**:某号累计 `BLOCK_MAX`(48) 次命中率仍 < `M`(0.85) → 判缓存
+无效 → 降权 10 分钟(可恢复),亲和与回退路径都跳过它。
+
+样本从「按驻留记」改为「按 (model, uid) 跨驻留累计」:亲和开启后多个会话
+各绑各的号交错服务,「驻留」概念只在回退路径存在,按驻留记会漏掉大部分
+真实反馈。回退路径换驻留时清一次样本(保持旧块语义:新驻留 = 新观察窗口)。
+
+### 9.3 状态
+
+| 项 | 结果 |
+|---|---|
+| 实现 | `src/router/prefix-affinity.ts`(指纹)、`account-pool.ts`(亲和/LRU/样本)、`index.ts`(透传 messages) |
+| 契约 | **不变**——指纹在核心内闭环,插件与 DSH 均无感知 |
+| 测试 | 191/191(含 9 个新亲和用例) |
+| 天花板 | 绑定表 LRU 封顶 512 条(防指纹无限增长);无状态短请求前 2 条全同 → 退化为同号,行为等同 fallback,可接受 |
+
+ponytail:会话标识目前靠前缀指纹推断,真要百分百准得等 DSH 在 `ChatRequest`
+透传会话 id(需改契约,不做);指纹对「首条消息就分叉」的客户端(极少见)
+会散得比会话更细,退化为均衡分发,无害。

package/lib/client-registry.js

@@ -1173,7 +1173,7 @@ window.__ModuleLoader__.load({
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 										className: "dshr-muted",
-										children: "回退 = 按连接池顺序取第一个健康链接；轮询 = 轮流使用健康链接。"
+										children: "回退 = 按连接池顺序取第一个健康链接；轮询 = 按会话前缀粘住同一链接（前缀亲和，多会话不打架），拿不到会话信息时退回块轮转。"
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("select", {
 										className: "dshr-select dshr-input",

package/lib/client.js

@@ -1173,7 +1173,7 @@ window.__ModuleLoader__.load({
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 										className: "dshr-muted",
-										children: "回退 = 按连接池顺序取第一个健康链接；轮询 = 轮流使用健康链接。"
+										children: "回退 = 按连接池顺序取第一个健康链接；轮询 = 按会话前缀粘住同一链接（前缀亲和，多会话不打架），拿不到会话信息时退回块轮转。"
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("select", {
 										className: "dshr-select dshr-input",

package/lib/index.js

@@ -1,7 +1,7 @@
 import { basename, dirname, join, resolve } from "node:path";
 import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
 import { EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, ReasoningEffortId, ToolCallId, attributionHeaders } from "@deepseek-ai/dsh-llm";
-import { randomBytes } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import { homedir } from "node:os";
@@ -9,6 +9,84 @@ import { homedir } from "node:os";
 /** Same-origin API base the client panel fetches (host half serves it). */
 const ROUTER_API_BASE = "/router/api";
 //#endregion
+//#region src/router/prefix-affinity.ts
+/**
+* 前缀指纹 —— 把一次请求的**消息前缀**压成一个短字符串，用于「同一个会话
+* 粘在同一个账号上」。
+*
+* ## 为什么要这个
+*
+* 上游 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（不为此改契约）。
+*/
+/** 取前几条消息：system + 首条用户消息。会话里这两个槽位永不变化 → 指纹从第 1 个请求起稳定。 */
+const FP_MSGS = 2;
+/** 每条消息取前多少字符。缓存前缀的区分度集中在开头，全量哈希只增成本。 */
+const FP_CHARS = 512;
+/**
+* 消息 content 可能是字符串，也可能是多模态分片数组
+* （`[{ type: 'text', text: '...' }]`）。只取文本部分：图片是 base64，
+* 既大又不参与前缀匹配的语义（同一张图每轮都是同一串）。
+*/
+function textOf(content) {
+	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.text;
+			if (typeof t === "string") s += t;
+		}
+	}
+	return s;
+}
+/**
+* 算请求的前缀指纹。
+* @param messages OpenAI 请求体的 `messages` 字段（未校验，来自外部输入）
+* @returns 指纹字符串；**空串 = 算不出来（无亲和，回退到块轮询）**
+*/
+function prefixFingerprint(messages) {
+	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;
+		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);
+}
+//#endregion
 //#region src/router/account-pool.ts
 const MINUTE = 6e4;
 /**
@@ -85,6 +163,14 @@ const BLOCK_MIN = 16;
 const BLOCK_MAX = 48;
 /** 块轮询：判定「缓存无效」后的跳过时长。 */
 const BLOCK_DEMOTE_MS = 10 * MINUTE;
+/**
+* 前缀亲和：指纹 → 号 的绑定记忆上限。
+*
+* 会话指纹是无限集合（每个新会话一个），不封顶就是内存泄漏。超过了就丢掉
+* **最久没用**的那条：活跃会话的指纹每请求都在刷新，不会被误删。
+* 单号池（<= 几十个会话）绰绰有余。
+*/
+const AFFINITY_MAX = 512;
 /** 指数退避：等级 1 = BACKOFF_BASE_MS，每级翻倍，封顶 BACKOFF_MAX_MS。 */
 function backoffMs(level) {
 	return Math.min(BACKOFF_BASE_MS * 2 ** Math.max(0, level - 1), BACKOFF_MAX_MS);
@@ -99,10 +185,14 @@ var AccountPool = class {
 	/** uid → 连接级禁用 / 手动暂停。 */
 	byUid = /* @__PURE__ */ new Map();
 	rrCursor = 0;
-	/** (supplier, model) → 块轮询驻留状态。 */
+	/** (supplier, model) → 当前驻留的号（只有**无亲和**的回退路径用它）。 */
 	blocks = /* @__PURE__ */ new Map();
+	/** (supplier, model, uid) → 该号的缓存质量样本（降权判据，跨驻留累计）。 */
+	samples = /* @__PURE__ */ new Map();
 	/** (supplier, model, uid) → 缓存无效降权。 */
 	demoted = /* @__PURE__ */ new Map();
+	/** (supplier, model) → Map<前缀指纹, uid>：前缀亲和的选号记忆（LRU 封顶）。 */
+	affinity = /* @__PURE__ */ new Map();
 	constructor(supplierId = "") {
 		this.supplierId = supplierId;
 	}
@@ -169,22 +259,28 @@ var AccountPool = class {
 	/**
 	* 按策略为「某个模型」选一个健康账号。
 	*
-	* round-robin 走**块轮询**：一次轮转内连续服务若干请求，而不是每请求换号。
-	* 设计见 docs/pool-sticky-block.md。要点：
-	*  - 留守 = `计数 < N OR 命中率 < M`(OR,用户拍板):
-	*    命中率达标（缓存热了）→ 换号保均衡；计数到 N → 换号止损。
-	*    单号最多连续服务 N 次，不会因命中率低而死守到 N_max（打架场景关键）。
-	*  - 切号因子的思路：命中率是**留守**条件不是切号条件。反接会正反馈死锁
-	*    （切→cold miss→命中率 0%→触发切号→…），见文档 §3。
-	*  - `N_max` 绝对兜底：命中率永远不达标的号不能无限驻留（防死锁 + 防均衡归零）。
+	* 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, poolOrder, strategy, modelId) {
+	pick(accounts, poolOrder, strategy, modelId, messages) {
 		const now = Date.now();
 		const byUid = new Map(accounts.map((a) => [a.uid, a]));
 		const healthy = [...poolOrder.filter((uid) => byUid.has(uid)), ...accounts.map((a) => a.uid).filter((uid) => !poolOrder.includes(uid))].filter((uid) => this.healthy(uid, modelId, now));
@@ -192,24 +288,39 @@ var AccountPool = class {
 		if (strategy !== "round-robin") return healthy[0];
 		const usable = healthy.filter((uid) => !this.isDemoted(uid, modelId, now));
 		const pool = usable.length > 0 ? usable : healthy;
+		const fp = messages === void 0 ? "" : 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 (block !== void 0 && pool.includes(block.uid) && this.blockKeeps(block)) return block.uid;
-		const uid = pool[(block === void 0 ? this.rrCursor : Math.max(0, pool.indexOf(block.uid) + 1)) % pool.length];
+		if (fp === "" && block !== void 0 && pool.includes(block) && this.blockKeeps(modelId, block)) return block;
+		const uid = pool[(block === void 0 ? this.rrCursor : Math.max(0, pool.indexOf(block) + 1)) % pool.length];
 		this.rrCursor = (pool.indexOf(uid) + 1) % pool.length;
-		this.blocks.set(this.blockKey(modelId), {
-			uid,
-			served: 0,
-			hits: 0
-		});
+		this.blocks.set(this.blockKey(modelId), uid);
+		if (fp !== "") this.bind(modelId, fp, uid);
+		else this.samples.delete(this.key(modelId, uid));
 		return uid;
 	}
+	/** 记下「前缀指纹 → 号」的绑定（LRU：超上限丢最久未用的）。 */
+	bind(modelId, fp, uid) {
+		const k = this.blockKey(modelId);
+		let m = this.affinity.get(k);
+		if (m === void 0) {
+			m = /* @__PURE__ */ new Map();
+			this.affinity.set(k, m);
+		}
+		m.delete(fp);
+		m.set(fp, uid);
+		if (m.size > AFFINITY_MAX) {
+			const oldest = m.keys().next().value;
+			if (oldest !== void 0) m.delete(oldest);
+		}
+	}
 	/** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
 	isDemoted(uid, modelId, now) {
 		const e = this.demoted.get(this.key(modelId, uid));
 		return e !== void 0 && e.until > now;
 	}
 	/**
-	* 块是否还应驻留在当前号上。
+	* 驻留是否还应留在当前号上（**只用于无亲和的回退路径**）。
 	*
 	* OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
 	* 单一账号内部：一个号先被轮到（冷启动/热），然后
@@ -219,33 +330,39 @@ var AccountPool = class {
 	*
 	* 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
 	* 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
-	*
-	* 每个号各自守着「这个会话在自己账号上的那段前缀」，轮流热；
-	* 命中率 = 块的命中占比。单会话下每个号块都从冷到热各付一次,
-	* 收益来自块内连续驻留(缺了它就跟每请求轮询一样)。
 	*/
-	blockKeeps(block) {
-		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;
+	blockKeeps(modelId, uid) {
+		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;
 	}
 	/**
-	* 记录一次成功请求的缓存命中情况（块轮询的反馈信号）。
+	* 记录一次成功请求的缓存命中情况（降权判据的反馈信号）。
 	*
-	* 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错切。
+	* 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错降权。
+	* 统计按 (model, uid) 记，**不管这个号是不是「当前驻留」**——亲和开启后
+	* 多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
 	* @param uid 实际服务的号
 	* @param modelId 模型（块粒度）
 	* @param cachedTokens 上游报的命中 token 数；0 = 全量重算
 	*/
 	noteCache(uid, modelId, cachedTokens) {
-		const k = this.blockKey(modelId);
-		const block = this.blocks.get(k);
-		if (block === void 0 || block.uid !== uid) return;
-		block.served += 1;
-		if (cachedTokens > 0) block.hits += 1;
-		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 });
+		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);
+		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) {
 		this.blocks.delete(this.blockKey(modelId));
 	}
@@ -1237,6 +1354,17 @@ const TRANSIENT_SETTLE_MS = 2e3;
 function isTransient(state) {
 	return state === "transport" || state === "unavailable";
 }
+/**
+* 从请求体里取 `messages`（前缀亲和的指纹输入）。解析失败/字段缺失返回
+* undefined —— 亲和拿不到输入就自动回退到块轮询，不影响路由本身。
+*/
+function reqMessages(rawBody) {
+	try {
+		return JSON.parse(rawBody).messages;
+	} catch {
+		return;
+	}
+}
 /** 丢弃响应的假 ServerResponse（测试模型用：记录状态+内容，用于判定成败）。 */
 function sinkRes() {
 	let status = 200;
@@ -2075,9 +2203,10 @@ var Router = class {
 			}
 			return await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0);
 		}
+		const messages = reqMessages(req.rawBody);
 		const tried = /* @__PURE__ */ new Set();
 		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 === void 0) return false;
 			tried.add(uid);
 			const r = await s.chatOnce(uid, req.lv ?? "auto", req);
@@ -2174,11 +2303,16 @@ var Router = class {
 /**
 * 把 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, system) {
 	const out = [];
@@ -2506,7 +2640,7 @@ const ROUTER_REASONING_EFFORTS = [
 		name: "Max"
 	}
 ];
-var RouterAdapter = class extends LlmAdapter {
+var RouterAdapter = class RouterAdapter extends LlmAdapter {
 	baseURL;
 	source;
 	constructor(baseURL, source) {
@@ -2535,12 +2669,22 @@ var RouterAdapter = class extends LlmAdapter {
 		}
 		return out;
 	}
+	/**
+	* 只收文本。`resolveModel` 声明 `inputModalities: ['text']` 是**必须**的：
+	* 0.1.5 的 runtime 只在 `inputModalities` 存在且不含 `image` 时才把 image 块
+	* 投影成占位文本（见 dsh-llm adapterStream 的 projectImagesForTextModel）。
+	* 不声明 = "unknown" = 不投影，而 wireMessages 只读 text 块 → 图片**静默
+	* 丢失**，模型看到一条没有图片的用户消息却毫无提示。声明后由 runtime 统一
+	* 投影，我们仍只处理文本。
+	*/
+	static INPUT_MODALITIES = ["text"];
 	async resolveModel(_provider, model) {
 		const found = (await this.source.comboModels()).find((m) => m.id === model || m.name === model);
 		return {
 			provider: "router",
 			id: model,
 			name: found?.name ?? found?.id ?? model,
+			inputModalities: RouterAdapter.INPUT_MODALITIES,
 			...found?.contextWindow !== void 0 ? { context: { contextWindow: found.contextWindow } } : {},
 			reasoning: {
 				efforts: ROUTER_REASONING_EFFORTS,

package/lib/types/llm/adapter.d.ts

@@ -38,6 +38,15 @@ export declare class RouterAdapter extends LlmAdapter {
         name: string;
     };
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * 只收文本。`resolveModel` 声明 `inputModalities: ['text']` 是**必须**的：
+     * 0.1.5 的 runtime 只在 `inputModalities` 存在且不含 `image` 时才把 image 块
+     * 投影成占位文本（见 dsh-llm adapterStream 的 projectImagesForTextModel）。
+     * 不声明 = "unknown" = 不投影，而 wireMessages 只读 text 块 → 图片**静默
+     * 丢失**，模型看到一条没有图片的用户消息却毫无提示。声明后由 runtime 统一
+     * 投影，我们仍只处理文本。
+     */
+    private static readonly INPUT_MODALITIES;
     resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }

package/lib/types/router/account-pool.d.ts

@@ -31,10 +31,14 @@ export declare class AccountPool {
     /** uid → 连接级禁用 / 手动暂停。 */
     private byUid;
     private rrCursor;
-    /** (supplier, model) → 块轮询驻留状态。 */
+    /** (supplier, model) → 当前驻留的号（只有**无亲和**的回退路径用它）。 */
     private blocks;
+    /** (supplier, model, uid) → 该号的缓存质量样本（降权判据，跨驻留累计）。 */
+    private samples;
     /** (supplier, model, uid) → 缓存无效降权。 */
     private demoted;
+    /** (supplier, model) → Map<前缀指纹, uid>：前缀亲和的选号记忆（LRU 封顶）。 */
+    private affinity;
     constructor(supplierId?: string);
     private key;
     private entry;
@@ -51,26 +55,34 @@ export declare class AccountPool {
     /**
      * 按策略为「某个模型」选一个健康账号。
      *
-     * round-robin 走**块轮询**：一次轮转内连续服务若干请求，而不是每请求换号。
-     * 设计见 docs/pool-sticky-block.md。要点：
-     *  - 留守 = `计数 < N OR 命中率 < M`(OR,用户拍板):
-     *    命中率达标（缓存热了）→ 换号保均衡；计数到 N → 换号止损。
-     *    单号最多连续服务 N 次，不会因命中率低而死守到 N_max（打架场景关键）。
-     *  - 切号因子的思路：命中率是**留守**条件不是切号条件。反接会正反馈死锁
-     *    （切→cold miss→命中率 0%→触发切号→…），见文档 §3。
-     *  - `N_max` 绝对兜底：命中率永远不达标的号不能无限驻留（防死锁 + 防均衡归零）。
+     * 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;
+    /** 记下「前缀指纹 → 号」的绑定（LRU：超上限丢最久未用的）。 */
+    private bind;
     /** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
     private isDemoted;
     /**
-     * 块是否还应驻留在当前号上。
+     * 驻留是否还应留在当前号上（**只用于无亲和的回退路径**）。
      *
      * OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
      * 单一账号内部：一个号先被轮到（冷启动/热），然后
@@ -80,22 +92,20 @@ export declare class AccountPool {
      *
      * 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
      * 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
-     *
-     * 每个号各自守着「这个会话在自己账号上的那段前缀」，轮流热；
-     * 命中率 = 块的命中占比。单会话下每个号块都从冷到热各付一次,
-     * 收益来自块内连续驻留(缺了它就跟每请求轮询一样)。
      */
     private blockKeeps;
     /**
-     * 记录一次成功请求的缓存命中情况（块轮询的反馈信号）。
+     * 记录一次成功请求的缓存命中情况（降权判据的反馈信号）。
      *
-     * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错切。
+     * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错降权。
+     * 统计按 (model, uid) 记，**不管这个号是不是「当前驻留」**——亲和开启后
+     * 多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
      * @param uid 实际服务的号
      * @param modelId 模型（块粒度）
      * @param cachedTokens 上游报的命中 token 数；0 = 全量重算
      */
     noteCache(uid: string, modelId: string, cachedTokens: number): void;
-    /** 故障切走时作废当前块：换号后前缀归属变了，块计数不能沿用。 */
+    /** 故障切走时作废当前驻留：换号后前缀归属变了，驻留计数不能沿用。 */
     dropBlock(modelId: string): void;
     /** 块状态键：与冷却同粒度 (supplier, model)，不含 uid。 */
     private blockKey;

package/lib/types/router/prefix-affinity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 算请求的前缀指纹。
+ * @param messages OpenAI 请求体的 `messages` 字段（未校验，来自外部输入）
+ * @returns 指纹字符串；**空串 = 算不出来（无亲和，回退到块轮询）**
+ */
+export declare function prefixFingerprint(messages: unknown): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "DSH plugin: a simplified 9router (AI routing gateway). Adds a 路由系统 (Routing System) sidebar entry beside 记忆系统; the panel shows suppliers, account pool, combos, and endpoint/API keys.",
   "type": "module",
   "repository": {
@@ -66,9 +66,9 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
@@ -85,7 +85,7 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.1",
     "@types/node": "^26.4.1",
     "@types/react": "~19.2.18",
     "@types/react-dom": "~19.2.7",

package/src/client/SupplierDetail.tsx

@@ -908,7 +908,7 @@ export function SupplierDetail({ supplier, accounts, statusLoading, onBack, onRe
             </>
             <>
               <label className="dshr-fieldLabel">连接池策略</label>
-              <p className="dshr-muted">回退 = 按连接池顺序取第一个健康链接；轮询 = 轮流使用健康链接。</p>
+              <p className="dshr-muted">回退 = 按连接池顺序取第一个健康链接；轮询 = 按会话前缀粘住同一链接（前缀亲和，多会话不打架），拿不到会话信息时退回块轮转。</p>
               <select
                 className="dshr-select dshr-input"
                 value={poolStrategy}

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

@@ -161,6 +161,132 @@ test('【块】多号间长期均衡：块大小有界 → 请求数均分', ()
   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', () => {

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 {
@@ -95,6 +96,15 @@ const BLOCK_MAX = 48
 /** 块轮询：判定「缓存无效」后的跳过时长。 */
 const BLOCK_DEMOTE_MS = 10 * MINUTE
 
+/**
+ * 前缀亲和：指纹 → 号 的绑定记忆上限。
+ *
+ * 会话指纹是无限集合（每个新会话一个），不封顶就是内存泄漏。超过了就丢掉
+ * **最久没用**的那条：活跃会话的指纹每请求都在刷新，不会被误删。
+ * 单号池（<= 几十个会话）绰绰有余。
+ */
+const AFFINITY_MAX = 512
+
 /** 冷却记录（键 = (supplier, model, uid)）。 */
 interface CooldownEntry {
   until: number
@@ -124,6 +134,20 @@ interface BlockState {
   hits: number
 }
 
+/**
+ * 某号在某模型上的缓存质量样本（键 = (supplier, model, uid)）。
+ *
+ * 与「驻留」解耦：开启前缀亲和后多个会话各绑各的号交错服务，驻留概念只在
+ * 无亲和的回退路径上存在；而「这个号的缓存到底热不热」是**号本身的属性**，
+ * 必须跨驻留累计——否则每次换驻留就清零，永远攒不到 BLOCK_MAX 次判据。
+ */
+interface Sample {
+  /** 已服务的成功请求数。 */
+  served: number
+  /** 命中缓存（cachedTokens > 0）的请求数。 */
+  hits: number
+}
+
 /** 「缓存无效」降权记录（键 = (supplier, model, uid)）。 */
 interface DemoteEntry {
   until: number
@@ -145,10 +169,14 @@ export class AccountPool {
   /** uid → 连接级禁用 / 手动暂停。 */
   private byUid = new Map<string, UidEntry>()
   private rrCursor = 0
-  /** (supplier, model) → 块轮询驻留状态。 */
-  private blocks = new Map<string, BlockState>()
+  /** (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
@@ -203,22 +231,28 @@ export class AccountPool {
   /**
    * 按策略为「某个模型」选一个健康账号。
    *
-   * round-robin 走**块轮询**：一次轮转内连续服务若干请求，而不是每请求换号。
-   * 设计见 docs/pool-sticky-block.md。要点：
-   *  - 留守 = `计数 < N OR 命中率 < M`(OR,用户拍板):
-   *    命中率达标（缓存热了）→ 换号保均衡；计数到 N → 换号止损。
-   *    单号最多连续服务 N 次，不会因命中率低而死守到 N_max（打架场景关键）。
-   *  - 切号因子的思路：命中率是**留守**条件不是切号条件。反接会正反馈死锁
-   *    （切→cold miss→命中率 0%→触发切号→…），见文档 §3。
-   *  - `N_max` 绝对兜底：命中率永远不达标的号不能无限驻留（防死锁 + 防均衡归零）。
+   * 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]))
     // 池顺序优先，未配置的按插件自然顺序追加
@@ -229,21 +263,50 @@ 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]
-    // 缓存无效降权：驻留满 N_max 命中率仍不达标的号，跳过它（可到期恢复）
+    // 缓存无效降权：该号缓存质量样本长期不达标 → 跳过它（可到期恢复）
     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 (block !== undefined && pool.includes(block.uid) && this.blockKeeps(block)) {
-      return block.uid
+    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.uid) + 1)
+    // 无亲和（或块满/块达标）→ 前进游标。从当前号之后开始找，保证轮转顺序稳定。
+    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, served: 0, hits: 0 })
+    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))
@@ -251,7 +314,7 @@ export class AccountPool {
   }
 
   /**
-   * 块是否还应驻留在当前号上。
+   * 驻留是否还应留在当前号上（**只用于无亲和的回退路径**）。
    *
    * OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
    * 单一账号内部：一个号先被轮到（冷启动/热），然后
@@ -261,39 +324,40 @@ export class AccountPool {
    *
    * 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
    * 见文档 §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
+  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.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 })
+    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))
   }

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
@@ -1006,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)

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)
+}