dsh-prime-memory 0.11.0

package/dist/store/l0.js

@@ -0,0 +1,197 @@
+/**
+ * L0 原始对话存储(双写架构):
+ * - conversations/YYYY-MM-DD.jsonl:追加式事实源;
+ * - MemoryDb(SQLite):主检索引擎——检索不再按天扫文件、现建内存索引。
+ */
+import { existsSync, promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
+import { appendJsonl, dayKey, ensureDir, nowIso, readJsonl } from '../util/io.js';
+import { rrfMerge } from './search-utils.js';
+import { isZeroVector } from './sqlite.js';
+/** 官方过度召回倍数(conversation-search:limit × 3)。 */
+const CANDIDATE_MULTIPLIER = 3;
+export class L0Store {
+    db;
+    dir;
+    legacyDir;
+    helper;
+    embedSvc;
+    logger;
+    constructor(dataDir, db, embed = new NoopEmbeddingService(), logger) {
+        this.db = db;
+        this.dir = path.join(dataDir, 'conversations');
+        this.legacyDir = path.join(dataDir, 'l0');
+        this.embedSvc = embed;
+        this.helper = new EmbedHelper(embed, logger);
+        this.logger = logger;
+    }
+    async init() {
+        await ensureDir(this.dir);
+        await this.importLegacy();
+    }
+    /** 旧版 l0/*.jsonl 一次性导入检索库,成功后目录改名 l0.imported/。 */
+    async importLegacy() {
+        if (!existsSync(this.legacyDir))
+            return;
+        try {
+            const files = await fs.readdir(this.legacyDir).catch(() => []);
+            let imported = 0;
+            let total = 0;
+            for (const f of files.sort()) {
+                if (!f.endsWith('.jsonl'))
+                    continue;
+                const records = await readJsonl(path.join(this.legacyDir, f));
+                // 最小有效性门(同 L1 的 importLegacy):坏行读取时丢弃,按 valid 数判迁移完成
+                const valid = records.filter((r) => r && typeof r.id === 'string' && r.content);
+                const badCount = records.length - valid.length;
+                if (badCount > 0) {
+                    this.logger?.warn(`[memory] 旧版 L0 文件 ${f} 丢弃 ${badCount} 条坏行(缺 id/content)`);
+                }
+                if (valid.length > 0) {
+                    total += valid.length;
+                    if (this.db.upsertL0Batch(valid))
+                        imported += valid.length;
+                }
+            }
+            // 只有全部批次入库成功(或目录为空)才改名,避免数据被改名带走
+            if (imported === total) {
+                const renamed = await fs
+                    .rename(this.legacyDir, `${this.legacyDir}.imported`)
+                    .then(() => true, () => false);
+                if (renamed) {
+                    this.logger?.info(`[memory] 旧版 L0 数据已导入检索库 ${imported} 条(l0/ → l0.imported/)`);
+                }
+                else {
+                    this.logger?.warn('[memory] 旧版 L0 导入完成但改名失败(l0.imported/ 已存在?),下次启动会重复导入(幂等,无害)');
+                }
+            }
+            else {
+                this.logger?.warn(`[memory] 旧版 L0 导入不完整(${imported}/${total}),保留原目录下次重试`);
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] 旧版 L0 数据导入失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async append(sessionId, messages) {
+        if (messages.length === 0)
+            return;
+        const records = messages.map((m) => ({
+            sessionId,
+            recordedAt: nowIso(),
+            id: m.id,
+            role: m.role,
+            content: m.content,
+            timestamp: m.timestamp,
+        }));
+        // 事实源:按天追加
+        const byDay = new Map();
+        for (const r of records) {
+            const k = dayKey(r.timestamp);
+            const arr = byDay.get(k) ?? [];
+            arr.push(r);
+            byDay.set(k, arr);
+        }
+        for (const [day, list] of byDay) {
+            await appendJsonl(path.join(this.dir, `${day}.jsonl`), list);
+        }
+        // 检索引擎:DB + 向量(嵌入失败只跳过向量,不影响元数据/FTS,backfill 补齐)。
+        // 双写失败闭环:JSONL 事实源已先行追加,DB 缺行 = 这些消息检索不可见
+        // (conversation_search / 蒸馏背景参考都查不到)——升 error 并给自愈指引。
+        const vecs = await this.helper.batch(records.map((r) => r.content));
+        if (!this.db.upsertL0Batch(records, vecs)) {
+            this.logger?.error(`[memory] L0 检索库批量写入失败(${records.length} 条,JSONL 事实源完好),` +
+                '这些消息暂不可检索;可在设置页运行「重建记忆」修复');
+        }
+    }
+    /** 今日已捕获消息数(SQL 计数,不再读整文件)。 */
+    async countToday() {
+        const d = new Date();
+        return this.db.countL0Since(new Date(d.getFullYear(), d.getMonth(), d.getDate()).toISOString());
+    }
+    /** 该会话累计已捕获消息数(session-stats 数据源;索引 COUNT)。 */
+    async countBySession(sessionId) {
+        return this.db.countL0BySession(sessionId);
+    }
+    /** 该会话最近 n 条消息(时间升序;蒸馏背景参考用,按会话现查——ADR-0003)。 */
+    async recentBySession(sessionId, limit) {
+        return this.db.recentL0BySession(sessionId, limit);
+    }
+    /** 检索:FTS + 向量 hybrid(RRF 融合),返回按相关性排序的消息。 */
+    async search(query, limit) {
+        const caps = this.db.getCapabilities();
+        if (!caps.ftsSearch && !caps.vectorSearch)
+            return [];
+        const candidateK = limit * CANDIDATE_MULTIPLIER;
+        if (caps.vectorSearch && this.helper.vectorReady()) {
+            const [ftsRaw, vec] = await Promise.all([
+                Promise.resolve(this.db.searchL0Fts(query, candidateK)),
+                this.helper.query(query),
+            ]);
+            const vecList = vec ? this.db.searchL0Vector(vec, candidateK) : [];
+            const merged = rrfMerge([ftsRaw, vecList], (h) => h.id);
+            return merged.map(({ rrfScore: _rrf, ...r }) => r).slice(0, limit);
+        }
+        return this.db.searchL0Fts(query, limit).map(({ score: _score, ...r }) => r);
+    }
+    /** 活切换嵌入源:同步换底层服务(嵌入源三态切换用)。 */
+    setEmbeddingService(svc) {
+        this.embedSvc = svc;
+        this.helper.setService(svc);
+    }
+    /**
+     * 增量重嵌入(同 L1Store.reindex:只补缺失向量,零向量记 skipped 并入 skip 集,
+     * 不算失败、不阻塞同步标记——保证补齐判据收敛)。onProgress/shouldCancel
+     * 供活切换的进度展示与取消。
+     */
+    async reindex(opts) {
+        if (!this.helper.vectorReady())
+            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 {
+                vecs = await this.embedSvc.embedBatch(chunk.map((c) => c.text));
+            }
+            catch {
+                failed += chunk.length;
+                done += chunk.length;
+                opts?.onProgress?.(done, total);
+                continue;
+            }
+            const pending = [];
+            chunk.forEach((c, j) => {
+                if (isZeroVector(vecs[j])) {
+                    skipped++;
+                    skippedNow.push(c.id);
+                    return;
+                }
+                pending.push({ id: c.id, embedding: vecs[j] });
+            });
+            if (pending.length > 0) {
+                const ok = this.db.updateL0VecBatch(pending, '');
+                written += ok;
+                failed += pending.length - ok;
+            }
+            done += chunk.length;
+            opts?.onProgress?.(done, total);
+        }
+        if (skippedNow.length > 0)
+            this.db.addVecSkippedIds('l0', skippedNow);
+        return { written, failed, skipped, cancelled };
+    }
+}

package/dist/store/l1.d.ts

@@ -0,0 +1,93 @@
+import type { L1Hit, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+import { type EmbeddingService } from './embedding.js';
+import { type MemoryDb } from './sqlite.js';
+export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
+export interface L1SearchOptions {
+    /** 按记忆类型精确过滤(后置过滤,官方做法)。 */
+    type?: string;
+    /** 按族过滤(undefined = 不过滤,即 auto 档与浏览路径;检索唯一缝的族语义)。 */
+    family?: MemoryFamily;
+    /** 分数阈值(仅召回路径传;keyword/embedding 策略生效,FTS 含小语料例外;
+     *  hybrid 按官方语义在 RRF 融合前不过滤)。 */
+    scoreThreshold?: number;
+    /** 嵌入查询内层钳制(ms,只缩短不放大;召回路径传入给 FTS 降级留时间)。 */
+    embeddingTimeoutMs?: number;
+}
+export declare class L1Store {
+    private readonly db;
+    private readonly strategy;
+    private readonly recordsDir;
+    private readonly legacyFile;
+    private readonly helper;
+    private embedSvc;
+    private readonly logger?;
+    /** 时效衰减半衰期(天;0=关)。 */
+    private readonly decayHalfLifeDays;
+    constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger, 
+    /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
+    decayHalfLifeDays?: number);
+    init(): Promise<void>;
+    /** 旧版单文件 records.jsonl 一次性导入检索库,成功后改名 .imported。 */
+    private importLegacy;
+    get size(): number;
+    /** 全量读取(调试/迁移用;检索请走 search)。 */
+    all(): MemoryRecord[];
+    /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
+    getByIds(ids: string[]): MemoryRecord[];
+    /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。 */
+    appendNew(records: MemoryRecord[]): Promise<void>;
+    /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。 */
+    upsert(record: MemoryRecord): Promise<void>;
+    /** 活切换嵌入源:同步换底层服务(嵌入源三态切换用)。 */
+    setEmbeddingService(svc: EmbeddingService): void;
+    deleteBatch(ids: string[]): Promise<void>;
+    /**
+     * 三策略检索(自动召回与 memory_search 工具共用接缝)。
+     * embedding 不可用时自动降级 keyword;type 后置过滤;
+     * scoreThreshold 仅对 keyword/embedding 单路策略生效——hybrid 按官方语义
+     * 融合完整列表(融合分已归一化 0~1,可直接用于展示/过滤)。
+     */
+    search(query: string, limit: number, opts?: L1SearchOptions): Promise<L1Hit[]>;
+    /**
+     * 时效衰减加权(#29):三路共用的读路径后处理——阈值过滤之后、截断之前
+     * (才能轮转名额,而不只是重排已截断的集合)。updated_at 经主表批量点查
+     * 回填(FTS 表无该列;候选池 ≤ limit×3 条主键查询,微秒级)。关闭时零开销。
+     */
+    private applyDecay;
+    /** 浏览列表(UI 用):无关键词时按更新时间倒序分页,支持 Hall 过滤。 */
+    list(opts: {
+        type?: string;
+        scene?: string;
+        family?: string;
+        hall?: string;
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    /** 场景名去重列表(UI 筛选器数据源)。 */
+    distinctScenes(): string[];
+    /**
+     * 去重候选召回(官方 3 级):空库跳过 → 向量优先 → FTS 兜底。
+     * 传入 family 时只在同族记录里召回(去重永不跨族)。
+     */
+    searchCandidates(query: string, limit: number, family?: MemoryFamily): Promise<MemoryRecord[]>;
+    /**
+     * 增量重嵌入(embedding 配置变化 / 周期性补齐用):只处理缺失向量的记录,
+     * 排除已判定"当前 provider 不可嵌入"的 skip 集。返回写入/失败/跳过数——
+     * failed > 0 时调用方不应标记 meta 同步完成;skipped(零向量)不算失败、
+     * 不阻塞同步标记(否则补齐判据永不收敛,周期性全量重嵌死循环)。
+     * onProgress/shouldCancel 供活切换的进度展示与取消。
+     */
+    reindex(opts?: {
+        onProgress?: (done: number, total: number) => void;
+        shouldCancel?: () => boolean;
+    }): Promise<{
+        written: number;
+        failed: number;
+        skipped: number;
+        cancelled?: boolean;
+    }>;
+    private postProcess;
+}

package/dist/store/l1.js

@@ -0,0 +1,297 @@
+/**
+ * L1 原子记忆存储(双写架构):
+ * - records/YYYY-MM-DD.jsonl:追加式事实源(只增不改,备份/恢复用);
+ * - MemoryDb(SQLite):主检索引擎,upsert/delete 只动这里;
+ * - 检索三策略:keyword(FTS5 BM25)/ embedding(vec0 余弦)/ hybrid(双路 + RRF k=60)。
+ *
+ * 去重/合并的更新记录走 upsert(新 record id + 版本递增),不再全量重写文件。
+ */
+import { existsSync, promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { familyForType } from '../types.js';
+import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
+import { appendJsonl, dayKey, ensureDir, readJsonl } from '../util/io.js';
+import { applyDecayWeight, RRF_K, rrfMerge } from './search-utils.js';
+import { isZeroVector } from './sqlite.js';
+/** 官方过度召回倍数:候选池 = limit × 3(官方 tool 路径同款)。 */
+const CANDIDATE_MULTIPLIER = 3;
+export class L1Store {
+    db;
+    strategy;
+    recordsDir;
+    legacyFile;
+    helper;
+    embedSvc;
+    logger;
+    /** 时效衰减半衰期(天;0=关)。 */
+    decayHalfLifeDays;
+    constructor(dataDir, db, embed = new NoopEmbeddingService(), strategy = 'hybrid', logger, 
+    /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
+    decayHalfLifeDays) {
+        this.db = db;
+        this.strategy = strategy;
+        this.recordsDir = path.join(dataDir, 'records');
+        this.legacyFile = path.join(dataDir, 'l1', 'records.jsonl');
+        this.embedSvc = embed;
+        this.helper = new EmbedHelper(embed, logger);
+        this.logger = logger;
+        this.decayHalfLifeDays = decayHalfLifeDays ?? 30;
+    }
+    async init() {
+        await ensureDir(this.recordsDir);
+        await this.importLegacy();
+    }
+    /** 旧版单文件 records.jsonl 一次性导入检索库,成功后改名 .imported。 */
+    async importLegacy() {
+        if (!existsSync(this.legacyFile))
+            return;
+        try {
+            const records = await readJsonl(this.legacyFile);
+            const valid = records.filter((r) => r && typeof r.id === 'string' && r.content);
+            const badCount = records.length - valid.length;
+            let n = 0;
+            if (valid.length > 0 && this.db.upsertL1Batch(valid))
+                n = valid.length;
+            // 只有确实导入成功才改名,避免把未入库的数据改名带走;判据按 valid 数——
+            // 坏行已在读取时过滤,按 records.length 判会让混入坏行的文件迁移永不完成
+            if (n === valid.length) {
+                const renamed = await fs
+                    .rename(this.legacyFile, `${this.legacyFile}.imported`)
+                    .then(() => true, () => false);
+                if (renamed) {
+                    this.logger?.info(`[memory] 旧版 L1 数据已导入检索库 ${n} 条${badCount > 0 ? `(另丢弃 ${badCount} 条坏行)` : ''}(l1/records.jsonl → .imported)`);
+                }
+                else {
+                    this.logger?.warn('[memory] 旧版 L1 导入完成但改名失败,下次启动会重复导入(upsert 幂等,无害)');
+                }
+            }
+            else {
+                this.logger?.warn(`[memory] 旧版 L1 导入不完整(${n}/${valid.length}),保留原文件下次重试`);
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] 旧版 L1 数据导入失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    get size() {
+        return this.db.countL1();
+    }
+    /** 全量读取(调试/迁移用;检索请走 search)。 */
+    all() {
+        return this.db.getAllL1();
+    }
+    /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
+    getByIds(ids) {
+        return this.db.getL1ByIds(ids);
+    }
+    /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。 */
+    async appendNew(records) {
+        if (records.length === 0)
+            return;
+        for (const r of records) {
+            if (!r.family)
+                r.family = familyForType(r.type);
+        }
+        const byDay = new Map();
+        for (const r of records) {
+            const k = dayKey(r.createdAt || Date.now());
+            const arr = byDay.get(k) ?? [];
+            arr.push(r);
+            byDay.set(k, arr);
+        }
+        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));
+        // 单事务批量写:逐条开事务在 WAL FULL 下每条一次 fsync。
+        // 双写失败闭环:JSONL 事实源已先行追加,DB 缺行 = 这批记忆检索不可见、
+        // 去重候选缺失(重复记忆会累积)。upsert 内部已有逐条 warn,这里升 error
+        // 并给出自愈指引——检索库可由「重建记忆」从事实源全量重导修复。
+        if (!this.db.upsertL1Batch(records, vecs)) {
+            this.logger?.error(`[memory] L1 检索库批量写入失败(${records.length} 条,JSONL 事实源完好),` +
+                '这批记忆暂不可检索;可在设置页运行「重建记忆」修复');
+        }
+    }
+    /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。 */
+    async upsert(record) {
+        if (!record.family)
+            record.family = familyForType(record.type);
+        const vec = (await this.helper.batch([record.content]))[0];
+        if (!this.db.upsertL1(record, vec)) {
+            this.logger?.error(`[memory] L1 检索库写入失败 id=${record.id}(JSONL 事实源完好),该记忆暂不可检索,重建可修复`);
+        }
+    }
+    /** 活切换嵌入源:同步换底层服务(嵌入源三态切换用)。 */
+    setEmbeddingService(svc) {
+        this.embedSvc = svc;
+        this.helper.setService(svc);
+    }
+    async deleteBatch(ids) {
+        this.db.deleteL1Batch(ids);
+    }
+    /**
+     * 三策略检索(自动召回与 memory_search 工具共用接缝)。
+     * embedding 不可用时自动降级 keyword;type 后置过滤;
+     * scoreThreshold 仅对 keyword/embedding 单路策略生效——hybrid 按官方语义
+     * 融合完整列表(融合分已归一化 0~1,可直接用于展示/过滤)。
+     */
+    async search(query, limit, opts) {
+        const caps = this.db.getCapabilities();
+        const canVec = caps.vectorSearch && this.helper.vectorReady();
+        let strategy = this.strategy;
+        if (strategy !== 'keyword' && !canVec)
+            strategy = caps.ftsSearch ? 'keyword' : 'none';
+        const candidateK = limit * CANDIDATE_MULTIPLIER;
+        const threshold = opts?.scoreThreshold ?? 0;
+        if (strategy === 'none')
+            return [];
+        if (strategy === 'keyword') {
+            const fts = this.db.searchL1Fts(query, candidateK, opts?.family);
+            return this.postProcess(this.applyDecay(applyFtsThreshold(fts, threshold, limit)), opts?.type, limit);
+        }
+        if (strategy === 'embedding') {
+            const vec = await this.helper.query(query, opts?.embeddingTimeoutMs);
+            if (!vec) {
+                // embedding 调用失败:降级 FTS,不阻断
+                const fts = this.db.searchL1Fts(query, candidateK, opts?.family);
+                return this.postProcess(this.applyDecay(applyFtsThreshold(fts, threshold, limit)), opts?.type, limit);
+            }
+            const vecHits = this.db.searchL1Vector(vec, candidateK, opts?.family);
+            return this.postProcess(this.applyDecay(filterScore(vecHits, threshold)), opts?.type, limit);
+        }
+        // hybrid(官方语义):双路并行 → 完整列表 RRF 融合(融合前不过滤阈值)
+        // → 融合分归一化:rank1 双列表命中 = 1.0,单列表命中 ≤ 0.5,保持 0~1 语义
+        const [ftsList, vecRaw] = await Promise.all([
+            Promise.resolve(this.db.searchL1Fts(query, candidateK, opts?.family)),
+            this.helper.query(query, opts?.embeddingTimeoutMs),
+        ]);
+        const vecList = vecRaw ? this.db.searchL1Vector(vecRaw, candidateK, opts?.family) : [];
+        const merged = rrfMerge([ftsList, vecList], (h) => h.id);
+        return this.postProcess(this.applyDecay(merged.map(({ rrfScore, ...h }) => ({ ...h, score: normalizeRrf(rrfScore) }))), opts?.type, limit);
+    }
+    /**
+     * 时效衰减加权(#29):三路共用的读路径后处理——阈值过滤之后、截断之前
+     * (才能轮转名额,而不只是重排已截断的集合)。updated_at 经主表批量点查
+     * 回填(FTS 表无该列;候选池 ≤ limit×3 条主键查询,微秒级)。关闭时零开销。
+     */
+    applyDecay(hits) {
+        if (!(this.decayHalfLifeDays > 0) || hits.length === 0)
+            return hits;
+        const updatedAtById = new Map();
+        for (const r of this.db.getL1ByIds(hits.map((h) => h.id))) {
+            if (Number.isFinite(r.updatedAt))
+                updatedAtById.set(r.id, r.updatedAt);
+        }
+        return applyDecayWeight(hits, this.decayHalfLifeDays, (h) => updatedAtById.get(h.id));
+    }
+    /** 浏览列表(UI 用):无关键词时按更新时间倒序分页,支持 Hall 过滤。 */
+    list(opts) {
+        return this.db.listL1(opts);
+    }
+    /** 场景名去重列表(UI 筛选器数据源)。 */
+    distinctScenes() {
+        return this.db.distinctL1Scenes();
+    }
+    /**
+     * 去重候选召回(官方 3 级):空库跳过 → 向量优先 → FTS 兜底。
+     * 传入 family 时只在同族记录里召回(去重永不跨族)。
+     */
+    async searchCandidates(query, limit, family) {
+        if (this.db.countL1() === 0)
+            return [];
+        const caps = this.db.getCapabilities();
+        if (caps.vectorSearch && this.helper.vectorReady()) {
+            try {
+                const vec = await this.helper.query(query);
+                if (vec) {
+                    const hits = this.db.searchL1Vector(vec, limit, family);
+                    if (hits.length > 0)
+                        return this.db.getL1ByIds(hits.map((h) => h.id));
+                }
+            }
+            catch (err) {
+                this.logger?.warn(`[memory] 向量候选召回失败,降级 FTS: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const fts = this.db.searchL1Fts(query, limit * 2, family);
+        return this.db.getL1ByIds(fts.map((h) => h.id));
+    }
+    /**
+     * 增量重嵌入(embedding 配置变化 / 周期性补齐用):只处理缺失向量的记录,
+     * 排除已判定"当前 provider 不可嵌入"的 skip 集。返回写入/失败/跳过数——
+     * failed > 0 时调用方不应标记 meta 同步完成;skipped(零向量)不算失败、
+     * 不阻塞同步标记(否则补齐判据永不收敛,周期性全量重嵌死循环)。
+     * onProgress/shouldCancel 供活切换的进度展示与取消。
+     */
+    async reindex(opts) {
+        if (!this.helper.vectorReady())
+            return { written: 0, failed: 0, skipped: 0 };
+        const items = this.db.getL1ForReindex(this.db.getVecSkipSet('l1'));
+        const total = items.length;
+        let done = 0;
+        let written = 0;
+        let failed = 0;
+        let skipped = 0;
+        let cancelled = false;
+        const skippedNow = [];
+        const CHUNK = 16;
+        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 {
+                vecs = await this.embedSvc.embedBatch(chunk.map((c) => c.content));
+            }
+            catch {
+                failed += chunk.length;
+                done += chunk.length;
+                opts?.onProgress?.(done, total);
+                continue;
+            }
+            const pending = [];
+            chunk.forEach((c, j) => {
+                if (isZeroVector(vecs[j])) {
+                    skipped++;
+                    skippedNow.push(c.id);
+                    return;
+                }
+                pending.push({ id: c.id, embedding: vecs[j] });
+            });
+            if (pending.length > 0) {
+                const ok = this.db.updateL1VecBatch(pending);
+                written += ok;
+                failed += pending.length - ok;
+            }
+            done += chunk.length;
+            opts?.onProgress?.(done, total);
+        }
+        if (skippedNow.length > 0)
+            this.db.addVecSkippedIds('l1', skippedNow);
+        return { written, failed, skipped, cancelled };
+    }
+    postProcess(hits, type, limit) {
+        const filtered = type ? hits.filter((h) => h.type === type) : hits;
+        return filtered.slice(0, limit);
+    }
+}
+/** RRF 原始分归一化到 0~1:双列表 rank1 命中 = 2/(k+1) → 1.0。 */
+function normalizeRrf(rrfScore) {
+    return (rrfScore * (RRF_K + 1)) / 2;
+}
+/** FTS 阈值过滤(含官方小语料例外:全部低于阈值但结果数 ≤ maxResults 时保留)。 */
+function applyFtsThreshold(hits, threshold, maxResults) {
+    if (threshold <= 0)
+        return hits;
+    const filtered = hits.filter((h) => h.score >= threshold);
+    if (filtered.length === 0 && hits.length > 0 && hits.length <= maxResults)
+        return hits;
+    return filtered;
+}
+function filterScore(hits, threshold) {
+    if (threshold <= 0)
+        return hits;
+    return hits.filter((h) => h.score >= threshold);
+}

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

@@ -0,0 +1,89 @@
+import type { MemoryLogger } from '../types.js';
+import type { CatalogEntry } from './model-catalog.js';
+import type { EmbedCallOptions, EmbeddingProviderInfo, EmbeddingService } from './embedding.js';
+type LocalState = 'idle' | 'loading' | 'ready' | 'failed' | 'terminated';
+/** worker 启动参数(workerData;构造后不可变)。 */
+export interface EmbedWorkerData {
+    runtimeDir: string;
+    modelDir: string;
+    pooling: 'cls' | 'mean';
+    dtype: string;
+    maxInputChars: number;
+}
+/** 主线程 → worker 的调用(id 由通道分配)。 */
+export type EmbedWorkerCall = {
+    type: 'ping';
+} | {
+    type: 'warmup';
+} | {
+    type: 'embed';
+    texts: string[];
+    priority: boolean;
+};
+/** worker → 主线程的应答。 */
+export type EmbedWorkerReply = {
+    id: number;
+    ok: true;
+    type: 'pong';
+} | {
+    id: number;
+    ok: true;
+    type: 'ready';
+} | {
+    id: number;
+    ok: true;
+    type: 'embedded';
+    vectors: Float32Array[];
+} | {
+    id: number;
+    ok: false;
+    stage: 'load' | 'infer';
+    error: string;
+};
+/** worker 通道抽象(测试缝:注入假实现验证协议与状态机)。 */
+export interface EmbedWorkerChannel {
+    request(call: EmbedWorkerCall): Promise<EmbedWorkerReply>;
+    /** 立即终止 worker 并拒绝全部未决请求(close 语义);幂等。 */
+    terminate(): void;
+    /** worker 意外崩溃通知(此后所有未决请求已被通道拒绝)。 */
+    setOnCrash(cb: (error: string) => void): void;
+}
+export interface LocalEmbeddingOptions {
+    /** 数据目录 runtime/(worker 据此 createRequire 加载 transformers)。 */
+    runtimeDir: string;
+    /** worker 资产路径(默认 dist/embedding-worker.cjs;测试可显式指定)。 */
+    workerPath?: string;
+    /** 通道注入缝(测试用;缺省 spawn 真实 worker)。 */
+    channel?: EmbedWorkerChannel;
+    logger?: MemoryLogger;
+    maxInputChars?: number;
+}
+export declare class LocalEmbeddingService implements EmbeddingService {
+    private state;
+    private loadError;
+    private readonly channel;
+    private readonly entry;
+    private readonly logger?;
+    constructor(entry: CatalogEntry, modelDir: string, opts: LocalEmbeddingOptions);
+    getDimensions(): number;
+    getProviderInfo(): EmbeddingProviderInfo;
+    isReady(): boolean;
+    /** 状态(进度展示用)。 */
+    getState(): LocalState;
+    getLoadError(): string | null;
+    /** 后台预热:启动后让 worker 立即加载模型(幂等;失败态可重试)。 */
+    startWarmup(): void;
+    /** 等待模型就绪(warmup 协议;applyChain 的 warming 阶段与测试用)。 */
+    waitForReady(): Promise<void>;
+    embed(text: string, callOpts?: EmbedCallOptions): Promise<Float32Array>;
+    embedBatch(texts: string[], callOpts?: EmbedCallOptions): Promise<Float32Array[]>;
+    /** 释放 worker 线程与模型(嵌入源切走/关闭时调用;幂等)。terminated 后不可
+     *  再复用——防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻(内存泄漏)。 */
+    close(): void;
+    /** 内层钳制(仅缩短):超时放弃等待(迟到回复由通道按 id 丢弃),调用方降级。 */
+    private requestWithTimeout;
+    /** loading → ready 一次性日志(memory.log 时序可读性:启动到模型就绪的间隔)。 */
+    private markReady;
+    private applyLoadFailure;
+}
+export {};