@max-null/dsh-memory 0.20.0 → 0.22.0

package/dist/self.js

@@ -25,7 +25,8 @@ export const SELF_VERSION = (() => {
     }
 })();
 export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 14 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_move / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_move` 把放错了层的记忆移到 global、当前工作区或相对祖先；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
+    + '你有 16 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_move / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_move` 把放错了层的记忆移到 global、当前工作区或相对祖先；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
+    + '**同步工具** memory_sync / memory_conflicts：跨环境同步；`memory_sync` 的 `status` 只看状态、`pull` 拉取并导入、`push` 镜像并推送，`memory_conflicts` 列出**未被自动裁决**的冲突，同步**不会**自动决定哪一边对——两边都改过同一条时两个版本都留着等人处理，记忆被静默覆盖就没了；'
     + '**日记工具** diary_read / diary_write：日记是 md 文件，落在 `<DSH_HOME>/diary`，与记忆**分开存、不进检索、不占注入预算**。记的是经历——发生了什么（有细节）、我怎么想（可以有情绪、可以没结论）、关于他（他说了什么、我注意到了什么）；不是任务清单（那是 git log），也不是结论（那是 memory_save）。读它不吃预算，需要时整篇读。'
     + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
     + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'

package/dist/sync-export.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 同步导出层：把记忆库展开成「一条记忆一个文件」的镜像。
+ *
+ * **为什么需要它**：整份 `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;
+}
+/**
+ * 项目在同步面上的目录名——**项目目录名，不是路径哈希**。
+ *
+ * 2026-11-06 的第一版用的是 `cwd` 的 djb2 哈希（与引擎本地文件名同口径）。那个身份
+ * 只在一台机器内成立：换台机器换个盘符，同一个项目就成了另一个项目，记忆会静默分裂
+ * 成互不相认的两份。2026-11-11 改成项目名，依据是用户的三条约束——「以项目名为准」
+ * 「不会出现同名不同项目」「工作机上的目录不一样」。
+ *
+ * 统一小写：Windows 路径大小写不敏感、WSL/Linux 敏感，同一个项目在两处拼写可能不同；
+ * 不规范化就会变成 `records/project/WorkStation` 与 `records/project/workstation`
+ * 两个目录，又一次静默分裂。
+ */
+export declare function projectName(cwd: string): string;
+/**
+ * 把记忆库展开成镜像文件列表。**纯函数**：不读写磁盘、不看环境变量。
+ *
+ * @param options - 各层文档。
+ * @returns 待写入的文件与隔离跳过数。
+ */
+export declare function exportRecords(options: SyncExportOptions): SyncExportRun;

package/dist/sync-export.js

@@ -0,0 +1,150 @@
+/**
+ * 同步导出层：把记忆库展开成「一条记忆一个文件」的镜像。
+ *
+ * **为什么需要它**：整份 `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;
+}
+/**
+ * 项目在同步面上的目录名——**项目目录名，不是路径哈希**。
+ *
+ * 2026-11-06 的第一版用的是 `cwd` 的 djb2 哈希（与引擎本地文件名同口径）。那个身份
+ * 只在一台机器内成立：换台机器换个盘符，同一个项目就成了另一个项目，记忆会静默分裂
+ * 成互不相认的两份。2026-11-11 改成项目名，依据是用户的三条约束——「以项目名为准」
+ * 「不会出现同名不同项目」「工作机上的目录不一样」。
+ *
+ * 统一小写：Windows 路径大小写不敏感、WSL/Linux 敏感，同一个项目在两处拼写可能不同；
+ * 不规范化就会变成 `records/project/WorkStation` 与 `records/project/workstation`
+ * 两个目录，又一次静默分裂。
+ */
+export function projectName(cwd) {
+    // **不能用 `node:path` 的 basename**：它按平台分隔符切分，同一个字符串在 Windows 上
+    // 得到 `demo`、在 Linux 上得到整串 `H:\proj\demo`。2026-11-11 的 CI 就是这么红的
+    // （本地 Windows 全绿，Linux runner 上 `records/project/h:\proj\demo/`）。
+    // 两种分隔符都认，结果才跨平台一致——这也正是这个函数存在的意义。
+    const segments = cwd.replace(/\\/gu, '/').split('/').filter(segment => segment !== '');
+    const base = segments[segments.length - 1] ?? '';
+    // 盘符根（`H:\`）与路径根（`/`）都退到 `root`，不产生空目录名。
+    if (base === '' || /^[a-z]:$/iu.test(base))
+        return 'root';
+    return base.toLowerCase();
+}
+/** 只保留白名单字段；值为 `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', projectName(cwd)]);
+            if (file === undefined) {
+                skippedQuarantined += 1;
+                continue;
+            }
+            files.push(file);
+        }
+    }
+    return { files, skippedQuarantined };
+}

package/dist/sync-git.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 同步镜像的本地 git 仓库层。
+ *
+ * **这一步不联网**：只做 `init` / `add` / `commit`。远端 push 是下一步，单独一层——
+ * 分层的理由是可验证性：本地仓库能在完全离线的情况下验通「记忆库 → 镜像 → 有历史的
+ * 仓库」整条链，网络问题留到那一层单独排查。
+ *
+ * `isomorphic-git` 走**动态 import**（体积理由见设计 §五）：没开同步的人不加载它。
+ *
+ * **无改动不产生空提交**：定时跑一次同步是常态，每次都留一个空提交会让 `git log`
+ * 变成时间戳噪声，真正的变更被淹掉。
+ *
+ * @module dsh-memory/sync-git
+ */
+/** {@link commitMirror} 的入参。 */
+export interface MirrorCommitOptions {
+    /** 镜像仓库目录。 */
+    readonly dir: string;
+    /** 提交信息。 */
+    readonly message: string;
+    /** 作者；isomorphic-git 没有可读的全局 git 配置，必须显式传。 */
+    readonly author: {
+        readonly name: string;
+        readonly email: string;
+    };
+}
+/** 一次提交的结果。 */
+export interface MirrorCommitRun {
+    /** 是否真的产生了提交（无改动时为 `false`）。 */
+    readonly committed: boolean;
+    /** 新提交的 sha；没有提交时缺省。 */
+    readonly sha?: string;
+    /** 本次涉及的路径数（新增 + 修改 + 删除）。 */
+    readonly filesChanged: number;
+}
+/**
+ * 把镜像目录的当前状态提交成一个 commit。
+ *
+ * 三种路径逐个处理：新增/修改走 `add`，**删除走 `remove`**——只 `add` 的话，
+ * 镜像里被删掉的记录在 git 看来会一直存在。
+ *
+ * @param options - 目录、提交信息与作者。
+ * @returns 是否提交、sha 与涉及的路径数。
+ */
+export declare function commitMirror(options: MirrorCommitOptions): Promise<MirrorCommitRun>;
+/**
+ * 读仓库的提交历史（从新到旧）。测试与 `memory_sync status` 共用。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param depth - 最多取多少条；缺省不限。
+ * @returns 提交列表（sha / message / 时间）。仓库尚未建立时返回空数组。
+ */
+export declare function readHistory(dir: string, depth?: number): Promise<Array<{
+    sha: string;
+    message: string;
+    at: number;
+}>>;

package/dist/sync-git.js

@@ -0,0 +1,88 @@
+/**
+ * 同步镜像的本地 git 仓库层。
+ *
+ * **这一步不联网**：只做 `init` / `add` / `commit`。远端 push 是下一步，单独一层——
+ * 分层的理由是可验证性：本地仓库能在完全离线的情况下验通「记忆库 → 镜像 → 有历史的
+ * 仓库」整条链，网络问题留到那一层单独排查。
+ *
+ * `isomorphic-git` 走**动态 import**（体积理由见设计 §五）：没开同步的人不加载它。
+ *
+ * **无改动不产生空提交**：定时跑一次同步是常态，每次都留一个空提交会让 `git log`
+ * 变成时间戳噪声，真正的变更被淹掉。
+ *
+ * @module dsh-memory/sync-git
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import * as nodeFs from 'node:fs';
+import { join } from 'node:path';
+/** 仓库默认分支——与 GitHub 侧的约定一致。 */
+const DEFAULT_BRANCH = 'main';
+/** 动态载入 isomorphic-git（体积理由见文件头）。 */
+async function loadGit() {
+    return await import('isomorphic-git');
+}
+/** 确保目录是一个 git 仓库；已初始化时什么都不做。 */
+async function ensureRepo(dir) {
+    mkdirSync(dir, { recursive: true });
+    if (existsSync(join(dir, '.git')))
+        return;
+    const git = await loadGit();
+    await git.init({ fs: nodeFs, dir, defaultBranch: DEFAULT_BRANCH });
+}
+/**
+ * 把镜像目录的当前状态提交成一个 commit。
+ *
+ * 三种路径逐个处理：新增/修改走 `add`，**删除走 `remove`**——只 `add` 的话，
+ * 镜像里被删掉的记录在 git 看来会一直存在。
+ *
+ * @param options - 目录、提交信息与作者。
+ * @returns 是否提交、sha 与涉及的路径数。
+ */
+export async function commitMirror(options) {
+    await ensureRepo(options.dir);
+    const git = await loadGit();
+    // statusMatrix 每行是 [filepath, head, workdir, stage]：
+    // head=1 表示上一个 commit 里有；workdir=0 表示工作区里已经没有。
+    const matrix = await git.statusMatrix({ fs: nodeFs, dir: options.dir });
+    const changed = matrix.filter(([, head, workdir, stage]) => head !== workdir || workdir !== stage);
+    if (changed.length === 0) {
+        return { committed: false, filesChanged: 0 };
+    }
+    for (const [filepath, , workdir] of changed) {
+        if (workdir === 0)
+            await git.remove({ fs: nodeFs, dir: options.dir, filepath });
+        else
+            await git.add({ fs: nodeFs, dir: options.dir, filepath });
+    }
+    const sha = await git.commit({
+        fs: nodeFs,
+        dir: options.dir,
+        message: options.message,
+        author: options.author,
+    });
+    return { committed: true, sha, filesChanged: changed.length };
+}
+/**
+ * 读仓库的提交历史（从新到旧）。测试与 `memory_sync status` 共用。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param depth - 最多取多少条；缺省不限。
+ * @returns 提交列表（sha / message / 时间）。仓库尚未建立时返回空数组。
+ */
+export async function readHistory(dir, depth) {
+    if (!existsSync(join(dir, '.git')))
+        return [];
+    const git = await loadGit();
+    try {
+        const commits = await git.log({ fs: nodeFs, dir, ...depth === undefined ? {} : { depth } });
+        return commits.map(entry => ({
+            sha: entry.oid,
+            message: entry.commit.message.trim(),
+            at: entry.commit.author.timestamp * 1000,
+        }));
+    }
+    catch {
+        // 空仓库（init 之后一个 commit 都没有）会在这里抛；那是正常状态。
+        return [];
+    }
+}

package/dist/sync-import.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 同步导入层：把 `records/` 里的记录**规划**成一组待写入的操作。
+ *
+ * **这一层只出计划，不写任何东西。** 真正落库由调用方走引擎已有的写入路径完成，
+ * 理由：直接改 `memory.json` 会与内存缓存打架（引擎的写路径是「读—改—写全量覆盖」，
+ * 绕过它等于让两边各持一份真相）。分层之后，这一层是纯函数，可以在不碰数据的前提下
+ * 穷举冲突场景。
+ *
+ * 冲突策略见设计 §3.3：**同一条被两边改时不自动裁决**，两个版本都交出去让调用方写进
+ * `conflicts/`。记忆是长期资产，被静默覆盖的那份就没了。
+ *
+ * @module dsh-memory/sync-import
+ */
+import type { z } from 'zod';
+import type { blockSchema } from './schema.ts';
+/** 与存储层同构的一条记录。 */
+export type ImportedBlock = z.infer<typeof blockSchema>;
+/** 一条来自 `records/` 的记录及其归属。 */
+export interface IncomingRecord {
+    /** 记录 id（文件名去 `.json`）。 */
+    readonly id: string;
+    /** `global` 或 `project`。 */
+    readonly scope: 'global' | 'project';
+    /** `project` 作用域下的项目名；`global` 时缺省。 */
+    readonly projectName?: string;
+    /** 解析后的记录体。 */
+    readonly block: ImportedBlock;
+}
+/** 本地某一层现有的记录。 */
+export interface LocalLayer {
+    /** 该层现有的记录：id → block。 */
+    readonly blocks: Readonly<Record<string, ImportedBlock>>;
+}
+/** {@link planImport} 的入参。 */
+export interface ImportPlanOptions {
+    readonly incoming: readonly IncomingRecord[];
+    /** 本地 global 层。 */
+    readonly localGlobal: LocalLayer;
+    /** 本地的项目层：项目名（已小写）→ 该项目的记录。 */
+    readonly localProjects: Readonly<Record<string, LocalLayer>>;
+}
+/** 一条待写入的操作。 */
+export interface ImportUpsert {
+    readonly id: string;
+    readonly scope: 'global' | 'project';
+    readonly projectName?: string;
+    readonly block: ImportedBlock;
+}
+/** 一条需要人工裁决的冲突。 */
+export interface ImportConflict {
+    readonly id: string;
+    readonly scope: 'global' | 'project';
+    readonly projectName?: string;
+    /** 本地版本。 */
+    readonly mine: ImportedBlock;
+    /** 远端版本。 */
+    readonly theirs: ImportedBlock;
+    /** 判据：哪一边的 `updatedAt` 更新（仅作参考，决定写不写 `upserts`）。 */
+    readonly newer: 'mine' | 'theirs';
+}
+/** 一次导入规划的结果。 */
+export interface ImportPlan {
+    /** 需要新增或覆盖的条目。 */
+    readonly upserts: readonly ImportUpsert[];
+    /** 两边都改过、需要人裁决的条目。 */
+    readonly conflicts: readonly ImportConflict[];
+    /** 本地没有对应项目、无法落地的条目（留在远端等它出现）。 */
+    readonly orphaned: readonly string[];
+    /** 本地已一致、无需动作的条数。 */
+    readonly unchanged: number;
+}
+/**
+ * 规划一次导入。**不读写磁盘、不碰引擎状态。**
+ *
+ * 三种归属分别处理：
+ * - `global`：永远有落点。
+ * - `project` 且本地有同名项目：落到该项目。
+ * - `project` 但本地没有该项目 → 进 `orphaned`，**不丢**（留在远端等它出现）。
+ *
+ * @param options - 远端记录、本地各层、项目映射。
+ * @returns 计划：要写的、要裁决的、落不了的、不需要动的。
+ */
+export declare function planImport(options: ImportPlanOptions): ImportPlan;

package/dist/sync-import.js

@@ -0,0 +1,82 @@
+/**
+ * 同步导入层：把 `records/` 里的记录**规划**成一组待写入的操作。
+ *
+ * **这一层只出计划，不写任何东西。** 真正落库由调用方走引擎已有的写入路径完成，
+ * 理由：直接改 `memory.json` 会与内存缓存打架（引擎的写路径是「读—改—写全量覆盖」，
+ * 绕过它等于让两边各持一份真相）。分层之后，这一层是纯函数，可以在不碰数据的前提下
+ * 穷举冲突场景。
+ *
+ * 冲突策略见设计 §3.3：**同一条被两边改时不自动裁决**，两个版本都交出去让调用方写进
+ * `conflicts/`。记忆是长期资产，被静默覆盖的那份就没了。
+ *
+ * @module dsh-memory/sync-import
+ */
+/** 把一条记录投影成可比较的形状：只比内容，不比本地瞬态字段。 */
+function comparable(block) {
+    return JSON.stringify([
+        block.content,
+        block.keywords,
+        block.namespace,
+        block.status,
+        block.injected ?? null,
+        block.topic ?? null,
+        block.kind ?? null,
+        block.stale ?? null,
+        block.staleReason ?? null,
+        block.anchor ?? null,
+    ]);
+}
+/** 本地层里找一条。 */
+function findLocal(layer, id) {
+    return layer?.blocks[id];
+}
+/**
+ * 规划一次导入。**不读写磁盘、不碰引擎状态。**
+ *
+ * 三种归属分别处理：
+ * - `global`：永远有落点。
+ * - `project` 且本地有同名项目：落到该项目。
+ * - `project` 但本地没有该项目 → 进 `orphaned`，**不丢**（留在远端等它出现）。
+ *
+ * @param options - 远端记录、本地各层、项目映射。
+ * @returns 计划：要写的、要裁决的、落不了的、不需要动的。
+ */
+export function planImport(options) {
+    const upserts = [];
+    const conflicts = [];
+    const orphaned = [];
+    let unchanged = 0;
+    for (const record of options.incoming) {
+        const { id, scope, projectName, block } = record;
+        let localLayer;
+        if (scope === 'global') {
+            localLayer = options.localGlobal;
+        }
+        else {
+            const key = projectName?.toLowerCase() ?? '';
+            localLayer = key === '' ? undefined : options.localProjects[key];
+            if (localLayer === undefined) {
+                // 本机没有这个项目：记下来但不导入，也不报错。
+                orphaned.push(id);
+                continue;
+            }
+        }
+        const local = findLocal(localLayer, id);
+        if (local === undefined) {
+            upserts.push({ id, scope, ...projectName === undefined ? {} : { projectName }, block });
+            continue;
+        }
+        if (comparable(local) === comparable(block)) {
+            unchanged += 1;
+            continue;
+        }
+        // 两边内容不同：不自动裁决，两边都交出去。
+        const newer = (block.updatedAt ?? 0) > (local.updatedAt ?? 0) ? 'theirs' : 'mine';
+        conflicts.push({ id, scope, ...projectName === undefined ? {} : { projectName }, mine: local, theirs: block, newer });
+        // 远端更新的那份仍然写进去（否则用户看到的永远是旧内容），但冲突记录同时留下。
+        if (newer === 'theirs') {
+            upserts.push({ id, scope, ...projectName === undefined ? {} : { projectName }, block });
+        }
+    }
+    return { upserts, conflicts, orphaned, unchanged };
+}

package/dist/sync-remote.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 同步镜像的远端层：`push` / `pull` / 状态查询。
+ *
+ * **必须走 HTTP**：`isomorphic-git` 的 `push` 在没有 `http` 参数时直接抛
+ * `The function requires a "http" parameter but none was provided`（2026-11-11 实测，
+ * 想用本地 bare 仓库做离线测试也走不通）。所以本层天然依赖网络，与上一层的
+ * `sync-git.ts`（纯本地、可离线全测）分开。
+ *
+ * **认证用 PAT（https）而不是 SSH**：SSH key 在移动端的管理成本远高于 token，
+ * 而 dsh-go 那类环境正是目标场景之一。
+ *
+ * **token 不进 profile 配置**：由调用方从既有 credentials 机制取出后传入。本模块只
+ * 负责把它放进 http 请求，不负责存。
+ *
+ * @module dsh-memory/sync-remote
+ */
+/** 远端操作共用的参数。 */
+export interface RemoteOptions {
+    /** 镜像仓库目录。 */
+    readonly dir: string;
+    /** 远端地址（https）。 */
+    readonly url: string;
+    /** 分支名；缺省 `main`。 */
+    readonly branch?: string;
+    /** GitHub PAT；缺省时只尝试匿名（私有仓库会失败）。 */
+    readonly token?: string;
+}
+/** 一次远端操作的结果。 */
+export interface RemoteRun {
+    readonly ok: boolean;
+    /** 失败原因；成功时缺省。 */
+    readonly error?: string;
+    /**
+     * 失败分类——排查时最要紧的一件事：「认证错」和「连不上」的正确应对完全不同，
+     * 而它们的原始报错常常长得差不多。
+     */
+    readonly kind?: 'auth' | 'network' | 'unknown';
+}
+/**
+ * 确保镜像目录是一个**与远端有共同历史**的仓库。
+ *
+ * 首次同步时如果只 `git init`，本地与远端是两条无关的历史线——push 会被拒
+ * （`Push rejected because it was not a simple fast-forward`）。这是 2026-11-11
+ * 第一次用真实仓库跑时撞出来的：单元测试里没有真远端，所以永远发现不了。
+ *
+ * 因此首次必须 clone，而不是 init + push。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 是否执行了 clone；失败时带分类。
+ */
+export declare function ensureMirrorRepo(options: RemoteOptions): Promise<MirrorRepoRun>;
+/** {@link ensureMirrorRepo} 的结果。 */
+export interface MirrorRepoRun {
+    readonly cloned: boolean;
+    readonly error?: string;
+    readonly kind?: 'auth' | 'network' | 'unknown';
+}
+/**
+ * 把本地提交推到远端。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export declare function pushMirror(options: RemoteOptions): Promise<RemoteRun>;
+/**
+ * 从远端拉取并快进本地。
+ *
+ * `fastForwardOnly: true`：合并策略不该由这一层决定。本地有分叉时宁可失败让人看见，
+ * 也不要让 isomorphic-git 悄悄造出一个 merge commit。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export declare function pullMirror(options: RemoteOptions): Promise<RemoteRun>;
+/**
+ * 确保 `origin` 指向给定地址。地址变化时重设（用户换了仓库）。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param url - 期望的远端地址。
+ */
+export declare function ensureRemote(dir: string, url: string): Promise<void>;