@max-null/dsh-memory 0.21.0 → 0.22.1

package/dist/sync-service.js

@@ -0,0 +1,347 @@
+/**
+ * 同步编排：把导出 / 写盘 / 墓碑 / git / 远端五层串成一次操作。
+ *
+ * 这一层没有自己的算法，只有**顺序**。顺序在这里是有意义的：
+ *
+ * push 时先写镜像与墓碑、再提交、最后推送——反过来的话，一次失败会留下
+ * 「远端已有、本地没有」的状态，下次 push 会把差异当成删除。
+ *
+ * pull 时先拉、再规划导入、最后逐条落地——导入是唯一会改本地记忆库的一步，
+ * 放在最后意味着前面任何一步失败都不会动数据。
+ *
+ * @module dsh-memory/sync-service
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { exportRecords } from "./sync-export.js";
+import { commitMirror, readHistory } from "./sync-git.js";
+import { planImport } from "./sync-import.js";
+import { SYNC_STATE_FILE, TOMBSTONE_DIR, dropTombstoned, planTombstones } from "./sync-tombstone.js";
+import { ensureMirrorRepo, ensureRemote, pullMirror, pushMirror } from "./sync-remote.js";
+import { writeMirror } from "./sync-writer.js";
+/** 作者信息——isomorphic-git 没有可读的全局配置，必须显式给。 */
+const AUTHOR = { name: 'dsh-memory', email: 'dsh-memory@localhost' };
+/** 把一份 unit 文档里的 block 取出来。 */
+function blocksOfDocument(document) {
+    const doc = document;
+    return doc?.tables?.blocks ?? {};
+}
+/** 记录数组 → unit 文档形状（`exportRecords` 的入参）。 */
+function recordsToDocument(records) {
+    const blocks = {};
+    for (const record of records) {
+        const { id, ...rest } = record;
+        blocks[id] = rest;
+    }
+    return { tables: { blocks } };
+}
+/**
+ * 收集当前记忆库应有的镜像文件。
+ *
+ * 空项目不产生目录——`records/project/<name>/` 里一个文件都没有时，那个目录本身
+ * 不该出现在仓库里（否则每加一个空项目就多一个空目录）。
+ *
+ * @param memory - 引擎实例。
+ * @returns 待写入的记录文件列表。
+ */
+export async function collectMirror(memory) {
+    const global = await memory.list({ namespace: 'global' });
+    const projectDocuments = [];
+    for (const cwd of memory.projectCwds()) {
+        const records = await memory.list({ namespace: 'project' }, cwd);
+        if (records.length === 0)
+            continue;
+        projectDocuments.push({ cwd, document: recordsToDocument(records) });
+    }
+    return exportRecords({ globalDocument: recordsToDocument(global), projectDocuments }).files;
+}
+/** 从镜像文件列表推出「当前有哪些 id」——墓碑比对的当前态。 */
+function stateOfFiles(files) {
+    const global = [];
+    const project = {};
+    for (const file of files) {
+        const parts = file.path.replace(/\\/gu, '/').split('/');
+        // records/global/<id>.json 或 records/project/<name>/<id>.json
+        if (parts[0] !== 'records' || parts.length < 3)
+            continue;
+        const id = parts[parts.length - 1]?.replace(/\.json$/u, '') ?? '';
+        if (id === '')
+            continue;
+        if (parts[1] === 'global')
+            global.push(id);
+        else if (parts[1] === 'project' && parts.length >= 4) {
+            const name = parts[2] ?? '';
+            (project[name] ??= []).push(id);
+        }
+    }
+    return { global, project };
+}
+/** 读上一次同步留下的状态；没有时返回 `undefined`（首次同步）。 */
+function readState(dir) {
+    const file = join(dir, SYNC_STATE_FILE);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return {
+            global: Array.isArray(parsed.global) ? parsed.global : [],
+            project: typeof parsed.project === 'object' && parsed.project !== null ? parsed.project : {},
+        };
+    }
+    catch {
+        // 坏了就当没有：宁可这轮不产生墓碑，也不要基于坏数据删东西。
+        return undefined;
+    }
+}
+/** 写状态文件。 */
+function writeState(dir, state) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, SYNC_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/** 把墓碑落成文件（`tombstones/<id>.json`）。 */
+function writeTombstones(dir, tombstones) {
+    if (tombstones.length === 0)
+        return;
+    const target = join(dir, TOMBSTONE_DIR);
+    mkdirSync(target, { recursive: true });
+    for (const tombstone of tombstones) {
+        writeFileSync(join(target, `${tombstone.id}.json`), `${JSON.stringify(tombstone, null, 2)}\n`, 'utf8');
+    }
+}
+/**
+ * 推一次：收集 → 写镜像 → 写墓碑 → 提交 → 推送。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点（测试用）。
+ * @returns 各阶段统计；远端失败时保留本地提交已完成的事实。
+ */
+export async function syncPush(memory, config, now = Date.now()) {
+    // 首次同步**必须先 clone**：本地 `git init` 出来的仓库与远端是两条无关的历史线，
+    // push 会被拒（`not a simple fast-forward`）。这一步得在写镜像之前，否则写好的内容
+    // 会被随后的 clone 覆盖掉。
+    if (config.remote !== undefined && config.remote !== '' && !existsSync(join(config.mirrorDir, '.git'))) {
+        const ready = await ensureMirrorRepo({
+            dir: config.mirrorDir,
+            url: config.remote,
+            ...config.branch === undefined ? {} : { branch: config.branch },
+            ...config.token === undefined ? {} : { token: config.token },
+        });
+        if (!ready.cloned) {
+            return {
+                files: 0,
+                written: 0,
+                unchanged: 0,
+                removed: 0,
+                tombstones: 0,
+                committed: false,
+                pushed: false,
+                error: `首次同步无法 clone 远端：${ready.error ?? '未知原因'}`,
+                ...ready.kind === undefined ? {} : { errorKind: ready.kind },
+            };
+        }
+    }
+    const files = await collectMirror(memory);
+    const write = writeMirror({ targetDir: config.mirrorDir, files });
+    // 墓碑：用「上次状态」与「本次要写的 id」对比。首次同步没有上次状态 → 不产生墓碑。
+    const previous = readState(config.mirrorDir);
+    const current = stateOfFiles(files);
+    const tombstones = planTombstones({ previous, current, at: now });
+    writeTombstones(config.mirrorDir, tombstones);
+    writeState(config.mirrorDir, dropTombstoned(current, tombstones));
+    const commit = await commitMirror({
+        dir: config.mirrorDir,
+        message: `sync: ${files.length} 条记录${tombstones.length > 0 ? `，${tombstones.length} 条墓碑` : ''}`,
+        author: AUTHOR,
+    });
+    if (config.remote === undefined || config.remote === '') {
+        return {
+            files: files.length,
+            written: write.written,
+            unchanged: write.unchanged,
+            removed: write.removed,
+            tombstones: tombstones.length,
+            committed: commit.committed,
+            ...commit.sha === undefined ? {} : { sha: commit.sha },
+            pushed: false,
+            error: '未配置远端地址（memory.sync.remote）—— 已完成本地提交',
+        };
+    }
+    await ensureRemote(config.mirrorDir, config.remote);
+    const remote = await pushMirror({
+        dir: config.mirrorDir,
+        url: config.remote,
+        ...config.branch === undefined ? {} : { branch: config.branch },
+        ...config.token === undefined ? {} : { token: config.token },
+    });
+    return {
+        files: files.length,
+        written: write.written,
+        unchanged: write.unchanged,
+        removed: write.removed,
+        tombstones: tombstones.length,
+        committed: commit.committed,
+        ...commit.sha === undefined ? {} : { sha: commit.sha },
+        pushed: remote.ok,
+        ...remote.error === undefined ? {} : { error: remote.error },
+        ...remote.kind === undefined ? {} : { errorKind: remote.kind },
+    };
+}
+/** 读镜像目录里的记录文件。 */
+function readIncoming(mirrorDir) {
+    const root = join(mirrorDir, 'records');
+    if (!existsSync(root))
+        return [];
+    const incoming = [];
+    const walk = (dir, segments) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                walk(join(dir, entry.name), [...segments, entry.name]);
+                continue;
+            }
+            if (!entry.name.endsWith('.json'))
+                continue;
+            const id = entry.name.replace(/\.json$/u, '');
+            try {
+                const block = JSON.parse(readFileSync(join(dir, entry.name), 'utf8'));
+                if (segments[0] === 'global')
+                    incoming.push({ id, scope: 'global', block });
+                else if (segments[0] === 'project' && segments.length >= 2) {
+                    incoming.push({ id, scope: 'project', projectName: segments[1] ?? '', block });
+                }
+            }
+            catch {
+                // 坏文件跳过：一条损坏不该挡住整次拉取。
+            }
+        }
+    };
+    walk(root, []);
+    return incoming;
+}
+/**
+ * 拉一次：拉取 → 规划导入 → 逐条落地。
+ *
+ * 冲突不自动裁决：两边版本都写进 `conflicts/`，本地版本保留（§3.3）。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点。
+ * @returns 导入统计。
+ */
+export async function syncPull(memory, config, now = Date.now()) {
+    if (config.remote !== undefined && config.remote !== '') {
+        // 同 push：首次必须先 clone，否则本地 init 出来的仓库与远端没有共同祖先。
+        if (!existsSync(join(config.mirrorDir, '.git'))) {
+            const ready = await ensureMirrorRepo({
+                dir: config.mirrorDir,
+                url: config.remote,
+                ...config.branch === undefined ? {} : { branch: config.branch },
+                ...config.token === undefined ? {} : { token: config.token },
+            });
+            if (!ready.cloned) {
+                return {
+                    pulled: false,
+                    imported: 0,
+                    conflicts: 0,
+                    orphaned: 0,
+                    error: `首次同步无法 clone 远端：${ready.error ?? '未知原因'}`,
+                    ...ready.kind === undefined ? {} : { errorKind: ready.kind },
+                };
+            }
+        }
+        await ensureRemote(config.mirrorDir, config.remote);
+        const remote = await pullMirror({
+            dir: config.mirrorDir,
+            url: config.remote,
+            ...config.branch === undefined ? {} : { branch: config.branch },
+            ...config.token === undefined ? {} : { token: config.token },
+        });
+        if (!remote.ok) {
+            return {
+                pulled: false,
+                imported: 0,
+                conflicts: 0,
+                orphaned: 0,
+                ...remote.error === undefined ? {} : { error: remote.error },
+                ...remote.kind === undefined ? {} : { errorKind: remote.kind },
+            };
+        }
+    }
+    const incoming = readIncoming(config.mirrorDir);
+    // 本地各层现状
+    const globalRecords = await memory.list({ namespace: 'global' });
+    const localGlobal = { blocks: blocksOfDocument(recordsToDocument(globalRecords)) };
+    const localProjects = {};
+    for (const cwd of memory.projectCwds()) {
+        const name = (cwd.replace(/\\/gu, '/').split('/').pop() ?? '').toLowerCase();
+        if (name === '')
+            continue;
+        const records = await memory.list({ namespace: 'project' }, cwd);
+        localProjects[name] = { blocks: blocksOfDocument(recordsToDocument(records)) };
+    }
+    const plan = planImport({ incoming, localGlobal, localProjects });
+    // 冲突留证：两边都写进 conflicts/
+    if (plan.conflicts.length > 0) {
+        const dir = join(config.mirrorDir, 'conflicts');
+        mkdirSync(dir, { recursive: true });
+        for (const conflict of plan.conflicts) {
+            const env = config.envName ?? 'local';
+            writeFileSync(join(dir, `${conflict.id}.${env}.json`), `${JSON.stringify(conflict, null, 2)}\n`, 'utf8');
+        }
+    }
+    // 逐条落地（唯一会改本地记忆库的一步）
+    let imported = 0;
+    for (const upsert of plan.upserts) {
+        const cwd = upsert.scope === 'project' && upsert.projectName !== undefined
+            ? memory.projectCwds().find(candidate => (candidate.replace(/\\/gu, '/').split('/').pop() ?? '').toLowerCase() === upsert.projectName?.toLowerCase())
+            : undefined;
+        if (upsert.scope === 'project' && cwd === undefined)
+            continue;
+        try {
+            await memory.adopt(upsert.id, upsert.block, cwd);
+            imported += 1;
+        }
+        catch {
+            // 单条失败跳过——一条不合规不该挡住整次拉取。
+        }
+    }
+    return {
+        pulled: true,
+        imported,
+        conflicts: plan.conflicts.length,
+        orphaned: plan.orphaned.length,
+    };
+}
+/**
+ * 查同步状态。
+ *
+ * @param config - 同步配置。
+ * @returns 镜像目录、最近提交、冲突与墓碑数量。
+ */
+export async function syncStatus(config) {
+    const initialized = existsSync(join(config.mirrorDir, '.git'));
+    const history = initialized ? await readHistory(config.mirrorDir) : [];
+    const conflictsDir = join(config.mirrorDir, 'conflicts');
+    const tombstonesDir = join(config.mirrorDir, TOMBSTONE_DIR);
+    const countFiles = (dir) => {
+        if (!existsSync(dir))
+            return 0;
+        return readdirSync(dir).filter(name => name.endsWith('.json')).length;
+    };
+    return {
+        mirrorDir: config.mirrorDir,
+        initialized,
+        ...config.remote === undefined ? {} : { remote: config.remote },
+        ...history[0] === undefined ? {} : { lastCommit: history[0] },
+        commits: history.length,
+        conflicts: countFiles(conflictsDir),
+        tombstones: countFiles(tombstonesDir),
+    };
+}
+/** 便于测试：导出一份当前冲突的快照。 */
+export function conflictFiles(config) {
+    const dir = join(config.mirrorDir, 'conflicts');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter(name => name.endsWith('.json'));
+}

package/dist/sync-tombstone.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 同步墓碑：把 `memory_forget` 的真删表达成「记录被修改」，而不是「文件消失」。
+ *
+ * **为什么需要**（设计 §3.1）：多写者下，本地看着「git 里有、我这儿没有」有两种可能——
+ * 本机删了（该删远端），或另一端刚加、我还没拉到（该拉下来）。两种情况的正确动作**完全
+ * 相反**，靠猜一定出错。
+ *
+ * 区分它们的唯一依据是**上一次同步时本机有哪些 id**：曾同步过、现在没了 ⇒ 本机删的。
+ * 所以本模块配一个随仓库走的 `.sync-state.json`。
+ *
+ * **墓碑不删文件、只改文件**，还顺带避开 git 里最难处理的 modify/delete 冲突：删除与
+ * 「另一端改了同一条」于是变成同一类冲突。
+ *
+ * **不记删前内容**：内容在 git 历史里（文件被删除但仍在历史），墓碑只负责回答
+ * 「这条是被删的还是还没同步到」。省下的体积换的是快照体积可控。
+ *
+ * @module dsh-memory/sync-tombstone
+ */
+/** 随同步仓库走的本地状态。 */
+export interface SyncState {
+    /** 上次同步时 global 层有哪些 id。 */
+    readonly global: readonly string[];
+    /** 上次同步时各项目有哪些 id（项目名已小写）。 */
+    readonly project: Readonly<Record<string, readonly string[]>>;
+}
+/** 一条墓碑。 */
+export interface Tombstone {
+    readonly id: string;
+    readonly scope: 'global' | 'project';
+    /** `project` 作用域下的项目名。 */
+    readonly projectName?: string;
+    readonly deletedAt: number;
+}
+/** {@link planTombstones} 的入参。 */
+export interface TombstonePlanOptions {
+    /** 上一次同步留下的状态；首次同步时为 `undefined`。 */
+    readonly previous: SyncState | undefined;
+    /** 当前本地各层实际有哪些 id。 */
+    readonly current: SyncState;
+    /** 删除时刻（epoch ms）；测试可注入。 */
+    readonly at: number;
+}
+/** 状态文件在同步仓库里的位置。 */
+export declare const SYNC_STATE_FILE = ".sync-state.json";
+/** 状态文件的相对路径（含墓碑目录）。 */
+export declare const TOMBSTONE_DIR = "tombstones";
+/**
+ * 对比上一次与当前的 id 集合，算出本次该写哪些墓碑。
+ *
+ * **首次同步（`previous` 为空）永远不产生墓碑**：那时没有「曾经有过」这个信息，
+ * 把所有"远端有、本地没有"都判成删除会把另一端刚记的东西全删掉。这是整个模块最容易
+ * 写错的一处。
+ *
+ * @param options - 上次状态、当前状态与删除时刻。
+ * @returns 待写墓碑列表。
+ */
+export declare function planTombstones(options: TombstonePlanOptions): Tombstone[];
+/**
+ * 把墓碑合并进上一次的状态：写过的墓碑不该在下一轮又被判成"删除"。
+ *
+ * 具体做法是把墓碑 id 从 `previous` 里剔掉——它们的删除已经被记录过了。
+ *
+ * @param state - 刚刚用于比对的那份状态。
+ * @param written - 本次写下的墓碑。
+ * @returns 更新后的状态。
+ */
+export declare function dropTombstoned(state: SyncState, written: readonly Tombstone[]): SyncState;

package/dist/sync-tombstone.js

@@ -0,0 +1,83 @@
+/**
+ * 同步墓碑：把 `memory_forget` 的真删表达成「记录被修改」，而不是「文件消失」。
+ *
+ * **为什么需要**（设计 §3.1）：多写者下，本地看着「git 里有、我这儿没有」有两种可能——
+ * 本机删了（该删远端），或另一端刚加、我还没拉到（该拉下来）。两种情况的正确动作**完全
+ * 相反**，靠猜一定出错。
+ *
+ * 区分它们的唯一依据是**上一次同步时本机有哪些 id**：曾同步过、现在没了 ⇒ 本机删的。
+ * 所以本模块配一个随仓库走的 `.sync-state.json`。
+ *
+ * **墓碑不删文件、只改文件**，还顺带避开 git 里最难处理的 modify/delete 冲突：删除与
+ * 「另一端改了同一条」于是变成同一类冲突。
+ *
+ * **不记删前内容**：内容在 git 历史里（文件被删除但仍在历史），墓碑只负责回答
+ * 「这条是被删的还是还没同步到」。省下的体积换的是快照体积可控。
+ *
+ * @module dsh-memory/sync-tombstone
+ */
+/** 状态文件在同步仓库里的位置。 */
+export const SYNC_STATE_FILE = '.sync-state.json';
+/** 状态文件的相对路径（含墓碑目录）。 */
+export const TOMBSTONE_DIR = 'tombstones';
+/**
+ * 对比上一次与当前的 id 集合，算出本次该写哪些墓碑。
+ *
+ * **首次同步（`previous` 为空）永远不产生墓碑**：那时没有「曾经有过」这个信息，
+ * 把所有"远端有、本地没有"都判成删除会把另一端刚记的东西全删掉。这是整个模块最容易
+ * 写错的一处。
+ *
+ * @param options - 上次状态、当前状态与删除时刻。
+ * @returns 待写墓碑列表。
+ */
+export function planTombstones(options) {
+    const { previous, current, at } = options;
+    if (previous === undefined)
+        return [];
+    const tombstones = [];
+    const currentGlobal = new Set(current.global);
+    for (const id of previous.global) {
+        if (!currentGlobal.has(id))
+            tombstones.push({ id, scope: 'global', deletedAt: at });
+    }
+    for (const [projectName, ids] of Object.entries(previous.project)) {
+        const still = new Set(current.project[projectName] ?? []);
+        for (const id of ids) {
+            if (!still.has(id))
+                tombstones.push({ id, scope: 'project', projectName, deletedAt: at });
+        }
+    }
+    return tombstones;
+}
+/**
+ * 把墓碑合并进上一次的状态：写过的墓碑不该在下一轮又被判成"删除"。
+ *
+ * 具体做法是把墓碑 id 从 `previous` 里剔掉——它们的删除已经被记录过了。
+ *
+ * @param state - 刚刚用于比对的那份状态。
+ * @param written - 本次写下的墓碑。
+ * @returns 更新后的状态。
+ */
+export function dropTombstoned(state, written) {
+    if (written.length === 0)
+        return state;
+    const globalGone = new Set(written.filter(t => t.scope === 'global').map(t => t.id));
+    const projectGone = new Map();
+    for (const tombstone of written) {
+        if (tombstone.scope !== 'project' || tombstone.projectName === undefined)
+            continue;
+        const key = tombstone.projectName;
+        const set = projectGone.get(key) ?? new Set();
+        set.add(tombstone.id);
+        projectGone.set(key, set);
+    }
+    const project = {};
+    for (const [name, ids] of Object.entries(state.project)) {
+        const gone = projectGone.get(name);
+        project[name] = gone === undefined ? ids : ids.filter(id => !gone.has(id));
+    }
+    return {
+        global: state.global.filter(id => !globalGone.has(id)),
+        project,
+    };
+}

package/dist/sync-writer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 同步写盘层：把 {@link exportRecords} 的输出落到磁盘上的镜像目录。
+ *
+ * **两条硬要求**（见设计文档 §9.2 第 1 步）：
+ *
+ * 1. **增量**：内容相同的文件不重写。不做这件事的后果不是"慢"，是每次写盘都产生
+ *    一批 mtime 变动——git 看起来像全量改动，`git log` 与 `git diff` 随即失去意义。
+ * 2. **删除先算差集**：现有文件里不在待写列表的才算该删。不能边扫边删——边扫边删
+ *    在目录枚举顺序变化时会漏删或错删。
+ *
+ * **只管 `records/`**：`conflicts/`（§3.3 的留证）与 `index.json`（§3.2 的派生品）
+ * 都不归这里管。写盘层负责的是"把记忆库投影成一条一文件"，不是"维护整个同步仓库"。
+ *
+ * @module dsh-memory/sync-writer
+ */
+import type { SyncRecordFile } from './sync-export.ts';
+/** {@link writeMirror} 的入参。 */
+export interface MirrorWriteOptions {
+    /** 镜像仓库的根（`records/` 就在它下面）。 */
+    readonly targetDir: string;
+    /** 待写入的记录文件；路径相对 `targetDir`。 */
+    readonly files: readonly SyncRecordFile[];
+}
+/** 一次写盘的结果。 */
+export interface MirrorWriteRun {
+    /** 真正写了的文件数（内容有变化的）。 */
+    readonly written: number;
+    /** 内容与磁盘一致的、跳过的文件数。 */
+    readonly unchanged: number;
+    /** 被删掉的文件数。 */
+    readonly removed: number;
+    /** 被删掉的相对路径（便于日志与测试断言）。 */
+    readonly removedPaths: readonly string[];
+}
+/**
+ * 把记录文件镜像到磁盘。**纯 IO，不读写任何记忆状态**。
+ *
+ * 三个步骤按固定顺序：先算差集（该删哪些）、再写（内容有变的）、最后删。
+ * 顺序不能调换——先删会让"写失败 + 删成功"变成净损失。
+ *
+ * 单文件失败不会中断整批：记忆镜像少一份总比整次同步失败好，缺的那份下次写盘会补上。
+ *
+ * @param options - 目标目录与待写文件。
+ * @returns 写入 / 跳过 / 删除的统计。
+ */
+export declare function writeMirror(options: MirrorWriteOptions): MirrorWriteRun;

package/dist/sync-writer.js

@@ -0,0 +1,85 @@
+/**
+ * 同步写盘层：把 {@link exportRecords} 的输出落到磁盘上的镜像目录。
+ *
+ * **两条硬要求**（见设计文档 §9.2 第 1 步）：
+ *
+ * 1. **增量**：内容相同的文件不重写。不做这件事的后果不是"慢"，是每次写盘都产生
+ *    一批 mtime 变动——git 看起来像全量改动，`git log` 与 `git diff` 随即失去意义。
+ * 2. **删除先算差集**：现有文件里不在待写列表的才算该删。不能边扫边删——边扫边删
+ *    在目录枚举顺序变化时会漏删或错删。
+ *
+ * **只管 `records/`**：`conflicts/`（§3.3 的留证）与 `index.json`（§3.2 的派生品）
+ * 都不归这里管。写盘层负责的是"把记忆库投影成一条一文件"，不是"维护整个同步仓库"。
+ *
+ * @module dsh-memory/sync-writer
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** 记录文件所在的顶层目录名。 */
+const RECORDS_DIR = 'records';
+/** 路径规范成 `/` 分隔——`exportRecords` 用 `join()` 产出，在 Windows 上是反斜杠。 */
+function normalize(path) {
+    return path.replace(/\\/gu, '/');
+}
+/** 递归列出 `root` 下的文件，返回相对 `relBase` 的路径（`/` 分隔）。 */
+function scan(root, relBase) {
+    if (!existsSync(root))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const rel = relBase === '' ? entry.name : `${relBase}/${entry.name}`;
+        if (entry.isDirectory())
+            found.push(...scan(join(root, entry.name), rel));
+        else
+            found.push(rel);
+    }
+    return found;
+}
+/**
+ * 把记录文件镜像到磁盘。**纯 IO，不读写任何记忆状态**。
+ *
+ * 三个步骤按固定顺序：先算差集（该删哪些）、再写（内容有变的）、最后删。
+ * 顺序不能调换——先删会让"写失败 + 删成功"变成净损失。
+ *
+ * 单文件失败不会中断整批：记忆镜像少一份总比整次同步失败好，缺的那份下次写盘会补上。
+ *
+ * @param options - 目标目录与待写文件。
+ * @returns 写入 / 跳过 / 删除的统计。
+ */
+export function writeMirror(options) {
+    const recordsRoot = join(options.targetDir, RECORDS_DIR);
+    // 待写集合：normalize 之后的相对路径 → 内容
+    const wanted = new Map();
+    for (const file of options.files)
+        wanted.set(normalize(file.path), file.content);
+    // 差集先算：磁盘上有、但这次不该存在的，才是要删的
+    const stale = scan(recordsRoot, RECORDS_DIR).filter(path => !wanted.has(path));
+    let written = 0;
+    let unchanged = 0;
+    for (const [relativePath, content] of wanted) {
+        const absolute = join(options.targetDir, relativePath);
+        try {
+            if (existsSync(absolute) && readFileSync(absolute, 'utf8') === content) {
+                unchanged += 1;
+                continue;
+            }
+            mkdirSync(dirname(absolute), { recursive: true });
+            writeFileSync(absolute, content, 'utf8');
+            written += 1;
+        }
+        catch {
+            // 单个文件写失败不中断整批；缺的那份下次写盘会补。
+        }
+    }
+    const removedPaths = [];
+    for (const relativePath of stale) {
+        try {
+            rmSync(join(options.targetDir, relativePath), { force: true });
+            removedPaths.push(relativePath);
+        }
+        catch {
+            // 同上：删除失败留到下次。
+        }
+    }
+    return { written, unchanged, removed: removedPaths.length, removedPaths };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "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": {
@@ -66,6 +66,7 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
+    "isomorphic-git": "^1.44.11",
     "zod": "^4.4.3"
   },
   "peerDependencies": {