dsh-prime-memory 0.26.25 → 0.26.26

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 更新日志（Changelog）
 
+## [0.26.26] — 2026-11-02
+
+> `0.26.25` 把 #22 的 token 护栏落地了，但把**最关键的那条验证当成了「已接上报」而非「已实测」**。本版用真 bge-m3 把它跑完，跑出了三个真实缺陷并逐个修掉。
+
+- **T1 从「上报机制」补成「真模型实证」**（新增 `scripts/verify-token-guard-realmodel.mjs` + `scripts/_t3-runner.mjs`，可选跑、不进 CI——需本机 runtime 与 bge-m3）。在真 bge-m3 上实测：**5000/4000/3800 中文字符（报告里全部 SIGTRAP 的那三档）截断后进模型的序列长度均为 2047 ≤ 预算 2048**；无护栏时实测 **5003**；截断前后向量不同（排除「只报了个数、实际没截」）。护栏留位从「假设」变成「事实」。
+- **修掉三个被真模型才抓得出的缺陷**（桩测试永远测不到）：
+  1. **`tokensMax` 恒为 -1，等于没上报**——原实现从输出张量取 `.shape`，而实测发现 transformers 的 Tensor **根本没有 `.shape`**（叫 `.dims`），且池化后输出是 `[1024]` 一维、里面**不存在 seq** 这个维度。现改为截断时按库自己的口径（`padding:true, truncation:true`）实测并上报，脚本还拿两个独立取法互验（实测 2047 == 2047）。
+  2. **「预算留 2 位」是侥幸不是保证**——真测：切 2046 个 id → decode → 重分词得 2045 token，+2 special = 2047，预算 2048 **只剩 1 位余量**；BPE/Unigram 的切片→解码→再编码不保证同序列，换一段文本就可能多漂而越界。现改为**由实测超出量逐轮递降收紧**（每轮重编码取真 seq，严格变短，至多 3 轮；量不出来就报 -1 而不是猜）。
+  3. **基准不能只看 encode 的 id 数**——5000 中文字符的 `encode` 长 5000，而 pipeline 实际会送进 5003；已改为取两者较大值作基准。
+- **消除一个我自己引入的测试污染**：本为取 `shrinkToBudget` 而让测试 `require('embedding-child.cjs')`，会把它的顶层 `process.on('uncaughtException')`（处理器会 `process.exit(1)`）与 `message` 监听装进 vitest 的 worker——**实测同 worker 的 `tests/memory-md-sync.test.ts` 因此无端转红（单跑绿、全量红）**。现恢复 child 的 fork-only 契约（只加一条文件头说明为何不可被 require），截断逻辑住在无副作用纯模块，对 child 仅做字面接线断言 + 产物 smoke，真行为由真模型脚本负责。
+- 另记一条**既有偶发失败**（非本次引入、本次未修）：`memory-md-sync.test.ts` 在全量并行下会间歇红（恢复活跃时 `.md.disable` 后缀未及时消失）。已用基线 worktree 对照：**不含本批改动的 `f3c1c07` 连跑 5 次也红过 1 次**，而本树连跑 3 次全绿，故不属本刀回归；具体原因是该用例的异步写盘与 `existsSync` 同步断言竞速，待另案。
+- smoke 的两条产物断言从「贴字面量」改为「断意图」（上一版贴了 `module.exports = { shrinkToBudget }` 与 `maxTokens - 2`，实现一改就误报）。
+- **测试**：`tests/embedding-token-guard.test.ts` 24 → **29 例**（新增逐轮递降、量不出来降级报 -1、`seqLenOf` 同时吃数组/张量两形等）；全量 **1933 例 / 191 文件**全绿（连跑 3 次），typecheck 0 error、lint 0 error（4 条既有 warning）、build/build:smoke/smoke/verify-catalog 均 0。公开配置面无破坏性变更（`maxInputTokens`/`maxInputChars` 语义与默认值未动）。
+
 ## [0.26.25] — 2026-11-02
 
 - **#22 根治：本地嵌入新增 token 维度护栏**。报告实测同一 5000 中文字符（≈3651 token）在纯 node 跑通（峰值 RSS **4.7GB**）、在宿主 Electron-node 被 **SIGTRAP 静默打死**（796ms、峰值仅 1.05GB），且崩溃瞬间 writable resident 只 3381K、机器 24GB 未吃满——**不是 OOM，是「单笔大块对齐分配被拒」**。本轮在本机（Windows/纯 node）实测内存峰值严格 **O(T²)**（750/1500/3003 token → ΔRSS +106/437/1635 MB，比 1:4.1:15.4 对应 T² 的 1:4:16），机制是 attention 张量 `[1,heads,T,T]`；外推 3651 token ≈4.6GB，与报告的 4.7GB 跨平台互证。**T 是唯一可控自变量，降 token 预算同时是崩溃护栏和内存护栏。**

package/dist/embedding-child.cjs

@@ -31,6 +31,13 @@ const { createRequire } = require('node:module');
 // 「无 IPC 就 exit」守卫,被测试 require 会把副作用带进来。截断逻辑本身必须零模型可验。
 const { shrinkToBudget } = require('./embedding-token-guard.cjs');
 
+/**
+ * 本文件是 **fork 专用入口**：顶层的 `process.on('message'/'disconnect'/'uncaughtException')`
+ * 与「无 IPC 就 exit」守卫都是执行体行为，**不得被测试 require**（给宿主进程装全局监听会
+ * 污染同进程的其他代码：实测过给 vitest worker 装 `uncaughtException` 后，同 worker 的
+ * `memory-md-sync` 用例无端转红）。需要零模型可验的逻辑一律放 `embedding-token-guard.cjs`。
+ */
+
 // 必须由 fork 启动(需要 IPC channel);裸 node 执行时静默退出,不报 SyntaxError、不永挂。
 if (typeof process.send !== 'function') {
   console.error('[embedding-child] 未经 fork 启动,无 IPC 通道,退出');
@@ -138,21 +145,15 @@ async function pump() {
       try {
         // 字符粗筛(IPC 体积) + token 精截(#22 崩溃/内存护栏);截断只在推理前,run() 同步不可中断
         const screened = job.text.slice(0, MAX_INPUT_CHARS);
-        const sent = shrinkToBudget(screened, MAX_INPUT_TOKENS, tokenizer);
-        const result = await extractor([sent], { pooling: POOLING, normalize: true });
+        const cut = shrinkToBudget(screened, MAX_INPUT_TOKENS, tokenizer);
+        const result = await extractor([cut.text], { pooling: POOLING, normalize: true });
         const data = result[0] && result[0].data;
         job.request.vectors[job.index] = data instanceof Float32Array ? data : new Float32Array(data);
-        // 实测优先于推断:特征抽取输出是 [1, seq, hidden],seq 就是**真正进了模型**的 token 数
-        // (含 special token、含 padding 与否取决于 pipeline)——比“截断后 id 长度”可靠,
-        // 后者在 decode 失败回退原文时会给出错的数。不可读时给 -1(=不可证,不是 0)。
-        let real = -1;
-        try {
-          const shape = result[0] && result[0].shape;
-          if (Array.isArray(shape) && shape.length >= 3) real = Number(shape[1]) || -1;
-        } catch {
-          /* shape 不可读不致命 */
-        }
-        if (real > job.request.tokensMax) job.request.tokensMax = real;
+        // tokensMax 用 cut.seq（按库口径实测将要进模型的 seq 长度,含 special token）。
+        // 曾试过从**输出**张量取 shape——真 bge-m3 实测证明两事:① Tensor 上根本没有 `.shape`
+        // (叫 `.dims`),② 池化后输出是 `[1024]` 一维,里面不存在 seq ——旧写法恒为 -1,等于没上报。
+        // 不可证时为 -1（不是 0）,不拿假数据当护栏证据。
+        if (cut.seq > job.request.tokensMax) job.request.tokensMax = cut.seq;
         job.request.remaining -= 1;
         settle(job.request);
       } catch (err) {

package/dist/embedding-token-guard.cjs

@@ -5,37 +5,91 @@
 'use strict';
 
 /**
- * 把一条文本裁到 token 预算内。返回**实际应送进 pipeline 的文本**。
+ * 把一条文本裁到 **实测** token 预算内。返回 `{ text, seq }`：
+ * - `text` = 应送进 pipeline 的文本；
+ * - `seq` = 按库自己的口径（`padding:true, truncation:true`，含 special token）**实测将要**进模型
+ *   的序列长度；不可测时为 -1（-1 是「不可证」，不是 0）。
  *
- * 为什么截断只能在子进程做:tokenizer 只在加载后的 pipeline 对象上可达,且 onnxruntime
- * 的 run() 是同步阻塞调用——单条内部不可中断,预检只能放推理前。又因为「子进程隔离」本身
- * 是 #11(libvips-42.dll 同进程撞名)的修复,不得为省一次 IPC 把 tokenize 挪回主线程。
+ * 为什么截断只能在子进程做：tokenizer 只在加载后的 pipeline 对象上可达，且 onnxruntime
+ * 的 run() 是同步阻塞调用——单条内部不可中断，预检只能放推理前。又因为「子进程隔离」本身
+ * 是 #11（libvips-42.dll 同进程撞名）的修复，不得为省一次 IPC 把 tokenize 挪回主线程。
  *
- * 预算留 special token 位([CLS]/[SEP] 实测 +2):截完要 decode 回文本再送 pipeline,
- * pipeline 内部会重新分词并补上 special token。
+ * 为什么不靠「budget - 2 留位」这种推断（真 bge-m3 实测已证伪）：
+ * 切 ids → decode 回文本 → pipeline 再分词，**不保证得到同一序列**——实测 2046 个 id
+ * 解码后重分词得 2045 token，加 2 个 special token = **2047**，预算 2048 只剩 1 位余量。
+ * 换一段文本就可能多漂 1 位以上而越界，所以下限靠**实测逐轮收紧**，不靠常数猜测。
  *
- * 不做「短文本跳过 tokenize」的优化:字符→token 比值按词表而变(CJK≈1、emoji/泰文>1.5、
- * 英文≈0.27),任何启发式下限都可能放走真超限的文本(实测反例:3800 中文字符 ×0.5=1900
- * 会跳过,而它实际约 2774 token,正落在 #22 致死档),而 tokenize 只占单次推理 ≈2.4%
- * (121-136ms vs 5427ms)。护栏上省 2.4% 不值一个未验证的跳跃。
+ * 不做「短文本跳过 tokenize」的优化：字符→token 比值按词表而变（CJK≈1、emoji/泰文>1.5、
+ * 英文≈0.27），任何启发式下限都可能放走真超限的文本（实测反例：3800 中文字符 ×0.5=1900
+ * 会跳过，而它实际约 2774 token，正落在 #22 致死档），而 tokenize 只占单次推理 ≈2.4%。
+ * 护栏上省 2.4% 不值一个未验证的跳跃。
  *
- * 任何一步不可用(transformers 未挂 tokenizer、不认选项、decode 回空串、抛错)一律
- * **退回粗筛原文保持旧行为**:护栏不得把能跑的链路搞坏。真实偏差由 tokensMax 实测上报兼证。
+ * 任何一步不可用（transformers 未挂 tokenizer、不认选项、decode 回空串、抛错）一律
+ * **退回粗筛原文保持旧行为**：护栏不得把能跑的链路搞坏。
+ *
+ * 成本：每轮多一个 encode（实测占单次推理 ≈2.4%）；至多重试 ROUNDS 轮。
  */
+const ROUNDS = 3;
+
+/** 按库口径量一次真实序列长度（pipeline 内部就是 `this.tokenizer(texts,{padding:true,truncation:true})`）。 */
+function seqLenOf(tok, text) {
+  const enc = tok(text, { padding: true, truncation: true });
+  const ids = enc && enc.input_ids;
+  if (!ids) return -1;
+  if (Array.isArray(ids)) return ids.length;
+  if (Array.isArray(ids.dims) && ids.dims.length >= 2) return ids.dims[1];
+  return -1;
+}
+
 function shrinkToBudget(raw, maxTokens, tok) {
-  if (!tok || !(maxTokens > 0)) return raw;
+  if (!tok || !(maxTokens > 0)) return { text: raw, seq: -1 };
   try {
     // 实测陷阱:return_tensor 缺省为 true,直取 .input_ids 得到的是 _Tensor(.length undefined
     // 且不抛错) -> 必须显式 return_tensor:false
     const ids = tok.encode(raw, { return_tensor: false });
-    if (!Array.isArray(ids) || ids.length <= maxTokens) return raw;
-    const kept = ids.slice(0, Math.max(1, maxTokens - 2));
-    // 实测陷阱:decode 缺省 skip_special_tokens=false,会把 [CLS]/[SEP] 编回文本再二次分词
-    const shrunk = tok.decode(kept, { skip_special_tokens: true });
-    return typeof shrunk === 'string' && shrunk.length > 0 ? shrunk : raw;
+    if (!Array.isArray(ids)) return { text: raw, seq: -1 };
+    // 基准长度用原文的库口径实测值（含 special token）。注意：**不能**只看 encode 的 id 数——
+    // 真 bge-m3 实测 5000 中文字符的 encode 长 5000,而 pipeline 实际会送进 5003(库自己补的
+    // special token 与词表边界),所以只有库口径才是「到底进了多少」的那个数。
+    let base = ids.length;
+    let direct = -1;
+    try {
+      direct = seqLenOf(tok, raw);
+    } catch {
+      direct = -1;
+    }
+    if (direct >= 0) base = Math.max(base, direct);
+    if (base <= maxTokens) return { text: raw, seq: direct >= 0 ? direct : -1 };
+
+    // 递降量由**上一轮实测的超出量**推出,而不是猜常数:切片长度是编码的单调函数,
+    // 所以每轮必比上一轮更短;再编码一次是为了拿到那个长度的真 seq,不做二次推断。
+    // 起点先留 2 位（special token 的下界,真测=+2）,之后按实测超出量继续收。
+    let text = raw;
+    let seq = -1;
+    let prevLen = ids.length;
+    let cut = Math.max(1, ids.length - (base - maxTokens) - 2);
+    for (let round = 0; round < ROUNDS; round++) {
+      if (cut >= prevLen) cut = Math.max(1, prevLen - 1); // 保证严格变短
+      const kept = ids.slice(0, cut);
+      // 实测陷阱：decode 缺省 skip_special_tokens=false，会把 [CLS]/[SEP] 编回文本再二次分词
+      const shrunk = tok.decode(kept, { skip_special_tokens: true });
+      if (typeof shrunk !== 'string' || shrunk.length === 0) break; // decode 不可用 -> 停止递降
+      text = shrunk;
+      const reIds = tok.encode(text, { return_tensor: false });
+      if (!Array.isArray(reIds) || reIds.length === 0) return { text: raw, seq: -1 };
+      seq = seqLenOf(tok, text);
+      if (seq < 0) return { text: raw, seq: -1 }; // 量不了 -> 降级（不送无法审计的截断文本）
+      if (seq <= maxTokens) return { text, seq };
+      prevLen = reIds.length;
+      // 递降量 = 实测超出量 + 2 位余量（经验值,但正确性不依赖它:依赖上文的严格变短）
+      cut = Math.max(1, prevLen - (seq - maxTokens) - 2);
+    }
+    // 逐轮后仍超（极端漂移）：宁报 -1（不可证）也不报一个超限的数当安全证据。
+    if (seq > maxTokens) return { text, seq: -1 };
+    return { text, seq };
   } catch {
-    return raw; // 降级:不截断,保持旧行为
+    return { text: raw, seq: -1 }; // 降级:不截断,保持旧行为
   }
 }
 
-module.exports = { shrinkToBudget };
+module.exports = { shrinkToBudget, seqLenOf };

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-prime-memory",
   "name": "dsh-prime-memory",
-  "version": "0.26.25",
+  "version": "0.26.26",
   "description": {
     "en": "Layered distilled memory plugin (L0 capture → L1 atomic memory → L2 scenes → L3 persona) with automatic recall injection before each model step.",
     "zh": "L0~L3 分层蒸馏记忆插件:自动捕获对话、抽取原子记忆、整合场景块、蒸馏核心画像,并在模型步骤前自动召回注入。"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-prime-memory",
-  "version": "0.26.25",
+  "version": "0.26.26",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",