dsh-prime-memory 0.26.23 → 0.26.25

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 更新日志（Changelog）
 
+## [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 预算同时是崩溃护栏和内存护栏。**
+- **护栏早就在子进程，错的是单位**（实读校正了一处长期误解）：`resources/embedding-child.cjs` 一直在子进程内截断，但按**字符**截。bge-m3/embeddinggemma 是 Unigram/BPE，中文≈1 字/token 而 emoji/泰文可 >1.5，所以 5000 字符既可只 750 token 也可近 8192——**字符帽与崩溃条件不同源、不可换算**；库自带 `truncation:true` 只截到 `model_max_length=8192`，本身就在致死线 ≈2700 之上，**等于没兜**。另证：`src/util/context-occupancy.ts` 的 `CHARS_PER_TOKEN = 4`（官方同值）对中文低估 4 倍，很可能就是「5000 字符看着安全」长期未被怀疑的成因，**已明令禁止用于嵌入预算**。
+- **新增 `embedding.maxInputTokens`（默认 `0`=自动）与唯一真值来源 `HARD_CAP_TOKENS = 2048`**（`src/store/model-catalog.ts` 的 `deriveTokenBudget`）。生效预算 `= min(模型 contextTokens, HARD_CAP_TOKENS)`：bge-small-zh(512) 不受影响、bge-m3(8192) 被压到 2048；用户显式超限只 **clamp + warn**，不抛错。`contextTokens` 原注释「仅 UI 展示」已升格为推导真值并同步改注释（不改就是下一轮声明漂移）。
+- **配置面只加键不改键**：`maxInputChars` 的键名/边界（`min(100).max(100_000)`）/默认值 5000 **完全不动**。实测 schemastery **未知键静默透传不报错**，改名或换单位会让已部署 YAML 的值**无声失效并回落 `?:5000`**（新主进程 + 旧 `dist/embedding-child.cjs` 错配时同理）；而收窄边界会让已部署 YAML **解析直接抛错**，故障半径是整个配置树。字符帽继续只管远程档与 IPC 粗筛、token 帽只管本地推理——**各自单一实施点，不做同层双旋钮**。
+- **截断执行留在子进程**（新增 `resources/embedding-token-guard.cjs`，无副作用纯模块）：tokenizer 只在加载后的 pipeline 对象上可达，且 ORT `run()` 同步阻塞、单条内部不可中断，预检只能放推理前；而子进程隔离本身是 #11（同进程 `libvips-42.dll` 撞名）的修复，不得为省一次 IPC 拆开。tokenize 成本实测占单次推理 ≈2.4%（121-136ms vs 5427ms）。旧逃生门 `embedding-worker.cjs` **有意不同步**并在文件头写明理由（硬同步 = 维护两份口径）。
+- **实现期三个实测陷阱**（不避开就是静默错位）：`encode()` 缺省返回 `_Tensor`（`.length === undefined` 且**不报错**，须显式 `return_tensor:false`）；`decode()` 缺省 `skip_special_tokens=false`，slice→decode→re-encode 会 **+2 token**；`tokenizer.model_max_length` **只读**（实测 `has only a getter`），不能当旋钮。**主动删掉一个自己写出的缺陷**：初版带了「`raw.length * 0.5 < 预算` 即跳过 tokenize」的省开销优化，但 3800 中文字符×0.5=1900 会跳过、其实际≈2774 token 正落在致死档，属未验证跳跃 → 改为无条件实测。
+- **可见性修复（#22 归因链路的前置）**：`child.on('exit',(code)=>…)` 只接 code、**丢弃 signalCode**，使 SIGTRAP / OOM-kill / 自然退出在日志里同为 `code=null`（本轮就是靠 macOS 4 份崩溃报告对毫秒时间戳才归因上的）；现由 `describeExit()` 同时输出 `code` 与 `signal`，一处修三处可见（crashed 串 / warn / `getLoadError()`），worker 旧通道同型修正。子进程另上报本批**实测**进模型的最大 token 数（`tokensMax` 取输出张量 `[1,seq,hidden]` 的 seq，不用推断值）；fork 时一条 info 记录 `execPath`/`process.release.name`/pid/模型/生效预算——之前仓内没有任何地方记录 execPath 差异，而那正是「同代码纯 node 能跑、Electron 崩」的唯一区分量。
+- **补齐停摆不再静默**：`reindex` 首行 `if (!vectorReady()) return {0,0,0}` 与「本轮无事可做」不可区分，且 `index.ts` 的 `failed>0` / `missingAfter==0` 两分支都不进 → **一行日志都不打**（崩后熔断也不在环上，环上是 `isReady()` 短路）。现补齐链分流出「缺失数统计失败」与「本轮未写入且仍差 N 条」两条 warn；reindex 批次的 `catch {}` 补上日志并**带 record id**（否则无从定位是哪条长文本致崩）。**已收回一条调研结论**：`markEmbeddingSynced` 的「缺失全落 skip 集」并非假成功——`l1.ts` 注释明确写明 skipped 有意不阻塞同步标记（否则永不收敛、周期性全量重嵌死循环），照误报去改会引入新缺陷。
+- **本版本不含崩溃自愈**：`startReindex` 前置 `vectorsReady()` 门使自愈在崩溃态根本进不去，而 respawn 的真实半径含六处长期引用重绑、状态机新分支、三腿 thundering herd 与 60s 冷却叠乘；且本刀目标是「不让毒形成」而非「毒已形成怎么办」。也不自动全库重建（该腿无超时无熔断、成本不可量化，且新帽只缩不扩、语义退化有界）；历史向量口径如需严格一致可手动触发重建。
+- **测试**：新增 `tests/embedding-token-guard.test.ts` 24 例（预算推导 4 组 + 精截与降级路径 + 两个实测陷阱 + 配置面回归 + 退出归因）。**红绿对拍已逐条验证有效性**：断开接线→1 红、不留 special 位→2 红、塞回字符启发式→4 红、预算不写进 cfg→1 红。过程中查出并修掉自己的两个测试缺陷：直接调纯函数**测不到调用点**（接线整行删掉时 19 例全绿）→ 补接线/产物哨兵；对拍脚本把 vitest「收集期报错」误读成「无失败」→ 判据改为区分 `Test Files failed`/`Tests no tests`。**跨平台限制如实声明**：`malloc_zone_memalign` 是 macOS 分配器符号，Windows 既不能复现 SIGTRAP 也发不出该信号（`EINVAL`），故本仓可证的是「进模型的 token 数受预算约束」与「被信号杀可归因」，崩溃是否消失需报告人在 macOS 回验。全量 **1923 例 / 191 文件**，typecheck/lint(0 error)/build/build:smoke/smoke 全 0；smoke 新增 3 条产物断言钉住 `dist/embedding-token-guard.cjs` 存在、child 相对 require 可达、guard 导出正确（漏拷是子进程起不来的硬故障）。
+
+## [0.26.24] — 2026-11-02
+
+- **修掉 `0.26.23` 自己引入的回归：读面可能被永久堵死**。上一版规定「对端已升版但 `drsReadFacade()` 返回 undefined 时抛可重试错、不回退自开库」，用意是避免把自开库结果永久缓存。但**未就绪是无法与「本进程根本不会有人 activate collector」区分的**，两类真实场景落进后者：① 宿主外跑本仓读面做校验的脚本（新进程 import collector，`apply()` 从未运行，门面永远 undefined）；② collector 装了但未进当前 profile 的装载清单。它们会每次读都报错，比 `0.26.21` 的直接自开库更糟。
+- **改法：有界重试后再回退**（`src/clients/drsc-inproc.ts`）。预算 `FACADE_RETRY_BUDGET = 3`：前 3 次读抛可重试错且不缓存（给宿主内 collector 的 `setImmediate` 初始化留出窗口，保住「优先用门面」）；第 4 次仍拿不到门面即认定本进程等不到，回退自开只读库。两条路径都读的是同一个 WAL 库、句柄只读，不存在读到错数据的风险，差别只是是否多占一份常驻 `summaries`。门面一旦就绪，计数器归零。
+- **测试**：`tests/drsc-inproc.test.ts` 相应改为断言完整状态机——预算内逐次抛错（错误文本含 `1/3`、`2/3`、`3/3`）且期间**绝不**调用 `openProjectionStore`；第 4 次回退成功打开自有句柄并返回正常结果；`resetCollectorReadState()` 后门面就绪能拿回门面。全量 **1904 例 / 190 文件**，typecheck/lint/build/build:smoke/smoke 全 0。
+- **验证口径提示**：宿主外脚本按设计走的是**回退路径**（会开自己的只读句柄），因此「脚本里出现自开库」不是缺陷；宿主内的判据是日志无「背景窗拉取失败」且蒸馏/`conversation_search` 出真数据。
+
 ## [0.26.23] — 2026-11-02
 
 - **方案 B：DRSC 读面改走 collector 的正式门面（`drsReadFacade`）**。`0.26.21` 的进程内直调虽然绕开了宿主鉴权，但代价是**耦合 collector 的五个内部导出名**（`openProjectionStore`/`createQueryContext`/`search`/`sessionDetail`/`listSessions`），并且**自己另开一份投影库**——多占一份常驻 `summaries` 内存与一个读事务。现在 collector `0.2.5` 导出 `drsReadFacade()`，返回绑它**自己活 QueryContext** 的只读对象；本仓优先用这个门面，只认一个稳定符号，也不再开第二份库。

package/README.de.md

@@ -323,6 +323,7 @@ Drei Embedding-Quellen: **aus** (Standard, reine BM25-Schlüsselwortsuche), **re
 | `embedding.model`            | leer                    | Embedding-Modellname |
 | `embedding.dimensions`       | `0`                     | Vektordimension (bei Aktivierung Pflicht, muss zur Modellausgabe passen) |
 | `embedding.maxInputChars`    | `5000`                  | Maximale Zeichen je Text (bei Überlänge abgeschnitten) |
+| `embedding.maxInputTokens`   | `0`                     | **Token**-Budget pro Text für lokale Einbettung: `0` (Standard) = min(Modellfenster, harte Grenze 2048); >0 = explizit, bei Überschreitung geklemmt inkl. warn. Andere Rolle als die Zeile oben – das Zeichenlimit betrifft nur Remote-Modus & IPC-Größe, die lokale Absturz-/Speichergrenze muss in Tokens stehen (#22) |
 | `embedding.timeoutMs`        | `10000`                 | Timeout eines einzelnen Embedding-Aufrufs (ms) |
 | `embedding.allowLocalModels` | `true`                  | Lokale Embedding-Stufe erlauben (Deployment-Obergrenze: ausgeschaltet kann die Einstellungsseite keine Modelle laden und nicht auf Lokal schalten) |
 | `embedding.mirror`           | `https://hf-mirror.com` | Wurzeladresse des Download-Spiegels für lokale Modelle (zurücksetzbar auf das offizielle `https://huggingface.co`) |

package/README.en.md

@@ -330,6 +330,7 @@ the bundle layer appends and causes `duplicate loader entry id` startup failure)
 | `embedding.model` | empty | embedding model name |
 | `embedding.dimensions` | `0` | Vector dimensions (required when enabled; must match model output) |
 | `embedding.maxInputChars` | `5000` | Max characters per text (overlong inputs truncated) |
+| `embedding.maxInputTokens` | `0` | Per-text **token** budget for local embedding: `0` (default) = min(model window, hard cap 2048); >0 = explicit, clamped with a warn above the cap. Not the same guard as the row above — the character cap only bounds the remote tier and IPC size, while local crash/memory limits must be in tokens (#22) |
 | `embedding.timeoutMs` | `10000` | Per-call embedding timeout (ms) |
 | `embedding.allowLocalModels` | `true` | Allow the local embedding tier (deployment ceiling; when off, no model downloads and no local tier in settings) |
 | `embedding.mirror` | `https://hf-mirror.com` | Download mirror root for local models (can be changed back to `https://huggingface.co`) |

package/README.es.md

@@ -324,6 +324,7 @@ Los ajustes que pisan los valores por defecto se escriben en el `cordis.patch.ym
 | `embedding.model`            | vacío                   | Nombre del modelo de embeddings |
 | `embedding.dimensions`       | `0`                     | Dimensión de los vectores (obligatoria si está activada, debe coincidir con la salida del modelo) |
 | `embedding.maxInputChars`    | `5000`                  | Número máximo de caracteres por texto (recorte si se supera) |
+| `embedding.maxInputTokens`   | `0`                     | Presupuesto de **tokens** por texto para la incrustación local: `0` (pred.) = min(ventana del modelo, límite 2048); >0 = explícito, recortado con warn si excede. No es el mismo límite que la fila de arriba: el de caracteres solo cubre el modo remoto y el tamaño de IPC, y la protección local contra fallos/memoria debe ir en tokens (#22) |
 | `embedding.timeoutMs`        | `10000`                 | Tiempo máximo de una llamada de embeddings (ms) |
 | `embedding.allowLocalModels` | `true`                  | Permite el modo de embeddings local (techo de despliegue: desactivado, la página de ajustes no puede descargar modelos ni pasar a local) |
 | `embedding.mirror`           | `https://hf-mirror.com` | Raíz del espejo de descarga de modelos locales (se puede devolver al oficial `https://huggingface.co`) |

package/README.fr.md

@@ -322,6 +322,7 @@ Les réglages par-dessus les valeurs par défaut s'écrivent dans le `cordis.pat
 | `embedding.model`            | vide                    | Nom du modèle d'embedding |
 | `embedding.dimensions`       | `0`                     | Dimension des vecteurs (obligatoire si activé, doit correspondre à la sortie du modèle) |
 | `embedding.maxInputChars`    | `5000`                  | Nombre maximal de caractères par texte (troncature au-delà) |
+| `embedding.maxInputTokens`   | `0`                     | Budget de **jetons** par texte pour l'intégration locale : `0` (défaut) = min(fenêtre du modèle, plafond 2048) ; >0 = explicite, réduit avec un warn s'il dépasse. Ce n'est pas la même limite que la ligne au-dessus : celle en caractères ne borne que le mode distant et la taille IPC, la protection locale doit être en jetons (#22) |
 | `embedding.timeoutMs`        | `10000`                 | Délai maximal d'un appel d'embedding (ms) |
 | `embedding.allowLocalModels` | `true`                  | Autorise le mode embedding local (plafond de déploiement : désactivé, la page de paramètres ne peut plus télécharger de modèles ni passer en local) |
 | `embedding.mirror`           | `https://hf-mirror.com` | Racine du miroir de téléchargement des modèles locaux (ramenérable à l'officiel `https://huggingface.co`) |

package/README.it.md

@@ -324,6 +324,7 @@ Le impostazioni che scavalcano i predefiniti si scrivono nel `cordis.patch.yml`
 | `embedding.model`            | vuoto                   | Nome del modello d'embedding |
 | `embedding.dimensions`       | `0`                     | Dimensione dei vettori (obbligatoria se attiva, deve corrispondere all'output del modello) |
 | `embedding.maxInputChars`    | `5000`                  | Numero massimo di caratteri per testo (troncamento oltre) |
+| `embedding.maxInputTokens`   | `0`                     | Budget di **token** per testo per l'embedding locale: `0` (default) = min(finestra del modello, limite 2048); >0 = esplicito, ridotto con un warn se oltre il limite. Non è lo stesso limite della riga sopra: quello in caratteri copre solo modalità remota e dimensione IPC, la protezione locale contro cadute/memoria deve essere in token (#22) |
 | `embedding.timeoutMs`        | `10000`                 | Timeout di una singola chiamata d'embedding (ms) |
 | `embedding.allowLocalModels` | `true`                  | Consente la modalità d'embedding locale (tetto di distribuzione: disattivata, la pagina impostazioni non può scaricare modelli né passare in locale) |
 | `embedding.mirror`           | `https://hf-mirror.com` | Radice del mirror di scaricamento dei modelli locali (riportabile all'ufficiale `https://huggingface.co`) |

package/README.ja.md

@@ -274,6 +274,7 @@ node bench/harness/retrieval-metrics.mjs <runDir> --flood 200,600
 | `embedding.model` | 空 | 埋め込みモデル名 |
 | `embedding.dimensions` | `0` | ベクトル次元（有効時必須） |
 | `embedding.maxInputChars` | `5000` | 単テキスト最大文字数（超長は切り捨て） |
+| `embedding.maxInputTokens` | `0` | ローカル埋め込みの 1 件あたり **トークン** 予算：`0`（既定）= モデル窓と上限 2048 の小さい方、>0 = 明示値（超過は clamp + warn）。上の行とは役割が異なる——文字上限はリモートモードと IPC サイズのみを制限し、ローカルのクラッシュ/メモリ防護はトークン単位が必須（#22） |
 | `embedding.timeoutMs` | `10000` | 単回埋め込み呼び出しタイムアウト（ms） |
 | `embedding.allowLocalModels` | `true` | ローカル埋め込み档を許可（デプロイ上限） |
 | `embedding.mirror` | `https://hf-mirror.com` | ローカルモデルダウンロードミラー根 |

package/README.ko.md

@@ -274,6 +274,7 @@ node bench/harness/retrieval-metrics.mjs <runDir> --flood 200,600
 | `embedding.model` | 빈값 | 임베딩 모델명 |
 | `embedding.dimensions` | `0` | 벡터 차원（활성 시 필수） |
 | `embedding.maxInputChars` | `5000` | 단텍스트 최대 문자 수（초장 잘림） |
+| `embedding.maxInputTokens` | `0` | 로컬 임베딩 1건당 **토큰** 예산: `0`(기본) = 모델 창과 상한 2048 중 작은 값, >0 = 명시값(초과 시 clamp + warn). 위 행과 역할이 다름 — 문자 상한은 원격 모드와 IPC 크기만 제한하고, 로컬 충돌/메모리 방지는 토큰 단위가 필수(#22) |
 | `embedding.timeoutMs` | `10000` | 단회 임베딩 호출 타임아웃（ms） |
 | `embedding.allowLocalModels` | `true` | 로컬 임베딩档 허용（배포 상한） |
 | `embedding.mirror` | `https://hf-mirror.com` | 로컬 모델 다운로드 미러 루트 |

package/README.md

@@ -342,6 +342,7 @@ ONNX 量化 **CPU 推理**——无需 API Key，数据不出本机）。本地
 | `embedding.model`            | 空                       | embedding 模型名                                                                                                                                                                                                                                                                                                                    |
 | `embedding.dimensions`       | `0`                     | 向量维度（启用时必填，须与模型输出一致）                                                                                                                                                                                                                                                                                                             |
 | `embedding.maxInputChars`    | `5000`                  | 单条文本最大字符数（超长截断）                                                                                                                                                                                                                                                                                                                  |
+| `embedding.maxInputTokens`   | `0`                     | 本地嵌入的单条 **token** 预算：`0`（默认）= 按模型窗口与硬上限 2048 自动取小；>0 = 显式预算，超上限会被 clamp 并记 warn。与上一行不是同类护栏——字符帽只管远程档与 IPC 体积，本地推理的崩溃/内存护栏必须按 token（#22） |
 | `embedding.timeoutMs`        | `10000`                 | 单次 embedding 调用超时（ms）                                                                                                                                                                                                                                                                                                            |
 | `embedding.allowLocalModels` | `true`                  | 允许本地嵌入档（部署上限：关闭后设置页不能下载模型、不能切本地档）                                                                                                                                                                                                                                                                                                |
 | `embedding.mirror`           | `https://hf-mirror.com` | 本地模型下载镜像根地址（可改回官方 `https://huggingface.co`）                                                                                                                                                                                                                                                                                      |

package/README.ru.md

@@ -324,6 +324,7 @@ node bench/harness/retrieval-metrics.mjs <runDir> --flood 200,600
 | `embedding.model`            | пусто                   | Имя модели эмбеддингов |
 | `embedding.dimensions`       | `0`                     | Размерность векторов (при включении обязательна, должна совпадать с выходом модели) |
 | `embedding.maxInputChars`    | `5000`                  | Максимум символов на один текст (сверх — усечение) |
+| `embedding.maxInputTokens`   | `0`                     | Бюджет **токенов** на один текст для локальных эмбеддингов: `0` (умолч.) = min(окно модели, жёсткий лимит 2048); >0 = явное значение, при превыщении усекается с warn. Это не тот же лимит, что строкой выше: символьный ограничивает только удалённый режим и размер IPC, а локальная защита от падений/памяти должна считаться в токенах (#22) |
 | `embedding.timeoutMs`        | `10000`                 | Таймаут одного вызова эмбеддинга (мс) |
 | `embedding.allowLocalModels` | `true`                  | Разрешить локальный режим эмбеддингов (потолок развёртывания: выключено — страница настроек не может скачивать модели и переключаться в локальный) |
 | `embedding.mirror`           | `https://hf-mirror.com` | Корень зеркала загрузки локальных моделей (можно вернуть на официальный `https://huggingface.co`) |

package/dist/clients/drsc-inproc.js

@@ -22,6 +22,14 @@
 const COLLECTOR_PACKAGE = 'dsh-reference-session-collector';
 const defaultLoader = async () => (await import(/* @vite-ignore */ COLLECTOR_PACKAGE));
 let modulePromise;
+/**
+ * 对端已升版但库未就绪时的重试预算。不能无限重试：宿主**外**的脚本、以及
+ * 「collector 装了但未装载」的部署里，drsReadFacade() 永远返回 undefined，
+ * 死等会把读面永久堵死（比回退更糟）。也不能一上来就回退：那会把自开库
+ * 结果永久缓存，把“优先用门面”变成只在首轮赌运气。
+ */
+const FACADE_RETRY_BUDGET = 3;
+let facadeMisses = 0;
 /**
  * 兼容路径（旧 collector）的只读句柄（`openProjectionStore` 的返回值）。常驻 summaries
  * 是内存 Map，每请求重开等于重扫全表，故只开一次；undefined 是合法的未开哨兵。
@@ -31,6 +39,7 @@ let storeHandle;
 export function resetCollectorReadState() {
     modulePromise = undefined;
     storeHandle = undefined;
+    facadeMisses = 0;
 }
 /** 把门面对象适配成本模块统一的「模块形」，以便与兼容路径共用同一套参数映射。
  * 前三个成员在门面路径上永不会被调用：moduleOf 命中门面后直接返回，不走进兼容分支。
@@ -54,14 +63,18 @@ async function moduleOf(load) {
         const mod = (await load());
         if (typeof mod.drsReadFacade === 'function') {
             const facade = mod.drsReadFacade();
-            // 对端是新版本但库未就绪（collector 的重活推迟在 setImmediate 臂）：本轮**不**回退
-            // 自开库，而是抛可重试错——否则会把自开库结果永久缓存，把“优先用门面”变成
-            // 只在首轮赌运气。抛错走既有降级链（背景窗当轮空窗、工具面显式报错），
-            // 且不缓存 rejection，下一次读会重取门面。
-            if (facade === undefined) {
-                throw new Error('collector 投影库尚未就绪（稍后自动重试）');
+            // 对端是新版本但库未就绪（collector 的重活推迟在 setImmediate 臂）：先给它几次
+            // 重试机会（抛可重试错、不缓存 rejection，下一次读重取门面）；超过预算就认定
+            // 本进程里不会有人 activate 它（宿主外的脚本、或 collector 装了但未装载），
+            // 回退自开只读库。两条路都不会读错数据：库是同一个 WAL 文件，自开句柄只读。
+            facadeMisses += 1;
+            if (facade !== undefined) {
+                facadeMisses = 0;
+                return fromFacade(facade);
+            }
+            if (facadeMisses <= FACADE_RETRY_BUDGET) {
+                throw new Error(`collector 投影库尚未就绪（第 ${facadeMisses}/${FACADE_RETRY_BUDGET} 次重试）`);
             }
-            return fromFacade(facade);
         }
         return legacyStoreModule(mod);
     })().catch((err) => {

package/dist/config.d.ts

@@ -360,6 +360,15 @@ export interface MemoryConfig {
         dimensions: number;
         /** 单条文本最大字符数(超长截断)。 */
         maxInputChars: number;
+        /**
+         * 本地嵌入的单条 **token** 预算(0 = 按模型窗口与硬上限自动推导)。
+         *
+         * 与 `maxInputChars` 不是同类护栏:字符帽只管 IPC 体积与远程档,bge-m3/embeddinggemma
+         * 是 Unigram/BPE、中文≈1 字/token 而 emoji/泰文>1.5,所以**字符帽约不到安全线**
+         * (issue #22:5000 字符≈3651 token,已在宿主分配器致死线 ≈2700 之上)。本键只管本地推理。
+         * 超上限会被 clamp 并留 warn(不抛错,见 model-catalog.ts `deriveTokenBudget`)。
+         */
+        maxInputTokens: number;
         /** 单次调用超时(ms)。 */
         timeoutMs: number;
         /** 允许本地嵌入模型档(部署上限:公司环境可禁下载与本地推理)。 */

package/dist/config.js

@@ -341,6 +341,10 @@ export const memorySchema = Schema.object({
         // 0 = 纯 FTS 模式(合法值,勿设 min>0)
         dimensions: Schema.number().min(0).max(8192).default(0),
         maxInputChars: Schema.number().min(100).max(100_000).default(5000),
+        // 12-13 个已有 fixture 用 maxInputChars;本键**只增不改**(schemastery 实测未知键静默透传,
+        // 改名会让已部署 YAML 无声失效),且**不收窄边界**(越界值抛错的故障半径是整个配置树)。
+        // 上限交由 deriveTokenBudget 按模型窗口 clamp,这里给宽松外壁仅为防溢出输入。
+        maxInputTokens: Schema.number().min(0).max(100_000).default(0),
         timeoutMs: Schema.number().min(1000).max(300_000).default(10_000),
         allowLocalModels: Schema.boolean().default(true),
         mirror: Schema.string().default('https://hf-mirror.com'),

package/dist/embedding-child.cjs

@@ -1,192 +1,223 @@
-/**
- * 本地嵌入子进程(fix #11):transformers.js 的模型加载与推理在 fork 出的独立
- * 子进程执行,主线程只投递文本、收回向量。取代 worker_threads 的原因:
- * 插件 runtime 的 sharp/libvips 与宿主 Electron 的 sharp/libvips 在同一进程内
- * 加载会撞 libvips-42.dll 名字(OS LoadLibrary 层冲突,同名不同路径行为未定义)
- * ——worker_thread 与主线程同进程,撞名前提仍在;子进程自带独立 DLL 表,物理隔离。
- *
- * 推理队列语义与 embedding-worker.cjs 完全一致(单线程串行、priority 插队、
- * 条间 setImmediate 让路),只有 IPC 传输层不同:
- *
- * 协议(与 src/store/local-embedding.ts 的 RealChildChannel 配对;自增 id):
- * - 启动配置:env DSH_EMBED_CFG(JSON 字符串:{runtimeDir,modelDir,pooling,dtype,
- *   maxInputChars}——fork 的 env 只收标量,嵌套对象经序列化传递);
- * - 入向:{id,type:'ping'} | {id,type:'warmup'} | {id,type:'embed',texts,priority}
- * - 出向:{id,ok:true,type:'pong'|'ready'|'embedded',vectors?}(vectors 为
- *   number[][],fork IPC 默认 JSON 序列化不支持 TypedArray,主线程侧重建
- *   Float32Array;512d×32 条 ≈64KB,序列化 <5ms,瓶颈在推理不在传输)
- *   | {id,ok:false,stage:'load'|'infer',error} | {type:'fatal',error}
- *
- * 信任边界(沿 AGENTS.md 审查记录):runtime/ 目录在数据目录信任边界内,
- * 本进程按其 package.json createRequire 加载 transformers——对数据目录有写
- * 权限的进程理论上可植入恶意模块;模型文件逐文件 sha256 锁定,运行时代码
- * 无同级防护,完整修复需安装指纹设计,暂以文档化假设为准。
- */
-'use strict';
-
-const path = require('node:path');
-const { createRequire } = require('node:module');
-
-// 必须由 fork 启动(需要 IPC channel);裸 node 执行时静默退出,不报 SyntaxError、不永挂。
-if (typeof process.send !== 'function') {
-  console.error('[embedding-child] 未经 fork 启动,无 IPC 通道,退出');
-  process.exit(0);
-}
-
-/** 错误消息归一化(Error 取 message,其余 String 化)。 */
-function errMsg(err) {
-  return err && err.message ? err.message : String(err);
-}
-
-const cfg = JSON.parse(process.env.DSH_EMBED_CFG || '{}');
-const RUNTIME_DIR = typeof cfg.runtimeDir === 'string' ? cfg.runtimeDir : '';
-const MODEL_DIR = typeof cfg.modelDir === 'string' ? cfg.modelDir : '';
-const POOLING = cfg.pooling === 'cls' ? 'cls' : 'mean';
-const DTYPE = typeof cfg.dtype === 'string' ? cfg.dtype : 'q8';
-const MAX_INPUT_CHARS = cfg.maxInputChars > 0 ? cfg.maxInputChars : 5000;
-
-let extractor = null; // pipeline('feature-extraction', …)
-let loadState = 'idle'; // idle | loading | ready | failed
-let loadPromise = null;
-let loadError = null;
-
-// ── 模型懒加载(首请求触发;失败后经 warmup 可重试,embed 请求失败快返回) ──
-function ensureLoaded() {
-  if (loadState === 'ready') return Promise.resolve();
-  if (loadState === 'loading' && loadPromise) return loadPromise;
-  loadState = 'loading';
-  loadError = null;
-  loadPromise = (async () => {
-    try {
-      if (!RUNTIME_DIR || !MODEL_DIR) throw new Error('DSH_EMBED_CFG 缺少 runtimeDir/modelDir');
-      const req = createRequire(path.join(RUNTIME_DIR, 'package.json'));
-      const mod = req('@huggingface/transformers');
-      if (mod.env) {
-        mod.env.allowRemoteModels = false;
-        if (mod.env.allowLocalModels !== undefined) mod.env.allowLocalModels = true;
-      }
-      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, { dtype: DTYPE });
-      loadState = 'ready';
-    } catch (err) {
-      loadState = 'failed';
-      loadError = errMsg(err);
-      loadPromise = null; // 失败后下一次 warmup 重新走加载
-      throw err;
-    }
-  })();
-  return loadPromise;
-}
-
-// ── 推理队列(逐条 job;priority 插队;条间让路) ──
-const queue = []; // [{ request, index, text }]
-let pumping = false;
-
-function postReply(msg) {
-  // 通道已断(父进程退出/正在终止)时 send 抛错——静默即可,父进程侧有 exit 兜底
-  try {
-    process.send(msg);
-  } catch {
-    /* IPC 已关闭,回复无处可去 */
-  }
-}
-
-/** 请求全部条目完成 → 回执(Float32Array → number[] 序列化,IPC JSON 通道不支持 TypedArray)。 */
-function settle(request) {
-  if (request.failed || request.remaining !== 0) return;
-  postReply({
-    id: request.id,
-    ok: true,
-    type: 'embedded',
-    vectors: request.vectors.map((v) => Array.from(v)),
-  });
-}
-
-/** 首个失败即回执错误,并移除该请求尚未开跑的条目(正在跑的至多 1 条,算完即弃)。 */
-function failRequest(request, error, stage) {
-  if (request.failed) return;
-  request.failed = true;
-  for (let i = queue.length - 1; i >= 0; i--) {
-    if (queue[i].request === request) queue.splice(i, 1);
-  }
-  postReply({ id: request.id, ok: false, stage: stage, error: errMsg(error) });
-}
-
-async function pump() {
-  if (pumping) return;
-  pumping = true;
-  try {
-    while (queue.length > 0) {
-      const job = queue.shift();
-      if (job.request.failed) continue;
-      try {
-        const result = await extractor([job.text.slice(0, MAX_INPUT_CHARS)], { pooling: POOLING, normalize: true });
-        const data = result[0] && result[0].data;
-        job.request.vectors[job.index] = data instanceof Float32Array ? data : new Float32Array(data);
-        job.request.remaining -= 1;
-        settle(job.request);
-      } catch (err) {
-        failRequest(job.request, err, 'infer');
-      }
-      // 条间让路:交还本进程事件循环,新消息(含 priority 插队)可在批间被处理
-      await new Promise((resolve) => setImmediate(resolve));
-    }
-  } finally {
-    pumping = false;
-  }
-}
-
-function handleEmbed(msg) {
-  const texts = Array.isArray(msg.texts) ? msg.texts : [];
-  if (texts.length === 0) {
-    postReply({ id: msg.id, ok: true, type: 'embedded', vectors: [] });
-    return;
-  }
-  const request = { id: msg.id, vectors: new Array(texts.length), remaining: texts.length, failed: false };
-  // 单条请求(召回 query)插队到队首;批次追加到队尾(批内条目间仍会被后来的插队)
-  const priority = msg.priority === true && texts.length === 1;
-  for (let i = 0; i < texts.length; i++) {
-    const job = { request: request, index: i, text: String(texts[i] == null ? '' : texts[i]) };
-    if (priority) queue.unshift(job);
-    else queue.push(job);
-  }
-  void pump();
-}
-
-process.on('message', (msg) => {
-  if (!msg || typeof msg.id !== 'number' || typeof msg.type !== 'string') return;
-  if (msg.type === 'ping') {
-    postReply({ id: msg.id, ok: true, type: 'pong' });
-    return;
-  }
-  if (msg.type === 'warmup') {
-    ensureLoaded().then(
-      () => postReply({ id: msg.id, ok: true, type: 'ready' }),
-      () => postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' }),
-    );
-    return;
-  }
-  if (msg.type === 'embed') {
-    void (async () => {
-      try {
-        await ensureLoaded();
-      } catch {
-        postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' });
-        return;
-      }
-      handleEmbed(msg);
-    })();
-    return;
-  }
-});
-
-// 父进程disconnect(通道被主动关闭,如宿主优雅退出/RealChildChannel 前置断开):
-// 模型与 onnxruntime 都只服务于这条通道,留着就是孤儿常驻——直接退出。
-// taskkill /T /F 兜底覆盖"父进程被硬杀、无 disconnect"的路径。
-process.on('disconnect', () => process.exit(0));
-
-// 未捕获异常:尽力通知父进程后强制退出(父进程的 exit 处理会拒绝全部 pending
-// 并转入 failed 态)。不保持半死状态——半死的子进程只会让调用方挂到超时。
-process.on('uncaughtException', (err) => {
-  postReply({ type: 'fatal', error: errMsg(err) });
-  setTimeout(() => process.exit(1), 50);
-});
+/**
+ * 本地嵌入子进程(fix #11):transformers.js 的模型加载与推理在 fork 出的独立
+ * 子进程执行,主线程只投递文本、收回向量。取代 worker_threads 的原因:
+ * 插件 runtime 的 sharp/libvips 与宿主 Electron 的 sharp/libvips 在同一进程内
+ * 加载会撞 libvips-42.dll 名字(OS LoadLibrary 层冲突,同名不同路径行为未定义)
+ * ——worker_thread 与主线程同进程,撞名前提仍在;子进程自带独立 DLL 表,物理隔离。
+ *
+ * 推理队列语义与 embedding-worker.cjs 完全一致(单线程串行、priority 插队、
+ * 条间 setImmediate 让路),只有 IPC 传输层不同:
+ *
+ * 协议(与 src/store/local-embedding.ts 的 RealChildChannel 配对;自增 id):
+ * - 启动配置:env DSH_EMBED_CFG(JSON 字符串:{runtimeDir,modelDir,pooling,dtype,
+ *   maxInputChars,maxInputTokens}——fork 的 env 只收标量,嵌套对象经序列化传递);
+ * - 入向:{id,type:'ping'} | {id,type:'warmup'} | {id,type:'embed',texts,priority}
+ * - 出向:{id,ok:true,type:'pong'|'ready'|'embedded',vectors?,tokensMax?}(vectors 为
+ *   number[][],fork IPC 默认 JSON 序列化不支持 TypedArray,主线程侧重建
+ *   Float32Array;512d×32 条 ≈64KB,序列化 <5ms,瓶颈在推理不在传输)。
+ *   tokensMax = 本批真正进模型的最大 token 数(#22 护栏自证用,主线程不消费也不报错)
+ *   | {id,ok:false,stage:'load'|'infer',error} | {type:'fatal',error}
+ *
+ * 信任边界(沿 AGENTS.md 审查记录):runtime/ 目录在数据目录信任边界内,
+ * 本进程按其 package.json createRequire 加载 transformers——对数据目录有写
+ * 权限的进程理论上可植入恶意模块;模型文件逐文件 sha256 锁定,运行时代码
+ * 无同级防护,完整修复需安装指纹设计,暂以文档化假设为准。
+ */
+'use strict';
+
+const path = require('node:path');
+const { createRequire } = require('node:module');
+// token 精截放在独立无副作用模块(而非本文件):本文件是 fork 入口,顶层有进程监听与
+// 「无 IPC 就 exit」守卫,被测试 require 会把副作用带进来。截断逻辑本身必须零模型可验。
+const { shrinkToBudget } = require('./embedding-token-guard.cjs');
+
+// 必须由 fork 启动(需要 IPC channel);裸 node 执行时静默退出,不报 SyntaxError、不永挂。
+if (typeof process.send !== 'function') {
+  console.error('[embedding-child] 未经 fork 启动,无 IPC 通道,退出');
+  process.exit(0);
+}
+
+/** 错误消息归一化(Error 取 message,其余 String 化)。 */
+function errMsg(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+const cfg = JSON.parse(process.env.DSH_EMBED_CFG || '{}');
+const RUNTIME_DIR = typeof cfg.runtimeDir === 'string' ? cfg.runtimeDir : '';
+const MODEL_DIR = typeof cfg.modelDir === 'string' ? cfg.modelDir : '';
+const POOLING = cfg.pooling === 'cls' ? 'cls' : 'mean';
+const DTYPE = typeof cfg.dtype === 'string' ? cfg.dtype : 'q8';
+const MAX_INPUT_CHARS = cfg.maxInputChars > 0 ? cfg.maxInputChars : 5000;
+/**
+ * token 预算(issue #22)。预算值由主进程从模型窗口与硬上限推导后传进来(单一真值源
+ * 在 src/store/model-catalog.ts);本处只消费。**截断必须在子进程做**:tokenizer 只在
+ * pipeline 对象上可达,且 ORT run() 同步阻塞——单条内部不可中断,预检只能放推理前。
+ */
+const MAX_INPUT_TOKENS = cfg.maxInputTokens > 0 ? cfg.maxInputTokens : 0; // 0 = 未给,不启用 token 截断
+
+// 字符粗筛后的 token 精截需要 tokenizer(pipeline 对象上的 .tokenizer,加载后可达)
+let tokenizer = null;
+
+let extractor = null; // pipeline('feature-extraction', …)
+let loadState = 'idle'; // idle | loading | ready | failed
+let loadPromise = null;
+let loadError = null;
+
+// ── 模型懒加载(首请求触发;失败后经 warmup 可重试,embed 请求失败快返回) ──
+function ensureLoaded() {
+  if (loadState === 'ready') return Promise.resolve();
+  if (loadState === 'loading' && loadPromise) return loadPromise;
+  loadState = 'loading';
+  loadError = null;
+  loadPromise = (async () => {
+    try {
+      if (!RUNTIME_DIR || !MODEL_DIR) throw new Error('DSH_EMBED_CFG 缺少 runtimeDir/modelDir');
+      const req = createRequire(path.join(RUNTIME_DIR, 'package.json'));
+      const mod = req('@huggingface/transformers');
+      if (mod.env) {
+        mod.env.allowRemoteModels = false;
+        if (mod.env.allowLocalModels !== undefined) mod.env.allowLocalModels = true;
+      }
+      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, { dtype: DTYPE });
+      // token 截断要用到 pipeline 内部的 tokenizer（未单独暴露 AutoTokenizer,4.x 形态）
+      tokenizer = extractor && extractor.tokenizer ? extractor.tokenizer : null;
+      loadState = 'ready';
+    } catch (err) {
+      loadState = 'failed';
+      loadError = errMsg(err);
+      loadPromise = null; // 失败后下一次 warmup 重新走加载
+      throw err;
+    }
+  })();
+  return loadPromise;
+}
+
+// ── 推理队列(逐条 job;priority 插队;条间让路) ──
+const queue = []; // [{ request, index, text }]
+let pumping = false;
+
+function postReply(msg) {
+  // 通道已断(父进程退出/正在终止)时 send 抛错——静默即可,父进程侧有 exit 兜底
+  try {
+    process.send(msg);
+  } catch {
+    /* IPC 已关闭,回复无处可去 */
+  }
+}
+
+/** 请求全部条目完成 → 回执(Float32Array → number[] 序列化,IPC JSON 通道不支持 TypedArray)。 */
+function settle(request) {
+  if (request.failed || request.remaining !== 0) return;
+  postReply({
+    id: request.id,
+    ok: true,
+    type: 'embedded',
+    vectors: request.vectors.map((v) => Array.from(v)),
+    // #22 护栏自证:本批**实测**进模型的最大 token 数(不可测时为 -1,主线程不读此字段也不会坏)
+    tokensMax: request.tokensMax,
+  });
+}
+
+/** 首个失败即回执错误,并移除该请求尚未开跑的条目(正在跑的至多 1 条,算完即弃)。 */
+function failRequest(request, error, stage) {
+  if (request.failed) return;
+  request.failed = true;
+  for (let i = queue.length - 1; i >= 0; i--) {
+    if (queue[i].request === request) queue.splice(i, 1);
+  }
+  postReply({ id: request.id, ok: false, stage: stage, error: errMsg(error) });
+}
+
+async function pump() {
+  if (pumping) return;
+  pumping = true;
+  try {
+    while (queue.length > 0) {
+      const job = queue.shift();
+      if (job.request.failed) continue;
+      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 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;
+        job.request.remaining -= 1;
+        settle(job.request);
+      } catch (err) {
+        failRequest(job.request, err, 'infer');
+      }
+      // 条间让路:交还本进程事件循环,新消息(含 priority 插队)可在批间被处理
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+  } finally {
+    pumping = false;
+  }
+}
+
+function handleEmbed(msg) {
+  const texts = Array.isArray(msg.texts) ? msg.texts : [];
+  if (texts.length === 0) {
+    postReply({ id: msg.id, ok: true, type: 'embedded', vectors: [] });
+    return;
+  }
+  const request = { id: msg.id, vectors: new Array(texts.length), remaining: texts.length, failed: false, tokensMax: 0 };
+  // 单条请求(召回 query)插队到队首;批次追加到队尾(批内条目间仍会被后来的插队)
+  const priority = msg.priority === true && texts.length === 1;
+  for (let i = 0; i < texts.length; i++) {
+    const job = { request: request, index: i, text: String(texts[i] == null ? '' : texts[i]) };
+    if (priority) queue.unshift(job);
+    else queue.push(job);
+  }
+  void pump();
+}
+
+process.on('message', (msg) => {
+  if (!msg || typeof msg.id !== 'number' || typeof msg.type !== 'string') return;
+  if (msg.type === 'ping') {
+    postReply({ id: msg.id, ok: true, type: 'pong' });
+    return;
+  }
+  if (msg.type === 'warmup') {
+    ensureLoaded().then(
+      () => postReply({ id: msg.id, ok: true, type: 'ready' }),
+      () => postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' }),
+    );
+    return;
+  }
+  if (msg.type === 'embed') {
+    void (async () => {
+      try {
+        await ensureLoaded();
+      } catch {
+        postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' });
+        return;
+      }
+      handleEmbed(msg);
+    })();
+    return;
+  }
+});
+
+// 父进程disconnect(通道被主动关闭,如宿主优雅退出/RealChildChannel 前置断开):
+// 模型与 onnxruntime 都只服务于这条通道,留着就是孤儿常驻——直接退出。
+// taskkill /T /F 兜底覆盖"父进程被硬杀、无 disconnect"的路径。
+process.on('disconnect', () => process.exit(0));
+
+// 未捕获异常:尽力通知父进程后强制退出(父进程的 exit 处理会拒绝全部 pending
+// 并转入 failed 态)。不保持半死状态——半死的子进程只会让调用方挂到超时。
+process.on('uncaughtException', (err) => {
+  postReply({ type: 'fatal', error: errMsg(err) });
+  setTimeout(() => process.exit(1), 50);
+});

package/dist/embedding-token-guard.cjs

@@ -0,0 +1,41 @@
+// token 精截(#22)。**独立无副作用模块**,不注册任何进程级监听:
+// embedding-child.cjs 是 fork 入口(顶层有 process.on 与无 IPC 即 exit 的守卫),被测试
+// require 会把副作用一并带进来(vitest worker 里实测崩在收集期),故截断逻辑只能放在这里
+// 才能既被子进程用、又被测试用。**本文件同时被拷贝进 dist/**(见 scripts/copy-client.mjs)。
+'use strict';
+
+/**
+ * 把一条文本裁到 token 预算内。返回**实际应送进 pipeline 的文本**。
+ *
+ * 为什么截断只能在子进程做:tokenizer 只在加载后的 pipeline 对象上可达,且 onnxruntime
+ * 的 run() 是同步阻塞调用——单条内部不可中断,预检只能放推理前。又因为「子进程隔离」本身
+ * 是 #11(libvips-42.dll 同进程撞名)的修复,不得为省一次 IPC 把 tokenize 挪回主线程。
+ *
+ * 预算留 special token 位([CLS]/[SEP] 实测 +2):截完要 decode 回文本再送 pipeline,
+ * pipeline 内部会重新分词并补上 special token。
+ *
+ * 不做「短文本跳过 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% 不值一个未验证的跳跃。
+ *
+ * 任何一步不可用(transformers 未挂 tokenizer、不认选项、decode 回空串、抛错)一律
+ * **退回粗筛原文保持旧行为**:护栏不得把能跑的链路搞坏。真实偏差由 tokensMax 实测上报兼证。
+ */
+function shrinkToBudget(raw, maxTokens, tok) {
+  if (!tok || !(maxTokens > 0)) return raw;
+  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;
+  } catch {
+    return raw; // 降级:不截断,保持旧行为
+  }
+}
+
+module.exports = { shrinkToBudget };

package/dist/embedding-worker.cjs

@@ -1,5 +1,8 @@
 // DEPRECATED: use embedding-child.cjs (subprocess isolation, fix #11)
 // 保留一版兼容(opts.useWorker 逃生门),下版删除。不再主动修改。
+// 决策记录:#22 的 token 预算护栏**有意不同步到这里**（本通道仍只按 maxInputChars 粗筛）。
+// 逃生门本身就是「回到 #11 前的风险状态」，给它同步一份预算代码 = 维护两份口径;
+// 真需护栏请用默认 child 通道。参 embedding-child.cjs `shrinkToBudget`。
 /**
  * 本地嵌入 worker:transformers.js 的模型加载与推理在本线程执行,主线程只
  * 投递文本、收回向量。onnxruntime-node 的 run/loadModel 是 setImmediate 回调里

package/dist/index.js

@@ -161,7 +161,7 @@ export async function apply(ctx, config) {
         logger,
         proxy: config.embedding.proxy,
     });
-    const makeLocalService = makeLocalServiceFactory(installer, downloader, logger, config.embedding.maxInputChars);
+    const makeLocalService = makeLocalServiceFactory(installer, downloader, logger, config.embedding.maxInputChars, undefined, config.embedding.maxInputTokens);
     let initial = { svc: new NoopEmbeddingService(), dims: 0 };
     /** 管理器引用:启动重嵌链/backfill 闭包在运行期解引用(声明早于创建避免 TDZ)。 */
     // eslint-disable-next-line prefer-const -- 声明早于创建,后续单点赋值(TS 不允许 const 无初值)
@@ -366,6 +366,17 @@ export async function apply(ctx, config) {
                         else if (r1.failed > 0) {
                             logger.warn(`[memory] 向量补齐未完成(L1 失败 ${r1.failed}),下个周期重试`);
                         }
+                        else if (missingAfter < 0) {
+                            // 计数失败时 sqlite 层给 -1(它自己已 warn);本侧**不得**把「数不出」当「无缺失」
+                            // 而滑进下方的停摆告警,更不能标 synced。
+                            logger.warn('[memory] 向量补齐:缺失数统计失败,本轮不判定完成');
+                        }
+                        else {
+                            // 本轮未写入且仍有缺失:典型形态是本地嵌入转入 failed 后 reindex 首行早退
+                            // (`if (!vectorReady()) return 0/0/0`),与「本轮无事可做」在日志里原本不可区分。
+                            logger.warn(`[memory] 向量补齐停摆:本轮未写入且仍差 ${missingAfter} 条` +
+                                `(本地嵌入可能处于 failed 态,见上一条带 signal 的退出记录)`);
+                        }
                     }
                     catch (err) {
                         logger.warn(`[memory] 向量补齐失败: ${err instanceof Error ? err.message : String(err)}`);

package/dist/store/embedding-source.d.ts

@@ -63,10 +63,13 @@ export interface InitialEmbedding {
 export declare function remoteCeiling(cfg: MemoryConfig): boolean;
 export declare function resolveInitialEmbedding(cfg: MemoryConfig, sourceStore: EmbeddingSourceStore, downloader: ModelDownloadQueue, makeLocal: (modelId: string) => LocalEmbeddingService | null, logger?: MemoryLogger): Promise<InitialEmbedding>;
 /** 本地服务构造工厂(index.ts 的初始解析与 Manager 共用一份实现,防漂移)。
- *  推理在 fork 子进程(见 local-embedding.ts,fix #11);此处只传 runtime 目录与模型目录。 */
+ *  推理在 fork 子进程(见 local-embedding.ts,fix #11);此处只传 runtime 目录与模型目录。
+ *  新键一律**追加在末尾**:`childPath` 已有位置参数调用方(含测试),插中间会静默串位。 */
 export declare function makeLocalServiceFactory(installer: RuntimeInstaller, downloader: ModelDownloadQueue, logger?: MemoryLogger, maxInputChars?: number, 
 /** 测试注入缝:子进程资产路径(源码态下 dist 产物不存在,显式指向 resources 源文件)。 */
-childPath?: string): (modelId: string) => LocalEmbeddingService | null;
+childPath?: string, 
+/** 本地推理 token 预算(config `embedding.maxInputTokens`;0/缺省 = 按模型窗口与硬上限推导)。 */
+maxInputTokens?: number): (modelId: string) => LocalEmbeddingService | null;
 export interface EmbeddingManagerDeps {
     dataDir: string;
     cfg: MemoryConfig;

package/dist/store/embedding-source.js

@@ -153,10 +153,13 @@ export async function resolveInitialEmbedding(cfg, sourceStore, downloader, make
     return { svc, dims: cfg.embedding.dimensions, providerInfo: svc.getProviderInfo() };
 }
 /** 本地服务构造工厂(index.ts 的初始解析与 Manager 共用一份实现,防漂移)。
- *  推理在 fork 子进程(见 local-embedding.ts,fix #11);此处只传 runtime 目录与模型目录。 */
+ *  推理在 fork 子进程(见 local-embedding.ts,fix #11);此处只传 runtime 目录与模型目录。
+ *  新键一律**追加在末尾**:`childPath` 已有位置参数调用方(含测试),插中间会静默串位。 */
 export function makeLocalServiceFactory(installer, downloader, logger, maxInputChars, 
 /** 测试注入缝:子进程资产路径(源码态下 dist 产物不存在,显式指向 resources 源文件)。 */
-childPath) {
+childPath, 
+/** 本地推理 token 预算(config `embedding.maxInputTokens`;0/缺省 = 按模型窗口与硬上限推导)。 */
+maxInputTokens) {
     return (modelId) => {
         const entry = catalogById(modelId);
         if (!entry)
@@ -166,6 +169,7 @@ childPath) {
             childPath,
             logger,
             maxInputChars,
+            maxInputTokens,
         });
     };
 }
@@ -245,7 +249,8 @@ export class EmbeddingManager {
     }
     /** 构造绑定真实运行时 loader 的本地服务(deps.makeLocal 可注入,测试替换)。 */
     makeLocalService(modelId) {
-        const factory = this.deps.makeLocal ?? makeLocalServiceFactory(this.installer, this.downloader, this.deps.logger, this.deps.cfg.embedding.maxInputChars);
+        const factory = this.deps.makeLocal ??
+            makeLocalServiceFactory(this.installer, this.downloader, this.deps.logger, this.deps.cfg.embedding.maxInputChars, undefined, this.deps.cfg.embedding.maxInputTokens);
         return factory(modelId);
     }
     /** 活切换请求:验证通过即接受,后台执行应用链(进度轮询可见)。 */

package/dist/store/l1.js

@@ -984,9 +984,14 @@ export class L1Store {
             try {
                 vecs = await this.embedSvc.embedBatch(chunk.map((c) => c.content));
             }
-            catch {
+            catch (err) {
+                // 必须带 id(#22 取证面):本腿直接调 embedSvc、绕过 EmbedHelper 的熔断/超时/截断,
+                // 一整批全失败是常态(进程被杀时后续 chunk 均秒拒);不带 id 就无从定位是哪条长文本致崩。
+                // 只打前 3 个:失败可能是整库堆积,全打会把日志挤掉。
                 failed += chunk.length;
                 done += chunk.length;
+                this.logger?.warn(`[memory] 重嵌批次失败(${chunk.length} 条,本 chunk 首三个 id=` +
+                    `${chunk.slice(0, 3).map((c) => c.id).join(',')}…): ${err instanceof Error ? err.message : String(err)}`);
                 opts?.onProgress?.(done, total);
                 continue;
             }

package/dist/store/local-embedding.d.ts

@@ -1,5 +1,5 @@
 import type { MemoryLogger } from '../types.js';
-import type { CatalogEntry } from './model-catalog.js';
+import { type CatalogEntry } from './model-catalog.js';
 import type { EmbedCallOptions, EmbeddingProviderInfo, EmbeddingService } from './embedding.js';
 type LocalState = 'idle' | 'loading' | 'ready' | 'failed' | 'terminated';
 /** 推理侧启动参数(worker 经 workerData / 子进程经 env DSH_EMBED_CFG;构造后不可变)。 */
@@ -8,7 +8,13 @@ export interface EmbedWorkerData {
     modelDir: string;
     pooling: 'cls' | 'mean';
     dtype: string;
+    /** 字符粗筛上限(IPC 体积护栏;不是语义护栏,也**不是**崩溃护栏——token 帽才是)。 */
     maxInputChars: number;
+    /**
+     * 本地推理的单条 token 预算(issue #22)。主进程推导(`deriveTokenBudget`)、
+     * 子进程执行截断——因为 tokenizer 只在子进程可达,且 ORT `run()` 同步不可中断。
+     */
+    maxInputTokens: number;
 }
 /** 主线程 → worker 的调用(id 由通道分配)。 */
 export type EmbedWorkerCall = {
@@ -48,6 +54,12 @@ export interface EmbedWorkerChannel {
     /** worker 意外崩溃通知(此后所有未决请求已被通道拒绝)。 */
     setOnCrash(cb: (error: string) => void): void;
 }
+/**
+ * 退出描述归一化(issue #22 取证面):被信号硬杀时 Node 给的是 `code===null` + `signal`,
+ * 只打 code 会让 SIGTRAP(分配器 trap)/OOM-kill(SIGKILL)/自然退出(code=0)在日志里长得一模一样。
+ * signal 同时进 crashed 串、向上传为 loadError,故一处修三处可见。
+ */
+export declare function describeExit(what: string, code: number | null, signal: string | null): string;
 export interface LocalEmbeddingOptions {
     /** 数据目录 runtime/(推理侧据此 createRequire 加载 transformers)。 */
     runtimeDir: string;
@@ -61,6 +73,11 @@ export interface LocalEmbeddingOptions {
     channel?: EmbedWorkerChannel;
     logger?: MemoryLogger;
     maxInputChars?: number;
+    /**
+     * 用户显式 token 预算(config `embedding.maxInputTokens`);缺省/0 = 按模型窗口与
+     * `HARD_CAP_TOKENS` 自动推导。超限只 clamp + warn,不抛错。
+     */
+    maxInputTokens?: number;
 }
 export declare class LocalEmbeddingService implements EmbeddingService {
     private state;

package/dist/store/local-embedding.js

@@ -22,6 +22,7 @@ import { fork, spawn } from 'node:child_process';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Worker } from 'node:worker_threads';
+import { deriveTokenBudget, HARD_CAP_TOKENS } from './model-catalog.js';
 /** 默认 worker 资产路径(旧通道,useWorker 逃生门):dist/store/ → dist/embedding-worker.cjs(构建期拷入)。 */
 function defaultWorkerPath() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'embedding-worker.cjs');
@@ -56,9 +57,12 @@ class RealWorkerChannel {
         });
         // error(未捕获异常且 worker 未自处理)与 exit(含 fatal 后的退出)都兜底拒绝
         this.worker.on('error', (err) => this.failAll(`本地嵌入 worker 线程错误: ${err.message}`));
-        this.worker.on('exit', (code) => {
+        this.worker.on('exit', (code, signal) => {
+            // signal 必须留痕:被信号硬杀时 code===null,单看 code 无法区分「SIGTRAP/OOM-kill/自然退出」
+            // (issue #22 就是靠 macOS 崩溃报告对毫秒时间戳才归因上的)。
+            // worker 的 exit 事件在 typings 里无强类型重载,故 signal 取守性可选形参。
             if (!this.terminated)
-                this.failAll(`本地嵌入 worker 线程退出(code=${code})`);
+                this.failAll(describeExit('本地嵌入 worker 线程', code, signal ?? null));
         });
     }
     request(call) {
@@ -96,6 +100,14 @@ class RealWorkerChannel {
         }
     }
 }
+/**
+ * 退出描述归一化(issue #22 取证面):被信号硬杀时 Node 给的是 `code===null` + `signal`,
+ * 只打 code 会让 SIGTRAP(分配器 trap)/OOM-kill(SIGKILL)/自然退出(code=0)在日志里长得一模一样。
+ * signal 同时进 crashed 串、向上传为 loadError,故一处修三处可见。
+ */
+export function describeExit(what, code, signal) {
+    return `${what}退出(code=${code ?? 'null'},signal=${signal ?? 'null'})`;
+}
 /**
  * 真实子进程通道(fix #11 默认):fork 独立进程隔离 sharp/libvips DLL 冲突。
  * 与 RealWorkerChannel 同协议语义,差异仅在传输层:
@@ -140,9 +152,10 @@ class RealChildChannel {
         });
         // error(fork 启动失败等)与 exit(含 fatal 后自杀、OOM 被杀)都钉底拒绝
         this.child.on('error', (err) => this.failAll(`本地嵌入子进程错误: ${err.message}`));
-        this.child.on('exit', (code) => {
+        this.child.on('exit', (code, signal) => {
+            // 同上:signal 是被硬杀的唯一线索,不得丢弃(#22)
             if (!this.terminated)
-                this.failAll(`本地嵌入子进程退出(code=${code})`);
+                this.failAll(describeExit('本地嵌入子进程', code, signal));
         });
     }
     request(call) {
@@ -213,13 +226,25 @@ export class LocalEmbeddingService {
         this.entry = entry;
         this.logger = opts.logger;
         const maxInputChars = opts.maxInputChars && opts.maxInputChars > 0 ? opts.maxInputChars : 5000;
+        const budget = deriveTokenBudget(entry.contextTokens, opts.maxInputTokens);
+        if (budget.clamped) {
+            // 用户写了个必崩的值:压到上限并留痕(不抛错——拒绝启动比 clamp 更难排查)
+            this.logger?.warn(`[memory] 本地嵌入 token 预算已从 ${opts.maxInputTokens} 压到 ${budget.tokens}` +
+                `(模型窗口 ${entry.contextTokens} / 硬上限 ${HARD_CAP_TOKENS},#22 安全余量)`);
+        }
         const cfgObj = {
             runtimeDir: opts.runtimeDir,
             modelDir,
             pooling: entry.pooling,
             dtype: 'q8',
             maxInputChars,
+            maxInputTokens: budget.tokens,
         };
+        // #22 取证面:同一份代码在纯 node 能跑、在 Electron-node 崩,而仓内任何地方都没记录
+        // execPath 差异与生效预算 —— 下次不用靠系统崩溃报告对时间戳。
+        this.logger?.info(`[memory] 本地嵌入子进程拉起:execPath=${process.execPath},release=${process.release?.name ?? 'unknown'},` +
+            `model=${entry.id},contextTokens=${entry.contextTokens},tokenBudget=${budget.tokens},` +
+            `粗筛 chars=${maxInputChars},通道=${opts.useWorker ? 'worker(旧逃生门,无 token 护栏)' : 'child'}`);
         this.channel =
             opts.channel ??
                 (opts.useWorker

package/dist/store/model-catalog.d.ts

@@ -31,7 +31,10 @@ export interface CatalogEntry {
     revision: string;
     /** 向量维度（vec0 建表与切换重嵌的判据）。 */
     dims: number;
-    /** 上下文窗口（token），仅 UI 展示。 */
+    /**
+     * 上下文窗口（token）。0.26.25 起从「仅 UI 展示」升格为**本地推理预算的推导真值**
+     * （见 `deriveTokenBudget`）——改动这里就是改本地嵌入的截断口径,不再只是个展示字段。
+     */
     contextTokens: number;
     /** 池化方式：BGE 系 CLS；embeddinggemma 系（Gemma 解码器底座）MEAN。 */
     pooling: 'cls' | 'mean';
@@ -44,5 +47,32 @@ export interface CatalogEntry {
 export declare const MODEL_CATALOG: CatalogEntry[];
 /** 按 id 取目录项。 */
 export declare function catalogById(id: string): CatalogEntry | undefined;
+/**
+ * 本地 ONNX 推理的单条 token 上限（**唯一硬编码源**,issue #22）。
+ *
+ * 取值 2048 的理由（不是拍脑袋）：#22 实测 Electron 宿主下约 **2700 token** 即被分配器
+ * SIGTRAP 打死（栈：MatMul 输出张量 → BFCArena::Extend → malloc_zone_memalign），且峰值
+ * 内存按 **O(T²)** 增长（attention 张量 `[1,heads,T,T]`）——2048 在致死线下留 ≈24% 余量，
+ * 同时把单次峰值从 ≈4.7GB 压到 ≈0.43 倍。它是**崩溃护栏也是内存护栏**，两者同源。
+ *
+ * 不拿 `maxInputChars` 当护栏的原因：bge-m3/embeddinggemma 是 Unigram/BPE，中文≈**1 字/token**
+ * 而 emoji/泰文可 >1.5，所以 5000 字符**既可只 750 token（英文）也可近 8192（中文）**——
+ * 字符与 token 无稳定比值，字符帽永远约不到安全线。
+ */
+export declare const HARD_CAP_TOKENS = 2048;
+/**
+ * 推导生效的本地嵌入 token 预算（**单一实现点**,截断执行在 `resources/embedding-child.cjs`）。
+ *
+ * 默认（`userTokens` 缺省/0/负）= `min(modelContext, HARD_CAP_TOKENS)`：bge-small-zh(512)
+ * 不受 HARD_CAP 影响（本来就到 512 窗口），bge-m3(8192) 被压到 2048。`modelContext`
+ * 取不到（非目录模型）时回退 HARD_CAP_TOKENS，**取小不取大**。
+ *
+ * 用户显式超限只 **clamp 不抛错**（收窄 schema 边界会让已部署 YAML 解析直接失败，故障半径
+ * 是整个插件配置树），`clamped` 由调用方打 warn 使其可见。
+ */
+export declare function deriveTokenBudget(modelContext: number | undefined, userTokens: number | undefined): {
+    tokens: number;
+    clamped: boolean;
+};
 /** 模型总字节数（磁盘检查与整体进度分母）。 */
 export declare function catalogTotalBytes(entry: CatalogEntry): number;

package/dist/store/model-catalog.js

@@ -75,6 +75,36 @@ export const MODEL_CATALOG = [
 export function catalogById(id) {
     return MODEL_CATALOG.find((m) => m.id === id);
 }
+/**
+ * 本地 ONNX 推理的单条 token 上限（**唯一硬编码源**,issue #22）。
+ *
+ * 取值 2048 的理由（不是拍脑袋）：#22 实测 Electron 宿主下约 **2700 token** 即被分配器
+ * SIGTRAP 打死（栈：MatMul 输出张量 → BFCArena::Extend → malloc_zone_memalign），且峰值
+ * 内存按 **O(T²)** 增长（attention 张量 `[1,heads,T,T]`）——2048 在致死线下留 ≈24% 余量，
+ * 同时把单次峰值从 ≈4.7GB 压到 ≈0.43 倍。它是**崩溃护栏也是内存护栏**，两者同源。
+ *
+ * 不拿 `maxInputChars` 当护栏的原因：bge-m3/embeddinggemma 是 Unigram/BPE，中文≈**1 字/token**
+ * 而 emoji/泰文可 >1.5，所以 5000 字符**既可只 750 token（英文）也可近 8192（中文）**——
+ * 字符与 token 无稳定比值，字符帽永远约不到安全线。
+ */
+export const HARD_CAP_TOKENS = 2048;
+/**
+ * 推导生效的本地嵌入 token 预算（**单一实现点**,截断执行在 `resources/embedding-child.cjs`）。
+ *
+ * 默认（`userTokens` 缺省/0/负）= `min(modelContext, HARD_CAP_TOKENS)`：bge-small-zh(512)
+ * 不受 HARD_CAP 影响（本来就到 512 窗口），bge-m3(8192) 被压到 2048。`modelContext`
+ * 取不到（非目录模型）时回退 HARD_CAP_TOKENS，**取小不取大**。
+ *
+ * 用户显式超限只 **clamp 不抛错**（收窄 schema 边界会让已部署 YAML 解析直接失败，故障半径
+ * 是整个插件配置树），`clamped` 由调用方打 warn 使其可见。
+ */
+export function deriveTokenBudget(modelContext, userTokens) {
+    const cap = Math.min(modelContext && modelContext > 0 ? modelContext : HARD_CAP_TOKENS, HARD_CAP_TOKENS);
+    const raw = userTokens && userTokens > 0 ? Math.floor(userTokens) : 0;
+    if (raw === 0)
+        return { tokens: cap, clamped: false };
+    return { tokens: Math.min(raw, cap), clamped: raw > cap };
+}
 /** 模型总字节数（磁盘检查与整体进度分母）。 */
 export function catalogTotalBytes(entry) {
     return entry.files.reduce((sum, f) => sum + f.size, 0);

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-prime-memory",
   "name": "dsh-prime-memory",
-  "version": "0.26.23",
+  "version": "0.26.25",
   "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.23",
+  "version": "0.26.25",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",