dsh-prime-memory 0.22.2 → 0.24.0

package/dist/store/memory-md-ledger.js

@@ -0,0 +1,243 @@
+/**
+ * md 投射的指纹账本（N9）。
+ *
+ * 它存在的唯一理由：**库里没有任何 hash 列**（spec F26），三处现成 hash 又全不落库
+ * （F27：快照是整集粗粒度、memport 每次现算、reconcile 只活在状态文件里）。没有这张
+ * 账本就无从回答"这个文件是被人改的，还是被我们上次写出去的"——而那是双向同步的
+ * 全部难点：两方比较必吃一边。
+ *
+ * 三条口径：
+ * - **键是文件的绝对路径**（N10 后根不止一个：workspace 根 + 单根，同名不同 workspace 会
+ *   在 relPath 上撞车）。绝对路径由 `targetFor` 一函数算出，读写对账改名四处共用，
+ *   所以键是确定性的（Windows 下 `workspace_id` 是小写形态，这一点已写进 `memory-md.ts`）。
+ * - **派生态**：删了这张表最坏是"下次全量重写一遍文件"，不会丢任何记忆。所以它
+ *   **不进**快照哈希投影（`canonicalRecords` 不动），也不需要迁移。
+ * - **写穿失败只降级为只读并 warn 一次**，绝不抛给调用方：投射是旁路，旁路不能弄挂主路。
+ */
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { atomicWriteText, ensureDir, readJsonStrict } from '../util/io.js';
+import { MEM_MD_LEDGER_FILE_VERSION } from './file-versions.js';
+/** 看起来就是绝对路径（Windows 盘符形状或 POSIX 以 `/` 开头）。归档侧也要用它挡坏数据。 */
+export function looksAbsolute(p) {
+    return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('/');
+}
+/**
+ * 由「绝对键 + 条目记的 root」推出相对形状（正斜杠）。
+ *
+ * 这是 relPath 的唯一正确算法：键才是事实源（N10 以后它是绝对路径），root 只是
+ * 其中一个字段。`root` 缺失、键不在 root 下、或推出 `..` 开头都返回 `undefined`——不猜。
+ *
+ * @param root - 投射根（绝对）。
+ * @param key - 账本键 = 文件绝对路径。
+ * @returns `<类型>/<名>` 的相对形状，推不出时 `undefined`。
+ */
+export function deriveRelPath(root, key) {
+    if (root.length === 0 || looksAbsolute(key) === false)
+        return undefined;
+    const rel = relative(root, key);
+    if (rel.length === 0 || rel.startsWith('..'))
+        return undefined;
+    return rel.split(sep).join('/');
+}
+/**
+ * 合批窗口(ms)。
+ *
+ * 账本是**整本 JSON 的原子重写**（临时文件 + rename），所以“每 set 一条就落盘”把导出
+ * 成本变成 O(n²)：本机实测 1200 条记录 9.4 秒，其中只碰文件面只需 1.6 秒。改为窗口内
+ * 只记脏、由 `flush()` 收尾落一次，1200 次 set 就是一次落盘。
+ * 窗口只是**兜底**：三个写方（导出 / 失效 / 同步）本来就在收尾 `await flush()`。
+ */
+const PERSIST_COALESCE_MS = 250;
+export class MdLedgerStore {
+    logger;
+    file;
+    entries = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    /** 有未落盘的变更。 */
+    dirty = false;
+    /** 已提醒过的 relPath 修正数（防上千条条目刷屏）。 */
+    mismatchWarned = 0;
+    /** 已发生的整本落盘次数（见 `writeCount`）。 */
+    writes = 0;
+    /** 已排上的合批定时器（undefined = 窗口外）。 */
+    timer;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = join(dataDir, 'mem-md-ledger.json');
+    }
+    async init() {
+        await ensureDir(dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] md 投射账本只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        for (const [key, e] of Object.entries(read.value.entries ?? {})) {
+            const parsed = this.normalize(e);
+            if (parsed === undefined)
+                continue;
+            // 键是**绝对路径**（N10），relPath 是 `<类型>/<名>` 的相对形状——两者本来就不该相等。
+            // 旧写法是“键与 relPath 不一致就以键为准重写”，那是键还叫 relPath 时代的逻辑；
+            // N10 之后它每次加载都必然判定不一致，于是相对形状被绝对键吃掉（真机 1167/1241 条命中）。
+            // 危害不是难看而是下游：孤儿归档拼出 `<批次>/home/C:\Users\...` 这种含冒号的非法
+            // 目录，75 条搬家全 ENOENT。现在规整判据换成“键 == join(root, relPath)”：
+            // 只有真推不出相对形状（root 缺失/越界）才退回存下来的值。
+            const derived = deriveRelPath(parsed.root, key);
+            let relPath = derived ?? parsed.relPath;
+            if (looksAbsolute(relPath)) {
+                // 坏数据兼容：以前被绝对键污染过的条目，若 root 也推不出来，退到文件名——
+                // 至少归档不会拼出带冒号的非法路径。名字重复由 freeSlot 的数字尾巴兼着。
+                relPath = basename(relPath);
+            }
+            if (relPath !== parsed.relPath && this.mismatchWarned < 8) {
+                this.mismatchWarned++;
+                this.logger?.warn(`[memory] md 账本 relPath 已按键修正: ${key} → ${relPath}`);
+            }
+            this.entries.set(key, { ...parsed, relPath });
+        }
+        this.loaded = true;
+    }
+    /** 逐条收窄：形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    normalize(e) {
+        if (!e || typeof e !== 'object')
+            return undefined;
+        const raw = e;
+        if (typeof raw.relPath !== 'string' || raw.relPath.length === 0)
+            return undefined;
+        if (typeof raw.dbDigest !== 'string' || typeof raw.fileDigest !== 'string')
+            return undefined;
+        return {
+            id: typeof raw.id === 'string' ? raw.id : '',
+            extKey: typeof raw.extKey === 'string' ? raw.extKey : '',
+            root: typeof raw.root === 'string' ? raw.root : '',
+            relPath: raw.relPath,
+            dbDigest: raw.dbDigest,
+            fileDigest: raw.fileDigest,
+            fileMtimeMs: typeof raw.fileMtimeMs === 'number' ? raw.fileMtimeMs : 0,
+            fileSize: typeof raw.fileSize === 'number' ? raw.fileSize : 0,
+            syncedAt: typeof raw.syncedAt === 'string' ? raw.syncedAt : '',
+        };
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('md 投射账本未初始化(先 await init())');
+    }
+    get(absPath) {
+        this.ensureLoaded();
+        return this.entries.get(absPath);
+    }
+    all() {
+        this.ensureLoaded();
+        return [...this.entries.values()];
+    }
+    /**
+     * 带键遍历：**账本的键（绝对路径）是唯一认身份的口径**，而 `all()` 把它抹掉了。
+     *
+     * 为什么需要这个口：孤儿扫描要回答“这个**路径**现在还有没有记录认领”，而条目里的
+     * `root`/`relPath` 只是归档时恢复相对形状用的——手工编辑过账本时两者可以不一致，
+     * 拿它们当路径就会把“键”与“内容”两套事实源弄混。只读，不暴露可变 Map。
+     */
+    allWithKeys() {
+        this.ensureLoaded();
+        return [...this.entries.entries()].map(([path, entry]) => ({ path, entry }));
+    }
+    set(absPath, entry) {
+        this.ensureLoaded();
+        this.entries.set(absPath, entry);
+        this.schedulePersist();
+    }
+    delete(absPath) {
+        this.ensureLoaded();
+        if (!this.entries.delete(absPath))
+            return false;
+        this.schedulePersist();
+        return true;
+    }
+    /** 条目上限护栏：投射是"文件 ↔ 库"的一一对应，超量只可能是脏数据堆积。 */
+    prune() {
+        const MAX = 50_000;
+        if (this.entries.size <= MAX)
+            return;
+        const sorted = [...this.entries.entries()].sort((a, b) => (a[1].syncedAt < b[1].syncedAt ? -1 : 1));
+        for (const [rel] of sorted.slice(0, this.entries.size - MAX))
+            this.entries.delete(rel);
+    }
+    schedulePersist() {
+        if (this.degraded)
+            return;
+        this.dirty = true;
+        // 已在窗口内就不再排：一个 burst 只留一次落盘。
+        if (this.timer !== undefined)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.enqueuePersist();
+        }, PERSIST_COALESCE_MS);
+        // 不让一个兜底定时器拖住进程退出（宿主常驻时无影响，测试收尾时干净）。
+        this.timer.unref?.();
+    }
+    /** 串行落盘：并发 set 不能交叠写同一个临时文件。 */
+    enqueuePersist() {
+        this.writeChain = this.writeChain.then(() => this.persistNow(), () => this.persistNow());
+        return this.writeChain;
+    }
+    async persistNow() {
+        if (!this.dirty || this.degraded)
+            return;
+        this.dirty = false;
+        this.writes += 1;
+        await this.persist();
+    }
+    /**
+     * 已发生的整本落盘次数。
+     *
+     * 留着它是因为这个类的性能形状就是它的全部意义：账本每次落盘都重写整本 JSON，
+     * 所以「这个数是不是跟 `set()` 次数一起涨」直接就能区分 O(n) 与 O(n²)。合批前 200 次
+     * `set()` 会落盘 200 次；合批后应该恒为 1。没这个计数器就只能靠时间差或磁盘状态去猜，
+     * 那种断言在旧实现上也能绿（自家刚踩过）。
+     */
+    get writeCount() {
+        return this.writes;
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        this.prune();
+        const data = {
+            version: MEM_MD_LEDGER_FILE_VERSION,
+            entries: Object.fromEntries(this.entries),
+        };
+        try {
+            await ensureDir(dirname(this.file));
+            await atomicWriteText(this.file, JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            this.degraded = err instanceof Error ? err.message : String(err);
+            if (!this.degradedLogged) {
+                this.degradedLogged = true;
+                this.logger?.warn(`[memory] md 投射账本写入失败，只读降级: ${this.degraded}`);
+            }
+        }
+    }
+    /**
+     * 等待在途写完成（测试/停机/导出收尾）。
+     *
+     * 合批之后这一步是**语义上的“现在就要落盘”**：清掉定时器并强制一次写，所以写完
+     * `set()` 不 `flush()` 就不能假设磁盘已经可信。`persistNow` 自带脏位判定，
+     * 没变更时不会空写一轮。
+     */
+    flush() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        return this.enqueuePersist();
+    }
+}

package/dist/store/memory-md-orphan.d.ts

@@ -0,0 +1,27 @@
+import { type MdLedgerStore } from './memory-md-ledger.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+import type { OrphanReport } from './memory-md-types.js';
+export interface OrphanDeps {
+    /** 当前全部记录（含退场行——退场行仍认领自己的文件，那不是孤儿）。 */
+    records: readonly MemoryRecord[];
+    /** `cfg.memExport.root`（空 = 默认单根）。 */
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    /** true = 只报告不搬（默认值由端点侧兜死，这里不设默认）。 */
+    dryRun: boolean;
+    maxFiles: number;
+    timeBudgetMs: number;
+    logger?: MemoryLogger;
+    /** 归档根；缺省 `<dataDir>/memories-orphans`。测试注入临时目录用。 */
+    archiveRoot?: string;
+    /** 注入时钟（测试用）。 */
+    now?: () => number;
+}
+/**
+ * 扫一遍账本，把无人认领的投射文件搬进归档目录。
+ *
+ * @param deps - 见 `OrphanDeps`。
+ * @returns 报告；`dir` 在干跑时是空串（还没建批次目录）。任何单条失败只计数并留痕，绝不抛挂整轮。
+ */
+export declare function sweepOrphanFiles(deps: OrphanDeps): Promise<OrphanReport>;

package/dist/store/memory-md-orphan.js

@@ -0,0 +1,153 @@
+/**
+ * 孤儿投射文件的归档（P4.4）。
+ *
+ * 孤儿是怎么长出来的：投射路径 = `<type>/<name>.memory.md`，而 `name` 会变——本轮的
+ * 撞车消歧（42 条挤 17 个同名文件）、下一次的身份改名、以及记录被物理删除，都会让
+ * **磁盘上的旧路径不再属于任何记录**。它们既不报错也不碍事，只是越积越多，而人无法分辨
+ * 哪份是历史、哪份是刚被覆盖的。
+ *
+ * 只归档**有账可查**的那部分，判据是一条硬边界：
+ * - 账本里记着这个绝对路径（= 确认是我们自己写出去的），且**现在没有记录映射到它** → 孤儿，搬走；
+ * - 账本里没有 = 来路不明。那可能是人自己放进投射目录、等着被同步进来的输入，
+ *   **绝对不许动**（md 同步侧对这类文件只计数不入库，同一个纪律）。
+ *
+ * 搬 ≠ 删：整批进 `<dataDir>/memories-orphans/<批次时间戳>/`，保留 `<ws|home>/<类型>/<名>` 的
+ * 相对形状。删是 cleanup 的活，这里只负责别再挡在活档案里。账本条目跟着删——文件已经搬走，
+ * 留着基线下一轮对账就会一直报「文件缺失」。
+ */
+import { mkdir, rename, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { disablePathOf, resolveMemoriesRoot, safeJoin, targetFor } from './memory-md.js';
+import { deriveRelPath, looksAbsolute } from './memory-md-ledger.js';
+/** 样本条数上限：孤儿可能上千，面板不需要全量。 */
+const SAMPLE_CAP = 20;
+/**
+ * 扫一遍账本，把无人认领的投射文件搬进归档目录。
+ *
+ * @param deps - 见 `OrphanDeps`。
+ * @returns 报告；`dir` 在干跑时是空串（还没建批次目录）。任何单条失败只计数并留痕，绝不抛挂整轮。
+ */
+export async function sweepOrphanFiles(deps) {
+    const { records, cfgRoot, dataDir, ledger, logger } = deps;
+    const now = deps.now ?? Date.now;
+    const startedAt = now();
+    const report = {
+        dryRun: deps.dryRun,
+        scanned: 0,
+        claimed: 0,
+        orphans: 0,
+        moved: 0,
+        failed: 0,
+        missing: 0,
+        remaining: 0,
+        capped: false,
+        dir: '',
+        samples: [],
+    };
+    const sample = (path, reason) => {
+        if (report.samples.length < SAMPLE_CAP)
+            report.samples.push({ path, reason });
+    };
+    // 认领集：每条记录现在的路径 + 它的 `.disable` 兄弟。后者必须在集合里，否则 N11 的失效
+    // 凭证会被当成孤儿搬走——那个后缀就是“这条已被判过时”的唯一文件侧表达。
+    const claimed = new Set();
+    for (const r of records) {
+        const abs = targetFor(r, cfgRoot, dataDir, logger).absPath;
+        if (abs === undefined)
+            continue;
+        claimed.add(abs);
+        claimed.add(disablePathOf(abs));
+    }
+    const homeRoot = resolveMemoriesRoot(cfgRoot, dataDir, logger);
+    const stamp = new Date(now()).toISOString().replace(/[:.]/g, '-');
+    const archiveBase = deps.archiveRoot ?? join(dataDir, 'memories-orphans');
+    const archiveDir = join(archiveBase, stamp);
+    // 走的是**带键**的遍历：账本的键才是绝对路径，条目里的 root/relPath 只供恢复归档形状。
+    const rows = ledger.allWithKeys();
+    // 配额只数**动作**（搬走/失败的孤儿），确认过“仍被认领”的不吃配额——与导出侧同一口径。
+    // 旧写法在这里会把配额花在“翻了一页全是认领”上，于是后面的孤儿永远扫不到，
+    // 报告却说“没孤儿”：那是把谎报写进了护栏。
+    let worked = 0;
+    for (let i = 0; i < rows.length; i++) {
+        // 两条护栏都在循环顶部查（写在末尾会被 continue 跳过，导出侧栽过）。
+        if (worked >= deps.maxFiles || now() - startedAt >= deps.timeBudgetMs) {
+            report.capped = true;
+            report.remaining = rows.length - i;
+            break;
+        }
+        const { path, entry: e } = rows[i];
+        report.scanned++;
+        if (path.length === 0) {
+            report.failed++;
+            worked++;
+            continue;
+        }
+        if (claimed.has(path)) {
+            report.claimed++;
+            continue;
+        }
+        report.orphans++;
+        if (deps.dryRun) {
+            // 干跑里“报出一个孤儿”就是本轮将要做的一个动作，所以它吃配额。
+            worked++;
+            sample(path, 'orphan');
+            continue;
+        }
+        // 账本说有文件、盘上没有：那是“文件缺失”，对账已经在报了，这里不重复处理，
+        // 也**不删账本条目**（删了就把“人把文件移走了”这个事实一起抹掉）。
+        if ((await stat(path).catch(() => undefined)) === undefined) {
+            report.missing++;
+            continue;
+        }
+        const side = e.root === homeRoot ? 'home' : 'ws';
+        // **不直接信存下来的 relPath**：它曾经被加载器污染成绝对路径（真机 1167/1241 条），
+        // 而 `safeJoin` 拦不住它——`join(归档根, 'home/C:\\Users\\…')` 的结果仍以归档根开头，
+        // 于是拼出含冒号的非法目录、75 条搬家全 ENOENT。键才是事实源：按 root+键重推，
+        // 推不出再退回存值（存值看着像绝对路径就一律不走）。
+        const rel = deriveRelPath(e.root, path) ?? (looksAbsolute(e.relPath) ? undefined : e.relPath);
+        const dest = rel === undefined ? undefined : safeJoin(archiveDir, `${side}/${rel}`);
+        if (rel === undefined || dest === undefined) {
+            // 账本被人手工编辑过（relPath 越界或 root 丢失）：宁可不动，也不要借这道手续把文件写到目录外。
+            report.failed++;
+            worked++;
+            sample(path, 'unsafe-relPath');
+            logger?.warn(`[memory] 孤儿投射跳过（推不出安全的归档相对路径）: ${path} → ${e.relPath}`);
+            continue;
+        }
+        try {
+            await mkdir(dirname(dest), { recursive: true });
+            await rename(path, await freeSlot(dest));
+            ledger.delete(path);
+            report.moved++;
+            worked++;
+            sample(path, 'moved');
+        }
+        catch (err) {
+            report.failed++;
+            worked++;
+            sample(path, 'failed');
+            logger?.warn(`[memory] 孤儿投射搬家失败: ${path} - ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!deps.dryRun && (report.moved > 0 || report.failed > 0))
+        report.dir = archiveDir;
+    await ledger.flush();
+    return report;
+}
+/**
+ * 目标位已被占用时加数字尾巴。
+ *
+ * 正常不会撞（每次跑都用新的批次目录），但账本里可能有两条指向同一 relPath 的不同绝对路径
+ * （不同 workspace 根），落进同一个 `ws/<类型>/<名>` 就会叠。叠了也不能覆盖——
+ * 那些文件是彼此不同的历史版本。
+ */
+async function freeSlot(dest) {
+    if ((await stat(dest).catch(() => undefined)) === undefined)
+        return dest;
+    for (let n = 2; n <= 999; n++) {
+        const candidate = `${dest}.${n}`;
+        if ((await stat(candidate).catch(() => undefined)) === undefined)
+            return candidate;
+    }
+    return `${dest}.${Date.now()}`;
+}

package/dist/store/memory-md-parse.d.ts

@@ -0,0 +1,35 @@
+/** 解析出的文件形状（值已按渲染时的类型还原）。 */
+export interface MdParsed {
+    /** 文件名干（= 渲染时写入的 `name` 键）。 */
+    name: string;
+    type: string;
+    priority: number;
+    /** ISO 串（渲染时就是 ISO；空串 = 没有）。 */
+    createdAt: string;
+    updatedAt: string;
+    usageScenario: string[];
+    extKey: string;
+    /** 文件里记的 record_id，只当线索。 */
+    id: string;
+    /** 文件声明的正文指纹（`hash` 键原文）；空串 = 老文件没带（未签名）。 */
+    hash: string;
+    /**
+     * 声明指纹与正文实算的比对：`true` 一致、`false` 不符、`undefined` = 文件没声明（无从判）。
+     *
+     * `false` **不是**拒收理由：正文被人改过恰恰是 P2 要回灌的正常输入；它只说明「文件不是
+     * 我们上次写出去的那份字节」，交给调用方计入报告并重盖指纹。结构性拒收仍在更上面
+     * （形状不符 / 正文为空）。
+     */
+    hashValid: boolean | undefined;
+    /** frontmatter 带 `retired: true`。 */
+    retired: boolean;
+    /** 正文（已去首尾空白）。 */
+    content: string;
+}
+/**
+ * 解析一个投射文件。
+ *
+ * @param text - 文件全文。
+ * @returns 解析结果；形状不符（无 frontmatter / 无正文 / 键全不认识）时 `undefined`。
+ */
+export declare function parseMdFile(text: string): MdParsed | undefined;

package/dist/store/memory-md-parse.js

@@ -0,0 +1,85 @@
+/**
+ * md 投射文件的解析（P2 反向同步的读侧）。
+ *
+ * 只认 `memory-md.ts` 自己渲染出来的那种 frontmatter：`key: <JSON 值>`，正文在第二个
+ * `---` 之后。**不做通用 YAML**——通用解析器会接受我们从不产出的形状，那些形状进到
+ * 回灌路径就是"看起来能读、读回来是垃圾"。解析不出来就返回 `undefined`，调用方跳过并
+ * 计数；绝不猜、绝不抛。
+ *
+ * 一条刻意的不对称：文件里的 `id` 只当**线索**，不当身份。id 每轮新铸（F1），一次合并
+ * 就换；真正认人靠账本键（绝对路径）与 `name`。
+ *
+ * 另有一条自校验：frontmatter 里的 `hash` 是投射时盖下的正文指纹（N13）。这里只**核对**它
+ * 与正文本体是否一致（`hashValid`），不替调用方决定怎么处置——那属于同步侧的裁决。
+ */
+import { contentHash } from './memory-md.js';
+/** 取 frontmatter 块：首行必须是 `---`，到下一个 `---` 为止。 */
+function splitFrontmatter(text) {
+    // BOM 与 CRLF 都要先吃掉：人在记事本里改一行就会引入 \r，而 `\r` 会让 key 匹配不上。
+    const normalized = text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const lines = normalized.split('\n');
+    if (lines.length < 2 || lines[0].trim() !== '---')
+        return undefined;
+    const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+    if (end < 0)
+        return undefined;
+    return { meta: lines.slice(1, end), body: lines.slice(end + 1).join('\n').trim() };
+}
+/** 一行 `key: <JSON>` → [key, 值]；值解析失败则退回原始字符串。 */
+function readLine(line) {
+    const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (m === null)
+        return undefined;
+    const raw = m[2];
+    if (raw.length === 0)
+        return [m[1], ''];
+    try {
+        return [m[1], JSON.parse(raw)];
+    }
+    catch {
+        return [m[1], raw];
+    }
+}
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+/**
+ * 解析一个投射文件。
+ *
+ * @param text - 文件全文。
+ * @returns 解析结果；形状不符（无 frontmatter / 无正文 / 键全不认识）时 `undefined`。
+ */
+export function parseMdFile(text) {
+    const parts = splitFrontmatter(text);
+    if (parts === undefined)
+        return undefined;
+    const fields = new Map();
+    for (const line of parts.meta) {
+        const kv = readLine(line);
+        if (kv !== undefined)
+            fields.set(kv[0], kv[1]);
+    }
+    // 正文为空 = 这条记忆没内容了。人手工清空正文不该被回灌成"一条空记忆"，
+    // 那既不是有效输入，也会让对账以为文件是权威。
+    if (parts.body.length === 0)
+        return undefined;
+    const scenario = Array.isArray(fields.get('usageScenario'))
+        ? fields.get('usageScenario').filter((s) => typeof s === 'string' && s.length > 0)
+        : [];
+    const prio = Number(fields.get('priority'));
+    const declaredHash = str(fields.get('hash'));
+    return {
+        name: str(fields.get('name')),
+        type: str(fields.get('type')),
+        priority: Number.isFinite(prio) ? prio : 60,
+        createdAt: str(fields.get('createdAt')),
+        updatedAt: str(fields.get('updatedAt')),
+        usageScenario: scenario,
+        extKey: str(fields.get('extKey')),
+        id: str(fields.get('id')),
+        hash: declaredHash,
+        hashValid: declaredHash.length === 0 ? undefined : declaredHash === contentHash(parts.body),
+        retired: fields.get('retired') === true,
+        content: parts.body,
+    };
+}

package/dist/store/memory-md-skeleton.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryLogger } from '../types.js';
+/** 每类目录下的索引文件名（不带 `.memory.md`，因此天然落在投射/扫描面之外）。 */
+export declare const SKELETON_INDEX_FILE = "_index.md";
+export interface SkeletonDeps {
+    /** 要补骨架的投射根（绝对路径）列表。单根必补、workspace 根按需由调用方决定。 */
+    roots: readonly string[];
+    /** 目录名（= 类型）→ 库里条数；缺省按 0 计（0 也写，否则"没目录"与"0 条"仍无法区分）。 */
+    countsByType: ReadonlyMap<string, number>;
+    /** 诊断口：任何单目录写失败只走它留痕，绝不抛挂整轮。 */
+    logger?: MemoryLogger;
+}
+/**
+ * 往每个投射根补齐 37 类目录及各自的 `_index.md`。
+ *
+ * @param deps - 见 `SkeletonDeps`。
+ * @returns 无（副作用为落盘）。任何单目录失败只 warn，不抛。
+ */
+export declare function ensureTypeSkeleton(deps: SkeletonDeps): Promise<void>;

package/dist/store/memory-md-skeleton.js

@@ -0,0 +1,61 @@
+/**
+ * 类型目录骨架 + `_index.md`（pm-name-distill Phase 4 / task_4.1）。
+ *
+ * 投射根（`<dataDir>/memories/` 或 `cfg.memExport.root`）过去只有"库里出现过记录"的类型目录
+ * （实测 6 个）；词表已扩到 37 类。空目录会被 git/压缩包吐掉，而"没这个目录"与"这类 0 条"
+ * 在人眼里长得一样——所以每类目录固定放一个 `_index.md`（类名 + 库里条数），目录集合从
+ * **词表真源** `memoryTypeDirs()` 派生，不再手抄。
+ *
+ * 三条纪律：
+ * 1. **幂等**：内容不变就不重写（也不刷 mtime）。投射是"库 → 文件"的旁路，重刷 mtime 会让
+ *    下一轮对账把"我们没动过"误判成"文件被改过"——与 `exportRecords` 的 mtime 纪律同口径。
+ * 2. **失败只 warn 不抛**：旁路写挂不能弄挂记忆本体（照 `resolveMemoriesRoot` / 导出侧的降级口径）。
+ * 3. **原子落盘**：临时文件 + rename，走仓内既有范式 `atomicWriteText`（带 fsync / 安全路径校验 /
+ *    失败清理）；根不存在由它内部 `ensureDir` recursive 建出。
+ *
+ * `_index.md` 刻意**不是**投射文件：md-sync 只认 `.memory.md` / `.memory.md.disable` 后缀
+ * （`listProjectionFiles`），孤儿扫描只遍历账本键（`sweepOrphanFiles`）——本模块从不把
+ * `_index.md` 写进账本，故两条通路都不会碰它（防误伤用例把这两条钉成断言）。
+ */
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { MEMORY_TYPE_LABELS, memoryTypeDirs } from '../memory-types.js';
+import { atomicWriteText } from '../util/io.js';
+/** 每类目录下的索引文件名（不带 `.memory.md`，因此天然落在投射/扫描面之外）。 */
+export const SKELETON_INDEX_FILE = '_index.md';
+/**
+ * 渲染一个目录的索引文本（纯函数：同一 (dir,label,count) 永远同一字节，幂等判据靠它）。
+ * 含类名标签、类型 id、条数三项——条数为 0 也如实写"0"。
+ */
+function renderIndex(dir, label, count) {
+    return `# ${label}\n\n- 类型: ${dir}\n- 条数: ${count}\n`;
+}
+/**
+ * 往每个投射根补齐 37 类目录及各自的 `_index.md`。
+ *
+ * @param deps - 见 `SkeletonDeps`。
+ * @returns 无（副作用为落盘）。任何单目录失败只 warn，不抛。
+ */
+export async function ensureTypeSkeleton(deps) {
+    const { roots, countsByType, logger } = deps;
+    // 目录集合来自词表真源，杜绝手抄漂移（换词表不改这里也不会静默少目录）。
+    const dirs = memoryTypeDirs();
+    for (const root of roots) {
+        for (const dir of dirs) {
+            const abs = join(root, dir, SKELETON_INDEX_FILE);
+            const count = countsByType.get(dir) ?? 0;
+            const label = MEMORY_TYPE_LABELS[dir] ?? dir;
+            const text = renderIndex(dir, label, count);
+            try {
+                // 读现内容比对：一致就跳过——既不重写，也不碰 mtime（atomicWriteText 会 rename 换 inode 刷 mtime）。
+                const existing = await readFile(abs, 'utf8').catch(() => undefined);
+                if (existing === text)
+                    continue;
+                await atomicWriteText(abs, text, { logger });
+            }
+            catch (err) {
+                logger?.warn(`[memory] 类型骨架写入失败(旁路，不影响投射本体): ${abs} - ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+}