dsh-prime-memory 0.11.0

package/dist/store/persona.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryFamily, MemoryLogger } from '../types.js';
+export declare const NAV_HEADER = "## \uD83D\uDDFA\uFE0F Scene Navigation";
+export declare class PersonaStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly family;
+    constructor(dataDir: string, family: MemoryFamily, logger?: MemoryLogger | undefined);
+    /** 旧布局迁移:persona.md → persona-chat.md(幂等,仅 chat 族执行)。 */
+    init(): Promise<void>;
+    /** 读取正文(剥离场景导航部分)。 */
+    read(): Promise<string | undefined>;
+    /** 写入正文(保留已有导航段则拼回尾部)。 */
+    write(body: string): Promise<void>;
+}
+export declare function stripSceneNavigation(content: string): string;

package/dist/store/persona.js

@@ -0,0 +1,60 @@
+/**
+ * L3 画像存储:persona-<family>.md(chat 族=用户画像 / work 族=Team Operating Doctrine)。
+ * 场景导航由工程侧自动追加/剥离(stripSceneNavigation 语义)。
+ * init() 把旧布局的 persona.md 一次性改名为 persona-chat.md(历史数据归属 chat 档)。
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { atomicWriteText, readTextIfExists } from '../util/io.js';
+export const NAV_HEADER = '## 🗺️ Scene Navigation';
+export class PersonaStore {
+    logger;
+    file;
+    family;
+    constructor(dataDir, family, logger) {
+        this.logger = logger;
+        this.family = family;
+        this.file = path.join(dataDir, `persona-${family}.md`);
+    }
+    /** 旧布局迁移:persona.md → persona-chat.md(幂等,仅 chat 族执行)。 */
+    async init() {
+        if (this.family !== 'chat')
+            return;
+        const dataDir = path.dirname(this.file);
+        const legacy = path.join(dataDir, 'persona.md');
+        try {
+            await fs.access(legacy);
+            await fs.rename(legacy, this.file);
+            this.logger?.info('[memory] 画像文件迁移:persona.md → persona-chat.md');
+        }
+        catch {
+            /* 无旧文件或已迁移 */
+        }
+    }
+    /** 读取正文(剥离场景导航部分)。 */
+    async read() {
+        const raw = await readTextIfExists(this.file);
+        if (!raw)
+            return undefined;
+        return stripSceneNavigation(raw).trim() || undefined;
+    }
+    /** 写入正文(保留已有导航段则拼回尾部)。 */
+    async write(body) {
+        const raw = await readTextIfExists(this.file);
+        const nav = raw ? extractSceneNavigation(raw) : undefined;
+        const content = nav ? `${body.trim()}\n\n${nav}\n` : `${body.trim()}\n`;
+        await atomicWriteText(this.file, content);
+    }
+}
+export function stripSceneNavigation(content) {
+    const idx = content.indexOf(NAV_HEADER);
+    if (idx === -1)
+        return content;
+    return content.slice(0, idx).trimEnd();
+}
+function extractSceneNavigation(content) {
+    const idx = content.indexOf(NAV_HEADER);
+    if (idx === -1)
+        return undefined;
+    return content.slice(idx).trim();
+}

package/dist/store/recall-dedupe.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryLogger } from '../types.js';
+/** 会话条目上限(按 updatedAt 淘汰最旧;防文件无限增长)。 */
+export declare const RECALL_DEDUPE_SESSION_CAP = 200;
+/** 单会话记录 id 上限(按插入序淘汰最旧;Set 迭代序即插入序)。 */
+export declare const RECALL_DEDUPE_IDS_CAP = 512;
+export declare class RecallDedupeStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private persistFailed;
+    /** 串行化持久化写(避免并发原子写撞临时文件名);init 链最前(先载入再落盘,防丢更新)。 */
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入持久化映射(合并进内存——构造与载入之间发生的 mark 不丢);失败降级内存态。 */
+    private init;
+    /** 该会话的已注入集合(热路径同步读;未出现过的会话返回空集合,惰性建条)。 */
+    seen(sessionId: string): Set<string>;
+    /** 标记本轮实际注入的记录 id(写穿;调用方保证只传模型真实看到的条目)。 */
+    mark(sessionId: string, recordIds: string[]): void;
+    /** 清空该会话的记录(compact/clear 后上下文已丢失,记忆需可重新注入)。 */
+    reset(sessionId: string): void;
+    /** 等待在途持久化写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

package/dist/store/recall-dedupe.js

@@ -0,0 +1,138 @@
+/**
+ * 召回去重存储:sessionId → 已注入 L1 记录 id 集合的持久化映射。
+ *
+ * 语义:
+ * - 同会话内已注入过的记忆不再重复注入(模型上下文已持有,重复注入浪费 token);
+ * - 压制粒度 = 记录 id——去重合并更新会换新 id,新内容天然解除压制重新注入;
+ * - compact/clear 事件重置(上下文被压缩/清空,注入内容已丢失);resume 不重置;
+ * - 热路径(召回 pre-step)同步内存读取,mark/reset 写穿持久化(session-modes 同款:
+ *   串行化原子写 + 失败降级内存态),任何 I/O 失败绝不抛进召回路径。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from '../util/io.js';
+/** 会话条目上限(按 updatedAt 淘汰最旧;防文件无限增长)。 */
+export const RECALL_DEDUPE_SESSION_CAP = 200;
+/** 单会话记录 id 上限(按插入序淘汰最旧;Set 迭代序即插入序)。 */
+export const RECALL_DEDUPE_IDS_CAP = 512;
+/** 条目过期清理(90 天未更新即丢弃,与 session-modes 同款量级)。 */
+const PRUNE_MS = 90 * 24 * 3600_000;
+export class RecallDedupeStore {
+    logger;
+    file;
+    entries = new Map();
+    persistFailed = false;
+    /** 串行化持久化写(避免并发原子写撞临时文件名);init 链最前(先载入再落盘,防丢更新)。 */
+    writeChain;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'recall-dedupe.json');
+        this.writeChain = this.init();
+    }
+    /** 载入持久化映射(合并进内存——构造与载入之间发生的 mark 不丢);失败降级内存态。 */
+    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 (!Array.isArray(entry?.recordIds))
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            const existing = this.entries.get(sid);
+            if (existing) {
+                // 合并:构造后、载入完成前已发生的 mark(保留较大 updatedAt)
+                for (const id of entry.recordIds)
+                    existing.ids.add(id);
+                existing.updatedAt = Math.max(existing.updatedAt, entry.updatedAt ?? 0);
+            }
+            else {
+                this.entries.set(sid, { ids: new Set(entry.recordIds), updatedAt: entry.updatedAt ?? now });
+            }
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 召回去重记录载入 ${count} 个会话`);
+    }
+    /** 该会话的已注入集合(热路径同步读;未出现过的会话返回空集合,惰性建条)。 */
+    seen(sessionId) {
+        let entry = this.entries.get(sessionId);
+        if (!entry) {
+            entry = { ids: new Set(), updatedAt: 0 };
+            this.entries.set(sessionId, entry);
+        }
+        return entry.ids;
+    }
+    /** 标记本轮实际注入的记录 id(写穿;调用方保证只传模型真实看到的条目)。 */
+    mark(sessionId, recordIds) {
+        if (recordIds.length === 0)
+            return;
+        const ids = this.seen(sessionId);
+        for (const id of recordIds)
+            ids.add(id);
+        // 插入序淘汰最旧(Set 迭代序 = 插入序)
+        while (ids.size > RECALL_DEDUPE_IDS_CAP) {
+            const oldest = ids.values().next().value;
+            if (oldest === undefined)
+                break;
+            ids.delete(oldest);
+        }
+        const entry = this.entries.get(sessionId);
+        entry.updatedAt = Date.now();
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 清空该会话的记录(compact/clear 后上下文已丢失,记忆需可重新注入)。 */
+    reset(sessionId) {
+        if (!this.entries.has(sessionId))
+            return;
+        this.entries.delete(sessionId);
+        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();
+        // 超期清理 + 条数上限(按 updatedAt 淘汰最旧)
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS && e.updatedAt > 0)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > RECALL_DEDUPE_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; // 只剩惰性空条目(updatedAt=0),不占文件体积可留待过期清理
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries) {
+            if (e.ids.size === 0)
+                continue; // 空集合不落盘
+            sessions[sid] = { recordIds: [...e.ids], updatedAt: e.updatedAt };
+        }
+        return { version: 1, sessions };
+    }
+}

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

@@ -0,0 +1,59 @@
+import type { MemoryLogger } from '../types.js';
+/** 钉死的 transformers.js 版本(精确版本,升级插件时在此变更并重装运行时)。 */
+export declare const PINNED_TRANSFORMERS_VERSION = "4.2.0";
+import type { RuntimeProgress } from '../contract.js';
+export type { RuntimeProgress } from '../contract.js';
+/** 子进程抽象(测试注入缝):注册输出行回调 + 终止 + 终态。 */
+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;
+    /** 随包 lockfile 路径(测试可注入;默认取 dist 根下构建期拷入的资产)。 */
+    private readonly lockfileSource;
+    private progress;
+    private child;
+    private current;
+    /** 安装超时(npm 卡死不罕见:registry 停滞即永挂,applyBusy 会被锁死)。每次 spawn 独立计时。 */
+    private static INSTALL_TIMEOUT_MS;
+    constructor(dataDir: string, targetVersion: string, opts?: {
+        logger?: MemoryLogger;
+        spawnImpl?: SpawnImpl;
+        lockfileSource?: string;
+    });
+    /** 包内模块名(与钉死版本一起构成安装目标)。 */
+    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 幂等重装)。
+     * 间隙兼容:ci 退出到回退 install 起跑之间 child 为 null——此时也置取消态,
+     * runNpm 起跑前复查即不再起新进程(否则回退的 npm 会跑到自然结束且无法再取消)。
+     */
+    cancel(): boolean;
+    private pushLine;
+    /** 跑一次 npm 子进程(采集尾行 + 超时 kill),返回退出码(null = 被杀死/启动失败)。 */
+    private runNpm;
+    /** 取消态判定。独立方法而非内联比较:cancel() 在 await 期间跨方法置位
+     *  phase,TS 的属性流分析不跟踪这种突变,内联比较会被窄化误报"无重叠"。 */
+    private wasCancelled;
+    private installOnce;
+}

package/dist/store/runtime-installer.js

@@ -0,0 +1,243 @@
+/**
+ * 运行时安装器:本地嵌入的推理运行时(@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 失败(锁与 package.json 漂移等)
+ *   自动回退 npm install 精确版本(可用性优先,树不再受锁);
+ * - 进度(用户硬性要求:不能傻等):npm 非交互模式无百分比 API,采用不确定进度——
+ *   已耗时 + 子进程 stdout/stderr 尾行实时流出 + 可 kill;
+ * - 幂等:已装版本 == 目标版本直接就绪;版本漂移(插件升级换了钉死版本)重装覆盖。
+ */
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 钉死的 transformers.js 版本(精确版本,升级插件时在此变更并重装运行时)。 */
+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)));
+                        },
+                        // Windows shell:true 下 child 只是 cmd.exe,npm/node 孙进程不随 child.kill()
+                        // 终止(超时与取消都会"表面停止")——taskkill /T 按进程树杀;启动失败回退裸 kill
+                        kill: () => {
+                            if (process.platform === 'win32' && child.pid !== undefined) {
+                                const tk = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true });
+                                tk.on('error', () => child.kill());
+                            }
+                            else {
+                                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 幂等重装)。
+     * 间隙兼容:ci 退出到回退 install 起跑之间 child 为 null——此时也置取消态,
+     * runNpm 起跑前复查即不再起新进程(否则回退的 npm 会跑到自然结束且无法再取消)。
+     */
+    cancel() {
+        if (this.progress.phase !== 'installing')
+            return false;
+        this.progress.phase = 'cancelled';
+        this.child?.kill();
+        return true;
+    }
+    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) {
+        // 起跑前复查取消:cancel() 在上一进程退出与本进程 spawn 之间的间隙置位时,不再起新进程
+        if (this.progress.phase === 'cancelled')
+            return null;
+        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;
+    }
+    /** 取消态判定。独立方法而非内联比较:cancel() 在 await 期间跨方法置位
+     *  phase,TS 的属性流分析不跟踪这种突变,内联比较会被窄化误报"无重叠"。 */
+    wasCancelled() {
+        return this.progress.phase === 'cancelled';
+    }
+    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 失败(锁与锚定版本漂移等)回退 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 回退 */
+        }
+        // ci 阶段被取消(退出码 null)不得落入回退分支——那是"ci 失败"语义,会让
+        // 取消后再白跑一次最长 10 分钟的 install
+        if (this.wasCancelled()) {
+            this.progress.elapsedMs = Date.now() - this.progress.startedAt;
+            this.logger?.warn('[memory] 运行时安装已取消(残留无害,重装幂等)');
+            return false;
+        }
+        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.wasCancelled()) {
+            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/scenes.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryFamily, MemoryLogger, SceneSummary } from '../types.js';
+export declare class SceneStore {
+    private readonly logger?;
+    private readonly dir;
+    private readonly family;
+    constructor(dataDir: string, family: MemoryFamily, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    /** 旧布局迁移:scenes/ 根下的 .md 移入本族目录。仅 chat 族执行(历史数据归属 chat)。 */
+    private migrateLegacyLayout;
+    listFiles(): Promise<string[]>;
+    /** 列出场景摘要(解析 META 块)。 */
+    list(): Promise<SceneSummary[]>;
+    read(name: string): Promise<string | undefined>;
+    /**
+     * 写入/重写场景文件。content 为 [DELETED] 时删除该文件(LLM 的 delete 操作)。
+     * 文件名自动归一化(空格→短横线、剔除非法字符),非法则抛错。
+     */
+    write(name: string, content: string): Promise<string>;
+    /** 场景导航索引(召回注入用)。 */
+    navigation(): Promise<string>;
+}
+/** 文件名归一化:只允许字母数字 CJK - _ .,以 .md 结尾,去空格/标点。
+ *  超长名截断到 120 字符(ENAMETOOLONG 防御);Windows 保留设备名加前缀 _ 避让。 */
+export declare function sanitizeFilename(name: string): string;