dsh-router-core 0.3.12 → 0.3.14

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",
@@ -4115,6 +4115,60 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region src/client/model-hint-copy.ts
+		/**
+		* 设置-模型 → Router 卡片：把宿主那句走不通的提示换成正确说法。
+		*
+		* 为什么不能直接改源头：Router 的卡片走宿主的 "unknown" 布局（宿主只认得
+		* llm-deepseek / llm-pi-ai 两套表单），那句
+		*   「其余字段在 settings.yaml 中，请直接编辑对应段。 (llm-dsh-router)」
+		* 属于宿主 `settings.models` 的 locale 字典，而字典注册对同一个 (ns, locale)
+		* 只允许一个占位者（重复注册直接抛），插件覆写不了，契约也没给可覆写字段。
+		* 所以沿用本插件既有的认领手法（同 settings-nav-icon.ts）：按文案指纹认出宿主
+		* 渲染的那一段，就地改写。
+		*
+		* 只写 `nodeValue`、不增删节点（节点归 React，摘掉会让它的引用落空）。React 重渲染
+		* 覆盖回来时观察器会再改一次；已是目标文案就早退，不会自激。
+		*
+		* 升级路径：宿主若给该提示长出可覆写字段（或 Router 有了专属布局），删掉本文件。
+		*/
+		/** 指纹：语言无关（不受中英文切换影响），且只出现在 Router 卡片上。 */
+		var FINGERPRINT = "(llm-dsh-router)";
+		/** 正确说法：对齐 README「组合即模型」。 */
+		var ROUTER_MODEL_HINT_COPY = "组合即模型 · 建好的组合会自动出现在 DSH 模型目录中，选中组合名即可直接使用。";
+		/**
+		* 这段文本要不要改写。
+		* @param text 段落当前文本
+		* @returns 需要改写时给出目标文案，否则 undefined
+		*/
+		function routerHintRewrite(text) {
+			if (!text.includes(FINGERPRINT)) return void 0;
+			if (text === "组合即模型 · 建好的组合会自动出现在 DSH 模型目录中，选中组合名即可直接使用。") return void 0;
+			return ROUTER_MODEL_HINT_COPY;
+		}
+		/**
+		* 持续把 Router 卡片里的宿主提示改写成 {@link ROUTER_MODEL_HINT_COPY}。
+		* @returns 清理函数：断开观察
+		*/
+		function rewriteRouterModelHint() {
+			const sync = () => {
+				for (const el of document.querySelectorAll("p[class*=\"advancedHint\"]")) {
+					const next = routerHintRewrite(el.textContent ?? "");
+					const node = el.firstChild;
+					if (next === void 0 || node?.nodeType !== Node.TEXT_NODE) continue;
+					node.nodeValue = next;
+				}
+			};
+			sync();
+			const observer = new MutationObserver(sync);
+			observer.observe(document.body, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			return () => observer.disconnect();
+		}
+		//#endregion
 		//#region src/client/index.tsx
 		/**
 		* Client half of dsh-router.
@@ -4157,6 +4211,7 @@ window.__ModuleLoader__.load({
 			}
 			ctx.effect(() => disposeSettings, "dsh-router: settings section");
 			ctx.effect(() => registerSettingsNavIcon(SECTION_LABEL), "dsh-router: settings nav icon");
+			ctx.effect(() => rewriteRouterModelHint(), "dsh-router: models provider hint copy");
 		}
 		//#endregion
 		exports.apply = apply;

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",
@@ -4115,6 +4115,60 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region src/client/model-hint-copy.ts
+		/**
+		* 设置-模型 → Router 卡片：把宿主那句走不通的提示换成正确说法。
+		*
+		* 为什么不能直接改源头：Router 的卡片走宿主的 "unknown" 布局（宿主只认得
+		* llm-deepseek / llm-pi-ai 两套表单），那句
+		*   「其余字段在 settings.yaml 中，请直接编辑对应段。 (llm-dsh-router)」
+		* 属于宿主 `settings.models` 的 locale 字典，而字典注册对同一个 (ns, locale)
+		* 只允许一个占位者（重复注册直接抛），插件覆写不了，契约也没给可覆写字段。
+		* 所以沿用本插件既有的认领手法（同 settings-nav-icon.ts）：按文案指纹认出宿主
+		* 渲染的那一段，就地改写。
+		*
+		* 只写 `nodeValue`、不增删节点（节点归 React，摘掉会让它的引用落空）。React 重渲染
+		* 覆盖回来时观察器会再改一次；已是目标文案就早退，不会自激。
+		*
+		* 升级路径：宿主若给该提示长出可覆写字段（或 Router 有了专属布局），删掉本文件。
+		*/
+		/** 指纹：语言无关（不受中英文切换影响），且只出现在 Router 卡片上。 */
+		var FINGERPRINT = "(llm-dsh-router)";
+		/** 正确说法：对齐 README「组合即模型」。 */
+		var ROUTER_MODEL_HINT_COPY = "组合即模型 · 建好的组合会自动出现在 DSH 模型目录中，选中组合名即可直接使用。";
+		/**
+		* 这段文本要不要改写。
+		* @param text 段落当前文本
+		* @returns 需要改写时给出目标文案，否则 undefined
+		*/
+		function routerHintRewrite(text) {
+			if (!text.includes(FINGERPRINT)) return void 0;
+			if (text === "组合即模型 · 建好的组合会自动出现在 DSH 模型目录中，选中组合名即可直接使用。") return void 0;
+			return ROUTER_MODEL_HINT_COPY;
+		}
+		/**
+		* 持续把 Router 卡片里的宿主提示改写成 {@link ROUTER_MODEL_HINT_COPY}。
+		* @returns 清理函数：断开观察
+		*/
+		function rewriteRouterModelHint() {
+			const sync = () => {
+				for (const el of document.querySelectorAll("p[class*=\"advancedHint\"]")) {
+					const next = routerHintRewrite(el.textContent ?? "");
+					const node = el.firstChild;
+					if (next === void 0 || node?.nodeType !== Node.TEXT_NODE) continue;
+					node.nodeValue = next;
+				}
+			};
+			sync();
+			const observer = new MutationObserver(sync);
+			observer.observe(document.body, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			return () => observer.disconnect();
+		}
+		//#endregion
 		//#region src/client/index.tsx
 		/**
 		* Client half of dsh-router.
@@ -4157,6 +4211,7 @@ window.__ModuleLoader__.load({
 			}
 			ctx.effect(() => disposeSettings, "dsh-router: settings section");
 			ctx.effect(() => registerSettingsNavIcon(SECTION_LABEL), "dsh-router: settings nav icon");
+			ctx.effect(() => rewriteRouterModelHint(), "dsh-router: models provider hint copy");
 		}
 		//#endregion
 		exports.apply = apply;