dsh-prime-memory 0.26.28 → 0.26.30

package/dist/clients/drsc-inproc.d.ts

@@ -48,3 +48,37 @@ export declare function resetCollectorReadState(): void;
  * 把传输从 fetch 换成函数调用，不顺手改任何语义。
  */
 export declare function callCollectorRead(query: string, load?: CollectorLoader): Promise<Record<string, unknown>>;
+/** 五态：`ok` 不渲染 banner；`unknown` 是探针失败的兜底（不得当成故障去误报）。 */
+export type DrscHealthState = 'ok' | 'not-running' | 'stale' | 'missing' | 'unknown';
+export interface DrscHealth {
+    state: DrscHealthState;
+    /** 包能 import → true。`missing` 时为 false。 */
+    installed: boolean;
+    /** 门面可用（= collector 真跑起来了）→ true。装了没启用时为 false。 */
+    mounted: boolean;
+    /** 投影库 `MAX(synced_at)` 的 epoch ms；无从读取为 null。 */
+    lastSyncAt: number | null;
+    /** now - lastSyncAt；null = 无从计算。 */
+    lagMs: number | null;
+    staleAfterMs: number;
+    indexPath: string | null;
+    checkedAt: number;
+    error?: string;
+}
+/** 超过这个滞后就判 `stale`（“装了但库不新鲜”）。30 分钟与同步器节拍同量级。 */
+export declare const DRSC_STALE_AFTER_MS: number;
+/**
+ * 探针（只观测，不改变读路径）。
+ *
+ * 三条铁律（违一条就会污染读面或误报）：
+ * 1. **不经 `moduleOf`**：它会推进 `facadeMisses` 并把结果缓进 `modulePromise`，
+ *    探针是观测面，不得改动读路径的重试预算与缓存——故这里直接调 `load()` 与 `drsReadFacade()`。
+ * 2. **复用模块级 `storeHandle`**：`openProjectionStore` 会把摘要全表载入（Issue #1 的根因），
+ *    每 60s 轮询重开一次就是事故；只在 undefined 时开。
+ * 3. **读库失败一律落 `unknown`**：探针失败不等于功能坏了，不得当成故障吓用户。
+ */
+export declare function probeDrscHealth(opts?: {
+    load?: CollectorLoader;
+    now?: number;
+    staleAfterMs?: number;
+}): Promise<DrscHealth>;

package/dist/clients/drsc-inproc.js

@@ -156,3 +156,91 @@ function positiveInt(raw) {
 }
 /** 统一形后的模块不再需要真 QueryContext，这个占位只用来占位。 */
 const READ_SURFACE = 'inproc-read-surface';
+/** 超过这个滞后就判 `stale`（“装了但库不新鲜”）。30 分钟与同步器节拍同量级。 */
+export const DRSC_STALE_AFTER_MS = 30 * 60 * 1000;
+/** `synced_at` 实测是 TEXT ISO（如 "2026-11-01T21:00:57.415Z"），兼容数值形式。 */
+function parseSyncStamp(v) {
+    if (typeof v === 'string' && v.trim() !== '') {
+        const t = Date.parse(v);
+        return Number.isFinite(t) ? t : null;
+    }
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+        return v;
+    return null;
+}
+/**
+ * 探针（只观测，不改变读路径）。
+ *
+ * 三条铁律（违一条就会污染读面或误报）：
+ * 1. **不经 `moduleOf`**：它会推进 `facadeMisses` 并把结果缓进 `modulePromise`，
+ *    探针是观测面，不得改动读路径的重试预算与缓存——故这里直接调 `load()` 与 `drsReadFacade()`。
+ * 2. **复用模块级 `storeHandle`**：`openProjectionStore` 会把摘要全表载入（Issue #1 的根因），
+ *    每 60s 轮询重开一次就是事故；只在 undefined 时开。
+ * 3. **读库失败一律落 `unknown`**：探针失败不等于功能坏了，不得当成故障吓用户。
+ */
+export async function probeDrscHealth(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const staleAfterMs = opts.staleAfterMs ?? DRSC_STALE_AFTER_MS;
+    const load = opts.load ?? defaultLoader;
+    const base = {
+        state: 'unknown',
+        installed: false,
+        mounted: false,
+        lastSyncAt: null,
+        lagMs: null,
+        staleAfterMs,
+        indexPath: null,
+        checkedAt: now,
+    };
+    let mod;
+    try {
+        mod = (await load());
+    }
+    catch (err) {
+        return { ...base, state: 'missing', error: err instanceof Error ? err.message : String(err) };
+    }
+    // 门面活 → 已启用（ok 态由客户端 return null，不占版面）
+    try {
+        if (typeof mod.drsReadFacade === 'function' && mod.drsReadFacade() !== undefined) {
+            return { ...base, state: 'ok', installed: true, mounted: true };
+        }
+    }
+    catch (err) {
+        // 门面自身抛错：按“装了没启用”继续往下判，不因此报 missing
+        base.error = err instanceof Error ? err.message : String(err);
+    }
+    // 装了没启用：读投影库水位区分 not-running / stale
+    let indexPath = null;
+    try {
+        indexPath = mod.resolveIndexDir();
+        if (storeHandle === undefined)
+            storeHandle = mod.openProjectionStore(indexPath);
+        const db = storeHandle.db;
+        if (!db)
+            return { ...base, state: 'unknown', installed: true, indexPath, error: '投影库句柄无 .db' };
+        const row = db.prepare('SELECT MAX(synced_at) AS s FROM sessions').get();
+        const lastSyncAt = parseSyncStamp(row?.s);
+        if (lastSyncAt === null) {
+            return { ...base, state: 'unknown', installed: true, indexPath, error: 'synced_at 无法解析（期望 ISO 字符串或 epoch ms）' };
+        }
+        const lagMs = Math.max(0, now - lastSyncAt);
+        return {
+            ...base,
+            state: lagMs <= staleAfterMs ? 'not-running' : 'stale',
+            installed: true,
+            lastSyncAt,
+            lagMs,
+            indexPath,
+            error: undefined,
+        };
+    }
+    catch (err) {
+        return {
+            ...base,
+            state: 'unknown',
+            installed: true,
+            indexPath,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/dist/config.d.ts

@@ -65,6 +65,18 @@ export interface MemoryConfig {
         dedupRetryCap?: number;
         /** 抽取结果 checkpoint 落盘:去重/落库失败后下轮从去重续跑、不重抽已成功块。R1″。 */
         extractCheckpoint?: boolean;
+        /**
+         * L1 **批内自去重**（同轮/同会话）：进 LLM 跨库去重前，先做"精确归一合并 → 同族同类向量聚类"。
+         *
+         * 解的是实测缺陷：候选池只来自库，同批 `extracted[]` 从不互相比，于是同一段对话被抽成的
+         * 多条碎片会一起塞进 LLM 批，只能由模型把内容"撑在一起"。关闭 = 回到旧行为（逐字节一致）。
+         */
+        intraBatchDedupe?: boolean;
+        /**
+         * 批内向量的余弦阈值（有效区间 0.85–0.99，缺省 0.92）。只在同 family + 同 type 内生效。
+         * 越界**不报错**（配置树抛错的故障半径是整个配置），由代码 clamp 并留 warn。
+         */
+        intraBatchCosine?: number;
     };
     l2: {
         enabled: boolean;
@@ -369,6 +381,14 @@ export interface MemoryConfig {
          * 超上限会被 clamp 并留 warn(不抛错,见 model-catalog.ts `deriveTokenBudget`)。
          */
         maxInputTokens: number;
+        /**
+         * 本地嵌入子进程被硬杀后是否**有界自愈**(#22 机理刀,默认 true)。
+         *
+         * 开:崩溃由 crashCb 单点重 fork+重预热,60s 窗内 ≤2 次;多条目批按实时断点(ack)
+         * 续试**一次**(不整批重放,毒输入最多多吃两批不成活锁);超限回 failed(旧语义)。
+         * 关:回到 0.26.25 语义——崩一次停摆到宿主重启/换源。**有意翻转**当时的「不做自愈」公告。
+         */
+        respawnOnCrash: boolean;
         /** 单次调用超时(ms)。 */
         timeoutMs: number;
         /** 允许本地嵌入模型档(部署上限:公司环境可禁下载与本地推理)。 */

package/dist/config.js

@@ -159,6 +159,11 @@ export const memorySchema = Schema.object({
         candidatePool: Schema.number().min(1).max(20).default(5),
         dedupRetryCap: Schema.number().min(1).max(20).default(5),
         extractCheckpoint: Schema.boolean().default(true),
+        // 批内自去重（#同会话碎片收拢）：默认开；关闭即回到 0.26.30 前的行为。
+        intraBatchDedupe: Schema.boolean().default(true),
+        // 宽外壁（0–10）只为防溢出输入；有效区间 0.85–0.99 在代码内 clamp+warn，
+        // 不用 min/max 卡窄区间——schemastery 越界会抛，故障半径是整个配置树。
+        intraBatchCosine: Schema.number().min(0).max(10).default(0.92),
     }),
     l2: Schema.object({
         enabled: Schema.boolean().default(true),
@@ -347,6 +352,9 @@ export const memorySchema = Schema.object({
         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),
+        // #22 机理刀:只增不改。**默认开**有界自愈(重 fork ≤2/60s + ack 断点续试一次),
+        // 有意翻转 0.26.25「不做自愈」公告;关键即回旧语义(崩一次停摆到重启)。
+        respawnOnCrash: Schema.boolean().default(true),
         mirror: Schema.string().default('https://hf-mirror.com'),
         proxy: Schema.string().default(''),
     }),

package/dist/contract.d.ts

@@ -1968,6 +1968,8 @@ export interface DshMemoryRequestMap {
     'dsh-memory/llm-providers': Record<string, never>;
     'dsh-memory/llm-models': LlmModelsRequest;
     'dsh-memory/embedding-state-get': Record<string, never>;
+    /** DRSC（参考会话库）健康探针：设置面板 banner 用（无入参）。 */
+    'dsh-memory/drsc-health': Record<string, never>;
     'dsh-memory/embedding-source-set': EmbeddingSourceSetRequest;
     'dsh-memory/embedding-download-start': EmbeddingDownloadStartRequest;
     'dsh-memory/embedding-download-cancel': Record<string, never>;
@@ -1996,6 +1998,19 @@ export interface DshMemoryRequestMap {
     'dsh-memory/mem-orphans': MemOrphansRequest;
     'dsh-memory/skills-action': SkillsActionRequest;
 }
+/** DRSC 健康五态（与 `drsc-inproc.probeDrscHealth` 返回同步；此处只保留形状，不引 node 侧代码）。 */
+export type DrscHealthStateName = 'ok' | 'not-running' | 'stale' | 'missing' | 'unknown';
+export interface DrscHealthResponse {
+    state: DrscHealthStateName;
+    installed: boolean;
+    mounted: boolean;
+    lastSyncAt: number | null;
+    lagMs: number | null;
+    staleAfterMs: number;
+    indexPath: string | null;
+    checkedAt: number;
+    error?: string;
+}
 export interface DshMemoryResponseMap {
     'dsh-memory/stats': StatsResponse;
     'dsh-memory/token-cost': TokenCostResponse;
@@ -2036,6 +2051,7 @@ export interface DshMemoryResponseMap {
     'dsh-memory/llm-providers': LlmProvidersResponse;
     'dsh-memory/llm-models': LlmModelsResponse;
     'dsh-memory/embedding-state-get': EmbeddingStateResponse;
+    'dsh-memory/drsc-health': DrscHealthResponse;
     'dsh-memory/embedding-source-set': EmbeddingSourceSetResponse;
     'dsh-memory/embedding-download-start': EmbeddingDownloadStartResponse;
     'dsh-memory/embedding-download-cancel': EmbeddingCancelResponse;

package/dist/embedding-child.cjs

@@ -15,7 +15,8 @@
  * - 出向:{id,ok:true,type:'pong'|'ready'|'embedded',vectors?,tokensMax?}(vectors 为
  *   number[][],fork IPC 默认 JSON 序列化不支持 TypedArray,主线程侧重建
  *   Float32Array;512d×32 条 ≈64KB,序列化 <5ms,瓶颈在推理不在传输)。
- *   tokensMax = 本批真正进模型的最大 token 数(#22 护栏自证用,主线程不消费也不报错)
+ *   tokensMax = 本批**实测**进模型的最大 token 数(#22 护栏自证用,主线程不消费也不报错);
+ *   初值为 -1 而非 0 —— -1 表示「不可证」,与「真的一个 token 也没进」必须区分开。
  *   | {id,ok:false,stage:'load'|'infer',error} | {type:'fatal',error}
  *
  * 信任边界(沿 AGENTS.md 审查记录):runtime/ 目录在数据目录信任边界内,
@@ -85,7 +86,16 @@ function ensureLoaded() {
         mod.env.allowRemoteModels = false;
         if (mod.env.allowLocalModels !== undefined) mod.env.allowLocalModels = true;
       }
-      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, { dtype: DTYPE });
+      // #22 机理面:关 memPattern。ORT 默认按图形预分配输入绑定驻留 BFCArena,连发时
+      // 新旧 T² 张量共存把峰值叠成 m×T²(实测 r0→r1 再跳 +341MB;单发/连发致死线之比
+      // ≈√2 即 m=2 的定量旁证)。关掉后同形状连发峰值 1583→1247MB(m:2→1 方向)、
+      // 稳态 infer 零代价、输出 12 位小数全同(不触发重嵌)。传参链已实证:
+      // pipelines.js:111/167 → onnx.js:286-293 摊进 InferenceSession.create。
+      // **边界**:对 macOS 分配器 trap 的消除效果本机不可证,不得据此宣称「不再崩」。
+      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, {
+        dtype: DTYPE,
+        session_options: { enableMemPattern: false },
+      });
       // token 截断要用到 pipeline 内部的 tokenizer（未单独暴露 AutoTokenizer,4.x 形态）
       tokenizer = extractor && extractor.tokenizer ? extractor.tokenizer : null;
       loadState = 'ready';
@@ -122,6 +132,9 @@ function settle(request) {
     vectors: request.vectors.map((v) => Array.from(v)),
     // #22 护栏自证:本批**实测**进模型的最大 token 数(不可测时为 -1,主线程不读此字段也不会坏)
     tokensMax: request.tokensMax,
+    // #22 机理刀:ack = 本批已完整完成的条目数(全部完成时恒 = total);多条目批另有
+    // embedProgress 实时推进度——子进程被硬杀时最后的 ack 就是父侧的断点位。
+    ack: request.total,
   });
 }
 
@@ -155,6 +168,10 @@ async function pump() {
         // 不可证时为 -1（不是 0）,不拿假数据当护栏证据。
         if (cut.seq > job.request.tokensMax) job.request.tokensMax = cut.seq;
         job.request.remaining -= 1;
+        // 多条目批实时上报断点(完成一条报一条;单条批无断点可续,不报)——
+        // 父侧若在两条之间被 SIGTRAP 打断,最后收到的 done 就是重试切片位。
+        // cid 由服务侧生成并回显(通道内部 id 与请求配对同形,不暴露给服务侧)。
+        if (job.request.total > 1) postReply({ id: job.request.id, cid: job.request.cid, type: 'embedProgress', done: job.request.total - job.request.remaining });
         settle(job.request);
       } catch (err) {
         failRequest(job.request, err, 'infer');
@@ -173,7 +190,11 @@ function handleEmbed(msg) {
     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 };
+  // tokensMax 初值必须是 -1（不可证）而不是 0：下面的累加用严格大于，若初值为 0，
+  // 则永远量不出 seq 的情形（tokenizer 不可达/预算为 0）会把 -1 压成 0，
+  // 而主线程的 `>= 0` 判据会把 0 当有效值印出来——正好印成「一条也没进」，
+  // 与「不可证」撞车，使这行日志在最需要它的时刻说谎（#22 报告人回验实测）。
+  const request = { id: msg.id, cid: msg.cid, total: texts.length, vectors: new Array(texts.length), remaining: texts.length, failed: false, tokensMax: -1 };
   // 单条请求(召回 query)插队到队首;批次追加到队尾(批内条目间仍会被后来的插队)
   const priority = msg.priority === true && texts.length === 1;
   for (let i = 0; i < texts.length; i++) {

package/dist/embedding-worker.cjs

@@ -62,7 +62,12 @@ function ensureLoaded() {
         mod.env.allowRemoteModels = false;
         if (mod.env.allowLocalModels !== undefined) mod.env.allowLocalModels = true;
       }
-      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, { dtype: DTYPE });
+      // #22 机理面:关 memPattern(与 embedding-child.cjs 同口径,峰值 m:2→1 方向、输出等价;
+      // 本逃生门无 token 护栏是既有限制,注明不在机理刀里扩面)
+      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, {
+        dtype: DTYPE,
+        session_options: { enableMemPattern: false },
+      });
       loadState = 'ready';
     } catch (err) {
       loadState = 'failed';
@@ -86,7 +91,7 @@ function postReply(msg, transfer) {
 function settle(request) {
   if (request.failed || request.remaining !== 0) return;
   postReply(
-    { id: request.id, ok: true, type: 'embedded', vectors: request.vectors },
+    { id: request.id, ok: true, type: 'embedded', vectors: request.vectors, ack: request.total },
     request.vectors.map((v) => v.buffer),
   );
 }
@@ -113,6 +118,8 @@ async function pump() {
         const data = result[0] && result[0].data;
         job.request.vectors[job.index] = data instanceof Float32Array ? data : new Float32Array(data);
         job.request.remaining -= 1;
+        // 多条目批实时上报断点(与 child 通道同协议;cid 回显,见 embedding-child.cjs 注释)
+        if (job.request.total > 1) postReply({ id: job.request.id, cid: job.request.cid, type: 'embedProgress', done: job.request.total - job.request.remaining });
         settle(job.request);
       } catch (err) {
         failRequest(job.request, err, 'infer');
@@ -131,7 +138,7 @@ function handleEmbed(msg) {
     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 };
+  const request = { id: msg.id, cid: msg.cid, total: texts.length, 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++) {

package/dist/index.js

@@ -21,6 +21,7 @@ import { registerMemoryRpc, PLUGIN_VERSION } from './stats.js';
 import { registerLiveSettings, suppressAutoSettingsForm } from './settings.js';
 import { NoopEmbeddingService } from './store/embedding.js';
 import { EmbeddingManager, EmbeddingSourceStore, makeLocalServiceFactory, resolveInitialEmbedding, } from './store/embedding-source.js';
+import { LocalEmbeddingService } from './store/local-embedding.js';
 import { ModelDownloadQueue } from './store/download-queue.js';
 import { PINNED_TRANSFORMERS_VERSION, RuntimeInstaller } from './store/runtime-installer.js';
 import { cleanupOrphanTmp, ensureDir } from './util/io.js';
@@ -161,7 +162,7 @@ export async function apply(ctx, config) {
         logger,
         proxy: config.embedding.proxy,
     });
-    const makeLocalService = makeLocalServiceFactory(installer, downloader, logger, config.embedding.maxInputChars, undefined, config.embedding.maxInputTokens);
+    const makeLocalService = makeLocalServiceFactory(installer, downloader, logger, config.embedding.maxInputChars, undefined, config.embedding.maxInputTokens, config.embedding.respawnOnCrash);
     let initial = { svc: new NoopEmbeddingService(), dims: 0 };
     /** 管理器引用:启动重嵌链/backfill 闭包在运行期解引用(声明早于创建避免 TDZ)。 */
     // eslint-disable-next-line prefer-const -- 声明早于创建,后续单点赋值(TS 不允许 const 无初值)
@@ -190,6 +191,11 @@ export async function apply(ctx, config) {
     if (storageOk) {
         try {
             dbInit = db.init(initial.providerInfo);
+            // #22 口径留痕:库里向量是在哪个 token 帽下嵌出来的,事后必须可查
+            // (providerInfo 判据不含预算——未来调档若无声,这行是唯一证据)
+            if (initial.providerInfo?.provider === 'local' && embed instanceof LocalEmbeddingService) {
+                db.recordEmbeddingTokenBudget(embed.getTokenBudget());
+            }
             if (db.isDegraded()) {
                 storageOk = false;
                 logger.error('[memory] 检索库初始化失败(schema/FTS 不可用),记忆功能停用');

package/dist/pipeline/intra-dedupe.d.ts

@@ -0,0 +1,85 @@
+/**
+ * L1 **批内自去重**（同轮/同会话）——纯函数，零 IO、零 import 副作用。
+ *
+ * 为什么需要它（#现场取证，见 .agents/plans/pm-dedupe-scale-drsc-hint/findings.md §4）：
+ * 既有 L1 去重只把**新记忆**和**库里的候选**对比（`store.searchCandidates`），同一批
+ * `extracted[]` 之间**从不互相比较**。于是同一段对话被抽成多条碎片时，它们会一起进同一条
+ * ≤20 条的 LLM 去重 prompt，只能由模型产出 `merged_content` 把内容"摞在一起"——
+ * 既费一次 LLM 判定，又让落库正文变肿。
+ *
+ * 做法：在进 LLM 之前先做两级收拢，**只减条数、不改语义**：
+ *   ① 精确层：归一化（trim / NFKC 全半角 / 空白折叠 / 去零宽）后同内容即合并；
+ *   ② 向量层：**仅同 family + 同 type** 内、余弦 ≥ tau 贪心聚类。
+ * 代表项规则：正文最长者（等长取 priority 高者，再等取先出现者）；其 record_id 与 content
+ * **原样保留**，因此调用方可以把它自己的向量直接复用（正文没被改写，向量不会错配）。
+ *
+ * 明确不做：不产生合并正文（那是 LLM merge 的职责，见 ADR-0006 receipt 一致性）；
+ * 不跨族/跨类合并；不替调用方决定 store/skip。
+ */
+/** 聚类所需的最小结构（`PendingMemory` 天然满足）。 */
+export interface DedupeShaped {
+    record_id: string;
+    content: string;
+    priority?: number;
+    family?: string;
+    type?: string;
+    /** 只有部分调用方带这两个字段；带了就取并集，没带就不凭空造。 */
+    timestamps?: number[];
+    source_message_ids?: string[];
+}
+export interface ClusterOutcome<T> {
+    /** 代表项（原对象字段 + 并入的 priority/timestamps/source_message_ids）。 */
+    effective: T[];
+    /** 逐簇的吸收关系（供 receipt 审计）。 */
+    absorbed: Array<{
+        representative: string;
+        absorbed: string[];
+    }>;
+    /** 扁平映射：被吸收 id → 代表 id（写 receipt 用）。 */
+    absorbedBy: Record<string, string>;
+}
+/**
+ * 用于比较的归一化文本。
+ * NFKC 会把全角标点/字母折到半角；零宽字符（U+200B–200F / U+FEFF）直接剔除——
+ * 它们肉眼不可见，却足以让两条"同一句话"取不同 hash。
+ */
+export declare function normalizeForDedupe(s: string): string;
+/** 余弦相似度；任一向量缺失/长度不等/零向量时返回 undefined（不可比，绝不猜）。 */
+export declare function cosineMaybe(a: Float32Array | undefined, b: Float32Array | undefined): number | undefined;
+/**
+ * 精确层：归一化后同内容合并（含全半角/空白/零宽差异）。
+ * 空内容条目**不参与**合并（各自成簇）——正文为空是上游缺陷，静默吞掉会更难查。
+ */
+export declare function clusterExact<T extends DedupeShaped>(items: readonly T[]): ClusterOutcome<T>;
+/**
+ * 向量层：**仅同 family + 同 type** 组内，余弦 ≥ tau 即并入先出现的代表簇。
+ * 缺向量 / 长度不等 / 零向量 → 不可比，直接自成代表（不猜相似）。
+ * 先精确层、后本层是刻意顺序：精确重复不必再花一次比较，且能让代表项更稳定。
+ */
+export declare function clusterByVector<T extends DedupeShaped>(items: readonly T[], vectors: ReadonlyArray<Float32Array | undefined>, tau: number): ClusterOutcome<T>;
+/** `preDedupeBatch` 的可注入口：向量获取（失败可抛，由本函数降级）。 */
+export type EmbedManyFn = (texts: string[]) => Promise<Array<Float32Array | undefined>>;
+export interface PreDedupeOpts {
+    /** 缺省 true；false 直接透传（行为与改动前逐字节一致）。 */
+    enabled?: boolean;
+    /** 有效区间 0.85–0.99，越界 clamp 并通过 onWarn 留痕（不抛）。 */
+    tau?: number;
+    onWarn?: (msg: string) => void;
+}
+export interface PreDedupeResult<T> {
+    effective: T[];
+    /** 代表项 record_id → 该正文的向量（候选召回与写侧复用同一份）。 */
+    vectors: Map<string, Float32Array>;
+    absorbedBy: Record<string, string>;
+    /** 三级计数（日志与用例断言用）。 */
+    raw: number;
+    exact: number;
+    vector: number;
+}
+/**
+ * 一次完成：精确层 → （可选）向量层，并把“代表项→向量”与“被吸收→代表”两表一并交回。
+ *
+ * 嵌入不可用时**降级只做精确层**（catch 后留一条 warn），绝不因向量故障阻断蒸馏——
+ * 它只是省 LLM 判定与写侧重嵌的优化，不是正确性前置。
+ */
+export declare function preDedupeBatch<T extends DedupeShaped>(items: readonly T[], embedMany: EmbedManyFn, opts?: PreDedupeOpts): Promise<PreDedupeResult<T>>;

package/dist/pipeline/intra-dedupe.js

@@ -0,0 +1,224 @@
+/**
+ * L1 **批内自去重**（同轮/同会话）——纯函数，零 IO、零 import 副作用。
+ *
+ * 为什么需要它（#现场取证，见 .agents/plans/pm-dedupe-scale-drsc-hint/findings.md §4）：
+ * 既有 L1 去重只把**新记忆**和**库里的候选**对比（`store.searchCandidates`），同一批
+ * `extracted[]` 之间**从不互相比较**。于是同一段对话被抽成多条碎片时，它们会一起进同一条
+ * ≤20 条的 LLM 去重 prompt，只能由模型产出 `merged_content` 把内容"摞在一起"——
+ * 既费一次 LLM 判定，又让落库正文变肿。
+ *
+ * 做法：在进 LLM 之前先做两级收拢，**只减条数、不改语义**：
+ *   ① 精确层：归一化（trim / NFKC 全半角 / 空白折叠 / 去零宽）后同内容即合并；
+ *   ② 向量层：**仅同 family + 同 type** 内、余弦 ≥ tau 贪心聚类。
+ * 代表项规则：正文最长者（等长取 priority 高者，再等取先出现者）；其 record_id 与 content
+ * **原样保留**，因此调用方可以把它自己的向量直接复用（正文没被改写，向量不会错配）。
+ *
+ * 明确不做：不产生合并正文（那是 LLM merge 的职责，见 ADR-0006 receipt 一致性）；
+ * 不跨族/跨类合并；不替调用方决定 store/skip。
+ */
+/**
+ * 用于比较的归一化文本。
+ * NFKC 会把全角标点/字母折到半角；零宽字符（U+200B–200F / U+FEFF）直接剔除——
+ * 它们肉眼不可见，却足以让两条"同一句话"取不同 hash。
+ */
+export function normalizeForDedupe(s) {
+    return s
+        .normalize('NFKC')
+        .replace(/[\u200b-\u200f\ufeff]/gu, '')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+/** 余弦相似度；任一向量缺失/长度不等/零向量时返回 undefined（不可比，绝不猜）。 */
+export function cosineMaybe(a, b) {
+    if (!a || !b || a.length === 0 || a.length !== b.length)
+        return undefined;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return undefined;
+    return dot / Math.sqrt(na * nb);
+}
+/** 代表项判定：正文最长 → priority 高 → 先出现。返回簇内下标。 */
+function pickRepresentative(items, idx) {
+    let best = idx[0];
+    for (const i of idx) {
+        const a = items[i];
+        const b = items[best];
+        const la = a.content.length;
+        const lb = b.content.length;
+        if (la > lb)
+            best = i;
+        else if (la === lb) {
+            const pa = a.priority ?? 0;
+            const pb = b.priority ?? 0;
+            if (pa > pb)
+                best = i;
+            // 等长等优先级：保留先出现者（不覆盖 best）
+        }
+    }
+    return best;
+}
+function unionNums(parts) {
+    const all = parts.filter((p) => Array.isArray(p));
+    if (all.length === 0)
+        return undefined;
+    return Array.from(new Set(all.flat())).sort((x, y) => x - y);
+}
+function unionStrs(parts) {
+    const all = parts.filter((p) => Array.isArray(p));
+    if (all.length === 0)
+        return undefined;
+    return Array.from(new Set(all.flat()));
+}
+/** 把一簇下标压成「代表项 + 吸收清单」。代表项字段保持原样，只并入可并集字段。 */
+function collapse(items, idx) {
+    const repIdx = pickRepresentative(items, idx);
+    const rep = items[repIdx];
+    const absorbed = idx.filter((i) => i !== repIdx).map((i) => items[i].record_id);
+    const ts = unionNums(idx.map((i) => items[i].timestamps));
+    const src = unionStrs(idx.map((i) => items[i].source_message_ids));
+    const maxPriority = idx.reduce((m, i) => Math.max(m, items[i].priority ?? 0), rep.priority ?? 0);
+    const merged = {
+        ...rep,
+        ...(maxPriority > 0 ? { priority: maxPriority } : {}),
+        ...(ts === undefined ? {} : { timestamps: ts }),
+        ...(src === undefined ? {} : { source_message_ids: src }),
+    };
+    return { rep: merged, absorbed };
+}
+function finish(items, clusters) {
+    const effective = [];
+    const absorbed = [];
+    const absorbedBy = {};
+    for (const idx of clusters) {
+        const { rep, absorbed: absorbedIds } = collapse(items, idx);
+        effective.push(rep);
+        if (absorbedIds.length > 0) {
+            absorbed.push({ representative: rep.record_id, absorbed: absorbedIds });
+            for (const id of absorbedIds)
+                absorbedBy[id] = rep.record_id;
+        }
+    }
+    return { effective, absorbed, absorbedBy };
+}
+/**
+ * 精确层：归一化后同内容合并（含全半角/空白/零宽差异）。
+ * 空内容条目**不参与**合并（各自成簇）——正文为空是上游缺陷，静默吞掉会更难查。
+ */
+export function clusterExact(items) {
+    if (items.length === 0)
+        return { effective: [], absorbed: [], absorbedBy: {} };
+    const byKey = new Map();
+    const order = [];
+    items.forEach((it, i) => {
+        const key = normalizeForDedupe(it.content);
+        if (key.length === 0) {
+            // 空内容单独成簇：用 record_id 做键，保证永不与别人合并
+            byKey.set(`\u0000${it.record_id}#${i}`, [i]);
+            order.push(`\u0000${it.record_id}#${i}`);
+            return;
+        }
+        const prev = byKey.get(key);
+        if (prev)
+            prev.push(i);
+        else {
+            byKey.set(key, [i]);
+            order.push(key);
+        }
+    });
+    return finish(items, order.map((k) => byKey.get(k)));
+}
+/**
+ * 向量层：**仅同 family + 同 type** 组内，余弦 ≥ tau 即并入先出现的代表簇。
+ * 缺向量 / 长度不等 / 零向量 → 不可比，直接自成代表（不猜相似）。
+ * 先精确层、后本层是刻意顺序：精确重复不必再花一次比较，且能让代表项更稳定。
+ */
+export function clusterByVector(items, vectors, tau) {
+    if (items.length === 0)
+        return { effective: [], absorbed: [], absorbedBy: {} };
+    const threshold = Number.isFinite(tau) ? Math.min(0.9999, Math.max(0.5, tau)) : 0.92;
+    const clusters = [];
+    /** groupKey → 该组已建立的代表簇下标（簇在 clusters 里的位置）。 */
+    const repsByGroup = new Map();
+    items.forEach((it, i) => {
+        const group = `${it.family ?? ''}\u0000${it.type ?? ''}`;
+        const repIdx = repsByGroup.get(group);
+        if (repIdx) {
+            const vec = vectors[i];
+            let hit;
+            let bestScore = -Infinity;
+            for (const ci of repIdx) {
+                const cand = clusters[ci][0];
+                const score = cosineMaybe(vec, vectors[cand]);
+                if (score !== undefined && score >= threshold && score > bestScore) {
+                    bestScore = score;
+                    hit = ci;
+                }
+            }
+            if (hit !== undefined) {
+                clusters[hit].push(i);
+                return;
+            }
+        }
+        const ci = clusters.length;
+        clusters.push([i]);
+        const list = repsByGroup.get(group);
+        if (list)
+            list.push(ci);
+        else
+            repsByGroup.set(group, [ci]);
+    });
+    return finish(items, clusters);
+}
+/**
+ * 一次完成：精确层 → （可选）向量层，并把“代表项→向量”与“被吸收→代表”两表一并交回。
+ *
+ * 嵌入不可用时**降级只做精确层**（catch 后留一条 warn），绝不因向量故障阻断蒸馏——
+ * 它只是省 LLM 判定与写侧重嵌的优化，不是正确性前置。
+ */
+export async function preDedupeBatch(items, embedMany, opts = {}) {
+    if (opts.enabled === false || items.length === 0) {
+        return { effective: [...items], vectors: new Map(), absorbedBy: {}, raw: items.length, exact: items.length, vector: items.length };
+    }
+    const tauRaw = opts.tau ?? 0.92;
+    const tau = Math.min(0.99, Math.max(0.85, Number.isFinite(tauRaw) ? tauRaw : 0.92));
+    if (tau !== tauRaw)
+        opts.onWarn?.(`[memory] extract.intraBatchCosine=${tauRaw} 超出有效区间 0.85–0.99，已按 ${tau} 处理`);
+    const exact = clusterExact(items);
+    let vecs = exact.effective.map(() => undefined);
+    const exactVecById = new Map();
+    try {
+        vecs = await embedMany(exact.effective.map((m) => m.content));
+        exact.effective.forEach((m, i) => {
+            const v = vecs[i];
+            if (v)
+                exactVecById.set(m.record_id, v);
+        });
+    }
+    catch (err) {
+        opts.onWarn?.(`[memory] L1 批内向量不可用，仅做精确层: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const byVec = clusterByVector(exact.effective, vecs, tau);
+    // 只回最终代表项的向量：被向量层吸收的条目（如 r3）虽然自己算过向量，但它不会入库，
+    // 留在表里只会误导写侧（按 record_id 查得到，却根本没有这条记录）。
+    const vectors = new Map();
+    for (const m of byVec.effective) {
+        const v = exactVecById.get(m.record_id);
+        if (v)
+            vectors.set(m.record_id, v);
+    }
+    return {
+        effective: byVec.effective,
+        vectors,
+        absorbedBy: { ...exact.absorbedBy, ...byVec.absorbedBy },
+        raw: items.length,
+        exact: exact.effective.length,
+        vector: byVec.effective.length,
+    };
+}