dsh-layered-memory 0.6.0 → 0.7.0

package/dist/store/l1.js

@@ -12,6 +12,7 @@ import { familyForType } from '../types.js';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, readJsonl } from './io.js';
 import { RRF_K, rrfMerge } from './search-utils.js';
+import { isZeroVector } from './sqlite.js';
 /** 官方过度召回倍数：候选池 = limit × 3（官方 tool 路径同款）。 */
 const CANDIDATE_MULTIPLIER = 3;
 export class L1Store {
@@ -41,13 +42,10 @@ export class L1Store {
             return;
         try {
             const records = await readJsonl(this.legacyFile);
+            const valid = records.filter((r) => r && typeof r.id === 'string' && r.content);
             let n = 0;
-            for (const r of records) {
-                if (r && typeof r.id === 'string' && r.content) {
-                    if (this.db.upsertL1(r))
-                        n++;
-                }
-            }
+            if (valid.length > 0 && this.db.upsertL1Batch(valid))
+                n = valid.length;
             // 只有确实导入成功（或文件为空）才改名，避免把未入库的数据改名带走
             if (n === records.length) {
                 const renamed = await fs
@@ -98,9 +96,8 @@ export class L1Store {
             await appendJsonl(path.join(this.recordsDir, `${day}.jsonl`), list);
         }
         const vecs = await this.helper.batch(records.map((r) => r.content));
-        for (let i = 0; i < records.length; i++) {
-            this.db.upsertL1(records[i], vecs[i]);
-        }
+        // 单事务批量写：逐条开事务在 WAL FULL 下每条一次 fsync
+        this.db.upsertL1Batch(records, vecs);
     }
     /** 去重 update/merge 产出的记录：只更新检索库（JSONL 事实源不改写，官方语义）。 */
     async upsert(record) {
@@ -109,6 +106,11 @@ export class L1Store {
         const vec = (await this.helper.batch([record.content]))[0];
         this.db.upsertL1(record, vec);
     }
+    /** 活切换嵌入源：同步换底层服务（嵌入源三态切换用）。 */
+    setEmbeddingService(svc) {
+        this.embedSvc = svc;
+        this.helper.setService(svc);
+    }
     async deleteBatch(ids) {
         this.db.deleteL1Batch(ids);
     }
@@ -185,17 +187,29 @@ export class L1Store {
         return this.db.getL1ByIds(fts.map((h) => h.id));
     }
     /**
-     * 全量重嵌入（embedding 配置变化 / 周期性补齐用）。
-     * 返回写入数与失败数——failed > 0 时调用方不应标记 meta 同步完成。
+     * 增量重嵌入（embedding 配置变化 / 周期性补齐用）：只处理缺失向量的记录，
+     * 排除已判定"当前 provider 不可嵌入"的 skip 集。返回写入/失败/跳过数——
+     * failed > 0 时调用方不应标记 meta 同步完成；skipped（零向量）不算失败、
+     * 不阻塞同步标记（否则补齐判据永不收敛，每 30 分钟全量重嵌死循环）。
+     * onProgress/shouldCancel 供活切换（D5）的进度展示与取消。
      */
-    async reindex() {
+    async reindex(opts) {
         if (!this.helper.vectorReady())
-            return { written: 0, failed: 0 };
-        const items = this.db.getL1ForReindex();
+            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 {
@@ -203,16 +217,27 @@ export class L1Store {
             }
             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.updateL1Vec(c.id, vecs[j]))
                     written++;
                 else
                     failed++;
             });
+            done += chunk.length;
+            opts?.onProgress?.(done, total);
         }
-        return { written, failed };
+        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;

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

@@ -0,0 +1,64 @@
+/**
+ * 本地嵌入服务（D1/D6 决策）：transformers.js + ONNX，进程内 CPU 推理。
+ *
+ * - 懒加载（D6）：首次嵌入调用才加载模型（下载完成后的预热也走这里），
+ *   加载后常驻，close() 释放（嵌入源切走/关闭时调用）；
+ * - 模型从数据目录 models/<id>/ 本地加载（env.allowRemoteModels=false 杜绝联网）；
+ * - loader 可注入（测试缝）：不依赖真实 transformers.js/模型文件即可测状态机；
+ * - 池化方式来自模型目录（BGE 系 CLS / Gemma 系 MEAN），normalize 交给 pipeline
+ *   内建 L2 归一（与远程路径的 sanitizeAndNormalize 语义一致）。
+ *
+ * 注意：真实模型路径的池化正确性（尤其 embeddinggemma 的 mean）属于实现期
+ * 待验证项——下载预热后应做一次相似度 sanity 检查（见 PR 验证指引）。
+ */
+import type { MemoryLogger } from '../types.js';
+import type { CatalogEntry } from './model-catalog.js';
+import type { EmbeddingProviderInfo, EmbeddingService } from './embedding.js';
+/** transformers.js 的 feature-extraction pipeline 最小面（结构化注入缝）。 */
+export interface ExtractorLike {
+    (texts: string[], opts: {
+        pooling: 'cls' | 'mean';
+        normalize: boolean;
+    }): Promise<Array<{
+        data: number[] | Float32Array;
+    }>>;
+    dispose?: () => Promise<void> | void;
+}
+export interface TransformersModuleLike {
+    pipeline: (task: string, model: string, opts?: Record<string, unknown>) => Promise<ExtractorLike>;
+    env?: {
+        allowLocalModels?: boolean;
+        allowRemoteModels?: boolean;
+    };
+}
+/** 模块加载器（默认走 RuntimeInstaller.resolveModule；测试注入假模块）。 */
+export type ModuleLoader = () => Promise<TransformersModuleLike>;
+type LocalState = 'idle' | 'loading' | 'ready' | 'failed' | 'terminated';
+export declare class LocalEmbeddingService implements EmbeddingService {
+    private state;
+    private extractor;
+    private loadPromise;
+    private loadError;
+    private readonly modelDir;
+    private readonly entry;
+    private readonly loader;
+    private readonly logger?;
+    constructor(entry: CatalogEntry, modelDir: string, loader: ModuleLoader, logger?: MemoryLogger);
+    getDimensions(): number;
+    getProviderInfo(): EmbeddingProviderInfo;
+    isReady(): boolean;
+    /** 状态（进度展示用）。 */
+    getState(): LocalState;
+    getLoadError(): string | null;
+    /** 后台预热：下载完成后验证可加载性（幂等；失败态可重试）。 */
+    startWarmup(): void;
+    /** 等待预热完成（测试用）。 */
+    waitForReady(): Promise<void>;
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /** 释放模型（嵌入源切走/关闭时调用；幂等）。terminated 后不可再复用——
+     * 防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻（内存泄漏）。 */
+    close(): void;
+    private ensureLoaded;
+}
+export {};

package/dist/store/local-embedding.js

@@ -0,0 +1,120 @@
+export class LocalEmbeddingService {
+    state = 'idle';
+    extractor = null;
+    loadPromise = null;
+    loadError = null;
+    modelDir;
+    entry;
+    loader;
+    logger;
+    constructor(entry, modelDir, loader, logger) {
+        this.entry = entry;
+        this.modelDir = modelDir;
+        this.loader = loader;
+        this.logger = logger;
+    }
+    getDimensions() {
+        return this.entry.dims;
+    }
+    getProviderInfo() {
+        // dimensions 语义与远程路径一致（sqlite.ts 的 providerInfo 比对含维度）
+        return { provider: 'local', model: this.entry.id, dimensions: this.entry.dims };
+    }
+    isReady() {
+        return this.state === 'ready' && this.extractor !== null;
+    }
+    /** 状态（进度展示用）。 */
+    getState() {
+        return this.state;
+    }
+    getLoadError() {
+        return this.loadError;
+    }
+    /** 后台预热：下载完成后验证可加载性（幂等；失败态可重试）。 */
+    startWarmup() {
+        void this.ensureLoaded();
+    }
+    /** 等待预热完成（测试用）。 */
+    async waitForReady() {
+        await this.ensureLoaded();
+    }
+    async embed(text) {
+        const [vec] = await this.embedBatch([text]);
+        return vec;
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        if (this.state === 'terminated') {
+            throw new Error('本地嵌入服务已释放（嵌入源已切换）；本实例不可复用');
+        }
+        // 首次调用触发懒加载（D6：加载期间调用方等待而非失败——召回只慢这一次）；
+        // 只有明确失败过的服务才抛错（EmbedHelper 捕获后降级 FTS）
+        if (this.state !== 'ready') {
+            if (this.state === 'failed') {
+                throw new Error(`本地嵌入模型加载失败: ${this.loadError ?? '未知原因'}（重启插件或重新下载模型可重试）`);
+            }
+            await this.ensureLoaded();
+        }
+        const out = [];
+        // CPU 推理逐条最稳（ORT session 内部并行），量级为本插件写入/重嵌批（≤16）没问题
+        for (const text of texts) {
+            const result = await this.extractor([text.slice(0, 5000)], { pooling: this.entry.pooling, normalize: true });
+            out.push(new Float32Array(result[0].data));
+        }
+        return out;
+    }
+    /** 释放模型（嵌入源切走/关闭时调用；幂等）。terminated 后不可再复用——
+     * 防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻（内存泄漏）。 */
+    close() {
+        const ext = this.extractor;
+        this.extractor = null;
+        this.loadPromise = null;
+        this.state = 'terminated';
+        this.loadError = null;
+        try {
+            const dispose = ext?.dispose;
+            if (dispose)
+                void Promise.resolve(dispose.call(ext));
+        }
+        catch {
+            /* 释放失败不影响状态复位 */
+        }
+    }
+    async ensureLoaded() {
+        if (this.state === 'ready')
+            return;
+        if (this.state === 'loading' && this.loadPromise)
+            return this.loadPromise;
+        this.state = 'loading';
+        this.loadError = null;
+        this.loadPromise = (async () => {
+            try {
+                const mod = await this.loader();
+                if (mod.env) {
+                    mod.env.allowRemoteModels = false;
+                    if (mod.env.allowLocalModels !== undefined)
+                        mod.env.allowLocalModels = true;
+                }
+                const extractor = await mod.pipeline('feature-extraction', this.modelDir, { dtype: 'q8' });
+                // loading 中被 close()（terminated）：不得覆写状态复活（review C）——直接释放丢弃
+                if (this.state === 'terminated') {
+                    const dispose = extractor.dispose;
+                    if (dispose)
+                        void Promise.resolve(dispose.call(extractor)).catch(() => { });
+                    throw new Error('加载期间服务已释放');
+                }
+                this.extractor = extractor;
+                this.state = 'ready';
+                this.logger?.info(`[memory] 本地嵌入模型就绪: ${this.entry.id}（dims=${this.entry.dims}，pooling=${this.entry.pooling}）`);
+            }
+            catch (err) {
+                this.state = 'failed';
+                this.loadError = err instanceof Error ? err.message : String(err);
+                this.logger?.warn(`[memory] 本地嵌入模型加载失败（${this.entry.id}）: ${this.loadError}`);
+                throw err;
+            }
+        })();
+        return this.loadPromise;
+    }
+}

package/dist/store/model-catalog.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 本地嵌入模型目录（D2 决策）：插件内置白名单，不提供任意 repo 下载。
+ * 每款锁定 revision（commit sha）+ 每文件 sha256——目录即完整性契约，
+ * 升级模型 = 改这里（维度变化会触发使用方全量重嵌入）。
+ *
+ * 数据来源（2026-08-17 采集）：
+ * - revision 与 LFS 大文件 sha256：HF tree API（LFS oid 即 sha256）；
+ * - 小文件 sha256：从镜像按锁定 revision 下载后本地实测。
+ * embeddinggemma 是 ONNX 外部权重格式：model_quantized.onnx（图，~0.5MB）与
+ * model_quantized.onnx_data（权重，~294MB）必须成对存在，onnxruntime 同目录自动加载。
+ */
+export interface CatalogFile {
+    /** 仓库内相对路径（同时是 models/<id>/ 下的落盘路径）。 */
+    path: string;
+    /** 字节数（磁盘检查的进度分母）。 */
+    size: number;
+    /** sha256 hex（64 位）。 */
+    sha256: string;
+}
+export interface CatalogEntry {
+    /** 稳定 id：嵌入源状态文件（embedding-source.json）引用它。 */
+    id: string;
+    /** 展示名。 */
+    name: string;
+    /** HF 仓库 repo id。 */
+    repo: string;
+    /** 锁定的 revision。 */
+    revision: string;
+    /** 向量维度（vec0 建表与切换重嵌的判据）。 */
+    dims: number;
+    /** 上下文窗口（token），仅 UI 展示。 */
+    contextTokens: number;
+    /** 池化方式：BGE 系 CLS；embeddinggemma 系（Gemma 解码器底座）MEAN。 */
+    pooling: 'cls' | 'mean';
+    /** UI 标签。 */
+    tags: string[];
+    /** 一句话说明（设置页模型卡）。 */
+    description: string;
+    files: CatalogFile[];
+}
+export declare const MODEL_CATALOG: CatalogEntry[];
+/** 按 id 取目录项。 */
+export declare function catalogById(id: string): CatalogEntry | undefined;
+/** 模型总字节数（磁盘检查与整体进度分母）。 */
+export declare function catalogTotalBytes(entry: CatalogEntry): number;

package/dist/store/model-catalog.js

@@ -0,0 +1,78 @@
+/**
+ * 本地嵌入模型目录（D2 决策）：插件内置白名单，不提供任意 repo 下载。
+ * 每款锁定 revision（commit sha）+ 每文件 sha256——目录即完整性契约，
+ * 升级模型 = 改这里（维度变化会触发使用方全量重嵌入）。
+ *
+ * 数据来源（2026-08-17 采集）：
+ * - revision 与 LFS 大文件 sha256：HF tree API（LFS oid 即 sha256）；
+ * - 小文件 sha256：从镜像按锁定 revision 下载后本地实测。
+ * embeddinggemma 是 ONNX 外部权重格式：model_quantized.onnx（图，~0.5MB）与
+ * model_quantized.onnx_data（权重，~294MB）必须成对存在，onnxruntime 同目录自动加载。
+ */
+export const MODEL_CATALOG = [
+    {
+        id: 'bge-small-zh-v1.5',
+        name: 'BGE small 中文',
+        repo: 'Xenova/bge-small-zh-v1.5',
+        revision: '75c43b069aac4d136ba6bc1122f995fedcfd2781',
+        dims: 512,
+        contextTokens: 512,
+        pooling: 'cls',
+        tags: ['中文', '轻量'],
+        description: '中文专用小模型：约 25MB，CPU 嵌入最快，适合先体验语义检索。',
+        files: [
+            { path: 'config.json', size: 716, sha256: 'd4193ead3a810fd694fa8a31d7fc72fbaebc0668b603e398734bf2f6538ff42f' },
+            { path: 'tokenizer_config.json', size: 367, sha256: 'e6f3b96db926a37d4039995fbf5ad17de158dfb8f6343d607e4dbaad18d75f5a' },
+            { path: 'special_tokens_map.json', size: 125, sha256: 'b6d346be366a7d1d48332dbc9fdf3bf8960b5d879522b7799ddba59e76237ee3' },
+            { path: 'tokenizer.json', size: 439125, sha256: '48cea5d44424912a6fd1ea647bf4fe50b55ab8b1e5879c3275f80e339e8fae26' },
+            { path: 'onnx/model_quantized.onnx', size: 24010842, sha256: '15b717c382bcb518ba457b93ea6850ede7f4f1cd8937454aa06972366cd19bcc' },
+        ],
+    },
+    {
+        id: 'embeddinggemma-300m',
+        name: 'EmbeddingGemma 300M',
+        repo: 'onnx-community/embeddinggemma-300m-ONNX',
+        revision: '5090578d9565bb06545b4552f76e6bc2c93e4a66',
+        dims: 768,
+        contextTokens: 2048,
+        pooling: 'mean',
+        tags: ['多语言', '均衡'],
+        description: 'Google 官方嵌入模型：100+ 语言含中文，约 295MB，质量与开销均衡（上游 MemoryCore 同款）。',
+        files: [
+            { path: 'config.json', size: 1765, sha256: '6e1f06404b7163e0325ed2ea3e6781cde50f4a50b31780a95ad0d30e8404d77b' },
+            { path: 'added_tokens.json', size: 35, sha256: '50b2f405ba56a26d4913fd772089992252d7f942123cc0a034d96424221ba946' },
+            { path: 'special_tokens_map.json', size: 662, sha256: '2f7b0adf4fb469770bb1490e3e35df87b1dc578246c5e7e6fc76ecf33213a397' },
+            { path: 'tokenizer_config.json', size: 1156830, sha256: '3ca953eea6c3c9fcda9cf3df22949ff18b216f7c74bd6459230f3f1013953f3a' },
+            { path: 'generation_config.json', size: 133, sha256: '1fb1efd221c1ca88a736b1b36cb47d754c177677e222acb3b1e5424c5d664870' },
+            { path: 'tokenizer.json', size: 20323312, sha256: '4dda02faaf32bc91031dc8c88457ac272b00c1016cc679757d1c441b248b9c47' },
+            { path: 'onnx/model_quantized.onnx', size: 567874, sha256: '172efde319fe1542dc41f31be6154910b05b78f7a861c265c4600eec906bd6d8' },
+            { path: 'onnx/model_quantized.onnx_data', size: 308890624, sha256: '705626e28e4c23c82ade34566b4197d97f534c12275fa406dfb71e9937d388c0' },
+        ],
+    },
+    {
+        id: 'bge-m3',
+        name: 'BGE-M3 大杯',
+        repo: 'Xenova/bge-m3',
+        revision: '4de13258303883538bd53b696b452bf8099f0858',
+        dims: 1024,
+        contextTokens: 8192,
+        pooling: 'cls',
+        tags: ['中文', '长上下文'],
+        description: '中文质量最强：8192 token 上下文，约 543MB，CPU 嵌入较慢（单条可达秒级）。',
+        files: [
+            { path: 'config.json', size: 770, sha256: '734a79bf12d388c1467a4e3ab625f45de7f6906cffcfb93a1eca1787504bed95' },
+            { path: 'special_tokens_map.json', size: 964, sha256: '8c785abebea9ae3257b61681b4e6fd8365ceafde980c21970d001e834cf10835' },
+            { path: 'tokenizer_config.json', size: 1173, sha256: '7e4c1cc848840aeccdd763458c18dd525eb0f795c992e00ebe9c28554e7db2d4' },
+            { path: 'tokenizer.json', size: 17082821, sha256: '6710678b12670bc442b99edc952c4d996ae309a7020c1fa0096dd245c2faf790' },
+            { path: 'onnx/model_quantized.onnx', size: 569694530, sha256: '0826f8c1ab9edf1801db86c61919d4d108e8bfc0b809ec823ad366882ff0b77d' },
+        ],
+    },
+];
+/** 按 id 取目录项。 */
+export function catalogById(id) {
+    return MODEL_CATALOG.find((m) => m.id === id);
+}
+/** 模型总字节数（磁盘检查与整体进度分母）。 */
+export function catalogTotalBytes(entry) {
+    return entry.files.reduce((sum, f) => sum + f.size, 0);
+}

package/dist/store/pending.d.ts

@@ -0,0 +1,15 @@
+import type { ConversationMessage, ExtractMode, MemoryLogger } from '../types.js';
+/** 三档蒸馏缓冲桶（off 在捕获侧已被拦截，永远不到这里）。 */
+export interface PendingBuckets {
+    auto: ConversationMessage[];
+    chat: ConversationMessage[];
+    work: ConversationMessage[];
+}
+export declare function emptyPending(): PendingBuckets;
+/** 读取缓冲文件：文件缺失/损坏 → 空桶（不抛出——丢了缓冲 L0 事实源仍在）。 */
+export declare function loadPending(file: string, logger?: MemoryLogger): Promise<PendingBuckets>;
+/** 全量原子落盘（每次蒸馏尝试后调用；桶有上限，量级为百条级）。 */
+export declare function savePending(file: string, buckets: PendingBuckets): Promise<void>;
+export declare function pendingPathFor(dataDir: string): string;
+/** 三档 key（调度/遍历用）。 */
+export declare const PENDING_MODES: readonly ExtractMode[];

package/dist/store/pending.js

@@ -0,0 +1,56 @@
+/**
+ * 未蒸馏缓冲持久化（pending.json）：
+ * 按档分桶的"已捕获但尚未成功蒸馏"消息——既包括抽取失败的待重试消息，
+ * 也包括攒够触发阈值之前的消息。跨重启不丢（CONTEXT.md「未蒸馏缓冲」）。
+ *
+ * 与 state.json / session-modes.json 同款原子写；读取宽容（坏行丢弃、坏文件空桶起步）。
+ */
+import * as path from 'node:path';
+import { atomicWriteJson, readJsonIfExists } from './io.js';
+export function emptyPending() {
+    return { auto: [], chat: [], work: [] };
+}
+function isMessage(m) {
+    if (!m || typeof m !== 'object')
+        return false;
+    const r = m;
+    return typeof r.id === 'string' && typeof r.content === 'string' && (r.role === 'user' || r.role === 'assistant');
+}
+/** 读取缓冲文件：文件缺失/损坏 → 空桶（不抛出——丢了缓冲 L0 事实源仍在）。 */
+export async function loadPending(file, logger) {
+    const out = emptyPending();
+    let raw;
+    try {
+        raw = await readJsonIfExists(file);
+    }
+    catch {
+        raw = undefined;
+    }
+    if (!raw || typeof raw !== 'object' || !raw.buckets || typeof raw.buckets !== 'object')
+        return out;
+    let dropped = 0;
+    for (const key of ['auto', 'chat', 'work']) {
+        const arr = raw.buckets[key];
+        if (!Array.isArray(arr))
+            continue;
+        for (const m of arr) {
+            if (isMessage(m))
+                out[key].push(m);
+            else
+                dropped++;
+        }
+    }
+    if (dropped > 0)
+        logger?.warn(`[memory] 未蒸馏缓冲文件含 ${dropped} 条坏记录，已丢弃`);
+    return out;
+}
+/** 全量原子落盘（每次蒸馏尝试后调用；桶有上限，量级为百条级）。 */
+export async function savePending(file, buckets) {
+    const payload = { version: 1, buckets };
+    await atomicWriteJson(file, payload);
+}
+export function pendingPathFor(dataDir) {
+    return path.join(dataDir, 'pending.json');
+}
+/** 三档 key（调度/遍历用）。 */
+export const PENDING_MODES = ['auto', 'chat', 'work'];

package/dist/store/runtime-installer.d.ts

@@ -0,0 +1,60 @@
+import type { MemoryLogger } from '../types.js';
+/** 钉死的 transformers.js 版本（D8：精确版本，升级插件时在此变更并重装运行时）。 */
+export declare const PINNED_TRANSFORMERS_VERSION = "4.2.0";
+export interface RuntimeProgress {
+    phase: 'idle' | 'installing' | 'ready' | 'error' | 'cancelled';
+    /** 插件钉死的目标版本。 */
+    targetVersion: string;
+    /** runtime 里实际就位的版本（未安装为 null）。 */
+    installedVersion: string | null;
+    startedAt: number;
+    /** 已运行毫秒（读时计算）。 */
+    elapsedMs: number;
+    /** npm 输出尾行（最近 5 行，让用户看到 npm 在干什么）。 */
+    lastLines: string[];
+    error?: string;
+}
+/** 子进程抽象（测试注入缝）：注册输出行回调 + 终止 + 终态。 */
+export interface SpawnedProcess {
+    onStdout(cb: (line: string) => void): void;
+    onStderr(cb: (line: string) => void): void;
+    kill(): void;
+    /** 终态 Promise：退出码（null = 被信号杀死）。 */
+    exited: Promise<number | null>;
+}
+export type SpawnImpl = (command: string, args: string[], cwd: string) => SpawnedProcess;
+export declare class RuntimeInstaller {
+    readonly runtimeDir: string;
+    private readonly target;
+    private readonly logger?;
+    private readonly spawnImpl;
+    private progress;
+    private child;
+    private current;
+    /** 安装超时（npm 卡死不罕见：registry 停滞即永挂，applyBusy 会被锁死）。 */
+    private static INSTALL_TIMEOUT_MS;
+    constructor(dataDir: string, targetVersion: string, opts?: {
+        logger?: MemoryLogger;
+        spawnImpl?: SpawnImpl;
+    });
+    /** 包内模块名（与钉死版本一起构成安装目标）。 */
+    static packageName: string;
+    /** 进度快照。 */
+    getProgress(): RuntimeProgress;
+    private pkgJsonPath;
+    /** 已就位版本（读 package.json；未安装返回 null）。 */
+    installedVersion(): Promise<string | null>;
+    /** 是否就绪（版本精确匹配目标）。 */
+    isReady(): Promise<boolean>;
+    /**
+     * 确保运行时就位：版本匹配直接就绪；否则安装（忙时并 await 同一次任务）。
+     * 返回是否就绪（失败/取消返回 false 并在 progress.error 说明原因）。
+     */
+    ensure(): Promise<boolean>;
+    /** 取消安装（kill 子进程；node_modules 残留无害，npm 幂等重装）。 */
+    cancel(): boolean;
+    /** 从 runtime 目录解析已安装的 transformers 模块（LocalEmbeddingService 用）。 */
+    resolveModule(): unknown;
+    private pushLine;
+    private installOnce;
+}