@max-null/dsh-memory 0.20.0 → 0.21.0

package/README.md

@@ -130,7 +130,7 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 
 | 项 | 默认值 |
 |---|---|
-| 备份内容 | `memory.json`（global）+ `memory_project_*.json`（project）+ `<DSH_HOME>/diary/*.md` |
+| 备份内容 | `memory.json`（global）+ 每个打开过的工作区各一份 `memory_project_*.json` + `<DSH_HOME>/diary/*.md` |
 | 目标目录 | 记忆：`~/.dsh-backups/memory/<时间戳>/`（**在 `DSH_HOME` 之外**）；日记：`~/.dsh-backups/memory/diary-archive/` |
 | 间隔 | 60 分钟（首次延迟 1 分钟）；**插件关闭时另补一次** |
 | 保留 | 记忆：最近 14 份；日记：全部（只增不删） |
@@ -138,7 +138,7 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 
 **边界**：
 
-- 只备份**当前工作区**的 project 文件（`<cwd>/.dsh/storages/`）；其它工作区的 project 记忆不在备份范围。
+- 备份**本轮运行打开过的所有工作区**的 project 文件：来源是引擎按会话 cwd 记下的那份工作区账，每轮备份时现取。**本轮一次都没打开过的工作区不在范围内**——备份是定时任务，没有「当前工作区」可问，打开过的才留得下痕迹。多个工作区给出同名文件时加递增后缀，绝不覆盖。
 - 只读文件、只复制——**绝不复用引擎的写入路径**。写路径会先 `reload()` 再合并，磁盘缺失时它会把内存覆盖掉，正是这次事故的成因；备份不能走同一条路。
 - 日记按**逐字节内容**判断是否已备份过，不按 mtime：复制与编辑都会动 mtime，内容才是事实。
 

package/dist/backup.d.ts

@@ -31,8 +31,14 @@ export interface MemoryBackupConfig {
 export interface MemoryBackupOptions {
     /** global 记忆的根（`$DSH_HOME/storages`）。 */
     globalRoot: string;
-    /** project 记忆的根（`<cwd>/.dsh/storages`）。 */
-    projectRoot: string;
+    /**
+     * project 记忆的根，一个工作区一项（`<cwd>/.dsh/storages`）。
+     *
+     * 是数组而非单值：项目记忆**按工作区分散**，一次运行里通常会打开好几个
+     * （本机实测同时存在 WorkStation / deepseek-harness / seek-soul-in-darkness
+     * 三份各自独立）。只备份一个等于默认放弃其余工作区的历史。
+     */
+    projectRoots: readonly string[];
     /** 日记的根（`$DSH_HOME/diary`）；缺省不备份日记。 */
     diaryRoot?: string;
     /** 备份根目录。 */

package/dist/backup.js

@@ -129,7 +129,7 @@ export function runMemoryBackup(options) {
         ? undefined
         : archiveDiary(options.diaryRoot, options.targetRoot, log);
     const globalFiles = candidateFiles(options.globalRoot, log).map(name => ({ name, from: join(options.globalRoot, name) }));
-    const projectFiles = candidateFiles(options.projectRoot, log).map(name => ({ name, from: join(options.projectRoot, name) }));
+    const projectFiles = options.projectRoots.flatMap(root => candidateFiles(root, log).map(name => ({ name, from: join(root, name) })));
     const sources = [...globalFiles, ...projectFiles];
     if (sources.length === 0) {
         log('memory backup: 没有可备份的记忆文件');
@@ -150,10 +150,22 @@ export function runMemoryBackup(options) {
         return { dir: null, files: [], pruned: [], error: message };
     }
     const files = [];
+    // 多个工作区可能给出同名文件（backend 名由 cwd 哈希得出，不同工作区几乎不会撞，
+    // 但不该把「备份的完整性」押在哈希碰撞概率上）。撞了就加递增后缀，绝不覆盖——
+    // 一次备份里静默少一份，等于这次备份没有做过。
+    const used = new Set();
     for (const source of sources) {
         try {
-            copyFileSync(source.from, join(dir, source.name));
-            files.push(source.name);
+            let name = source.name;
+            for (let suffix = 1; used.has(name); suffix += 1) {
+                name = source.name.replace(/\.json$/u, `-${String(suffix)}.json`);
+            }
+            copyFileSync(source.from, join(dir, name));
+            used.add(name);
+            files.push(name);
+            if (name !== source.name) {
+                log(`memory backup: ${source.from} 与本次快照里的同名文件冲突，落位为 ${name}`);
+            }
         }
         catch (error) {
             log(`memory backup: 复制 ${source.name} 失败: ${reason(error)}`);
@@ -163,7 +175,9 @@ export function runMemoryBackup(options) {
         writeFileSync(join(dir, 'manifest.json'), `${JSON.stringify({
             createdAt: now.toISOString(),
             globalRoot: options.globalRoot,
-            projectRoot: options.projectRoot,
+            // 记全部来源根：事后要判断「某个工作区的记忆到底有没有被备份到」，
+            // 只能靠这份清单——文件名里的哈希反推不出工作区路径。
+            projectRoots: [...options.projectRoots],
             files,
             // 日记不在本次快照目录里，manifest 只记「这一轮归档做了什么」，不列篇名。
             ...(diary === undefined ? {} : { diary: { root: options.diaryRoot, ...diary } }),

package/dist/engine.d.ts

@@ -360,6 +360,14 @@ export declare class MemoryEngine extends Service {
     private globalTable?;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     private projectTables;
+    /**
+     * 各 storage backend 的清理函数（摘名 + 关闭）。
+     *
+     * 不挂在独立 effect 上：cordis 的 dispose 后进先出，运行时才注册的那些会比
+     * `memory.domainsClose` 早执行，导致 domain 还握着 unit 时 backend 先关。
+     * 统一由 {@link closeBackends} 在 domain 全部关闭之后按插入顺序执行。
+     */
+    private readonly backendClosers;
     /** 子项目发现缓存（④-B 2026-09-19）：key = 工作区路径；值 = 其直接子目录中带记忆的（按条数降序）。 */
     private readonly neighborCache;
     /** 进行中的子项目发现（key → promise）：预热是 fire-and-forget，之后的显式调用与它合流而非重复扫描。 */
@@ -394,6 +402,15 @@ export declare class MemoryEngine extends Service {
     get lastSweepReport(): SweepReport | undefined;
     constructor(ctx: import('@deepseek-ai/cordis').Context, config?: MemoryConfig);
     protected [Service.init](): Promise<void>;
+    /**
+     * 注册一个 storage backend 并返回它的清理函数（摘名 + 关闭）。
+     *
+     * 清理函数**不立刻挂到 effect 上**，而是交给 {@link closeBackends} 在 domain 全部关闭
+     * 之后统一执行——理由见 `[Service.init]` 的注释。
+     */
+    private registerBackend;
+    /** 依次摘名并关闭所有已注册的 backend；必须由外部保证 domain 已先关闭。 */
+    private closeBackends;
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
     private openGlobalFacility;
     /** 工作区 project 存储根（<workspace>/.dsh/storages，随 git 分享）。 */
@@ -405,6 +422,19 @@ export declare class MemoryEngine extends Service {
      * 表已打开是常态，那时这条路径不该付出任何异步代价。
      */
     projectOpen(projectCwd?: string): boolean;
+    /**
+     * 已经打开过的工作区 project 存储根（`<cwd>/.dsh/storages`），供备份遍历。
+     *
+     * 备份是定时任务、没有会话 cwd，所以「现在在哪个工作区」这个问题它答不出来。
+     * 此前它拿 `process.cwd()` 兜底，而那是**进程启动目录**（桌面壳里通常是 profile
+     * 目录），与真实工作区无关——2026-11-05 实测：292 条项目记忆从未进过快照，备份
+     * 一直对着一个空目录反复报成功。
+     *
+     * 打开过的表由会话 cwd 驱动，见过的工作区都留在 {@link projectTables} 里；这是
+     * 备份唯一可靠的工作区来源。返回空数组表示「这次运行还没打开过任何工作区」，
+     * 由调用方决定回退策略。
+     */
+    projectStorageRoots(): string[];
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。

package/dist/engine.js

@@ -174,6 +174,14 @@ export class MemoryEngine extends Service {
     globalTable;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     projectTables = new Map();
+    /**
+     * 各 storage backend 的清理函数（摘名 + 关闭）。
+     *
+     * 不挂在独立 effect 上：cordis 的 dispose 后进先出，运行时才注册的那些会比
+     * `memory.domainsClose` 早执行，导致 domain 还握着 unit 时 backend 先关。
+     * 统一由 {@link closeBackends} 在 domain 全部关闭之后按插入顺序执行。
+     */
+    backendClosers = [];
     /** 子项目发现缓存（④-B 2026-09-19）：key = 工作区路径；值 = 其直接子目录中带记忆的（按条数降序）。 */
     neighborCache = new Map();
     /** 进行中的子项目发现（key → promise）：预热是 fire-and-forget，之后的显式调用与它合流而非重复扫描。 */
@@ -213,17 +221,55 @@ export class MemoryEngine extends Service {
         this.config = config;
     }
     async [Service.init]() {
-        // backend 只注册一次：registry 对重名注册抛 duplicate-backend
-        // （storage/tests/registry.spec 实测），reload 不得重复注册。
+        // backend 注册是**一个 effect**：`dsh-storage` 的 `BackendRegistry.register()` 契约是
+        // 「registration is an effect: the returned disposer removes the name」。丢掉那个 disposer
+        // 会让名字活过 fiber——issue #3 的真实成因：插件市场的更新流程会在同一进程里重新组合
+        // profile 并做一次构建校验，本 entry 第二次激活时 `register('memory-global', …)` 撞上
+        // 自己上次留下的名字，报 `duplicate-backend`；而那句报错被上层包装成「更新前的构建
+        // 未能验证恢复，请检查该 profile」，把用户引向「配置坏了」这个错误方向。
+        //
+        // **摘名与关闭不能各挂一个 effect**：cordis 的 dispose 后进先出，而 project backend 的
+        // effect 是运行时（`openProjectTable`）才注册的，会比这里晚注册、早执行——于是 domain
+        // 还握着 unit 时 backend 先被关掉，留下没释放的 open-slot，下一个实例打开同一目录
+        // 就失败（表现为「表打开了但一条都读不到」）。所以统一收进一个 closers 列表，
+        // 由本 effect 在**所有 domain 关闭之后**依次执行。
+        //
+        // reload 不重新注册 backend（见 `reload()`：它只重开 domain），所以这样改不改变
+        // reload 的语义——这些 closers 只在 dispose 时触发。
         const globalBackend = new JsonStorageBackend(this.config.globalRoot ?? globalRoot());
-        this.ctx.storage.backend.register('memory-global', globalBackend);
+        this.backendClosers.push(this.registerBackend('memory-global', globalBackend));
         await this.openGlobalFacility();
-        this.ctx.effect(() => () => {
-            void this.facility?.closeAll();
+        this.ctx.effect(() => async () => {
+            await this.facility?.closeAll();
             for (const facility of this.projectFacilities.values())
-                void facility.closeAll();
+                await facility.closeAll();
+            await this.closeBackends();
         }, 'memory.domainsClose');
     }
+    /**
+     * 注册一个 storage backend 并返回它的清理函数（摘名 + 关闭）。
+     *
+     * 清理函数**不立刻挂到 effect 上**，而是交给 {@link closeBackends} 在 domain 全部关闭
+     * 之后统一执行——理由见 `[Service.init]` 的注释。
+     */
+    registerBackend(name, backend) {
+        const unregister = this.ctx.storage.backend.register(name, backend);
+        return async () => {
+            unregister();
+            await backend.close();
+        };
+    }
+    /** 依次摘名并关闭所有已注册的 backend；必须由外部保证 domain 已先关闭。 */
+    async closeBackends() {
+        for (const close of this.backendClosers.splice(0)) {
+            try {
+                await close();
+            }
+            catch {
+                // 清理失败不该让 dispose 整体失败——名字可能已被别处摘掉。
+            }
+        }
+    }
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
     async openGlobalFacility() {
         const facility = new DomainFacility(this.ctx, { backend: 'memory-global', routes: {} });
@@ -252,6 +298,21 @@ export class MemoryEngine extends Service {
             return false;
         return this.projectTables.has(join(projectCwd));
     }
+    /**
+     * 已经打开过的工作区 project 存储根（`<cwd>/.dsh/storages`），供备份遍历。
+     *
+     * 备份是定时任务、没有会话 cwd，所以「现在在哪个工作区」这个问题它答不出来。
+     * 此前它拿 `process.cwd()` 兜底，而那是**进程启动目录**（桌面壳里通常是 profile
+     * 目录），与真实工作区无关——2026-11-05 实测：292 条项目记忆从未进过快照，备份
+     * 一直对着一个空目录反复报成功。
+     *
+     * 打开过的表由会话 cwd 驱动，见过的工作区都留在 {@link projectTables} 里；这是
+     * 备份唯一可靠的工作区来源。返回空数组表示「这次运行还没打开过任何工作区」，
+     * 由调用方决定回退策略。
+     */
+    projectStorageRoots() {
+        return [...this.projectTables.keys()].map(cwd => this.projectRootFor(cwd));
+    }
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
@@ -323,7 +384,10 @@ export class MemoryEngine extends Service {
         }
         if (!this.registeredProjectBackends.has(backendName)) {
             const backend = new JsonStorageBackend(root);
-            this.ctx.storage.backend.register(backendName, backend);
+            // 与 `memory-global` 同样走 closers 列表：`registeredProjectBackends` 只能防**同一
+            // 实例**内的重复注册，换一个实例这个 Set 就是空的，挡不住上一个 fiber 残留的名字
+            // （issue #3 里这一点被 `memory-global` 先撞上，所以看不出来）。
+            this.backendClosers.push(this.registerBackend(backendName, backend));
             this.registeredProjectBackends.add(backendName);
         }
         const facility = new DomainFacility(this.ctx, { backend: backendName, routes: {} });

package/dist/index.js

@@ -997,25 +997,47 @@ export async function apply(ctx, config) {
         const targetRoot = backup?.targetRoot ?? join(homedir(), '.dsh-backups', 'memory');
         const intervalMs = Math.max(1, backup?.intervalMinutes ?? 60) * 60_000;
         const keep = Math.max(1, backup?.keep ?? 14);
-        const roots = {
-            globalRoot: config?.globalRoot ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'storages'),
-            projectRoot: config?.projectRoot ?? join(process.cwd(), '.dsh', 'storages'),
-            // 日记在 `storages` 之外，得单独给根——漏了这一项就等于「备份记忆、不备份日记」。
-            diaryRoot: diaryDir(),
+        const globalRoot = config?.globalRoot ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'storages');
+        /**
+         * 本次要备份的 project 根。
+         *
+         * **每次备份时现算**，不能像 `globalRoot` 那样在启动时定死：工作区是随会话逐步
+         * 打开的，启动那一刻引擎里一个都没有，那时算出来永远是空的。
+         *
+         * 三档来源：引擎打开过的工作区（由会话 cwd 驱动，最可靠）、显式配置的
+         * `projectRoot`、两者都空时回退 `process.cwd()`。中间那一档要注意：`MemoryConfig`
+         * 把它注释成「project 记忆的根」，但**引擎实现从不读它**——它只在这里影响备份。
+         * 最后一档只是兜底——它是进程启动目录而非工作区，桌面壳里通常指向 profile
+         * 目录，那正是「项目记忆零快照」的成因（2026-11-05 实测：738 KB / 292 条从未
+         * 进过快照，备份一直对着空目录报成功）。
+         */
+        const projectRoots = () => {
+            const found = new Set(memory.projectStorageRoots());
+            if (config?.projectRoot !== undefined)
+                found.add(config.projectRoot);
+            if (found.size === 0)
+                found.add(join(process.cwd(), '.dsh', 'storages'));
+            return [...found];
+        };
+        const backupOnce = () => {
+            runMemoryBackup({
+                globalRoot,
+                projectRoots: projectRoots(),
+                // 日记在 `storages` 之外，得单独给根——漏了这一项就等于「备份记忆、不备份日记」。
+                diaryRoot: diaryDir(),
+                targetRoot,
+                keep,
+            });
         };
         ctx.effect(() => {
-            const first = setTimeout(() => {
-                runMemoryBackup({ ...roots, targetRoot, keep });
-            }, 60_000);
-            const timer = setInterval(() => {
-                runMemoryBackup({ ...roots, targetRoot, keep });
-            }, intervalMs);
+            const first = setTimeout(backupOnce, 60_000);
+            const timer = setInterval(backupOnce, intervalMs);
             timer.unref();
             return () => {
                 clearTimeout(first);
                 clearInterval(timer);
                 // 关闭时补一次：定时器只在运行期间生效，关 DSH 前最后一段变更靠这里兜住。
-                runMemoryBackup({ ...roots, targetRoot, keep });
+                backupOnce();
             };
         });
     }

package/dist/sync-export.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 同步导出层：把记忆库展开成「一条记忆一个文件」的镜像。
+ *
+ * **为什么需要它**：整份 `memory.json` 放进 git 会撞。2026-11-06 实测：两端各新增一条
+ * 记忆后 merge，`git` 报 `CONFLICT (content)`——两条记录挤在同一个插入点，按「取一边」
+ * 解决会静默丢掉另一端那条，而 git 仍报「合并成功」。改成一条一个文件后同一场景是
+ * `Merge made by the 'ort' strategy`，0 冲突。
+ *
+ * **为什么单独成模块**（与 `schema.ts` 同理由）：本模块只依赖 `node:path`，不 import
+ * cordis / dsh-storage / engine。这样单元测试与离线 CLI 能直接加载它，不必拉起整套
+ * 宿主依赖——否则「用插件自己的能力导出一份镜像」这条在用户环境里跑不起来。
+ *
+ * **同步面不带什么**（见设计文档 §5）：
+ * - `hitCount` / `lastUsedAt`：本地行为统计，每次检索命中都会改。带上它们会让镜像在内容
+ *   毫无变化时持续变脏，git 历史被噪声淹没。
+ * - `vector`：本地嵌入产物，体积大且可从 `content` 重算。
+ * - `quarantined` 的记录**整条不导出**：隔离区的存在理由就是它可能含凭据类内容，
+ *   推到远端仓库等于把那层保护绕开。
+ *
+ * @see docs/设计/2026-11-06-记忆云同步-设计方案.md
+ */
+/** 一条记录在镜像里的位置与内容。 */
+export interface SyncRecordFile {
+    /** 相对导出根的路径，如 `records/global/<uuid>.json`。 */
+    readonly path: string;
+    /** 文件内容（JSON + 末尾换行；已剔除同步面之外的字段）。 */
+    readonly content: string;
+}
+/** 导出的输入：各层记忆库的**解析后**文档。 */
+export interface SyncExportOptions {
+    /** `memory.json` 解析后的对象（global 层）。 */
+    readonly globalDocument: unknown;
+    /** 各工作区的记忆库文档；`cwd` 用于算目录名，须与引擎写入时一致。 */
+    readonly projectDocuments?: ReadonlyArray<{
+        readonly cwd: string;
+        readonly document: unknown;
+    }>;
+}
+/** 一次导出的结果。 */
+export interface SyncExportRun {
+    /** 待写入的记录文件（顺序稳定：global 在前，工作区按 cwd 排序）。 */
+    readonly files: readonly SyncRecordFile[];
+    /** 因处于隔离区而未导出的条数。 */
+    readonly skippedQuarantined: number;
+}
+/**
+ * 工作区目录名——必须与引擎写记忆文件名时用的口径一致（`engine.ts` 的
+ * `projectBackendName`：cwd 小写后过 djb2，取 base36）。
+ *
+ * 两边算法分叉的后果很隐蔽：镜像会落在另一个目录名下，另一端拉下来后
+ * 看起来像「这个项目的记忆凭空少了一批」。
+ */
+export declare function workspaceSlug(cwd: string): string;
+/**
+ * 把记忆库展开成镜像文件列表。**纯函数**：不读写磁盘、不看环境变量。
+ *
+ * @param options - 各层文档。
+ * @returns 待写入的文件与隔离跳过数。
+ */
+export declare function exportRecords(options: SyncExportOptions): SyncExportRun;

package/dist/sync-export.js

@@ -0,0 +1,141 @@
+/**
+ * 同步导出层：把记忆库展开成「一条记忆一个文件」的镜像。
+ *
+ * **为什么需要它**：整份 `memory.json` 放进 git 会撞。2026-11-06 实测：两端各新增一条
+ * 记忆后 merge，`git` 报 `CONFLICT (content)`——两条记录挤在同一个插入点，按「取一边」
+ * 解决会静默丢掉另一端那条，而 git 仍报「合并成功」。改成一条一个文件后同一场景是
+ * `Merge made by the 'ort' strategy`，0 冲突。
+ *
+ * **为什么单独成模块**（与 `schema.ts` 同理由）：本模块只依赖 `node:path`，不 import
+ * cordis / dsh-storage / engine。这样单元测试与离线 CLI 能直接加载它，不必拉起整套
+ * 宿主依赖——否则「用插件自己的能力导出一份镜像」这条在用户环境里跑不起来。
+ *
+ * **同步面不带什么**（见设计文档 §5）：
+ * - `hitCount` / `lastUsedAt`：本地行为统计，每次检索命中都会改。带上它们会让镜像在内容
+ *   毫无变化时持续变脏，git 历史被噪声淹没。
+ * - `vector`：本地嵌入产物，体积大且可从 `content` 重算。
+ * - `quarantined` 的记录**整条不导出**：隔离区的存在理由就是它可能含凭据类内容，
+ *   推到远端仓库等于把那层保护绕开。
+ *
+ * @see docs/设计/2026-11-06-记忆云同步-设计方案.md
+ */
+import { join } from 'node:path';
+/**
+ * 进入同步面的字段白名单。
+ *
+ * 用白名单而不是黑名单：`StoredBlock` 以后还会长出新字段（`topic` 就是 0.20.0 才加的），
+ * 黑名单会让新字段**默认泄漏**进来——而「一个只该存在本地的字段漏进远端仓库」这类事故，
+ * 发现的时候内容已经在别人能拉到的地方了。
+ */
+const SYNCED_FIELDS = [
+    'namespace',
+    'status',
+    'content',
+    'keywords',
+    'createdAt',
+    'updatedAt',
+    'injected',
+    'injectedAuto',
+    'topic',
+    'kind',
+    'anchor',
+    'stale',
+    'staleReason',
+    'source',
+    'meta',
+];
+/** 记录文件的目录名（与清单文件同级）。 */
+const RECORDS_DIR = 'records';
+/** 把 `unknown` 收窄成对象；不是对象返回 `undefined`。 */
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * 取出一份 unit 文档里的 blocks 表。
+ *
+ * 文档形状是 DSH storage 的 unit 格式：`{ unit, global, tables: { blocks: {...} } }`。
+ * 形状不符时返回空表而不是抛错——镜像导出不该因为一个损坏的库把整个同步卡死，
+ * 条数为 0 会被上层当作「没有可导出的东西」处理。
+ */
+function blocksOf(document) {
+    const doc = asObject(document);
+    const tables = asObject(doc?.tables);
+    const blocks = asObject(tables?.blocks);
+    if (blocks === undefined)
+        return {};
+    const out = {};
+    for (const [id, block] of Object.entries(blocks)) {
+        const value = asObject(block);
+        if (value !== undefined)
+            out[id] = value;
+    }
+    return out;
+}
+/**
+ * 工作区目录名——必须与引擎写记忆文件名时用的口径一致（`engine.ts` 的
+ * `projectBackendName`：cwd 小写后过 djb2，取 base36）。
+ *
+ * 两边算法分叉的后果很隐蔽：镜像会落在另一个目录名下，另一端拉下来后
+ * 看起来像「这个项目的记忆凭空少了一批」。
+ */
+export function workspaceSlug(cwd) {
+    let hash = 5381;
+    const text = cwd.toLowerCase();
+    for (let index = 0; index < text.length; index += 1) {
+        hash = ((hash << 5) + hash + text.charCodeAt(index)) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+/** 只保留白名单字段；值为 `undefined` 的键不落进文件（避免 `"x": null` 噪声）。 */
+function pickSyncedFields(block) {
+    const out = {};
+    for (const field of SYNCED_FIELDS) {
+        const value = block[field];
+        if (value !== undefined)
+            out[field] = value;
+    }
+    return out;
+}
+/** 一条记录 → 一个文件；返回 `undefined` 表示这条不该进镜像（隔离区）。 */
+function recordFile(id, block, segments) {
+    if (block.quarantined === true)
+        return undefined;
+    const payload = pickSyncedFields(block);
+    return {
+        path: join(...segments, `${id}.json`),
+        content: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+}
+/**
+ * 把记忆库展开成镜像文件列表。**纯函数**：不读写磁盘、不看环境变量。
+ *
+ * @param options - 各层文档。
+ * @returns 待写入的文件与隔离跳过数。
+ */
+export function exportRecords(options) {
+    const files = [];
+    let skippedQuarantined = 0;
+    for (const [id, block] of Object.entries(blocksOf(options.globalDocument))) {
+        const file = recordFile(id, block, [RECORDS_DIR, 'global']);
+        if (file === undefined) {
+            skippedQuarantined += 1;
+            continue;
+        }
+        files.push(file);
+    }
+    // 工作区按 cwd 排序：让两次导出的文件顺序稳定，git 不必为顺序抖动产生 diff。
+    const projects = [...(options.projectDocuments ?? [])].sort((left, right) => left.cwd.localeCompare(right.cwd));
+    for (const { cwd, document } of projects) {
+        for (const [id, block] of Object.entries(blocksOf(document))) {
+            const file = recordFile(id, block, [RECORDS_DIR, 'project', workspaceSlug(cwd)]);
+            if (file === undefined) {
+                skippedQuarantined += 1;
+                continue;
+            }
+            files.push(file);
+        }
+    }
+    return { files, skippedQuarantined };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {