dsh-prime-memory 0.11.0

package/dist/store/local-embedding.js

@@ -0,0 +1,227 @@
+/**
+ * 本地嵌入服务(worker 线程化版):transformers.js 的模型加载与 ONNX 推理全部在
+ * worker_threads 子线程执行(resources/embedding-worker.cjs),本类只是主线程侧的
+ * 协议代理——onnxruntime-node 的 run/loadModel 是主线程同步调用,留在宿主事件循环
+ * 会冻结整个 dsh 页面(0.8.6 修复的真实事故)。
+ *
+ * - 懒加载:首次嵌入/warmup 才让 worker 加载模型,close()=terminate 释放线程与
+ *   模型(嵌入源切走/关闭时调用),terminated 后不可复用;
+ * - 模型从数据目录 models/<id>/ 本地加载(worker 侧 env.allowRemoteModels=false);
+ * - channel 可注入(测试缝):用假通道验证协议与状态机,不触真模型;
+ * - callOpts.timeoutMs 经 Promise.race 钳制(迟到回复按 id 丢弃——推理在
+ *   worker 线程无法真正取消,但主线程可以停止等待并降级 FTS);
+ * - 池化方式来自模型目录(BGE 系 CLS / Gemma 系 MEAN),normalize 交给
+ *   pipeline 内建 L2 归一(与远程路径的 sanitizeAndNormalize 语义一致)。
+ */
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+/** 默认 worker 资产路径:dist/store/ → dist/embedding-worker.cjs(构建期拷入)。 */
+function defaultWorkerPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'embedding-worker.cjs');
+}
+/** 真实通道:spawn worker_threads + 自增 id 配对 + 崩溃兜底拒绝。 */
+class RealWorkerChannel {
+    worker;
+    pending = new Map();
+    nextId = 1;
+    terminated = false;
+    crashed;
+    crashCb;
+    constructor(workerPath, workerData) {
+        this.worker = new Worker(workerPath, { workerData });
+        this.worker.on('message', (msg) => {
+            if (msg && msg.type === 'fatal') {
+                this.failAll(`本地嵌入 worker 致命错误: ${msg.error ?? '未知'}`);
+                return;
+            }
+            const id = msg.id;
+            if (typeof id !== 'number')
+                return;
+            const entry = this.pending.get(id);
+            if (!entry)
+                return; // 迟到回复(调用方已超时放弃)
+            this.pending.delete(id);
+            entry.resolve(msg);
+        });
+        // error(未捕获异常且 worker 未自处理)与 exit(含 fatal 后的退出)都兜底拒绝
+        this.worker.on('error', (err) => this.failAll(`本地嵌入 worker 线程错误: ${err.message}`));
+        this.worker.on('exit', (code) => {
+            if (!this.terminated)
+                this.failAll(`本地嵌入 worker 线程退出(code=${code})`);
+        });
+    }
+    request(call) {
+        // 已释放/已崩溃的通道快速拒绝——postMessage 到死线程是静默无回应,调用方会挂到超时
+        if (this.terminated)
+            return Promise.reject(new Error('嵌入 worker 已释放'));
+        if (this.crashed)
+            return Promise.reject(new Error(this.crashed));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.worker.postMessage({ ...call, id });
+        });
+    }
+    terminate() {
+        if (this.terminated)
+            return;
+        this.terminated = true;
+        this.failAll('嵌入 worker 已释放');
+        void this.worker.terminate();
+    }
+    setOnCrash(cb) {
+        this.crashCb = cb;
+        // 构造与回调注册之间发生的崩溃(spawn 即失败等)不丢通知
+        if (this.crashed)
+            cb(this.crashed);
+    }
+    failAll(error) {
+        for (const [, entry] of this.pending)
+            entry.reject(new Error(error));
+        this.pending.clear();
+        if (!this.terminated && !this.crashed) {
+            this.crashed = error;
+            this.crashCb?.(error);
+        }
+    }
+}
+export class LocalEmbeddingService {
+    state = 'idle';
+    loadError = null;
+    channel;
+    entry;
+    logger;
+    constructor(entry, modelDir, opts) {
+        this.entry = entry;
+        this.logger = opts.logger;
+        const maxInputChars = opts.maxInputChars && opts.maxInputChars > 0 ? opts.maxInputChars : 5000;
+        this.channel =
+            opts.channel ??
+                new RealWorkerChannel(opts.workerPath ?? defaultWorkerPath(), {
+                    runtimeDir: opts.runtimeDir,
+                    modelDir,
+                    pooling: entry.pooling,
+                    dtype: 'q8',
+                    maxInputChars,
+                });
+        // 崩溃不自愈(换源/重启恢复):拒绝语义沿 EmbedHelper 降级链走 FTS
+        this.channel.setOnCrash((error) => {
+            if (this.state === 'terminated')
+                return;
+            this.state = 'failed';
+            this.loadError = error;
+            this.logger?.warn(`[memory] ${error}(本地嵌入转入 failed 态,换源或重启可恢复)`);
+        });
+    }
+    getDimensions() {
+        return this.entry.dims;
+    }
+    getProviderInfo() {
+        // dimensions 语义与远程路径一致(sqlite 的 providerInfo 比对含维度)
+        return { provider: 'local', model: this.entry.id, dimensions: this.entry.dims };
+    }
+    isReady() {
+        return this.state === 'ready';
+    }
+    /** 状态(进度展示用)。 */
+    getState() {
+        return this.state;
+    }
+    getLoadError() {
+        return this.loadError;
+    }
+    /** 后台预热:启动后让 worker 立即加载模型(幂等;失败态可重试)。 */
+    startWarmup() {
+        void this.waitForReady().catch(() => { });
+    }
+    /** 等待模型就绪(warmup 协议;applyChain 的 warming 阶段与测试用)。 */
+    async waitForReady() {
+        if (this.state === 'ready')
+            return;
+        if (this.state === 'terminated') {
+            throw new Error('本地嵌入服务已释放(嵌入源已切换);本实例不可复用');
+        }
+        if (this.state !== 'failed')
+            this.state = 'loading';
+        const reply = await this.channel.request({ type: 'warmup' });
+        if (!reply.ok) {
+            this.applyLoadFailure(reply.error);
+            throw new Error(reply.error);
+        }
+        this.markReady();
+    }
+    async embed(text, callOpts) {
+        const [vec] = await this.embedBatch([text], callOpts);
+        return vec;
+    }
+    async embedBatch(texts, callOpts) {
+        if (texts.length === 0)
+            return [];
+        if (this.state === 'terminated') {
+            throw new Error('本地嵌入服务已释放(嵌入源已切换);本实例不可复用');
+        }
+        if (this.state === 'failed') {
+            // 只有明确失败过的服务才抛错(EmbedHelper 捕获后降级 FTS);warmup 可重试
+            throw new Error(`本地嵌入模型加载失败: ${this.loadError ?? '未知原因'}(重启插件或重新下载模型可重试)`);
+        }
+        if (this.state !== 'ready')
+            this.state = 'loading';
+        // 单条请求(召回 query)带优先标记:worker 侧插队,不被 reindex 批次堵队尾
+        const reply = await this.requestWithTimeout({ type: 'embed', texts, priority: texts.length === 1 }, callOpts?.timeoutMs);
+        if (!reply.ok) {
+            if (reply.stage === 'load')
+                this.applyLoadFailure(reply.error);
+            else
+                this.markReady(); // 推理失败说明模型已加载成功(loading → ready),失败只属于这一次调用
+            throw new Error(reply.error);
+        }
+        if (reply.type !== 'embedded')
+            throw new Error(`嵌入 worker 返回异常消息类型: ${reply.type}`);
+        this.markReady();
+        for (const v of reply.vectors) {
+            if (v.length !== this.entry.dims) {
+                throw new Error(`本地嵌入维度不匹配:期望 ${this.entry.dims},得到 ${v.length}`);
+            }
+        }
+        return reply.vectors;
+    }
+    /** 释放 worker 线程与模型(嵌入源切走/关闭时调用;幂等)。terminated 后不可
+     *  再复用——防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻(内存泄漏)。 */
+    close() {
+        this.state = 'terminated';
+        this.loadError = null;
+        this.channel.terminate();
+    }
+    /** 内层钳制(仅缩短):超时放弃等待(迟到回复由通道按 id 丢弃),调用方降级。 */
+    async requestWithTimeout(call, timeoutMs) {
+        if (!(timeoutMs && timeoutMs > 0))
+            return this.channel.request(call);
+        let timer;
+        try {
+            return await Promise.race([
+                this.channel.request(call),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`本地嵌入调用超时(${timeoutMs}ms),已放弃等待`)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            // 先到者胜出后清掉另一个定时器(不清理会挂住引用至自然到期)
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** loading → ready 一次性日志(memory.log 时序可读性:启动到模型就绪的间隔)。 */
+    markReady() {
+        if (this.state === 'ready')
+            return;
+        this.state = 'ready';
+        this.logger?.info(`[memory] 本地嵌入模型就绪: ${this.entry.id}(dims=${this.entry.dims},pooling=${this.entry.pooling})`);
+    }
+    applyLoadFailure(error) {
+        this.state = 'failed';
+        this.loadError = error;
+        this.logger?.warn(`[memory] 本地嵌入模型加载失败(${this.entry.id}): ${error}`);
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 本地嵌入模型目录:插件内置白名单,不提供任意 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 同目录自动加载。
+ *
+ * 注:以下 revision/size/sha256 数据表为上游模型文件的完整性事实数据,
+ * 净室重写按原值逐字保留(改动任何一位都会破坏校验)。
+ */
+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,81 @@
+/**
+ * 本地嵌入模型目录:插件内置白名单,不提供任意 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 同目录自动加载。
+ *
+ * 注:以下 revision/size/sha256 数据表为上游模型文件的完整性事实数据,
+ * 净室重写按原值逐字保留(改动任何一位都会破坏校验)。
+ */
+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: '1fb1efd221c1ca88a736d1b36cb47d754c177677e222acb3b1e5424c5d664870' },
+            { 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/occupancy.d.ts

@@ -0,0 +1,30 @@
+import type { MemoryLogger } from '../types.js';
+import type { OccupancyLedger } from '../util/context-occupancy.js';
+/** 会话条目上限(按 updatedAt 淘汰最旧;防文件无限增长)。 */
+export declare const OCCUPANCY_SESSION_CAP = 200;
+export declare class OccupancyStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private persistFailed;
+    /** 串行化持久化写(避免并发原子写撞临时文件名);init 链最前(先载入再落盘,防丢更新)。 */
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入持久化账目(合并进内存——构造与载入之间发生的 save 不丢);失败降级内存态。 */
+    private init;
+    /**
+     * 该会话的持久化账目(热路径同步读;从未注入/已复位返回 null)。
+     * 返回浅拷贝——调用方(ledgerFor 复生)会在其上做迁移;若交出内部引用,
+     * 原地修改会让 save() 的数值比较误判"未变"而跳过写穿。
+     */
+    load(sessionId: string): OccupancyLedger | null;
+    /**
+     * 迁移后写穿。数值未变只刷新内存时间戳不落盘(profile 稳定区每次请求组装都
+     * 触发迁移,但内容不变时不应产生文件写);stock 归零即删除条目。
+     */
+    save(sessionId: string, ledger: OccupancyLedger): void;
+    /** 等待在途持久化写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

package/dist/store/occupancy.js

@@ -0,0 +1,134 @@
+/**
+ * 记忆占用流水存储:sessionId → OccupancyLedger 的持久化映射。
+ *
+ * 动机:占用账本是进程内存态,dsh 重启后历史会话"窗口里明明有记忆、账面却为零",
+ * 指示器对重启前注入的存量失明。本存储让账目跨进程复生:
+ * - 每次账本迁移后写穿(串行化原子写 + 失败降级内存态);
+ * - 查询热路径仍是同步内存读——文件只在迁移时刻与启动载入时触碰;
+ * - stock 归零的条目不落盘(compaction 复位即天然删除);
+ * - agent 销毁不删记录(持久化语义与召回去重一致:会话恢复后账目继续);
+ * - 90 天未更新过期清理 + 会话条目上限(session-modes/dedupe 同款量级)。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from '../util/io.js';
+/** 会话条目上限(按 updatedAt 淘汰最旧;防文件无限增长)。 */
+export const OCCUPANCY_SESSION_CAP = 200;
+/** 条目过期清理(90 天未更新即丢弃,与 session-modes/dedupe 同款量级)。 */
+const PRUNE_MS = 90 * 24 * 3600_000;
+export class OccupancyStore {
+    logger;
+    file;
+    entries = new Map();
+    persistFailed = false;
+    /** 串行化持久化写(避免并发原子写撞临时文件名);init 链最前(先载入再落盘,防丢更新)。 */
+    writeChain;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'occupancy.json');
+        this.writeChain = this.init();
+    }
+    /** 载入持久化账目(合并进内存——构造与载入之间发生的 save 不丢);失败降级内存态。 */
+    async init() {
+        const data = await readJsonIfExists(this.file);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        let count = 0;
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (typeof entry?.stockTokens !== 'number')
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            const existing = this.entries.get(sid);
+            if (existing) {
+                if (entry.updatedAt > existing.updatedAt)
+                    this.entries.set(sid, { ...entry });
+            }
+            else {
+                this.entries.set(sid, { ...entry });
+            }
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 记忆占用账目载入 ${count} 个会话`);
+    }
+    /**
+     * 该会话的持久化账目(热路径同步读;从未注入/已复位返回 null)。
+     * 返回浅拷贝——调用方(ledgerFor 复生)会在其上做迁移;若交出内部引用,
+     * 原地修改会让 save() 的数值比较误判"未变"而跳过写穿。
+     */
+    load(sessionId) {
+        const e = this.entries.get(sessionId);
+        return e ? { ...e } : null;
+    }
+    /**
+     * 迁移后写穿。数值未变只刷新内存时间戳不落盘(profile 稳定区每次请求组装都
+     * 触发迁移,但内容不变时不应产生文件写);stock 归零即删除条目。
+     */
+    save(sessionId, ledger) {
+        const prev = this.entries.get(sessionId);
+        const sameNumbers = prev !== undefined &&
+            prev.stockTokens === ledger.stockTokens &&
+            prev.recallTokens === ledger.recallTokens &&
+            prev.profileTokens === ledger.profileTokens &&
+            prev.lastInjectTokens === ledger.lastInjectTokens;
+        if (sameNumbers) {
+            prev.updatedAt = ledger.updatedAt;
+            return;
+        }
+        if (ledger.stockTokens <= 0) {
+            if (prev === undefined)
+                return;
+            this.entries.delete(sessionId);
+        }
+        else {
+            this.entries.set(sessionId, { ...ledger });
+        }
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 等待在途持久化写完成(测试/停机用)。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        try {
+            await ensureDir(path.dirname(this.file));
+            await atomicWriteJson(this.file, this.serialize());
+            this.persistFailed = false;
+        }
+        catch (err) {
+            if (!this.persistFailed) {
+                this.persistFailed = true;
+                this.logger?.warn(`[memory] 记忆占用持久化失败(降级内存态): ${errDetail(err)}`);
+            }
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS && e.updatedAt > 0)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > OCCUPANCY_SESSION_CAP) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [sid, e] of this.entries) {
+                if (e.updatedAt > 0 && e.updatedAt < oldestAt) {
+                    oldest = sid;
+                    oldestAt = e.updatedAt;
+                }
+            }
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries) {
+            if (e.stockTokens <= 0)
+                continue; // 归零条目不落盘
+            sessions[sid] = { ...e };
+        }
+        return { version: 1, sessions };
+    }
+}

package/dist/store/pending.d.ts

@@ -0,0 +1,36 @@
+import type { ConversationMessage, ExtractMode, MemoryLogger } from '../types.js';
+/** 带会话标识的未蒸馏消息(会话切片的成员;CONTEXT.md「会话切片」「捕获档位」)。 */
+export interface PendingMessage extends ConversationMessage {
+    /** 捕获该消息的会话;旧格式数据无此字段,加载时归 legacy 组一次性蒸馏。 */
+    sessionId: string;
+}
+/** 三档蒸馏缓冲桶(off 在捕获侧已被拦截,永远不到这里)。 */
+export interface PendingBuckets {
+    auto: PendingMessage[];
+    chat: PendingMessage[];
+    work: PendingMessage[];
+}
+/** 旧格式(无 sessionId 字段)条目加载时归属的会话组。 */
+export declare const LEGACY_SESSION = "legacy";
+/** 各档位桶的渐进阈值状态(0 = 已毕业用稳态值;1 = 爬坡起点;ADR-0003)。 */
+export type WarmupState = Record<ExtractMode, number>;
+/** 全新起步:三档都从 1 爬坡(首轮即触发抽取)。 */
+export declare function freshWarmup(): WarmupState;
+export declare function emptyPending(): PendingBuckets;
+/** 读取缓冲文件:文件缺失/损坏 → 空桶(不抛出——丢了缓冲 L0 事实源仍在)。
+ *  旧格式条目(无 sessionId)归 legacy 组;warmup 缺省 = 全新起步。 */
+export declare function loadPending(file: string, logger?: MemoryLogger): Promise<{
+    buckets: PendingBuckets;
+    warmup: WarmupState;
+}>;
+/** 按会话分组(会话切片):组按首条时间排序、组内按时间稳定排序——
+ *  蒸馏的一切触发都以切片为单位,切片内永不跨会话混装(ADR-0003)。 */
+export declare function groupPendingBySession(messages: PendingMessage[]): Array<{
+    sessionId: string;
+    messages: PendingMessage[];
+}>;
+/** 全量原子落盘(每次蒸馏尝试后调用;桶有上限,量级为百条级)。 */
+export declare function savePending(file: string, buckets: PendingBuckets, warmup?: WarmupState): 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,103 @@
+/**
+ * 未蒸馏缓冲持久化(pending.json):
+ * 按档分桶的"已捕获但尚未成功蒸馏"消息——既包括抽取失败的待重试消息,
+ * 也包括攒够触发阈值之前的消息。跨重启不丢(CONTEXT.md「未蒸馏缓冲」)。
+ *
+ * 与 state.json / session-modes.json 同款原子写;读取宽容(坏行丢弃、坏文件空桶起步)。
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { atomicWriteJson } from '../util/io.js';
+/** 旧格式(无 sessionId 字段)条目加载时归属的会话组。 */
+export const LEGACY_SESSION = 'legacy';
+/** 全新起步:三档都从 1 爬坡(首轮即触发抽取)。 */
+export function freshWarmup() {
+    return { auto: 1, chat: 1, work: 1 };
+}
+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 事实源仍在)。
+ *  旧格式条目(无 sessionId)归 legacy 组;warmup 缺省 = 全新起步。 */
+export async function loadPending(file, logger) {
+    const out = emptyPending();
+    // 直接读文件而非 readJsonIfExists:后者把"不存在"、"不可读"、"JSON 损坏"压成同一个 undefined,
+    // 会让形状/内容损坏静默降级为空桶(与"合法空 pending"不可区分)。此处区分 ENOENT(正常)与其余(需告警)。
+    let raw;
+    try {
+        raw = JSON.parse(await fs.readFile(file, 'utf-8'));
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT') {
+            logger?.warn(`[memory] 未蒸馏缓冲读取失败(按空桶起步): ${file} — ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { buckets: out, warmup: freshWarmup() };
+    }
+    if (!raw || typeof raw !== 'object' || !raw.buckets || typeof raw.buckets !== 'object') {
+        logger?.warn(`[memory] 未蒸馏缓冲格式不符(缺 buckets,按空桶起步): ${file}`);
+        return { buckets: out, warmup: freshWarmup() };
+    }
+    let dropped = 0;
+    let legacy = 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)) {
+                dropped++;
+                continue;
+            }
+            const sid = m.sessionId;
+            if (typeof sid === 'string' && sid) {
+                out[key].push({ ...m, sessionId: sid });
+            }
+            else {
+                legacy++;
+                out[key].push({ ...m, sessionId: LEGACY_SESSION });
+            }
+        }
+    }
+    if (dropped > 0)
+        logger?.warn(`[memory] 未蒸馏缓冲文件含 ${dropped} 条坏记录,已丢弃`);
+    if (legacy > 0)
+        logger?.info(`[memory] 未蒸馏缓冲含 ${legacy} 条旧格式条目,归入 legacy 会话组`);
+    const warmup = freshWarmup();
+    for (const key of ['auto', 'chat', 'work']) {
+        const w = raw.warmup?.[key];
+        if (typeof w === 'number' && Number.isFinite(w) && w >= 0)
+            warmup[key] = Math.floor(w);
+    }
+    return { buckets: out, warmup };
+}
+/** 按会话分组(会话切片):组按首条时间排序、组内按时间稳定排序——
+ *  蒸馏的一切触发都以切片为单位,切片内永不跨会话混装(ADR-0003)。 */
+export function groupPendingBySession(messages) {
+    const groups = new Map();
+    for (const m of messages) {
+        const g = groups.get(m.sessionId);
+        if (g)
+            g.push(m);
+        else
+            groups.set(m.sessionId, [m]);
+    }
+    return [...groups.entries()]
+        .map(([sessionId, msgs]) => ({ sessionId, messages: [...msgs].sort((a, b) => a.timestamp - b.timestamp) }))
+        .sort((a, b) => a.messages[0].timestamp - b.messages[0].timestamp);
+}
+/** 全量原子落盘(每次蒸馏尝试后调用;桶有上限,量级为百条级)。 */
+export async function savePending(file, buckets, warmup) {
+    const payload = { version: 1, buckets, ...(warmup ? { warmup } : {}) };
+    await atomicWriteJson(file, payload);
+}
+export function pendingPathFor(dataDir) {
+    return path.join(dataDir, 'pending.json');
+}
+/** 三档 key(调度/遍历用)。 */
+export const PENDING_MODES = ['auto', 'chat', 'work'];