dsh-prime-memory 0.26.29 → 0.26.31

package/dist/pipeline/intra-dedupe.js

@@ -0,0 +1,239 @@
+/**
+ * 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);
+}
+/**
+ * 把「被吸收 → 代表」关系映射成 receipt 输入项。
+ *
+ * 为什么用既有 `kind='merge'` + `candidateIds=[代表 id]` 而不新增表列/词表即可：
+ * 吸收本质上就是「本条被并入另一条」，`merge` 正是这个词；`candidateIds` 载代表项 id，
+ * 于是「本条被批内哪条吸收」只需一次 `(runId, recordId)` 回溯（inputDigest 含代表 id）。
+ * 关闭特性时 `absorbedBy` 为空 ⇒ 不产生任何额外行（凭证与改动前逐字节一致）。
+ */
+export function receiptItemsForAbsorbed(absorbedBy) {
+    return Object.entries(absorbedBy).map(([absorbedId, repId]) => ({
+        recordId: absorbedId,
+        candidateIds: [repId],
+        action: 'merge',
+    }));
+}
+/**
+ * 一次完成：精确层 → （可选）向量层，并把“代表项→向量”与“被吸收→代表”两表一并交回。
+ *
+ * 嵌入不可用时**降级只做精确层**（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,
+    };
+}

package/dist/pipeline/l1.js

@@ -16,6 +16,7 @@ import { normTags, normUsageScenario, readCognitiveHall, readWing } from '../met
 import { acceptTitle } from '../util/md-name.js';
 import { clampPriority } from '../util/priority.js';
 import { formatBatchConflictPrompt, getConflictDetectionSystemPrompt } from '../prompts/l1-dedup.js';
+import { preDedupeBatch, receiptItemsForAbsorbed } from './intra-dedupe.js';
 import { resolveSourceAnchors, withSourceAnchors } from './anchors.js';
 import { stampValidity, validToSourceOf } from '../store/validity.js';
 import { familyForType, normPersistence, normScope, resolveRecordFamily, resolveRecordScope, WING_FALLBACK } from '../types.js';
@@ -456,10 +457,30 @@ routeHealth) {
         markExtracted(states, mode, lastScene);
         return { stored: 0, skipped: false, sceneName: lastScene, newRecords: [], failedMessages: [] };
     }
+    // ── Step 1.5: 批内自去重（同轮/同会话）──
+    // 根因：候选池只来自库，同批 extracted[] 之间从不互比 → 同一段对话抽出的多条碎片
+    // 全被塞进同一条 LLM 批，只能靠模型的 merged_content 把内容"撬在一起"。
+    // 逻辑全在 `preDedupeBatch`（可注入 embedMany，故不必驱动 LLM 就能单测接线）。
+    const pre = await preDedupeBatch(extracted, (texts) => store.embedMany(texts), {
+        enabled: cfg.extract.intraBatchDedupe !== false,
+        tau: cfg.extract.intraBatchCosine ?? 0.92,
+        onWarn: (m) => logger.warn(m),
+    });
+    const effective = pre.effective;
+    /** 代表项 record_id → 其**本正文**的向量（候选召回与写侧复用同一份，免二次嵌入）。 */
+    const vecByRecordId = pre.vectors;
+    /** 批内吸收关系（被吸收 record_id → 代表 record_id），给 receipt 审计用。 */
+    const intraAbsorbedBy = pre.absorbedBy;
+    if (cfg.extract.intraBatchDedupe !== false) {
+        logger.info(`[memory] L1 批内自去重:raw=${pre.raw} exact=${pre.exact} ` +
+            `vector=${pre.vector} effective=${effective.length}（吸收 ${Object.keys(intraAbsorbedBy).length} 条）`);
+    }
     // ── Step 2: 去重(batch 冲突检测;候选只在本族内召回,去重永不跨族) ──
-    const matches = await Promise.all(extracted.map(async (m) => ({
+    const matches = await Promise.all(effective.map(async (m) => ({
         newMemory: m,
-        candidates: await store.searchCandidates(m.content, cfg.extract.candidatePool, m.family, wsFilter),
+        candidates: await store.searchCandidates(m.content, cfg.extract.candidatePool, m.family, wsFilter, {
+            queryVector: vecByRecordId.get(m.record_id),
+        }),
     })));
     // 按固定条数切块发送,失败半径与上下文同时可控(#10 去重侧同精)
     const dedupBatches = [];
@@ -492,12 +513,12 @@ routeHealth) {
     }
     // 去重决策统计:无决策的记录按 skip 处理,聚合成单行日志便于排查
     const actionCount = {};
-    for (const m of extracted) {
+    for (const m of effective) {
         const action = byRecord.get(m.record_id)?.action ?? 'skip(未返回)';
         actionCount[action] = (actionCount[action] ?? 0) + 1;
     }
     const candidateTotal = matches.reduce((n, m) => n + m.candidates.length, 0);
-    logger.info(`[memory] L1 去重判定:${extracted.length} 条候选记忆召回 ${candidateTotal} 条已有记录,决策 ${Object.entries(actionCount)
+    logger.info(`[memory] L1 去重判定:${effective.length} 条候选记忆召回 ${candidateTotal} 条已有记录,决策 ${Object.entries(actionCount)
         .map(([k, v]) => `${k}=${v}`)
         .join(' ')}`);
     // ── §B 决策凭证:在应用决策前留痕(旁路设施,写失败绝不中断蒸馏) ──
@@ -512,12 +533,17 @@ routeHealth) {
     const runId = newRunId();
     let byKind;
     {
-        const items = extracted.map((m, i) => ({
+        const items = effective.map((m, i) => ({
             recordId: m.record_id,
             candidateIds: (matches[i]?.candidates ?? []).map((c) => c.id),
             action: byRecord.get(m.record_id)?.action,
         }));
-        const rows = buildReceipts(runId, new Date().toISOString(), items);
+        // 批内被吸收的条目也必须留痕：否则「这条为何没进库」在库里完全查不到（skip 是现有
+        // 唯一零痕迹分支，批内吸收不能重蹈）。用既有 `kind='merge'` + candidateIds=[代表 id]：
+        // 不新增表列、不扩词表，回答“本条被批内哪条吸收”只需一次 (runId, recordId) 回溯。
+        // 关闭特性时 intraAbsorbedBy 为空 ⇒ 凭证与改动前逐字节一致。
+        const absorbedItems = receiptItemsForAbsorbed(intraAbsorbedBy);
+        const rows = buildReceipts(runId, new Date().toISOString(), [...items, ...absorbedItems]);
         persistReceiptsSafely((rows) => store.recordReceipts(rows), rows, logger);
         // §F 追踪捎带:六值决策词表聚合(与凭证同源,runner 侧并入 distill_run 事件)
         byKind = rows.reduce((acc, r) => {
@@ -544,7 +570,7 @@ routeHealth) {
      *    不成对而回落 store**(2026-09-18 取证确认,见 findings R6 / Agent A);
      * ② 队满自动了结的护栏 —— 败方若属本批新记忆,不得自动退场(见下方分支)。
      */
-    const batchIds = new Set(extracted.map((e) => e.record_id));
+    const batchIds = new Set(effective.map((e) => e.record_id));
     /**
      * update/merge 取代掉的旧记录 → **取代它的**新记录 id。
      * 用 Map 而非 Set:退场标记要带 `by`,否则"被谁取代"只能靠时间猜。
@@ -560,7 +586,7 @@ routeHealth) {
      */
     const rejected = [];
     const now = Date.now();
-    for (const m of extracted) {
+    for (const m of effective) {
         const decision = byRecord.get(m.record_id);
         if (!decision || decision.action === 'skip')
             continue;
@@ -746,7 +772,14 @@ routeHealth) {
         stampValidity(mergedRec, now, mt.validToSource);
         added.push(mergedRec);
     }
-    await store.appendNew(added);
+    await store.appendNew(added, {
+        vectors: added.map((r) => {
+            // 写侧复用：代表项正文未被改写 → 复用批内向量（免掉同一条记忆的第二次嵌入）。
+            // merge/update 产出的 merged_content 是**新文本**，同 record_id 也不得复用。
+            const orig = effective.find((m) => m.record_id === r.id)?.content;
+            return orig !== undefined && orig === r.content ? vecByRecordId.get(r.id) : undefined;
+        }),
+    });
     if (supersededBy.size > 0) {
         // **软删**(取代):不是物理删除——主表行保留 + 取代标记(marker 单源，门1 解耦后
         // 不再闭合 valid_to)，FTS/向量撤出检索面。于是"合并错了"也能恢复,而不必去
@@ -826,7 +859,7 @@ routeHealth) {
         states[f].memoriesSinceL3 += addedByFamily[f];
     }
     markExtracted(states, mode, lastScene);
-    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(取代退场 ${supersededBy.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
+    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条(批内收拢 ${effective.length}),去重后新增 ${added.length} 条(取代退场 ${supersededBy.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
     return { stored: added.length, skipped: false, sceneName: lastScene, newRecords: added, runId, byKind, failedMessages };
 }
 /** auto 档取最近活跃的族 checkpoint(情境链/计数锚点)。 */

package/dist/stats.js

@@ -18,6 +18,7 @@ import { EFFORT_CHOICES, resolveDataDir } from './config.js';
 import { typeCatalogEntries } from './memory-types.js';
 import { effectiveCfg } from './pipeline/runner.js';
 import { emptyRecallStats } from './hooks/recall.js';
+import { probeDrscHealth } from './clients/drsc-inproc.js';
 import { buildRouteChain, decideSendableEffort, LAYER_DEFAULT_BUDGETS, layerChainOrNull, resolveModelContextWindow, resolveModelEfforts, resolveModelRoute } from './llm.js';
 import { mergeRoom, renameRoom, mergeRoomCatalog } from './room-review.js';
 import { scanSources } from './memport/scan.js';
@@ -122,6 +123,7 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/llm-providers',
     'dsh-memory/llm-models',
     'dsh-memory/embedding-state-get',
+    'dsh-memory/drsc-health',
     'dsh-memory/embedding-source-set',
     'dsh-memory/embedding-download-start',
     'dsh-memory/embedding-download-cancel',
@@ -2354,6 +2356,11 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const v = { supported: true, ...(await embedManager.snapshot()) };
             return v;
         }
+        // DRSC 健康（设置面板 banner）：纯观测，不改读写路径，故不依赖 ctx/embedManager。
+        case 'dsh-memory/drsc-health': {
+            const v = await probeDrscHealth();
+            return v;
+        }
         case 'dsh-memory/embedding-source-set': {
             if (!embedManager)
                 throw new Error('嵌入管理器未初始化(存储不可用)');

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

@@ -69,7 +69,9 @@ export declare function makeLocalServiceFactory(installer: RuntimeInstaller, dow
 /** 测试注入缝:子进程资产路径(源码态下 dist 产物不存在,显式指向 resources 源文件)。 */
 childPath?: string, 
 /** 本地推理 token 预算(config `embedding.maxInputTokens`;0/缺省 = 按模型窗口与硬上限推导)。 */
-maxInputTokens?: number): (modelId: string) => LocalEmbeddingService | null;
+maxInputTokens?: number, 
+/** 崩溃有界自愈开关(config `embedding.respawnOnCrash`;缺省 true,与 LocalEmbeddingService 内默认一致)。 */
+respawnOnCrash?: boolean): (modelId: string) => LocalEmbeddingService | null;
 export interface EmbeddingManagerDeps {
     dataDir: string;
     cfg: MemoryConfig;

package/dist/store/embedding-source.js

@@ -159,7 +159,9 @@ export function makeLocalServiceFactory(installer, downloader, logger, maxInputC
 /** 测试注入缝:子进程资产路径(源码态下 dist 产物不存在,显式指向 resources 源文件)。 */
 childPath, 
 /** 本地推理 token 预算(config `embedding.maxInputTokens`;0/缺省 = 按模型窗口与硬上限推导)。 */
-maxInputTokens) {
+maxInputTokens, 
+/** 崩溃有界自愈开关(config `embedding.respawnOnCrash`;缺省 true,与 LocalEmbeddingService 内默认一致)。 */
+respawnOnCrash) {
     return (modelId) => {
         const entry = catalogById(modelId);
         if (!entry)
@@ -170,6 +172,7 @@ maxInputTokens) {
             logger,
             maxInputChars,
             maxInputTokens,
+            respawnOnCrash,
         });
     };
 }
@@ -250,7 +253,7 @@ 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, undefined, this.deps.cfg.embedding.maxInputTokens);
+            makeLocalServiceFactory(this.installer, this.downloader, this.deps.logger, this.deps.cfg.embedding.maxInputChars, undefined, this.deps.cfg.embedding.maxInputTokens, this.deps.cfg.embedding.respawnOnCrash);
         return factory(modelId);
     }
     /** 活切换请求:验证通过即接受,后台执行应用链(进度轮询可见)。 */

package/dist/store/l1.d.ts

@@ -335,10 +335,18 @@ export declare class L1Store {
     }): ConflictPair[];
     /** §C 打上裁决结论(已裁决的不覆盖)。 */
     resolveConflictPending(pairId: string, resolution: ConflictResolution, resolvedAt: string): number;
-    /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。 */
-    appendNew(records: MemoryRecord[]): Promise<void>;
-    /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。 */
-    upsert(record: MemoryRecord): Promise<void>;
+    /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。
+     *
+     *  `opts.vectors`:调用方（L1 批内自去重）已算好的向量；非 undefined 位直接复用，
+     *  其余现嵌。长度不等时**整批回落实嵌**（不猜位置，宁可多嵌一次）。 */
+    appendNew(records: MemoryRecord[], opts?: {
+        vectors?: Array<Float32Array | undefined>;
+    }): Promise<void>;
+    /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。
+     *  `opts.vector`:同 `appendNew`，merge 产出的**新正文**通常不复用（调用方不传即现嵌）。 */
+    upsert(record: MemoryRecord, opts?: {
+        vector?: Float32Array;
+    }): Promise<void>;
     /** 活切换嵌入源:同步换底层服务(嵌入源三态切换用)。 */
     setEmbeddingService(svc: EmbeddingService): void;
     /** 向量写入能力是否就绪。`reindex` 在未就绪时**静默短路**成 0/0/0
@@ -500,6 +508,14 @@ export declare class L1Store {
     scanAllMetadata(cb: (recordId: string, metadata: Record<string, unknown> | null) => void): number;
     /** 查询向量(域软门禁用):复用既有嵌入源;失败/未就绪返回 undefined,调用方降级。 */
     embedText(text: string, timeoutMs?: number): Promise<Float32Array | undefined>;
+    /**
+     * 批量取向量（批内自去重用）：走与写侧同一条 `helper.batch`。
+     *
+     * 为什么不用逐条 `embedText`：批内代表项的向量要同时喂给「候选召回」与「写入腿」，
+     * 一次取回才能把「同一条记忆嵌两次」压成一次；且熔断态下 `batch` 统一返回 undefined，
+     * 调用方能自然降级为「只做精确层」，不必各自判错。
+     */
+    embedMany(texts: string[]): Promise<Array<Float32Array | undefined>>;
     /**
      * 去重候选召回(官方 3 级):空库跳过 → 向量优先 → FTS 兜底。
      * 传入 family 时只在同族记录里召回(去重永不跨族);传入 workspaceId 时
@@ -509,7 +525,14 @@ export declare class L1Store {
      * 理由:候选池决定**新的去重决策**,若此处跨工作区,产出的是「项目 B 里看不见、
      * 但已经决定了项目 A 记忆去向」的记录——比不隔离更糟。
      */
-    searchCandidates(query: string, limit: number, family?: MemoryFamily, workspaceId?: string): Promise<MemoryRecord[]>;
+    searchCandidates(query: string, limit: number, family?: MemoryFamily, workspaceId?: string, 
+    /**
+     * 调用方已算好的查询向量（批内自去重场景）：给了就不再内部重嵌一次。
+     * 不传 → 维持旧行为（内部 `helper.query`）。增参不改旧签名，既有调用零改动。
+     */
+    opts?: {
+        queryVector?: Float32Array;
+    }): Promise<MemoryRecord[]>;
     /**
      * 增量重嵌入(embedding 配置变化 / 周期性补齐用):只处理缺失向量的记录,
      * 排除已判定"当前 provider 不可嵌入"的 skip 集。返回写入/失败/跳过数——

package/dist/store/l1.js

@@ -486,8 +486,11 @@ export class L1Store {
     resolveConflictPending(pairId, resolution, resolvedAt) {
         return this.db.resolveConflictPending(pairId, resolution, resolvedAt);
     }
-    /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。 */
-    async appendNew(records) {
+    /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。
+     *
+     *  `opts.vectors`:调用方（L1 批内自去重）已算好的向量；非 undefined 位直接复用，
+     *  其余现嵌。长度不等时**整批回落实嵌**（不猜位置，宁可多嵌一次）。 */
+    async appendNew(records, opts) {
         if (records.length === 0)
             return;
         // 写侧标注汇流口(task_3.2):所有新写路径(pipeline / memory_add / import / memport /
@@ -512,7 +515,19 @@ export class L1Store {
         for (const [day, list] of byDay) {
             await appendJsonl(path.join(this.recordsDir, `${day}.jsonl`), list);
         }
-        const vecs = await this.helper.batch(records.map((r) => r.content));
+        const reuse = opts?.vectors;
+        let vecs;
+        if (reuse && reuse.length === records.length && reuse.some((v) => v !== undefined)) {
+            const missing = records.map((_, i) => i).filter((i) => reuse[i] === undefined);
+            const fresh = missing.length > 0 ? await this.helper.batch(missing.map((i) => records[i].content)) : [];
+            vecs = reuse.slice();
+            missing.forEach((ri, k) => {
+                vecs[ri] = fresh[k];
+            });
+        }
+        else {
+            vecs = await this.helper.batch(records.map((r) => r.content));
+        }
         // 单事务批量写:逐条开事务在 WAL FULL 下每条一次 fsync。
         // 双写失败闭环:JSONL 事实源已先行追加,DB 缺行 = 这批记忆检索不可见、
         // 去重候选缺失(重复记忆会累积)。upsert 内部已有逐条 warn,这里升 error
@@ -524,15 +539,16 @@ export class L1Store {
         // 写对称:新增也即时上盘(不阻塞、失败只 warn)——否则「文件树 = 库当前状态」只对删成立。
         this.fireFileSync(records.map((r) => r.id), 'appendNew');
     }
-    /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。 */
-    async upsert(record) {
+    /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。
+     *  `opts.vector`:同 `appendNew`，merge 产出的**新正文**通常不复用（调用方不传即现嵌）。 */
+    async upsert(record, opts) {
         if (!record.family)
             record.family = familyForType(record.type);
         // 写侧标注汇流口(与 appendNew 同口径):merge 分支会继承胜方的 name；
         // 两边都没名字时在这里补上，别让新铸的行继续带空名。
         stampValidity(record, Date.now());
         this.assignMissingNames([record], { persist: false });
-        const vec = (await this.helper.batch([record.content]))[0];
+        const vec = opts?.vector ?? (await this.helper.batch([record.content]))[0];
         if (!this.db.upsertL1(record, vec)) {
             this.logger?.error(`[memory] L1 检索库写入失败 id=${record.id}(JSONL 事实源完好),该记忆暂不可检索,重建可修复`);
         }
@@ -923,6 +939,16 @@ export class L1Store {
     embedText(text, timeoutMs) {
         return this.helper.query(text, timeoutMs);
     }
+    /**
+     * 批量取向量（批内自去重用）：走与写侧同一条 `helper.batch`。
+     *
+     * 为什么不用逐条 `embedText`：批内代表项的向量要同时喂给「候选召回」与「写入腿」，
+     * 一次取回才能把「同一条记忆嵌两次」压成一次；且熔断态下 `batch` 统一返回 undefined，
+     * 调用方能自然降级为「只做精确层」，不必各自判错。
+     */
+    embedMany(texts) {
+        return this.helper.batch(texts);
+    }
     /**
      * 去重候选召回(官方 3 级):空库跳过 → 向量优先 → FTS 兜底。
      * 传入 family 时只在同族记录里召回(去重永不跨族);传入 workspaceId 时
@@ -932,7 +958,12 @@ export class L1Store {
      * 理由:候选池决定**新的去重决策**,若此处跨工作区,产出的是「项目 B 里看不见、
      * 但已经决定了项目 A 记忆去向」的记录——比不隔离更糟。
      */
-    async searchCandidates(query, limit, family, workspaceId) {
+    async searchCandidates(query, limit, family, workspaceId, 
+    /**
+     * 调用方已算好的查询向量（批内自去重场景）：给了就不再内部重嵌一次。
+     * 不传 → 维持旧行为（内部 `helper.query`）。增参不改旧签名，既有调用零改动。
+     */
+    opts) {
         // 治理哨兵(治理 W0 T0.2):标记去重候选路径;治理权重误入即抛(dev/test)。
         return markDedupPath(async () => {
             if (this.db.countL1() === 0)
@@ -940,7 +971,7 @@ export class L1Store {
             const caps = this.db.getCapabilities();
             if (caps.vectorSearch && this.helper.vectorReady()) {
                 try {
-                    const vec = await this.helper.query(query);
+                    const vec = opts?.queryVector ?? (await this.helper.query(query));
                     if (vec) {
                         const hits = this.db.searchL1Vector(vec, limit, family, workspaceId);
                         if (hits.length > 0)
@@ -997,12 +1028,16 @@ export class L1Store {
             }
             const pending = [];
             chunk.forEach((c, j) => {
-                if (isZeroVector(vecs[j])) {
+                // #22 机理刀:断点续试只补「尾部未完段」,头 ack 段的向量随崩溃子进程一起丢了
+                // → embedBatch 对这些位返回空洞(undefined)。这里必须当作「本 chunk 暂未取到向量」跳过
+                // (交后台 backfill 逐条补),否则 undefined 进 isZeroVector 会抛 TypeError 打断整轮重嵌。
+                const vec = vecs[j];
+                if (vec == null || isZeroVector(vec)) {
                     skipped++;
                     skippedNow.push(c.id);
                     return;
                 }
-                pending.push({ id: c.id, embedding: vecs[j] });
+                pending.push({ id: c.id, embedding: vec });
             });
             if (pending.length > 0) {
                 const ok = this.db.updateL1VecBatch(pending);