dsh-layered-memory 0.6.0 → 0.7.0

package/dist/store/sqlite.js

@@ -23,11 +23,24 @@ const require = createRequire(import.meta.url);
 const TAG = '[memory][sqlite]';
 /** vec0 KNN 对遗留零向量的补偿缓冲（官方同款）。 */
 const ZERO_VEC_BUFFER = 10;
+/** IN 查询/删除的分块大小（保守避开 SQLite 变量数上限：现代构建 32766，老版 999）。 */
+const IN_CHUNK = 900;
+/** 零向量 skip 集上限（≤ IN_CHUNK：notInClause 不分块，占位符数即集合大小，须避开老构建 999 上限）。 */
+const VEC_SKIP_CAP = 900;
+/** 把 id 列表切成 ≤IN_CHUNK 的块（分块执行后合并语义等价于单次 IN）。 */
+function chunkIds(ids) {
+    const out = [];
+    for (let i = 0; i < ids.length; i += IN_CHUNK)
+        out.push(ids.slice(i, i + IN_CHUNK));
+    return out;
+}
 export class MemoryDb {
     db;
     degraded = false;
     ftsAvailable = false;
     vecLoaded = false;
+    vecLoadWarned = false;
+    /** 向量维度：活切换嵌入源（D5）时会变——vec0 表随维度重建。 */
     dimensions;
     logger;
     stmtUpsertL1;
@@ -41,6 +54,7 @@ export class MemoryDb {
     stmtL1FtsSearch;
     stmtL1FtsSearchFamily;
     stmtUpsertL0;
+    stmtGetL0;
     stmtDeleteL0Vec;
     stmtInsertL0Vec;
     stmtSearchL0Vec;
@@ -87,28 +101,93 @@ export class MemoryDb {
         // 构造期已降级（开库失败）→ 直接短路
         if (this.degraded)
             return { needsReindex: false, reason: 'database open failed' };
-        // dimensions=0 是合法的"纯 FTS 模式"，不能因 sqlite-vec 缺失而降级（官方语义）
-        if (this.dimensions > 0) {
+        // dimensions=0 是合法的"纯 FTS 模式"，不能因 sqlite-vec 缺失而降级（官方语义）；
+        // 后续活切换本地嵌入（维度 > 0）时由 swapProvider 补加载
+        this.ensureVecLoaded();
+        try {
+            return this.initSchema(providerInfo);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger?.error(`${TAG} schema 初始化失败，存储进入降级模式: ${message}`);
+            this.degraded = true;
+            return { needsReindex: false, reason: `schema init failed: ${message}` };
+        }
+    }
+    /** 惰性加载 sqlite-vec（纯 FTS 起步后切本地嵌入时补加载）；失败只停用向量能力并告警一次。 */
+    ensureVecLoaded() {
+        if (this.vecLoaded || this.dimensions <= 0)
+            return;
+        try {
+            const sqliteVec = require('sqlite-vec');
+            this.db.enableLoadExtension(true);
             try {
-                const sqliteVec = require('sqlite-vec');
-                this.db.enableLoadExtension(true);
                 sqliteVec.load(this.db);
-                this.db.enableLoadExtension(false);
                 this.vecLoaded = true;
             }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
+            finally {
+                // 加载失败也必须复位扩展开关，不留常开的扩展加载面
+                this.db.enableLoadExtension(false);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!this.vecLoadWarned) {
+                this.vecLoadWarned = true;
                 this.logger?.warn(`${TAG} sqlite-vec 加载失败，向量检索停用（降级为纯 FTS）: ${message}`);
             }
         }
+    }
+    /**
+     * 活切换嵌入源（D5）：provider/model/维度任一变化 → drop 向量表按新维度重建，
+     * 返回 needsReindex=true（调用方后台重嵌，全部成功后 markEmbeddingSynced）；
+     * 配置未变化 → false（切回同一模型不重嵌）。
+     * 新维度 > 0 但 sqlite-vec 不可用 → ok=false（调用方向用户说明，维持 FTS）。
+     */
+    swapProvider(info) {
+        if (this.degraded)
+            return { ok: false, needsReindex: false, error: '数据库降级模式' };
+        if (info.dimensions <= 0) {
+            // 关闭档不走此路径（只换服务实例）；防御性兜底：不动表，无需重嵌
+            this.dimensions = 0;
+            return { ok: true, needsReindex: false };
+        }
+        // 先置新维度再懒加载（ensureVecLoaded 以 dimensions>0 为门）——0 维起步的库
+        // 在首次活切本地/远程嵌入时此处补加载 sqlite-vec
+        this.dimensions = info.dimensions;
+        this.ensureVecLoaded();
+        if (!this.vecLoaded) {
+            return { ok: false, needsReindex: false, error: 'sqlite-vec 扩展不可用，无法启用向量检索' };
+        }
+        // unchanged 判据不能只信 embedding_meta：取消/崩溃路径可能留下"meta=旧 provider、
+        // 物理表=新维度"的错位（切换已 drop 并按新维度重建，但重嵌取消/失败没写 meta）。
+        // 只比对 meta 会在切回旧源时跳过 drop → 旧维度服务往新维度表写向量 → vec0 抛错
+        // → upsert 整体回滚 → 记录从检索库静默消失。必须同时校验物理表的真实维度。
+        const saved = this.readEmbeddingMeta();
+        const physical = this.physicalVecDims();
+        const unchanged = saved &&
+            saved.provider === info.provider &&
+            saved.model === info.model &&
+            saved.dimensions === info.dimensions &&
+            physical === info.dimensions;
+        if (unchanged)
+            return { ok: true, needsReindex: false };
+        this.dropVectorTables();
+        return { ok: true, needsReindex: true };
+    }
+    /** l1_vec 物理表的向量维度（建表 DDL 里的 float[N]）；无表返回 null。 */
+    physicalVecDims() {
         try {
-            return this.initSchema(providerInfo);
+            const row = this.db
+                .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'l1_vec'")
+                .get();
+            if (!row?.sql)
+                return null;
+            const m = /float\[(\d+)\]/.exec(row.sql);
+            return m ? Number(m[1]) : null;
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.logger?.error(`${TAG} schema 初始化失败，存储进入降级模式: ${message}`);
-            this.degraded = true;
-            return { needsReindex: false, reason: `schema init failed: ${message}` };
+        catch {
+            return null;
         }
     }
     initSchema(providerInfo) {
@@ -231,6 +310,7 @@ export class MemoryDb {
         recorded_at=excluded.recorded_at,
         timestamp=excluded.timestamp
     `);
+        this.stmtGetL0 = this.db.prepare('SELECT session_id, role, message_text, recorded_at, timestamp FROM l0_conversations WHERE record_id = ?');
         this.prepareL0VecStatements();
         // ── FTS5 全文索引（建表失败仅停用 FTS，不降级整个库） ──
         try {
@@ -374,6 +454,11 @@ export class MemoryDb {
     dropVectorTables() {
         this.db.exec('DROP TABLE IF EXISTS l1_vec');
         this.db.exec('DROP TABLE IF EXISTS l0_vec');
+        // 表已重建：作废按块缓存的 IN 语句（旧语句指向已删表，不能依赖引擎自动重编译兜底）
+        this.inStmts.clear();
+        // provider/model/维度已变：旧的"不可嵌入"判定作废（新 provider 可能嵌入得了），skip 集清空
+        this.clearVecSkipIds('l1');
+        this.clearVecSkipIds('l0');
         this.prepareL1VecStatements();
         this.prepareL0VecStatements();
     }
@@ -430,9 +515,10 @@ export class MemoryDb {
             .run('embedding_provider_info', JSON.stringify(info));
     }
     /**
-     * 标记当前向量与 embedding 配置同步完成（持久化 meta）。
-     * 只应在重嵌入成功（或空库无历史向量）后调用——过早写入会让下次启动
-     * 比对通过而跳过补齐，向量表永远空着（review P7）。
+     * 持久化 embedding meta（语义：物理向量表当前对应的 provider/维度）。
+     * 活切换在 swapProvider 成功后即写（表已是新维度）；启动/补齐链在
+     * 缺失向量补齐收敛（missing=0）后写——缺失行补齐判据是行数差，
+     * 不依赖 meta（review P7 语义在 backfill 计数判据下仍然收敛）。
      */
     markEmbeddingSynced(info) {
         if (this.degraded)
@@ -452,26 +538,9 @@ export class MemoryDb {
         if (this.degraded)
             return false;
         try {
-            const ts = timestampsToDb(record.timestamps);
             this.db.exec('BEGIN');
             try {
-                this.stmtUpsertL1.run(record.id, record.content, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
-                // vec0 不支持 ON CONFLICT → 先删后插；零向量跳过（cosine 未定义）
-                if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
-                    this.stmtDeleteL1Vec.run(record.id);
-                    if (embedding && !isZeroVector(embedding)) {
-                        this.stmtInsertL1Vec.run(record.id, vecToBuffer(embedding), toIso(record.updatedAt));
-                    }
-                }
-                if (this.ftsAvailable) {
-                    try {
-                        this.stmtL1FtsDelete.run(record.id);
-                        this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
-                    }
-                    catch (ftsErr) {
-                        this.logger?.warn(`${TAG} L1 FTS 写入失败（非致命）id=${record.id}: ${ftsErr instanceof Error ? ftsErr.message : String(ftsErr)}`);
-                    }
-                }
+                this.upsertL1InTx(record, embedding);
                 this.db.exec('COMMIT');
             }
             catch (err) {
@@ -490,32 +559,156 @@ export class MemoryDb {
             return false;
         }
     }
-    /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。 */
+    /**
+     * 批量 upsert L1（单事务；与单条同语义：FTS 失败整批回滚）。
+     * 追加/导入热路径用它——逐条开事务在 WAL FULL 下每条一次 fsync。
+     * 整批失败时回退逐条写入：好记录照常入库、坏记录只丢自身——否则
+     * JSONL 事实源已先行追加，检索库却整批缺失且无自动重导路径（批次空洞）。
+     */
+    upsertL1Batch(records, embeddings) {
+        if (this.degraded || records.length === 0)
+            return false;
+        try {
+            this.db.exec('BEGIN');
+            try {
+                for (let i = 0; i < records.length; i++) {
+                    this.upsertL1InTx(records[i], embeddings?.[i]);
+                }
+                this.db.exec('COMMIT');
+            }
+            catch (err) {
+                try {
+                    this.db.exec('ROLLBACK');
+                }
+                catch {
+                    /* ignore */
+                }
+                throw err;
+            }
+            return true;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 批量写入失败，回退逐条写入: ${err instanceof Error ? err.message : String(err)}`);
+            const failed = [];
+            for (let i = 0; i < records.length; i++) {
+                if (!this.upsertL1(records[i], embeddings?.[i]))
+                    failed.push(records[i]?.id ?? `#${i}`);
+            }
+            if (failed.length > 0) {
+                this.logger?.warn(`${TAG} 逐条回退后仍失败 ${failed.length}/${records.length} 条: ${failed.slice(0, 5).join(', ')}${failed.length > 5 ? '…' : ''}`);
+            }
+            return failed.length === 0;
+        }
+    }
+    /** 事务内的单条写入体（upsertL1 / upsertL1Batch 共用；调用方负责 BEGIN/COMMIT）。 */
+    upsertL1InTx(record, embedding) {
+        const ts = timestampsToDb(record.timestamps);
+        this.stmtUpsertL1.run(record.id, record.content, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
+        // vec0 不支持 ON CONFLICT → 先删后插；零向量跳过（cosine 未定义）
+        if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
+            this.stmtDeleteL1Vec.run(record.id);
+            if (embedding && !isZeroVector(embedding)) {
+                this.stmtInsertL1Vec.run(record.id, vecToBuffer(embedding), toIso(record.updatedAt));
+            }
+        }
+        // FTS 删除/插入与元数据同事务：失败必须整体回滚——若只吞 FTS 错误照常 COMMIT，
+        // 已执行的 DELETE 会让该 id 的索引行被删未补，记录从此全文检索不可见（静默丢数据）。
+        if (this.ftsAvailable) {
+            this.stmtL1FtsDelete.run(record.id);
+            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
+        }
+    }
+    /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。IN 按 ≤900 分块（避变量数上限）。 */
     deleteL1Batch(ids) {
         if (this.degraded || ids.length === 0)
             return 0;
         try {
-            const placeholders = ids.map(() => '?').join(',');
             this.db.exec('BEGIN');
-            this.db.prepare(`DELETE FROM l1_records WHERE record_id IN (${placeholders})`).run(...ids);
-            if (this.stmtDeleteL1Vec) {
-                this.db.prepare(`DELETE FROM l1_vec WHERE record_id IN (${placeholders})`).run(...ids);
+            try {
+                for (const chunk of chunkIds(ids))
+                    this.inStatement('l1_records', 'delete', chunk.length).run(...chunk);
+                if (this.stmtDeleteL1Vec) {
+                    for (const chunk of chunkIds(ids))
+                        this.inStatement('l1_vec', 'delete', chunk.length).run(...chunk);
+                }
+                if (this.ftsAvailable) {
+                    for (const chunk of chunkIds(ids))
+                        this.inStatement('l1_fts', 'delete', chunk.length).run(...chunk);
+                }
+                this.db.exec('COMMIT');
+                return ids.length;
             }
-            if (this.ftsAvailable) {
-                this.db.prepare(`DELETE FROM l1_fts WHERE record_id IN (${placeholders})`).run(...ids);
+            catch (err) {
+                try {
+                    this.db.exec('ROLLBACK');
+                }
+                catch {
+                    /* ignore */
+                }
+                throw err;
             }
-            this.db.exec('COMMIT');
-            return ids.length;
         }
         catch (err) {
+            this.logger?.warn(`${TAG} L1 批量删除失败: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
+    /** 按块缓存的 IN 语句（表名/动作/尺寸 → 预编译语句）：热路径不再每次动态 prepare。 */
+    inStmts = new Map();
+    inStatement(table, action, size) {
+        const key = `${table}:${action}:${size}`;
+        let stmt = this.inStmts.get(key);
+        if (!stmt) {
+            const ph = Array.from({ length: size }, () => '?').join(',');
+            stmt =
+                action === 'delete'
+                    ? this.db.prepare(`DELETE FROM ${table} WHERE record_id IN (${ph})`)
+                    : this.db.prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family FROM ${table} WHERE record_id IN (${ph})`);
+            this.inStmts.set(key, stmt);
+        }
+        return stmt;
+    }
+    /**
+     * 清空 L1 检索库全部数据（重建用）。records/FTS 直接 DELETE；
+     * 向量表走 DROP + 重建（vec0 的全表 DELETE 语义不可靠，dropVectorTables
+     * 会连 l0_vec 一起删——L0 向量必须保留——故此处单独处理 l1_vec）。
+     * L0 表与 embedding_meta 不动：backfill 的行数比对天然重新一致。
+     */
+    clearL1() {
+        if (this.degraded)
+            return false;
+        try {
+            this.db.exec('BEGIN');
             try {
-                this.db.exec('ROLLBACK');
+                this.db.exec('DELETE FROM l1_records');
+                if (this.ftsAvailable)
+                    this.db.exec('DELETE FROM l1_fts');
+                this.db.exec('COMMIT');
             }
-            catch {
-                /* ignore */
+            catch (err) {
+                try {
+                    this.db.exec('ROLLBACK');
+                }
+                catch {
+                    /* ignore */
+                }
+                throw err;
             }
-            this.logger?.warn(`${TAG} L1 批量删除失败: ${err instanceof Error ? err.message : String(err)}`);
-            return 0;
+            // vec0 全表 DELETE 语义不可靠 → DROP + 重建空表；放事务外（vtab DDL 事务性弱）。
+            // 中间态：向量行短暂孤儿——检索侧对缺 meta 的向量本就跳过（searchL1Vector 回查过滤）。
+            if (this.stmtDeleteL1Vec) {
+                this.db.exec('DROP TABLE IF EXISTS l1_vec');
+                this.prepareL1VecStatements();
+                this.inStmts.clear();
+            }
+            // 重建后 L1 id 全新，旧 skip 集是死数据，清空让新记录获得一次嵌入机会
+            this.clearVecSkipIds('l1');
+            this.logger?.info(`${TAG} L1 检索库已清空（重建）`);
+            return true;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 清空失败: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
         }
     }
     countL1() {
@@ -542,10 +735,10 @@ export class MemoryDb {
     getL1ByIds(ids) {
         if (this.degraded || ids.length === 0)
             return [];
-        const placeholders = ids.map(() => '?').join(',');
-        const rows = this.db
-            .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family FROM l1_records WHERE record_id IN (${placeholders})`)
-            .all(...ids);
+        const rows = [];
+        for (const chunk of chunkIds(ids)) {
+            rows.push(...this.inStatement('l1_records', 'select', chunk.length).all(...chunk));
+        }
         return rows.map(rowToRecord);
     }
     /** 浏览列表（UI 用）：按更新时间倒序，支持类型/场景/族过滤与分页。失败返回空。 */
@@ -676,13 +869,9 @@ export class MemoryDb {
                     }
                 }
                 if (this.ftsAvailable) {
-                    try {
-                        this.stmtL0FtsDelete.run(r.id);
-                        this.stmtL0FtsInsert.run(tokenizeForFts(r.content), r.content, r.id, r.sessionId, r.role, r.recordedAt, r.timestamp);
-                    }
-                    catch (ftsErr) {
-                        this.logger?.warn(`${TAG} L0 FTS 写入失败（非致命）id=${r.id}: ${ftsErr instanceof Error ? ftsErr.message : String(ftsErr)}`);
-                    }
+                    // 同 upsertL1：FTS 失败冒泡触发整批回滚，禁止"删了没补"的索引空洞。
+                    this.stmtL0FtsDelete.run(r.id);
+                    this.stmtL0FtsInsert.run(tokenizeForFts(r.content), r.content, r.id, r.sessionId, r.role, r.recordedAt, r.timestamp);
                 }
             }
             this.db.exec('COMMIT');
@@ -724,6 +913,42 @@ export class MemoryDb {
             return 0;
         }
     }
+    /** L0 全量列举（重建快照用；按时间升序，事务一致性避开 JSONL 追加竞态）。 */
+    listL0All() {
+        if (this.degraded)
+            return [];
+        try {
+            const rows = this.db
+                .prepare('SELECT record_id, session_id, role, message_text, recorded_at, timestamp FROM l0_conversations ORDER BY timestamp ASC')
+                .all();
+            return rows.map((r) => ({
+                sessionId: r.session_id,
+                recordedAt: r.recorded_at,
+                id: r.record_id,
+                role: r.role,
+                content: r.message_text,
+                timestamp: r.timestamp ?? 0,
+            }));
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L0 全量列举失败（返回空）: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    /** 重建成本预估（一次全表聚合：会话数 / 消息数 / 字符量）。 */
+    l0RebuildEstimate() {
+        if (this.degraded)
+            return { sessions: 0, messages: 0, chars: 0 };
+        try {
+            const row = this.db
+                .prepare('SELECT COUNT(DISTINCT session_id) AS s, COUNT(*) AS n, COALESCE(SUM(LENGTH(message_text)), 0) AS c FROM l0_conversations')
+                .get();
+            return { sessions: row?.s ?? 0, messages: row?.n ?? 0, chars: row?.c ?? 0 };
+        }
+        catch {
+            return { sessions: 0, messages: 0, chars: 0 };
+        }
+    }
     /** 向量表行数（backfill 判据：与元数据行数的差值即缺失向量数；不可用时返回 -1）。 */
     countL1Vec() {
         if (this.degraded || !this.stmtSearchL1Vec)
@@ -783,9 +1008,7 @@ export class MemoryDb {
             for (const { record_id, distance } of rows) {
                 if (distance == null || Number.isNaN(distance))
                     continue;
-                const row = this.db
-                    .prepare('SELECT session_id, role, message_text, recorded_at, timestamp FROM l0_conversations WHERE record_id = ?')
-                    .get(record_id);
+                const row = this.stmtGetL0.get(record_id);
                 if (!row)
                     continue;
                 hits.push({
@@ -808,19 +1031,124 @@ export class MemoryDb {
     // ============================
     // 重嵌入（reindexAll 用）
     // ============================
-    getL1ForReindex() {
+    /** L1 缺失向量的记录数（排除 skip 集后的补齐判据；向量能力不可用返回 -1）。 */
+    countL1VecMissing(exclude) {
+        if (this.degraded || !this.stmtSearchL1Vec)
+            return -1;
+        try {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) AS n FROM l1_records r
+           LEFT JOIN l1_vec v ON v.record_id = r.record_id
+           WHERE v.record_id IS NULL${notInClause('r.record_id', exclude)}`)
+                .all(...notInParams(exclude))[0];
+            return row?.n ?? 0;
+        }
+        catch (err) {
+            // -1 会让补齐判据（> 0）按"无缺失"处理——必须留痕，不能静默停摆
+            this.logger?.warn(`${TAG} L1 缺失向量计数失败（补齐判据按无缺失处理）: ${err instanceof Error ? err.message : String(err)}`);
+            return -1;
+        }
+    }
+    /** L0 缺失向量的记录数（同上）。 */
+    countL0VecMissing(exclude) {
+        if (this.degraded || !this.stmtSearchL0Vec)
+            return -1;
+        try {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) AS n FROM l0_conversations r
+           LEFT JOIN l0_vec v ON v.record_id = r.record_id
+           WHERE v.record_id IS NULL${notInClause('r.record_id', exclude)}`)
+                .all(...notInParams(exclude))[0];
+            return row?.n ?? 0;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L0 缺失向量计数失败（补齐判据按无缺失处理）: ${err instanceof Error ? err.message : String(err)}`);
+            return -1;
+        }
+    }
+    /**
+     * 待重嵌入的 L1：只取缺失向量的记录（增量），排除 skip 集里已判定
+     * "当前 provider 下不可嵌入（零向量）"的 id——缺 1 条不再全量重嵌，
+     * 零向量记录也不再反复喂给 embeddings API（H1 死循环双根因）。
+     */
+    getL1ForReindex(exclude) {
         if (this.degraded)
             return [];
-        return this.db
-            .prepare('SELECT record_id AS id, content FROM l1_records')
-            .all();
+        try {
+            return this.db
+                .prepare(`SELECT r.record_id AS id, r.content FROM l1_records r
+           LEFT JOIN l1_vec v ON v.record_id = r.record_id
+           WHERE v.record_id IS NULL${notInClause('r.record_id', exclude)}`)
+                .all(...notInParams(exclude));
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 重嵌入取数失败（返回空，本轮跳过）: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
     }
-    getL0ForReindex() {
+    /** 待重嵌入的 L0（增量 + 排除 skip 集，同 getL1ForReindex）。 */
+    getL0ForReindex(exclude) {
         if (this.degraded)
             return [];
-        return this.db
-            .prepare('SELECT record_id AS id, message_text AS text FROM l0_conversations')
-            .all();
+        try {
+            return this.db
+                .prepare(`SELECT r.record_id AS id, r.message_text AS text FROM l0_conversations r
+           LEFT JOIN l0_vec v ON v.record_id = r.record_id
+           WHERE v.record_id IS NULL${notInClause('r.record_id', exclude)}`)
+                .all(...notInParams(exclude));
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L0 重嵌入取数失败（返回空，本轮跳过）: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    // ── 零向量 skip 集（embedding_meta 持久化；provider 变化时随向量表一起清空） ──
+    getVecSkipSet(kind) {
+        if (this.degraded)
+            return new Set();
+        try {
+            const row = this.db
+                .prepare('SELECT value FROM embedding_meta WHERE key = ?')
+                .get(vecSkipKey(kind));
+            if (!row)
+                return new Set();
+            const parsed = JSON.parse(row.value);
+            if (!Array.isArray(parsed))
+                return new Set();
+            return new Set(parsed.filter((x) => typeof x === 'string'));
+        }
+        catch {
+            return new Set();
+        }
+    }
+    addVecSkippedIds(kind, ids) {
+        if (this.degraded || ids.length === 0)
+            return;
+        try {
+            let merged = [...new Set([...this.getVecSkipSet(kind), ...ids])];
+            // 上限防 NOT IN 占位符无界膨胀（老构建变量上限 999）；达到上限本身
+            // 说明 embedding 服务大面积返回零向量，被挤出的旧 id 只是多一次重试
+            if (merged.length > VEC_SKIP_CAP) {
+                merged = merged.slice(-VEC_SKIP_CAP);
+                this.logger?.warn(`${TAG} skip 集达上限 ${VEC_SKIP_CAP}（零向量记录过多，embedding 服务疑似异常）`);
+            }
+            this.db
+                .prepare('INSERT INTO embedding_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value')
+                .run(vecSkipKey(kind), JSON.stringify(merged));
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} skip 集写入失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    clearVecSkipIds(kind) {
+        if (this.degraded)
+            return;
+        try {
+            this.db.prepare('DELETE FROM embedding_meta WHERE key = ?').run(vecSkipKey(kind));
+        }
+        catch {
+            /* 空集语义，失败无影响 */
+        }
     }
     /** 只更新向量行（重嵌入用）。 */
     updateL1Vec(id, embedding) {
@@ -904,13 +1232,28 @@ function toIso(epochMs) {
         return '';
     return new Date(epochMs).toISOString();
 }
-function isZeroVector(vec) {
+/** 全零向量（cosine 未定义，不可入向量表）。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
+export function isZeroVector(vec) {
     for (const v of vec) {
         if (v !== 0)
             return false;
     }
     return true;
 }
+/** NOT IN 片段（空集 → 空串；配合 notInParams 使用）。 */
+function notInClause(column, exclude) {
+    if (!exclude || exclude.size === 0)
+        return '';
+    return ` AND ${column} NOT IN (${[...exclude].map(() => '?').join(',')})`;
+}
+function notInParams(exclude) {
+    if (!exclude || exclude.size === 0)
+        return [];
+    return [...exclude];
+}
+function vecSkipKey(kind) {
+    return kind === 'l1' ? 'embedding_zero_vec_l1' : 'embedding_zero_vec_l0';
+}
 /** DB 字符串 → 族（异常值按 type 前缀兜底归一）。 */
 function normFamily(raw, type) {
     if (raw === 'work' || raw === 'chat')

package/dist/store/state.d.ts

@@ -30,6 +30,12 @@ export declare class StateStore {
     get didMigrate(): boolean;
     /** 取某族的 checkpoint（活引用——改字段后 save 生效）。 */
     forFamily(family: MemoryFamily): MemoryState;
+    /**
+     * 重建用：两族 checkpoint 重置为默认值。
+     * 必须原地突变（Object.assign）——runner.states 等处持有桶对象的活引用，
+     * 换新对象会让引用指向已废弃的桶，后续计数写到内存孤儿上。
+     */
+    reset(): void;
     save(): Promise<void>;
     static pathFor(dataDir: string): string;
 }

package/dist/store/state.js

@@ -52,6 +52,17 @@ export class StateStore {
     forFamily(family) {
         return this.buckets[family];
     }
+    /**
+     * 重建用：两族 checkpoint 重置为默认值。
+     * 必须原地突变（Object.assign）——runner.states 等处持有桶对象的活引用，
+     * 换新对象会让引用指向已废弃的桶，后续计数写到内存孤儿上。
+     */
+    reset() {
+        for (const family of ['chat', 'work']) {
+            Object.assign(this.buckets[family], defaultState());
+            this.buckets[family].personaRequestedReason = undefined;
+        }
+    }
     async save() {
         const file = { version: 2, families: this.buckets };
         await atomicWriteJson(this.file, file);