dsh-layered-memory 0.6.1 → 0.7.0

package/dist/store/embedding-source.js

@@ -0,0 +1,421 @@
+/**
+ * 嵌入源状态层 + 活切换管理器（D4/D5/D6 决策落地）。
+ *
+ * - 状态文件 embedding-source.json（写穿持久化，session-modes 同款：内存态 + 原子写
+ *   + 写队列串行化）；无文件 = remote（与历史行为完全一致，老用户无感）；
+ * - 生效 = 部署上限 AND 运行时选择（仓库铁律）：远程档要求静态四件套配齐，
+ *   本地档受 embedding.allowLocalModels 上限约束；
+ * - 活切换链（后台执行，RPC 立即返回 accepted，进度靠轮询）：
+ *   安装运行时（首次本地）→ 预热加载 → 换服务 + swapProvider（维度变化 drop 向量表）
+ *   → 后台全量重嵌（L1/L0 计数进度，可取消）→ 持久化状态。
+ *   失败语义：异常（安装失败/模型加载失败/db 拒绝）→ 状态不持久化，重启回到旧源；
+ *   重嵌取消/部分失败 → 已切换（物理表即新维度，meta 已同步），缺失向量由周期
+ *   backfill 补齐——不回滚（回滚需要再 drop 一次表，得不偿失）。
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { NoopEmbeddingService, RemoteEmbeddingService } from './embedding.js';
+import { catalogById, MODEL_CATALOG } from './model-catalog.js';
+import { LocalEmbeddingService } from './local-embedding.js';
+// ── 状态存储（写穿持久化） ──
+export class EmbeddingSourceStore {
+    state = { source: 'remote', activeModel: null };
+    file;
+    writeQueue = Promise.resolve();
+    logger;
+    constructor(dataDir, logger) {
+        this.file = path.join(dataDir, 'embedding-source.json');
+        this.logger = logger;
+    }
+    get() {
+        return { ...this.state };
+    }
+    async init() {
+        try {
+            const raw = await fs.readFile(this.file, 'utf8');
+            const parsed = JSON.parse(raw);
+            if ((parsed.source === 'remote' || parsed.source === 'local' || parsed.source === 'off') &&
+                (parsed.activeModel === null || typeof parsed.activeModel === 'string')) {
+                this.state = { source: parsed.source, activeModel: parsed.activeModel };
+            }
+            else {
+                this.logger?.warn('[memory] 嵌入源状态文件损坏，按默认 remote 起步');
+            }
+        }
+        catch {
+            // 无文件 = 历史行为（跟随部署配置的远程嵌入）
+        }
+    }
+    async set(next) {
+        this.state = { source: next.source, activeModel: next.activeModel };
+        this.writeQueue = this.writeQueue.then(() => this.persist()).catch(() => { });
+        await this.writeQueue;
+    }
+    async persist() {
+        const tmp = this.file + '.tmp';
+        await fs.writeFile(tmp, JSON.stringify(this.state, null, 2), 'utf8');
+        await fs.rename(tmp, this.file);
+    }
+}
+/** 远程档部署上限：静态四件套 + enabled。 */
+export function remoteCeiling(cfg) {
+    const e = cfg.embedding;
+    return e.enabled && !!e.baseUrl && !!e.apiKey && !!e.model && e.dimensions > 0;
+}
+export async function resolveInitialEmbedding(cfg, sourceStore, downloader, makeLocal, logger) {
+    const state = sourceStore.get();
+    if (state.source === 'off') {
+        return { svc: new NoopEmbeddingService(), dims: 0 };
+    }
+    if (state.source === 'local') {
+        if (!cfg.embedding.allowLocalModels) {
+            logger?.warn('[memory] 嵌入源为 local 但部署已禁用本地模型（allowLocalModels=false），本次运行纯 FTS');
+            return { svc: new NoopEmbeddingService(), dims: 0, note: '部署配置已禁用本地嵌入模型' };
+        }
+        const entry = state.activeModel ? catalogById(state.activeModel) : undefined;
+        if (!entry) {
+            logger?.warn(`[memory] 嵌入源 local 的模型 ${state.activeModel} 不在目录，本次运行纯 FTS`);
+            return { svc: new NoopEmbeddingService(), dims: 0, note: '启用的模型不在内置目录' };
+        }
+        if (!(await downloader.isDownloaded(entry.id))) {
+            logger?.warn(`[memory] 本地模型 ${entry.id} 文件缺失（可能被清理），本次运行纯 FTS`);
+            return { svc: new NoopEmbeddingService(), dims: 0, note: '模型文件缺失，请重新下载' };
+        }
+        const svc = makeLocal(entry.id);
+        if (!svc)
+            return { svc: new NoopEmbeddingService(), dims: 0, note: '本地服务构造失败' };
+        return { svc, dims: entry.dims, providerInfo: { provider: 'local', model: entry.id, dimensions: entry.dims } };
+    }
+    // remote（默认）
+    if (!remoteCeiling(cfg)) {
+        return { svc: new NoopEmbeddingService(), dims: 0 };
+    }
+    const svc = new RemoteEmbeddingService({
+        baseUrl: cfg.embedding.baseUrl,
+        apiKey: cfg.embedding.apiKey,
+        model: cfg.embedding.model,
+        dimensions: cfg.embedding.dimensions,
+        maxInputChars: cfg.embedding.maxInputChars,
+        timeoutMs: cfg.embedding.timeoutMs,
+        logger,
+    });
+    return { svc, dims: cfg.embedding.dimensions, providerInfo: svc.getProviderInfo() };
+}
+/** 本地服务构造工厂（index.ts 的初始解析与 Manager 共用一份实现，防漂移）。 */
+export function makeLocalServiceFactory(installer, downloader, logger) {
+    return (modelId) => {
+        const entry = catalogById(modelId);
+        if (!entry)
+            return null;
+        return new LocalEmbeddingService(entry, downloader.modelsDir(entry.id), () => Promise.resolve(installer.resolveModule()), logger);
+    };
+}
+export class EmbeddingManager {
+    sourceStore;
+    installer;
+    downloader;
+    deps;
+    current;
+    localSvc = null;
+    applyPhase = 'idle';
+    applyMessage = '';
+    applyStartedAt = 0;
+    applyBusy = false;
+    reindex = {
+        running: false,
+        l1Done: 0,
+        l1Total: 0,
+        l0Done: 0,
+        l0Total: 0,
+        startedAt: 0,
+        cancelled: false,
+    };
+    reindexCancel = false;
+    /** 停机标志：dispose 后应用链不再推进（防卸载后的孤儿重嵌/安装）。 */
+    disposedFlag = false;
+    /** 当前生效目标的 providerInfo（backfill/启动链的 meta 写入用——杜绝陈旧闭包）。 */
+    currentInfo;
+    /** 初始解析的降级说明（活切换成功后清空，防过期提示常驻）。 */
+    activeNote;
+    constructor(deps) {
+        this.deps = deps;
+        this.sourceStore = deps.sourceStore;
+        this.installer = deps.installer;
+        this.downloader = deps.downloader;
+        this.current = deps.initial.svc;
+        this.currentInfo = deps.initial.providerInfo;
+        this.activeNote = deps.initial.note;
+        // 启动即本地档：initial.svc 已是绑定真实运行时 loader 的 LocalEmbeddingService。
+        // 立即后台预热（不阻塞启动）——否则 L1/L0.reindex 与 EmbedHelper.batch 的
+        // vectorReady 短路都不会触发懒加载，缺失向量要等到首次召回才补（review A）
+        if (deps.initial.providerInfo?.provider === 'local') {
+            this.localSvc = this.current;
+            this.localSvc.startWarmup();
+        }
+    }
+    /** 当前目标的 providerInfo（index.ts 的启动重嵌链/周期 backfill 写 meta 用）。 */
+    currentProviderInfo() {
+        return this.currentInfo;
+    }
+    /** 取消运行时安装（RPC：npm 卡死/用户主动放弃）。 */
+    cancelRuntimeInstall() {
+        return this.installer.cancel();
+    }
+    /** 当前生效服务（index.ts 初始建 store 用）。 */
+    getService() {
+        return this.current;
+    }
+    /** 构造绑定真实运行时 loader 的本地服务（deps.makeLocal 可注入，测试替换）。 */
+    makeLocalService(modelId) {
+        const factory = this.deps.makeLocal ?? makeLocalServiceFactory(this.installer, this.downloader, this.deps.logger);
+        return factory(modelId);
+    }
+    /** 活切换请求：验证通过即接受，后台执行应用链（进度轮询可见）。 */
+    requestSource(next) {
+        if (this.applyBusy)
+            return { accepted: false, error: '切换进行中，请等待完成' };
+        if (next.source === 'remote' && !remoteCeiling(this.deps.cfg)) {
+            return { accepted: false, error: '部署未配置远程嵌入（baseUrl/apiKey/model/dimensions 或 enabled），远程档不可选' };
+        }
+        if (next.source === 'local') {
+            if (!this.deps.cfg.embedding.allowLocalModels) {
+                return { accepted: false, error: '部署已禁用本地嵌入模型（allowLocalModels=false）' };
+            }
+            if (!next.activeModel || !catalogById(next.activeModel)) {
+                return { accepted: false, error: '请选择内置目录中的模型' };
+            }
+        }
+        const state = {
+            source: next.source,
+            activeModel: next.source === 'local' ? next.activeModel : null,
+        };
+        this.applyBusy = true;
+        this.applyStartedAt = Date.now();
+        this.applyMessage = '';
+        void this.applyChain(state).finally(() => {
+            this.applyBusy = false;
+        });
+        return { accepted: true };
+    }
+    /** 下载启动（串行队列忙时拒绝）；完成后自动做一次可加载性预热验证（D6）。 */
+    startDownload(modelId) {
+        if (!this.deps.cfg.embedding.allowLocalModels) {
+            return { ok: false, error: '部署已禁用本地嵌入模型' };
+        }
+        if (!catalogById(modelId))
+            return { ok: false, error: '未知模型' };
+        if (this.downloader.isBusy())
+            return { ok: false, error: '已有下载任务进行中' };
+        void this.downloader
+            .start(modelId)
+            .then(async (p) => {
+            if (p.phase !== 'done')
+                return;
+            // 下载完成自动预热验证：当前启用模型 → 直接 warmup；未启用的临时模型验完即释放
+            if (this.sourceStore.get().source === 'local' && this.sourceStore.get().activeModel === modelId) {
+                this.localSvc?.startWarmup();
+                return;
+            }
+            const scratch = this.makeLocalService(modelId);
+            if (!scratch)
+                return;
+            if (await this.installer.isReady()) {
+                // 预热只为验证可加载性：完成后必须释放（bge-m3 ~550MB，不关就常驻泄漏，
+                // 且 onnxruntime 持文件句柄会卡住该模型的删除）
+                scratch.startWarmup();
+                void scratch.waitForReady().then(() => scratch.close(), () => scratch.close());
+            }
+        })
+            .catch(() => {
+            /* 失败态在 downloader 进度里 */
+        });
+        return { ok: true };
+    }
+    cancelDownload() {
+        return this.downloader.cancel();
+    }
+    async deleteModel(modelId) {
+        const state = this.sourceStore.get();
+        if (state.source === 'local' && state.activeModel === modelId) {
+            return { ok: false, error: '该模型正在使用中，请先切换嵌入源' };
+        }
+        return this.downloader.deleteModel(modelId);
+    }
+    cancelReindex() {
+        if (!this.reindex.running)
+            return false;
+        this.reindexCancel = true;
+        return true;
+    }
+    /** 应用链/后台任务是否在跑（backfill 并发门禁用）。 */
+    isBusy() {
+        return this.applyBusy || this.reindex.running || this.downloader.isBusy();
+    }
+    /** 停机钩子（插件 dispose）：取消 npm 安装、下载与重嵌——不留后台孤儿任务。 */
+    dispose() {
+        this.disposedFlag = true;
+        this.installer.cancel();
+        this.downloader.cancel();
+        this.cancelReindex();
+        this.localSvc?.close();
+    }
+    async applyChain(next) {
+        try {
+            let svc;
+            let providerInfo;
+            if (next.source === 'off') {
+                this.applyPhase = 'switching';
+                svc = new NoopEmbeddingService();
+                providerInfo = undefined;
+                this.currentInfo = undefined;
+            }
+            else if (next.source === 'remote') {
+                this.applyPhase = 'switching';
+                svc = new RemoteEmbeddingService({
+                    baseUrl: this.deps.cfg.embedding.baseUrl,
+                    apiKey: this.deps.cfg.embedding.apiKey,
+                    model: this.deps.cfg.embedding.model,
+                    dimensions: this.deps.cfg.embedding.dimensions,
+                    maxInputChars: this.deps.cfg.embedding.maxInputChars,
+                    timeoutMs: this.deps.cfg.embedding.timeoutMs,
+                    logger: this.deps.logger,
+                });
+                providerInfo = svc.getProviderInfo();
+            }
+            else {
+                // local：下载完整性前置校验 → 运行时 → 预热 → 切换
+                if (!(await this.downloader.isDownloaded(next.activeModel))) {
+                    throw new Error('模型文件不完整（未下载或已损坏），请先完成下载');
+                }
+                if (!(await this.installer.isReady())) {
+                    this.applyPhase = 'installing-runtime';
+                    const ok = await this.installer.ensure();
+                    if (!ok) {
+                        throw new Error(`运行时安装失败: ${this.installer.getProgress().error ?? '未知原因'}`);
+                    }
+                }
+                if (this.disposedFlag)
+                    throw new Error('插件已卸载，切换中止');
+                this.applyPhase = 'warming';
+                const local = this.makeLocalService(next.activeModel);
+                if (!local)
+                    throw new Error('模型不在目录');
+                await local.waitForReady();
+                svc = local;
+                providerInfo = local.getProviderInfo();
+                this.applyPhase = 'switching';
+            }
+            // 换服务 + 换表（providerInfo 变化 → drop 向量表按新维度重建）
+            let needsReindex = false;
+            if (providerInfo) {
+                const swap = this.deps.db.swapProvider(providerInfo);
+                if (!swap.ok)
+                    throw new Error(swap.error ?? '切换向量引擎失败');
+                needsReindex = swap.needsReindex;
+                // 物理表在 swap 成功那一刻已是新维度——meta 立即跟上（即使后续重嵌被取消/
+                // 部分失败）：meta 的语义是"物理表现状"，缺失行由 backfill 按 missing 计数补，
+                // 不依赖 meta。拖着不写会把"meta=旧 provider"留给下次比对埋雷。
+                this.deps.db.markEmbeddingSynced(providerInfo);
+                this.currentInfo = providerInfo;
+            }
+            const oldLocal = this.localSvc;
+            this.localSvc = next.source === 'local' ? svc : null;
+            this.current = svc;
+            this.deps.l0.setEmbeddingService(svc);
+            this.deps.l1.setEmbeddingService(svc);
+            oldLocal?.close();
+            let pendingNote = '';
+            if (needsReindex) {
+                if (this.disposedFlag)
+                    throw new Error('插件已卸载，重嵌入中止');
+                this.applyPhase = 'reindexing';
+                const result = await this.reindexNow();
+                if (result.cancelled) {
+                    pendingNote = '；重嵌入已取消，缺失向量由周期任务补齐';
+                    this.deps.logger.warn('[memory] 重嵌入已取消，缺失向量将由周期补齐（检索暂按关键词降级）');
+                }
+                else if (result.failedTotal > 0) {
+                    pendingNote = `；${result.failedTotal} 条向量待补齐（周期任务会补）`;
+                }
+                if (result.error)
+                    throw new Error(result.error);
+            }
+            await this.sourceStore.set(next);
+            this.activeNote = undefined;
+            this.applyPhase = 'done';
+            this.applyMessage =
+                next.source === 'off'
+                    ? '已切换为关键词检索'
+                    : '切换完成' + pendingNote;
+        }
+        catch (err) {
+            this.applyPhase = 'error';
+            this.applyMessage = err instanceof Error ? err.message : String(err);
+            this.deps.logger.warn(`[memory] 嵌入源切换失败（状态保持不变）: ${this.applyMessage}`);
+        }
+    }
+    async reindexNow() {
+        this.reindexCancel = false;
+        this.reindex = { running: true, l1Done: 0, l1Total: 0, l0Done: 0, l0Total: 0, startedAt: Date.now(), cancelled: false };
+        let failedTotal = 0;
+        try {
+            const r1 = await this.deps.l1.reindex({
+                onProgress: (done, total) => {
+                    this.reindex.l1Done = done;
+                    this.reindex.l1Total = total;
+                },
+                shouldCancel: () => this.reindexCancel,
+            });
+            failedTotal += r1.failed;
+            const r0 = await this.deps.l0.reindex({
+                onProgress: (done, total) => {
+                    this.reindex.l0Done = done;
+                    this.reindex.l0Total = total;
+                },
+                shouldCancel: () => this.reindexCancel,
+            });
+            failedTotal += r0.failed;
+            const cancelled = !!(r1.cancelled || r0.cancelled);
+            this.reindex.cancelled = cancelled;
+            this.reindex.running = false;
+            return { cancelled, failedTotal };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.reindex.running = false;
+            this.reindex.error = message;
+            return { cancelled: false, failedTotal, error: `重嵌入失败: ${message}` };
+        }
+    }
+    /** RPC 快照（设置页嵌入区块数据源；client 忙时 1s 轮询）。 */
+    async snapshot() {
+        const status = await this.downloader.listStatus();
+        const models = MODEL_CATALOG.map((entry) => {
+            const s = status.find((x) => x.id === entry.id);
+            return {
+                id: entry.id,
+                name: entry.name,
+                dims: entry.dims,
+                contextTokens: entry.contextTokens,
+                tags: entry.tags,
+                description: entry.description,
+                totalBytes: s?.totalBytes ?? 0,
+                bytesOnDisk: s?.bytesOnDisk ?? 0,
+                state: s?.state ?? 'none',
+            };
+        });
+        const state = this.sourceStore.get();
+        return {
+            source: state.source,
+            activeModel: state.activeModel,
+            ceilings: { remote: remoteCeiling(this.deps.cfg), local: this.deps.cfg.embedding.allowLocalModels },
+            runtime: this.installer.getProgress(),
+            models,
+            download: this.downloader.getProgress(),
+            apply: { phase: this.applyPhase, message: this.applyMessage, startedAt: this.applyStartedAt, busy: this.applyBusy },
+            local: this.localSvc ? { state: this.localSvc.getState(), error: this.localSvc.getLoadError() } : null,
+            reindex: { ...this.reindex },
+            activeNote: this.activeNote,
+        };
+    }
+}

package/dist/store/embedding.d.ts

@@ -55,10 +55,12 @@ export declare class RemoteEmbeddingService implements EmbeddingService {
  * 同类失败只告警一次，避免刷屏。
  */
 export declare class EmbedHelper {
-    private readonly embed;
+    private embed;
     private readonly logger?;
     private warned;
     constructor(embed: EmbeddingService, logger?: MemoryLogger | undefined);
+    /** 活切换嵌入源（D4/D5）：换掉底层服务并复位一次性告警（新服务重新获得告警机会）。 */
+    setService(svc: EmbeddingService): void;
     vectorReady(): boolean;
     /** 查询向量；失败或空向量返回 undefined（调用方降级 FTS）。 */
     query(text: string): Promise<Float32Array | undefined>;

package/dist/store/embedding.js

@@ -95,6 +95,11 @@ export class EmbedHelper {
         this.embed = embed;
         this.logger = logger;
     }
+    /** 活切换嵌入源（D4/D5）：换掉底层服务并复位一次性告警（新服务重新获得告警机会）。 */
+    setService(svc) {
+        this.embed = svc;
+        this.warned = false;
+    }
     vectorReady() {
         return this.embed.isReady();
     }

package/dist/store/l0.d.ts

@@ -1,12 +1,12 @@
 import type { ConversationMessage, L0MessageRecord, MemoryLogger } from '../types.js';
 import { type EmbeddingService } from './embedding.js';
-import type { MemoryDb } from './sqlite.js';
+import { type MemoryDb } from './sqlite.js';
 export declare class L0Store {
     private readonly db;
     private readonly dir;
     private readonly legacyDir;
     private readonly helper;
-    private readonly embedSvc;
+    private embedSvc;
     private readonly logger?;
     constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, logger?: MemoryLogger);
     init(): Promise<void>;
@@ -17,12 +17,20 @@ export declare class L0Store {
     countToday(): Promise<number>;
     /** 检索：FTS + 向量 hybrid（RRF 融合），返回按相关性排序的消息。 */
     search(query: string, limit: number): Promise<L0MessageRecord[]>;
+    /** 活切换嵌入源：同步换底层服务（嵌入源三态切换用）。 */
+    setEmbeddingService(svc: EmbeddingService): void;
     /**
-     * 全量重嵌入（embedding 启用 / 周期性补齐用）。
-     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     * 增量重嵌入（同 L1Store.reindex：只补缺失向量，零向量记 skipped 并入 skip 集，
+     * 不算失败、不阻塞同步标记——保证补齐判据收敛）。onProgress/shouldCancel
+     * 供活切换（D5）的进度展示与取消。
      */
-    reindex(): Promise<{
+    reindex(opts?: {
+        onProgress?: (done: number, total: number) => void;
+        shouldCancel?: () => boolean;
+    }): Promise<{
         written: number;
         failed: number;
+        skipped: number;
+        cancelled?: boolean;
     }>;
 }

package/dist/store/l0.js

@@ -8,6 +8,7 @@ import * as path from 'node:path';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, nowIso, readJsonl } from './io.js';
 import { rrfMerge } from './search-utils.js';
+import { isZeroVector } from './sqlite.js';
 /** 官方过度召回倍数（conversation-search：limit × 3）。 */
 const CANDIDATE_MULTIPLIER = 3;
 export class L0Store {
@@ -115,18 +116,33 @@ export class L0Store {
         }
         return this.db.searchL0Fts(query, limit).map(({ score: _score, ...r }) => r);
     }
+    /** 活切换嵌入源：同步换底层服务（嵌入源三态切换用）。 */
+    setEmbeddingService(svc) {
+        this.embedSvc = svc;
+        this.helper.setService(svc);
+    }
     /**
-     * 全量重嵌入（embedding 启用 / 周期性补齐用）。
-     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     * 增量重嵌入（同 L1Store.reindex：只补缺失向量，零向量记 skipped 并入 skip 集，
+     * 不算失败、不阻塞同步标记——保证补齐判据收敛）。onProgress/shouldCancel
+     * 供活切换（D5）的进度展示与取消。
      */
-    async reindex() {
+    async reindex(opts) {
         if (!this.helper.vectorReady())
-            return { written: 0, failed: 0 };
-        const items = this.db.getL0ForReindex();
+            return { written: 0, failed: 0, skipped: 0 };
+        const items = this.db.getL0ForReindex(this.db.getVecSkipSet('l0'));
+        const total = items.length;
+        let done = 0;
         let written = 0;
         let failed = 0;
+        let skipped = 0;
+        let cancelled = false;
+        const skippedNow = [];
         const CHUNK = 32;
         for (let i = 0; i < items.length; i += CHUNK) {
+            if (opts?.shouldCancel?.()) {
+                cancelled = true;
+                break;
+            }
             const chunk = items.slice(i, i + CHUNK);
             let vecs;
             try {
@@ -134,15 +150,26 @@ export class L0Store {
             }
             catch {
                 failed += chunk.length;
+                done += chunk.length;
+                opts?.onProgress?.(done, total);
                 continue;
             }
             chunk.forEach((c, j) => {
+                if (isZeroVector(vecs[j])) {
+                    skipped++;
+                    skippedNow.push(c.id);
+                    return;
+                }
                 if (this.db.updateL0Vec(c.id, vecs[j], ''))
                     written++;
                 else
                     failed++;
             });
+            done += chunk.length;
+            opts?.onProgress?.(done, total);
         }
-        return { written, failed };
+        if (skippedNow.length > 0)
+            this.db.addVecSkippedIds('l0', skippedNow);
+        return { written, failed, skipped, cancelled };
     }
 }

package/dist/store/l1.d.ts

@@ -1,6 +1,6 @@
 import type { L1Hit, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
 import { type EmbeddingService } from './embedding.js';
-import type { MemoryDb } from './sqlite.js';
+import { type MemoryDb } from './sqlite.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
 export interface L1SearchOptions {
     /** 按记忆类型精确过滤（后置过滤，官方做法）。 */
@@ -17,7 +17,7 @@ export declare class L1Store {
     private readonly recordsDir;
     private readonly legacyFile;
     private readonly helper;
-    private readonly embedSvc;
+    private embedSvc;
     private readonly logger?;
     constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger);
     init(): Promise<void>;
@@ -32,6 +32,8 @@ export declare class L1Store {
     appendNew(records: MemoryRecord[]): Promise<void>;
     /** 去重 update/merge 产出的记录：只更新检索库（JSONL 事实源不改写，官方语义）。 */
     upsert(record: MemoryRecord): Promise<void>;
+    /** 活切换嵌入源：同步换底层服务（嵌入源三态切换用）。 */
+    setEmbeddingService(svc: EmbeddingService): void;
     deleteBatch(ids: string[]): Promise<void>;
     /**
      * 三策略检索（自动召回与 memory_search 工具共用接缝）。
@@ -59,12 +61,20 @@ export declare class L1Store {
      */
     searchCandidates(query: string, limit: number, family?: MemoryFamily): Promise<MemoryRecord[]>;
     /**
-     * 全量重嵌入（embedding 配置变化 / 周期性补齐用）。
-     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     * 增量重嵌入（embedding 配置变化 / 周期性补齐用）：只处理缺失向量的记录，
+     * 排除已判定"当前 provider 不可嵌入"的 skip 集。返回写入/失败/跳过数——
+     * failed > 0 时调用方不应标记 meta 同步完成；skipped（零向量）不算失败、
+     * 不阻塞同步标记（否则补齐判据永不收敛，每 30 分钟全量重嵌死循环）。
+     * onProgress/shouldCancel 供活切换（D5）的进度展示与取消。
      */
-    reindex(): Promise<{
+    reindex(opts?: {
+        onProgress?: (done: number, total: number) => void;
+        shouldCancel?: () => boolean;
+    }): Promise<{
         written: number;
         failed: number;
+        skipped: number;
+        cancelled?: boolean;
     }>;
     private postProcess;
 }