dsh-layered-memory 0.6.0 → 0.7.0

package/dist/store/runtime-installer.js

@@ -0,0 +1,181 @@
+/**
+ * 运行时安装器（D8 决策）：本地嵌入的推理运行时（@huggingface/transformers，
+ * 纯库、二进制随 npm 包分发、零 postinstall）在用户首次开启本地嵌入时才安装——
+ * 插件 npm 包本体不带重依赖，不用本地嵌入的用户零成本。
+ *
+ * - 安装位置：数据目录 runtime/（自带 package.json 锚定，防 npm 向上层目录逃逸安装）；
+ * - 子进程 npm install --ignore-scripts --no-audit --no-fund，钉死精确版本；
+ * - 进度（用户硬性要求：不能傻等）：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';
+/** 钉死的 transformers.js 版本（D8：精确版本，升级插件时在此变更并重装运行时）。 */
+export const PINNED_TRANSFORMERS_VERSION = '4.2.0';
+export class RuntimeInstaller {
+    runtimeDir;
+    target;
+    logger;
+    spawnImpl;
+    progress;
+    child = null;
+    current = null;
+    /** 安装超时（npm 卡死不罕见：registry 停滞即永挂，applyBusy 会被锁死）。 */
+    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.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);
+    }
+    async installOnce() {
+        // 锚定 package.json：没有它 npm 会向上层目录找最近的 package.json 安装（逃逸事故）
+        await fs.mkdir(this.runtimeDir, { recursive: true });
+        const manifestPath = path.join(this.runtimeDir, 'package.json');
+        try {
+            await fs.access(manifestPath);
+        }
+        catch {
+            await fs.writeFile(manifestPath, JSON.stringify({ name: 'dsh-memory-runtime', private: true }, null, 2));
+        }
+        this.progress = {
+            phase: 'installing',
+            targetVersion: this.target,
+            installedVersion: await this.installedVersion(),
+            startedAt: Date.now(),
+            elapsedMs: 0,
+            lastLines: [`npm install ${RuntimeInstaller.packageName}@${this.target}（--ignore-scripts）`],
+        };
+        const child = this.spawnImpl('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel', 'notice', `${RuntimeInstaller.packageName}@${this.target}`], 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);
+        this.logger?.info(`[memory] 运行时安装开始: ${RuntimeInstaller.packageName}@${this.target} → ${this.runtimeDir}`);
+        const code = await new Promise((resolve) => {
+            void child.exited.then((c) => {
+                clearTimeout(timeout);
+                resolve(c);
+            });
+        });
+        this.progress.elapsedMs = Date.now() - this.progress.startedAt;
+        this.child = null;
+        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,35 @@ 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
+     * 会连 l0_vec 一起删——L0 向量必须保留——故此处单独处理 l1_vec）。
+     * L0 表与 embedding_meta 不动：backfill 的行数比对天然重新一致。
+     */
+    clearL1(): boolean;
     countL1(): number;
     /** 全量读取（调试/迁移/重嵌入用；检索请走 FTS/向量）。 */
     getAllL1(): MemoryRecord[];
@@ -101,21 +139,44 @@ export declare class MemoryDb {
     countL0(): number;
     /** 统计 recorded_at >= iso 的消息数（状态面板"今日捕获"用）。 */
     countL0Since(iso: string): number;
+    /** L0 全量列举（重建快照用；按时间升序，事务一致性避开 JSONL 追加竞态）。 */
+    listL0All(): L0MessageRecord[];
+    /** 重建成本预估（一次全表聚合：会话数 / 消息数 / 字符量）。 */
+    l0RebuildEstimate(): {
+        sessions: number;
+        messages: number;
+        chars: number;
+    };
     /** 向量表行数（backfill 判据：与元数据行数的差值即缺失向量数；不可用时返回 -1）。 */
     countL1Vec(): number;
     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;
     close(): void;
 }
+/** 全零向量（cosine 未定义，不可入向量表）。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
+export declare function isZeroVector(vec: Float32Array): boolean;