dsh-layered-memory 0.6.1 → 0.7.1

package/dist/store/runtime-installer.js

@@ -0,0 +1,220 @@
+/**
+ * 运行时安装器（D8 决策）：本地嵌入的推理运行时（@huggingface/transformers，
+ * 纯库、二进制随 npm 包分发、零 postinstall）在用户首次开启本地嵌入时才安装——
+ * 插件 npm 包本体不带重依赖，不用本地嵌入的用户零成本。
+ *
+ * - 安装位置：数据目录 runtime/（自带 package.json 锚定，防 npm 向上层目录逃逸安装）；
+ * - 子进程 npm ci --ignore-scripts --no-audit --no-fund，钉死精确版本 + 随包 lockfile
+ *   （resources/runtime-package-lock.json，构建期拷入 dist/）锁定完整传递依赖树——
+ *   纯 install 只锁直接依赖的精确版本，传递依赖按 semver 浮动解析，registry 端
+ *   后续发布/投毒会随安装时间漂移；lockfile 把树冻结在作者侧。ci 失败（lock 与
+ *   package.json 漂移等）自动回退 npm install 精确版本（可用性优先，树不再受锁）；
+ * - 进度（用户硬性要求：不能傻等）：npm 非交互模式无百分比 API，采用不确定进度——
+ *   已耗时 + 子进程 stdout/stderr 尾行实时流出 + 可 kill；
+ * - 幂等：已装版本 == 目标版本直接就绪；版本漂移（插件升级换了钉死版本）重装覆盖。
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 钉死的 transformers.js 版本（D8：精确版本，升级插件时在此变更并重装运行时）。 */
+export const PINNED_TRANSFORMERS_VERSION = '4.2.0';
+export class RuntimeInstaller {
+    runtimeDir;
+    target;
+    logger;
+    spawnImpl;
+    /** 随包 lockfile 路径（测试可注入；默认取 dist 根下构建期拷入的资产）。 */
+    lockfileSource;
+    progress;
+    child = null;
+    current = null;
+    /** 安装超时（npm 卡死不罕见：registry 停滞即永挂，applyBusy 会被锁死）。每次 spawn 独立计时。 */
+    static INSTALL_TIMEOUT_MS = 10 * 60_000;
+    constructor(dataDir, targetVersion, opts) {
+        this.runtimeDir = path.join(dataDir, 'runtime');
+        this.target = targetVersion;
+        this.logger = opts?.logger;
+        this.lockfileSource =
+            opts?.lockfileSource ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'runtime-package-lock.json');
+        this.spawnImpl =
+            opts?.spawnImpl ??
+                ((command, args, cwd) => {
+                    const child = spawn(command, args, {
+                        cwd,
+                        // Windows 上 .cmd 必须走 shell（Node 20+ 安全限制）；参数全部来自插件常量，无注入面
+                        shell: process.platform === 'win32',
+                        windowsHide: true,
+                    });
+                    const spawned = {
+                        onStdout(cb) {
+                            child.stdout?.on('data', (d) => String(d).split(/\r?\n/).forEach((l) => l && cb(l)));
+                        },
+                        onStderr(cb) {
+                            child.stderr?.on('data', (d) => String(d).split(/\r?\n/).forEach((l) => l && cb(l)));
+                        },
+                        kill: () => child.kill(),
+                        // 'error'（如 ENOENT：PATH 无 npm）只发 error 不发 close——不监听会永挂
+                        exited: new Promise((resolve) => {
+                            child.on('close', (code) => resolve(code));
+                            child.on('error', () => resolve(null));
+                        }),
+                    };
+                    return spawned;
+                });
+        this.progress = {
+            phase: 'idle',
+            targetVersion: targetVersion,
+            installedVersion: null,
+            startedAt: 0,
+            elapsedMs: 0,
+            lastLines: [],
+        };
+    }
+    /** 包内模块名（与钉死版本一起构成安装目标）。 */
+    static packageName = '@huggingface/transformers';
+    /** 进度快照。 */
+    getProgress() {
+        const elapsed = this.progress.phase === 'installing' ? Date.now() - this.progress.startedAt : this.progress.elapsedMs;
+        return { ...this.progress, lastLines: [...this.progress.lastLines], elapsedMs: elapsed };
+    }
+    pkgJsonPath() {
+        return path.join(this.runtimeDir, 'node_modules', RuntimeInstaller.packageName, 'package.json');
+    }
+    /** 已就位版本（读 package.json；未安装返回 null）。 */
+    async installedVersion() {
+        try {
+            const raw = await fs.readFile(this.pkgJsonPath(), 'utf8');
+            const pkg = JSON.parse(raw);
+            return typeof pkg.version === 'string' ? pkg.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 是否就绪（版本精确匹配目标）。 */
+    async isReady() {
+        return (await this.installedVersion()) === this.target;
+    }
+    /**
+     * 确保运行时就位：版本匹配直接就绪；否则安装（忙时并 await 同一次任务）。
+     * 返回是否就绪（失败/取消返回 false 并在 progress.error 说明原因）。
+     */
+    async ensure() {
+        if (await this.isReady()) {
+            this.progress.phase = 'ready';
+            this.progress.installedVersion = this.target;
+            return true;
+        }
+        if (this.current)
+            return this.current;
+        this.current = this.installOnce();
+        try {
+            return await this.current;
+        }
+        finally {
+            this.current = null;
+        }
+    }
+    /** 取消安装（kill 子进程；node_modules 残留无害，npm 幂等重装）。 */
+    cancel() {
+        if (this.progress.phase !== 'installing' || !this.child)
+            return false;
+        this.progress.phase = 'cancelled';
+        this.child.kill();
+        return true;
+    }
+    /** 从 runtime 目录解析已安装的 transformers 模块（LocalEmbeddingService 用）。 */
+    resolveModule() {
+        const req = createRequire(path.join(this.runtimeDir, 'package.json'));
+        return req(RuntimeInstaller.packageName);
+    }
+    pushLine(line) {
+        const lines = this.progress.lastLines;
+        lines.push(line.length > 300 ? line.slice(0, 300) + '…' : line);
+        if (lines.length > 5)
+            lines.splice(0, lines.length - 5);
+    }
+    /** 跑一次 npm 子进程（采集尾行 + 超时 kill），返回退出码（null = 被杀死/启动失败）。 */
+    async runNpm(args) {
+        const child = this.spawnImpl('npm', args, this.runtimeDir);
+        this.child = child;
+        child.onStdout((l) => this.pushLine(l));
+        child.onStderr((l) => this.pushLine(l));
+        const timeout = setTimeout(() => {
+            this.pushLine('安装超时（10 分钟），终止子进程');
+            child.kill();
+        }, RuntimeInstaller.INSTALL_TIMEOUT_MS);
+        const code = await child.exited;
+        clearTimeout(timeout);
+        this.child = null;
+        return code;
+    }
+    async installOnce() {
+        // 锚定 package.json（带精确依赖）：没有它 npm 会向上层目录找最近的 package.json 安装（逃逸事故）；
+        // npm ci 还要求它与 lockfile 根条目一致——每次安装都写规范化形状，覆盖历史遗留/被 npm 改写的副本。
+        await fs.mkdir(this.runtimeDir, { recursive: true });
+        const manifest = {
+            name: 'dsh-memory-runtime',
+            private: true,
+            dependencies: { [RuntimeInstaller.packageName]: this.target },
+        };
+        await fs.writeFile(path.join(this.runtimeDir, 'package.json'), JSON.stringify(manifest, null, 2));
+        this.progress = {
+            phase: 'installing',
+            targetVersion: this.target,
+            installedVersion: await this.installedVersion(),
+            startedAt: Date.now(),
+            elapsedMs: 0,
+            lastLines: [],
+        };
+        this.logger?.info(`[memory] 运行时安装开始: ${RuntimeInstaller.packageName}@${this.target} → ${this.runtimeDir}`);
+        // 首选 npm ci + 随包 lockfile（传递依赖树冻结在作者侧）；lockfile 资产缺失（npm 包被裁剪等）
+        // 或 ci 失败（lock 与锚定版本漂移等）回退 npm install 精确版本——可用性优先。
+        let code = null;
+        let usedCi = false;
+        try {
+            const lock = await fs.readFile(this.lockfileSource, 'utf8');
+            await fs.writeFile(path.join(this.runtimeDir, 'package-lock.json'), lock);
+            this.pushLine(`npm ci（随包 lockfile 锁定依赖树，@${this.target}，--ignore-scripts）`);
+            usedCi = true;
+            code = await this.runNpm(['ci', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel', 'notice']);
+        }
+        catch {
+            /* 无随包 lockfile，直接走 install 回退 */
+        }
+        if (!usedCi || code !== 0) {
+            if (usedCi) {
+                this.pushLine('npm ci 失败（lockfile 与钉死版本漂移？），回退 npm install');
+                this.logger?.warn('[memory] 运行时 npm ci 失败，回退 npm install（传递依赖不再受随包 lockfile 锁定）');
+            }
+            this.pushLine(`npm install ${RuntimeInstaller.packageName}@${this.target}（--ignore-scripts）`);
+            code = await this.runNpm([
+                'install',
+                '--ignore-scripts',
+                '--no-audit',
+                '--no-fund',
+                '--loglevel',
+                'notice',
+                `${RuntimeInstaller.packageName}@${this.target}`,
+            ]);
+        }
+        this.progress.elapsedMs = Date.now() - this.progress.startedAt;
+        const version = await this.installedVersion();
+        this.progress.installedVersion = version;
+        if (this.progress.phase === 'cancelled') {
+            this.logger?.warn('[memory] 运行时安装已取消（残留无害，重装幂等）');
+            return false;
+        }
+        if (code === 0 && version === this.target) {
+            this.progress.phase = 'ready';
+            this.logger?.info(`[memory] 运行时安装完成: v${version}`);
+            return true;
+        }
+        this.progress.phase = 'error';
+        this.progress.error = `npm 退出码 ${code ?? '被杀死'}${version ? `（就位版本 ${version}）` : '（模块未就位）'}`;
+        this.logger?.warn(`[memory] 运行时安装失败: ${this.progress.error}`);
+        return false;
+    }
+}

package/dist/store/sqlite.d.ts

@@ -28,7 +28,9 @@ export declare class MemoryDb {
     private degraded;
     private ftsAvailable;
     private vecLoaded;
-    private readonly dimensions;
+    private vecLoadWarned;
+    /** 向量维度：活切换嵌入源（D5）时会变——vec0 表随维度重建。 */
+    private dimensions;
     private readonly logger?;
     private stmtUpsertL1;
     private stmtGetL1;
@@ -41,6 +43,7 @@ export declare class MemoryDb {
     private stmtL1FtsSearch;
     private stmtL1FtsSearchFamily;
     private stmtUpsertL0;
+    private stmtGetL0;
     private stmtDeleteL0Vec?;
     private stmtInsertL0Vec?;
     private stmtSearchL0Vec?;
@@ -55,6 +58,21 @@ export declare class MemoryDb {
      * providerInfo 变化（provider/model/维度）时 drop 向量表并返回 needsReindex。
      */
     init(providerInfo?: EmbeddingProviderInfo): StoreInitResult;
+    /** 惰性加载 sqlite-vec（纯 FTS 起步后切本地嵌入时补加载）；失败只停用向量能力并告警一次。 */
+    private ensureVecLoaded;
+    /**
+     * 活切换嵌入源（D5）：provider/model/维度任一变化 → drop 向量表按新维度重建，
+     * 返回 needsReindex=true（调用方后台重嵌，全部成功后 markEmbeddingSynced）；
+     * 配置未变化 → false（切回同一模型不重嵌）。
+     * 新维度 > 0 但 sqlite-vec 不可用 → ok=false（调用方向用户说明，维持 FTS）。
+     */
+    swapProvider(info: EmbeddingProviderInfo): {
+        ok: boolean;
+        needsReindex: boolean;
+        error?: string;
+    };
+    /** l1_vec 物理表的向量维度（建表 DDL 里的 float[N]）；无表返回 null。 */
+    private physicalVecDims;
     private initSchema;
     private prepareL1VecStatements;
     private prepareL0VecStatements;
@@ -66,15 +84,28 @@ export declare class MemoryDb {
     private readEmbeddingMeta;
     private writeEmbeddingMeta;
     /**
-     * 标记当前向量与 embedding 配置同步完成（持久化 meta）。
-     * 只应在重嵌入成功（或空库无历史向量）后调用——过早写入会让下次启动
-     * 比对通过而跳过补齐，向量表永远空着（review P7）。
+     * 持久化 embedding meta（语义：物理向量表当前对应的 provider/维度）。
+     * 活切换在 swapProvider 成功后即写（表已是新维度）；启动/补齐链在
+     * 缺失向量补齐收敛（missing=0）后写——缺失行补齐判据是行数差，
+     * 不依赖 meta（review P7 语义在 backfill 计数判据下仍然收敛）。
      */
     markEmbeddingSynced(info: EmbeddingProviderInfo): void;
     /** upsert 一条 L1（元数据 + FTS 同步；embedding 非零时写向量）。失败返回 false 不抛。 */
     upsertL1(record: MemoryRecord, embedding?: Float32Array): boolean;
-    /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。 */
+    /**
+     * 批量 upsert L1（单事务；与单条同语义：FTS 失败整批回滚）。
+     * 追加/导入热路径用它——逐条开事务在 WAL FULL 下每条一次 fsync。
+     * 整批失败时回退逐条写入：好记录照常入库、坏记录只丢自身——否则
+     * JSONL 事实源已先行追加，检索库却整批缺失且无自动重导路径（批次空洞）。
+     */
+    upsertL1Batch(records: MemoryRecord[], embeddings?: Array<Float32Array | undefined>): boolean;
+    /** 事务内的单条写入体（upsertL1 / upsertL1Batch 共用；调用方负责 BEGIN/COMMIT）。 */
+    private upsertL1InTx;
+    /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。IN 按 ≤900 分块（避变量数上限）。 */
     deleteL1Batch(ids: string[]): number;
+    /** 按块缓存的 IN 语句（表名/动作/尺寸 → 预编译语句）：热路径不再每次动态 prepare。 */
+    private readonly inStmts;
+    private inStatement;
     /**
      * 清空 L1 检索库全部数据（重建用）。records/FTS 直接 DELETE；
      * 向量表走 DROP + 重建（vec0 的全表 DELETE 语义不可靠，dropVectorTables
@@ -121,16 +152,46 @@ export declare class MemoryDb {
     countL0Vec(): number;
     searchL0Fts(query: string, limit: number): L0SearchHit[];
     searchL0Vector(embedding: Float32Array, topK: number): L0SearchHit[];
-    getL1ForReindex(): Array<{
+    /** L1 缺失向量的记录数（排除 skip 集后的补齐判据；向量能力不可用返回 -1）。 */
+    countL1VecMissing(exclude?: Set<string>): number;
+    /** L0 缺失向量的记录数（同上）。 */
+    countL0VecMissing(exclude?: Set<string>): number;
+    /**
+     * 待重嵌入的 L1：只取缺失向量的记录（增量），排除 skip 集里已判定
+     * "当前 provider 下不可嵌入（零向量）"的 id——缺 1 条不再全量重嵌，
+     * 零向量记录也不再反复喂给 embeddings API（H1 死循环双根因）。
+     */
+    getL1ForReindex(exclude?: Set<string>): Array<{
         id: string;
         content: string;
     }>;
-    getL0ForReindex(): Array<{
+    /** 待重嵌入的 L0（增量 + 排除 skip 集，同 getL1ForReindex）。 */
+    getL0ForReindex(exclude?: Set<string>): Array<{
         id: string;
         text: string;
     }>;
+    getVecSkipSet(kind: 'l1' | 'l0'): Set<string>;
+    addVecSkippedIds(kind: 'l1' | 'l0', ids: string[]): void;
+    clearVecSkipIds(kind: 'l1' | 'l0'): void;
     /** 只更新向量行（重嵌入用）。 */
     updateL1Vec(id: string, embedding: Float32Array): boolean;
     updateL0Vec(id: string, embedding: Float32Array, recordedAt: string): boolean;
+    /**
+     * 批量更新 L1 向量行（重嵌入热路径）：单事务写入整批，替代逐条裸写——
+     * 逐条每行一次隐式事务，批量场景（万级记录重嵌）开销集中在 fsync 上。
+     * 整批失败回退逐条：好行照常入库，坏行只丢自身（向量行 id 寻址，无顺序依赖）。
+     * 返回成功写入的行数（零向量行防御性跳过、不计入）。
+     */
+    updateL1VecBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+    }>): number;
+    /** L0 版 updateL1VecBatch（语义同：单事务 + 失败回退逐条）。recordedAt 整批统一。 */
+    updateL0VecBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+    }>, recordedAt: string): number;
     close(): void;
 }
+/** 全零向量（cosine 未定义，不可入向量表）。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
+export declare function isZeroVector(vec: Float32Array): boolean;