@yandy0725/pi-memory 1.4.0 → 2.0.0

package/src/migrate.ts

@@ -0,0 +1,303 @@
+import { cp, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isEntryType } from "./entry-file";
+import { BACKUP_DIR, INDEX_FILE, LOCK_FILE, unlinkStrict, type MemoryStore } from "./memory-store";
+
+/** 迁移完成标记。写在**最后一步** —— 中途失败时它不存在，下次 session_start 会重试（spec §15.4）。 */
+export const MIGRATED_FILE = ".migrated";
+
+/** spec §15.3 步骤 1：迁移的整轮锁超时是 30s（要在锁内逐条重写整个目录）。 */
+export const MIGRATE_LOCK_TIMEOUT_MS = 30_000;
+
+export interface MigrationResult {
+	/** 被拆开并删除的 legacy topic 文件数。 */
+	files: number;
+	/** 生成的 entry 数。 */
+	entries: number;
+	/** 回滚点目录（`.backups/migrate-<ts>/`），原 topic 文件另存于其下的 `originals/`。 */
+	backupDir: string;
+}
+
+interface MigrationMarker extends MigrationResult {
+	migratedAt: string;
+}
+
+export interface LegacyEntry {
+	title: string;
+	content: string;
+	type: string;
+	updated: string;
+}
+
+/** CRLF（以及老 Mac 的单独 CR）会让下面每一个正则都失配：`line === "---"` 不成立、
+ *  `^## (.+)$` 里的 `.` 不匹配 `\r`。归一只在解析入口做一次。 */
+function normalizeEol(raw: string): string {
+	return raw.includes("\r") ? raw.replace(/\r\n?/g, "\n") : raw;
+}
+
+const FIELD_RE = /^([A-Za-z_][A-Za-z0-9_]*):[ \t]*(.*)$/;
+
+/**
+ * 拆分文件开头的 frontmatter：返回字段表与正文。
+ *
+ * v1 的 `parseEntries` 把每一行 `---` 都当作 frontmatter 开关：正文里只要出现一行 `---`
+ * （markdown 常见的分隔线），其后所有内容（包括下一个 `## ` 段）都会被当成 frontmatter 静默
+ * 吞掉。这里**有意收紧**：frontmatter 只在文件开头识别一次，找到第一个闭合的 `---` 行后，
+ * 其后整体视为正文，正文扫描期间不再切换状态。理由：迁移会 `unlink` 原文件（只留 `.backups/`
+ * 里的副本），宽松解析吞掉的数据用户不会再看见。
+ *
+ * 没有 frontmatter（不以 `---\n` 开头）或没有闭合行时 `fields` 为空、`body` 为原文 ——
+ * 无 frontmatter 的 legacy 文件同样合法（spec §15.2 的第二个触发条件是「≥2 个 `## ` 段」）。
+ */
+function splitFrontmatter(text: string): { fields: Record<string, string>; body: string } {
+	if (!text.startsWith("---\n")) return { fields: {}, body: text };
+	const lines = text.split("\n");
+	let end = -1;
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i] === "---") {
+			end = i;
+			break;
+		}
+	}
+	if (end === -1) return { fields: {}, body: text };
+	const fields: Record<string, string> = {};
+	for (const line of lines.slice(1, end)) {
+		const m = line.match(FIELD_RE);
+		if (m) fields[m[1]] = m[2].trim();
+	}
+	return { fields, body: lines.slice(end + 1).join("\n") };
+}
+
+/**
+ * 按 `## ` 切段（算法迁自 v1 `topic-file.ts#parseEntries`，但按 Finding I1 收紧：调用方必须
+ * 先用 `splitFrontmatter` 剥掉开头的 frontmatter，正文里的 `---` 不再是分隔符）。
+ */
+function parseLegacySections(body: string): Array<{ title: string; content: string }> {
+	const entries: Array<{ title: string; content: string }> = [];
+	let currentTitle = "";
+	let currentContent: string[] = [];
+	let inEntry = false;
+
+	for (const line of body.split("\n")) {
+		const h2 = line.match(/^## (.+)$/);
+		if (h2) {
+			if (inEntry) entries.push({ title: currentTitle, content: currentContent.join("\n").trim() });
+			currentTitle = h2[1];
+			currentContent = [];
+			inEntry = true;
+			continue;
+		}
+		if (inEntry) currentContent.push(line);
+	}
+	if (inEntry) entries.push({ title: currentTitle, content: currentContent.join("\n").trim() });
+	return entries;
+}
+
+/**
+ * 这个文件是不是 v1 的 topic 文件（spec §15.2）？
+ *
+ * 判据：`MEMORY.md` 之外的 `.md`，且（frontmatter 含旧字段 `updated` **或** 含 ≥2 个 `## ` 段）。
+ *
+ * **必须先排除含 `modified` 的文件**：v2 的 entry 文件正文里完全可能有多个 `## ` 小标题，
+ * 若不排除，一条正常的 v2 记忆会被当成 legacy topic 再拆一次 —— 正文被切碎、原文件被删。
+ */
+export function isLegacyTopicFile(raw: string): boolean {
+	const { fields, body } = splitFrontmatter(normalizeEol(raw));
+	if (fields.modified !== undefined) return false;
+	if (fields.updated !== undefined) return true;
+	return parseLegacySections(body).length >= 2;
+}
+
+/** 拆出 legacy topic 文件里的全部 `## ` 段，并把该文件 frontmatter 的 `type` / `updated` 附到每一段上。 */
+export function parseLegacyEntries(raw: string): LegacyEntry[] {
+	const { fields, body } = splitFrontmatter(normalizeEol(raw));
+	return parseLegacySections(body).map((section) => ({
+		title: section.title,
+		content: section.content,
+		type: fields.type ?? "",
+		updated: fields.updated ?? "",
+	}));
+}
+
+/**
+ * 把 legacy 标题变成合法的 entry `name`。
+ *
+ * `](` 必须中和：`MemoryStore.#validateName` 会拒绝它（它能伪造索引行的 name/file 分组），
+ * 而迁移**不能**因为一条标题里有个 markdown 链接就整轮失败。替换成 `] (` 保住可读性。
+ */
+function sanitizeName(title: string): string {
+	return title
+		.replace(/[\r\n]+/g, " ")
+		.replaceAll("](", "] (")
+		.trim();
+}
+
+/**
+ * 给一条 legacy 段落挑一个不与其它记忆冲突的 `name`（spec §15.3 的后缀规则）。
+ *
+ * 候选按 `base`、`base (2)`、`base (3)`…… 依次探测（`name` 精确匹配，与 store 的语义一致）：
+ * - 未被占用 → 采用。
+ * - 已被占用，但磁盘上同名条目的正文与这一段相同 → **复用**这个名字：`addEntry` 对同名条目
+ *   是幂等覆盖，且保留磁盘上的 `created`。迁移中途失败后重跑时，上一轮已经写成功的条目走的正是
+ *   这条路 —— 不会产出 ` (2)` 影子副本（spec §15.4 的重跑安全）。
+ * - 已被占用、正文不同 → 试下一个后缀：迁移前就存在的同名用户条目必须被保护。
+ */
+function pickName(used: Set<string>, bodies: Map<string, string>, base: string, body: string): string {
+	const wanted = body.trim();
+	let candidate = base;
+	for (let n = 2; used.has(candidate) && bodies.get(candidate)?.trim() !== wanted; n++) {
+		candidate = `${base} (${n})`;
+	}
+	return candidate;
+}
+
+/** 旧 `updated` 归一为 store 接受的 `YYYY-MM-DD`；解析不出来就用今天（`created` 是必填字段）。 */
+function normalizeDate(updated: string, now: Date): string {
+	const iso = updated.match(/(\d{4})-(\d{2})-(\d{2})/);
+	if (iso) return `${iso[1]}-${iso[2]}-${iso[3]}`;
+	const parsed = updated ? new Date(updated) : null;
+	if (parsed && !Number.isNaN(parsed.getTime())) return parsed.toISOString().slice(0, 10);
+	return now.toISOString().slice(0, 10);
+}
+
+async function isFile(path: string): Promise<boolean> {
+	return stat(path).then(
+		(info) => info.isFile(),
+		() => false,
+	);
+}
+
+/** 只把 ENOENT 当作「文件不在了」；其余读取错误（EISDIR/EACCES/EIO）一律上抛（spec §15.4）。 */
+async function readIfExists(path: string): Promise<string | null> {
+	try {
+		return await readFile(path, "utf8");
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw e;
+	}
+}
+
+/**
+ * 自建回滚点 `.backups/migrate-<ts>/`（spec §15.3 步骤 2）。
+ *
+ * **不能用 `createSnapshot`**：它恒产出 `<ts>-<label>`，不可能以 `migrate-` 开头，
+ * 而 `pruneSnapshots` 只豁免 `migrate-` 前缀 —— 用它建的回滚点会在后续任何一次写入时
+ * 被 `snapshotKeep`（默认 5）裁掉，用户就再也回不去了（spec §19 风险表明列了这一条）。
+ *
+ * 布局：`migrate-<ts>/` = memoryDir 下所有普通文件的副本；`migrate-<ts>/originals/` = 待迁移的
+ * topic 文件副本（手工回滚时从这里恢复，见 spec §15.5）。
+ */
+async function createRollbackPoint(memoryDir: string, legacyFiles: string[], now: Date): Promise<string> {
+	const stamp = now.toISOString().replace(/[:.]/g, "-");
+	const backupDir = join(memoryDir, BACKUP_DIR, `migrate-${stamp}`);
+	await mkdir(join(backupDir, "originals"), { recursive: true });
+
+	// memoryDir 的存在性已在调用前检查过；列表失败（EACCES/EIO）不能吞：那会返回一个只有
+	// `originals/` 的不完整回滚点，而它随后就被写进 `.migrated` —— 用户再也回不去（spec §15.4）。
+	const entries = await readdir(memoryDir, { withFileTypes: true });
+	for (const entry of entries) {
+		// 只复制普通文件、跳过锁记录；`.backups` 与 `sessions/` 是目录，天然被排除。
+		// `.migrated` 此刻还不存在（它在最后一步才写），所以不需要显式排除。
+		if (!entry.isFile() || entry.name === LOCK_FILE) continue;
+		await cp(join(memoryDir, entry.name), join(backupDir, entry.name));
+	}
+	for (const file of legacyFiles) {
+		await cp(join(memoryDir, file), join(backupDir, "originals", file));
+	}
+	return backupDir;
+}
+
+async function writeMarker(path: string, marker: MigrationMarker): Promise<void> {
+	await writeFile(path, `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+}
+
+/**
+ * 首次 `session_start` 时把 v1 的 topic 布局迁移到 v2 的 per-entry 布局（spec §15 / D10）。
+ *
+ * 返回 `null` 表示「本次没有迁移任何东西」（已迁移过、目录不存在、或没有 legacy 文件）。
+ * 失败时**不写** `.migrated`、保留备份、把错误原样上抛（spec §15.4）：下次 session_start 重试，
+ * 而重跑是安全的 —— `addEntry` 对同名条目幂等，且候选名只在「磁盘上同名条目的正文与当前段落不同」
+ * 时才追加后缀（正文相同即复用，见 `pickName`）。
+ */
+export async function migrateIfNeeded(store: MemoryStore, options?: { now?: Date }): Promise<MigrationResult | null> {
+	const memoryDir = store.cfg.memoryDir;
+	const markerPath = join(memoryDir, MIGRATED_FILE);
+	if (await isFile(markerPath)) return null;
+
+	// 目录还不存在：没有 legacy 数据，也不在这里替 store 建目录（首次写入时它自己会建）。
+	const names = await readdir(memoryDir).catch(() => null);
+	if (names === null) return null;
+
+	const now = options?.now ?? new Date();
+	const nothing: MigrationMarker = { migratedAt: now.toISOString(), entries: 0, files: 0, backupDir: "" };
+
+	// 触发条件之一是「MEMORY.md 存在」（spec §15.2）。不存在就没有旧索引可迁，写标记以免每次
+	// session_start 都全目录 readFile。
+	if (!names.includes(INDEX_FILE)) {
+		await writeMarker(markerPath, nothing);
+		return null;
+	}
+
+	const candidates = names.filter((n) => n.endsWith(".md") && n !== INDEX_FILE && !n.startsWith(".")).sort();
+	const legacyFiles: string[] = [];
+	for (const file of candidates) {
+		// 只容忍 ENOENT（readdir 与 read 之间文件消失 → 当作非 legacy）。EISDIR/EACCES/EIO 必须上抛：
+		// 把不可读的候选归为「非 legacy」会在它是唯一候选时写下 0/0 标记，重试永久不再发生（spec §15.4）。
+		const raw = await readIfExists(join(memoryDir, file));
+		if (raw !== null && isLegacyTopicFile(raw)) legacyFiles.push(file);
+	}
+	if (legacyFiles.length === 0) {
+		await writeMarker(markerPath, nothing);
+		return null;
+	}
+
+	return store.withLogicalLock(async () => {
+		const backupDir = await createRollbackPoint(memoryDir, legacyFiles, now);
+
+		// `name` 唯一性集合的初值来自磁盘：这让「迁移中途失败后重跑」不会产出 ` (2)` 影子副本 ——
+		// 上一轮已经写成功的条目会在 listEntries 里，正文与当前段落相同的候选会被复用（addEntry 幂等）。
+		const summaries = await store.listEntries();
+		const usedNames = new Set(summaries.map((summary) => summary.name));
+		// 候选探测还需要「同名的正文」。一次 `searchEntries("")` 拿走全部正文（空 needle 对
+		// 任何字符串都是 includes 命中），避免旧实现里在摘要循环内反复 `readEntry`（每次都重扫
+		// 目录 → O(N²)）。同名多条目时以 listEntries 的顺序为准（后者覆盖前者），与现状一致。
+		const bodies = new Map<string, string>();
+		for (const entry of await store.searchEntries("")) bodies.set(entry.name, entry.body);
+		let entries = 0;
+
+		for (const file of legacyFiles) {
+			const raw = await readFile(join(memoryDir, file), "utf8");
+			for (const legacy of parseLegacyEntries(raw)) {
+				const name = pickName(usedNames, bodies, sanitizeName(legacy.title), legacy.content);
+				// 空标题或空正文的段落不生成 entry：store 会拒绝（"name is required" / "body is required"），
+				// 而让整轮迁移因为一个空 `## ` 段失败是更差的取舍。原文件在 originals/ 里，信息没有丢。
+				if (!name || !legacy.content) continue;
+				usedNames.add(name);
+				await store.addEntry(
+					{
+						name,
+						description: name,
+						type: isEntryType(legacy.type) ? legacy.type : "feedback",
+						body: legacy.content,
+						created: normalizeDate(legacy.updated, now),
+					},
+					{ skipLogicalLock: true, skipSnapshot: true },
+				);
+				entries++;
+			}
+		}
+
+		await store.rebuildIndex({ skipLogicalLock: true, skipSnapshot: true });
+
+		// 原 topic 文件从 memory 目录移除，否则 rebuildIndex 之后它们还会作为「无法解析的 .md」
+		// 留在目录里（spec §15.3 步骤 5）。它们已经保留在 migrate-<ts>/originals/。
+		// 删除失败必须上抛（只有 ENOENT 视为已删除）：吞掉的话 `.migrated` 会在文件仍留在目录里的
+		// 情况下被写下，重试永久不再发生（spec §15.4）。
+		for (const file of legacyFiles) {
+			await unlinkStrict(join(memoryDir, file));
+		}
+
+		await writeMarker(markerPath, { migratedAt: now.toISOString(), entries, files: legacyFiles.length, backupDir });
+		return { files: legacyFiles.length, entries, backupDir };
+	}, MIGRATE_LOCK_TIMEOUT_MS);
+}

package/src/paths.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
-import { join, normalize, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 
 const execFileP = promisify(execFile);
@@ -175,16 +175,3 @@ export async function resolveMemoryDir(config: { memoryDir: string }, cwd: strin
 	const { kind, key } = await projectIdentity(cwd);
 	return join(config.memoryDir, kind, projectDirName(key));
 }
-
-export function safeTopicPath(memoryDir: string, topic: string): string {
-	const normalized = normalize(topic);
-	if (normalized.includes("..") || normalized.startsWith(sep)) {
-		throw new Error(`Unsafe topic path: ${topic}`);
-	}
-	const resolved = resolve(memoryDir, normalized);
-	const resolvedMemoryDir = resolve(memoryDir);
-	if (!resolved.startsWith(resolvedMemoryDir + sep) && resolved !== resolvedMemoryDir) {
-		throw new Error(`Topic escapes memory dir: ${topic}`);
-	}
-	return resolved;
-}

package/src/process-lock.ts

@@ -0,0 +1,122 @@
+/**
+ * 进程内互斥（**不跨进程**）。
+ *
+ * 为什么存在：`memory add`、extract、dream 都在**同一个 pi 进程**里（dream 与 extract 是
+ * 进程内的 SDK 会话，不是子进程），而它们的互斥作用域长度相差三个数量级 —— 单次写入是毫秒，
+ * dream 整轮是分钟。让一把**跨进程**的 `.lock` 同时承担这两段时长会引出两串麻烦：
+ *   1. dream 整轮持 `.lock` 时，它自己的每次原语调用都会撞上自己的锁（`.lock` 不可重入）；
+ *   2. 另一个 pi 进程（同仓库的多个 worktree 共享 memory 目录）的写入要被堵住整轮；
+ *   3. 「持锁数分钟」逼出了 TTL 续约心跳与 stale 接管，而后者在 POSIX 上没有
+ *      compare-and-replace，无法做到可证明安全（见 fs-lock.ts 的说明）。
+ *
+ * 所以分层：**本模块承担「逻辑作用域」（毫秒的单次调用 或 分钟的整轮），
+ * `.lock` 只承担毫秒级的物理写入。** 进程内互斥是一个 Promise 队列 —— 天然可嵌套地表达
+ * 「谁在等谁」，零文件系统、零 staleness、零平台语义。
+ */
+
+/** 等待超过 `timeoutMs` 仍未拿到锁。调用方应把它当作可向用户交代的明确失败，而不是可重试的抖动。 */
+export class ProcessLockTimeoutError extends Error {
+	constructor(
+		readonly key: string,
+		readonly timeoutMs: number,
+	) {
+		super(`Memory operations for ${key} are already running in this process (waited ${timeoutMs}ms)`);
+		this.name = "ProcessLockTimeoutError";
+	}
+}
+
+/** 每个 key 的状态。**永不删除** —— 删了会出现「同一 key 两套状态」的脑裂互斥（一方用旧状态、一方用新状态）。条目数 = 进程见过的 memoryDir 数，可忽略。 */
+interface LockState {
+	/** 队尾：最后一个等待者放行后 resolve 的 promise。 */
+	tail: Promise<void>;
+	/** 当前是否有人持有。仅用于诊断/断言 —— 互斥本身依赖 `tail`，不依赖它。 */
+	held: boolean;
+	/** 正在排队（尚未拿到）的调用数。 */
+	waiters: number;
+}
+
+const states = new Map<string, LockState>();
+
+function stateFor(key: string): LockState {
+	let state = states.get(key);
+	if (!state) {
+		state = { tail: Promise.resolve(), held: false, waiters: 0 };
+		states.set(key, state);
+	}
+	return state;
+}
+
+/**
+ * 排队取得某个 key 的进程内锁，返回释放函数。
+ *
+ * 超时时**必须把自己的 gate 放掉**：我们从未持有过锁，若不放行，排在后面的调用会被我们的 gate
+ * 永久挂住（队尾链是 `previous.then(() => gate)`，我们的 gate 不放，后面所有人都拿不到）。
+ *
+ * 注意：**不能用「队尾是否为空」当作「有没有被持有」** —— 等待者超时会把自己从队尾摘掉，
+ * 而持有者仍在工作，于是队尾变空而锁定仍被持有。所以 `held` / `waiters` 单独计数。
+ */
+async function acquire(key: string, timeoutMs: number): Promise<() => void> {
+	const state = stateFor(key);
+	const previous = state.tail;
+	let release!: () => void;
+	const gate = new Promise<void>((resolve) => {
+		release = resolve;
+	});
+	state.tail = previous.then(() => gate, () => gate);
+	state.waiters += 1;
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timedOut = Symbol("timeout");
+	const outcome = await Promise.race([
+		previous.then(() => "acquired" as const),
+		new Promise<typeof timedOut>((resolve) => {
+			timer = setTimeout(() => resolve(timedOut), timeoutMs);
+		}),
+	]);
+	if (timer) clearTimeout(timer);
+	state.waiters -= 1;
+
+	if (outcome === timedOut) {
+		release();
+		throw new ProcessLockTimeoutError(key, timeoutMs);
+	}
+
+	state.held = true;
+	return () => {
+		state.held = false;
+		release();
+	};
+}
+
+/** 在进程内串行执行 `fn`（按 `key` 分键）。超时抛 `ProcessLockTimeoutError`。 */
+export async function withProcessLock<T>(key: string, timeoutMs: number, fn: () => Promise<T>): Promise<T> {
+	const release = await acquire(key, timeoutMs);
+	try {
+		return await fn();
+	} finally {
+		release();
+	}
+}
+
+/** 只在 `key` 空闲时执行 `fn`；有人在持有或排队则立刻返回 `null`，绝不等待（extract 的「锁忙则跳过本轮」）。 */
+export async function tryWithProcessLock<T>(key: string, fn: () => Promise<T>): Promise<T | null> {
+	try {
+		return await withProcessLock(key, 0, fn);
+	} catch (e) {
+		if (e instanceof ProcessLockTimeoutError) return null;
+		throw e;
+	}
+}
+
+/**
+ * 该 key 上是否有人在持有或排队。
+ * 用途：整轮持有者（dream / 迁移）启动前断言自己确实已经包住了锁 —— 「忘了包」会静默失去整轮互斥，
+ * 这条断言把它变成一个立刻可见的错误。
+ *
+ * 注意它只是**诊断用**的：互斥由 `tail` 保证。释放与下一个持有者接上之间存在一个微任务窗口，
+ * 此窗口内 `isProcessLockActive` 可能瞬时返回 false，但那时新调用者仍然会正确地排在 `tail` 之后。
+ */
+export function isProcessLockActive(key: string): boolean {
+	const state = states.get(key);
+	return state !== undefined && (state.held || state.waiters > 0);
+}

package/src/sanitize.ts

@@ -0,0 +1,36 @@
+/**
+ * 注入净化（spec §13）。**只在注入时**使用，绝不写回磁盘（D11）—— 磁盘上的 entry 必须
+ * 保持用户可读、可手工编辑的原始形态。
+ *
+ * 本模块是纯函数模块：不 import `node:fs`、不读配置、不碰 store。
+ */
+
+/**
+ * 全部 Unicode `Cf`（format）类别字符：零宽（U+200B–U+200D、U+FEFF）、bidi 控制符
+ * （U+202A–U+202E、U+2066–U+2069）、软连字符、LRM/RLM、word joiner 等。
+ *
+ * 用 `\p{Cf}` 而不是逐个码点枚举：新加入的格式字符自动被覆盖。`\n` / `\t` 是 Cc、
+ * 空格是 Zs，都不在此列 —— 注入文本的排版必须原样保留。
+ */
+const INVISIBLE_RE = /\p{Cf}/gu;
+
+/** 剥离全部不可见格式字符（bidi 覆写可以让磁盘上的记忆在注入后"读出"别的意思）。 */
+export function stripInvisibleChars(text: string): string {
+	return text.replace(INVISIBLE_RE, "");
+}
+
+/**
+ * 净化一段将要进入 system prompt / 注入消息的文本：剥离不可见字符 + 中和尖括号。
+ *
+ * **幂等是硬要求，所以这里刻意不转义 `&`。** 若把 `&` → `&`，第一次产出的 `<`
+ * 在第二次就会变成 `<`；而 `memory_index` 的值在 resume / fork / reload 时会被
+ * 逐轮重放（D13 / D14），每重放一次就漂移一次 —— system prompt 头部再也稳定不下来，
+ * prefix cache 全废。`sanitizeForInjection(sanitizeForInjection(x)) === sanitizeForInjection(x)`
+ * 由测试钉住。
+ *
+ * 代价：正文里字面的 `&lt;` 在注入后无法与「原本是 `<`」区分。这是可接受的取舍 ——
+ * 两者在模型眼里都读作 `<`，而我们要防的正是「用 `<` 伪造系统标签」。
+ */
+export function sanitizeForInjection(text: string): string {
+	return stripInvisibleChars(text).replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/src/snapshot.ts

@@ -0,0 +1,68 @@
+import { cp, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+export interface SnapshotOptions {
+	keep: number;
+	now?: () => Date;
+}
+
+/** 可字典序排序的快照时间戳（ISO 8601，`:` 与 `.` 换为 `-`）。 */
+export function snapshotStamp(now: () => Date): string {
+	return now().toISOString().replace(/[:.]/g, "-");
+}
+
+async function uniqueDir(backupRoot: string, base: string): Promise<string> {
+	await mkdir(backupRoot, { recursive: true });
+	for (let n = 1; ; n++) {
+		const candidate = n === 1 ? join(backupRoot, base) : join(backupRoot, `${base}-${n}`);
+		try {
+			await mkdir(candidate);
+			return candidate;
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+		}
+	}
+}
+
+/** 将给定的 memory 目录相对路径复制到新快照目录；不存在的文件被跳过。 */
+export async function createSnapshot(
+	backupRoot: string,
+	label: string,
+	files: string[],
+	memoryDir: string,
+	options: SnapshotOptions,
+): Promise<string> {
+	const dir = await uniqueDir(backupRoot, `${snapshotStamp(options.now ?? (() => new Date()))}-${label}`);
+	for (const file of files) {
+		try {
+			await cp(join(memoryDir, file), join(dir, basename(file)));
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code === "ENOENT") continue;
+			throw e;
+		}
+	}
+	await pruneSnapshots(backupRoot, options.keep);
+	return dir;
+}
+
+/** 保留名字序最新的 keep 个快照；`migrate-` 开头的目录永不参与裁剪。 */
+export async function pruneSnapshots(backupRoot: string, keep: number): Promise<void> {
+	let names: string[];
+	try {
+		names = await readdir(backupRoot);
+	} catch {
+		return;
+	}
+
+	const dirs: string[] = [];
+	for (const name of names) {
+		if (name.startsWith("migrate-")) continue;
+		const info = await stat(join(backupRoot, name)).catch(() => null);
+		if (info?.isDirectory()) dirs.push(name);
+	}
+
+	dirs.sort();
+	for (const name of dirs.slice(0, Math.max(0, dirs.length - Math.max(0, keep)))) {
+		await rm(join(backupRoot, name), { recursive: true, force: true });
+	}
+}

package/src/index-file.ts

@@ -1,91 +0,0 @@
-export interface IndexEntry {
-	name: string; // 原名 title，取自 frontmatter name
-	topic: string; // 文件名
-	hook: string; // 一行描述
-	raw: string; // 原始行文本
-}
-
-export interface IndexFile {
-	entries: IndexEntry[];
-	raw: string;
-}
-
-// Matches: - [Name](topic.md) — hook
-const LINE_RE = /^-\s+\[([^\]]+)\]\(([^)]+)\)\s*—\s*(.*)$/;
-
-export function parseIndex(content: string): IndexFile {
-	const entries: IndexEntry[] = [];
-	for (const line of content.split("\n")) {
-		const m = line.match(LINE_RE);
-		if (m) {
-			entries.push({
-				name: m[1].trim(),
-				topic: m[2].trim(),
-				hook: m[3].trim(),
-				raw: line,
-			});
-		}
-	}
-	return { entries, raw: content };
-}
-
-export function serializeIndex(entries: IndexEntry[]): string {
-	return entries.map((e) => `- [${e.name}](${e.topic}) — ${e.hook}`).join("\n");
-}
-
-export function upsertEntryByTopic(entries: IndexEntry[], entry: IndexEntry): IndexEntry[] {
-	const idx = entries.findIndex((e) => e.topic === entry.topic);
-	if (idx === -1) return [...entries, entry];
-	const next = [...entries];
-	next[idx] = entry;
-	return next;
-}
-
-export function removeEntryByTopic(entries: IndexEntry[], topic: string): IndexEntry[] {
-	const idx = entries.findIndex((e) => e.topic === topic);
-	if (idx === -1) throw new Error(`Topic "${topic}" not found in index`);
-	const next = [...entries];
-	next.splice(idx, 1);
-	return next;
-}
-
-export function findEntryByTopic(entries: IndexEntry[], topic: string): IndexEntry | null {
-	return entries.find((e) => e.topic === topic) ?? null;
-}
-
-export function updateHook(entries: IndexEntry[], topic: string, hook: string): IndexEntry[] {
-	const idx = entries.findIndex((e) => e.topic === topic);
-	if (idx === -1) throw new Error(`Topic "${topic}" not found in index`);
-	const next = [...entries];
-	next[idx] = { ...next[idx], hook, raw: "" };
-	return next;
-}
-
-export function truncateForInjection(
-	content: string,
-	maxLines: number,
-	maxBytes: number,
-): { ok: boolean; content: string; truncated: boolean } {
-	const lines = content.split("\n");
-	let out = content;
-	let truncated = false;
-	if (lines.length > maxLines) {
-		out = lines.slice(0, maxLines).join("\n");
-		truncated = true;
-	}
-	if (Buffer.byteLength(out, "utf8") > maxBytes) {
-		let cut = out;
-		while (Buffer.byteLength(cut, "utf8") > maxBytes && cut.length > 0) cut = cut.slice(0, -1);
-		out = cut;
-		truncated = true;
-	}
-	if (truncated) out += `\n[truncated: memory index exceeds injection limit]`;
-	return { ok: !truncated, content: out, truncated };
-}
-
-export function checkCapacity(entries: IndexEntry[], maxLines: number, maxBytes: number): boolean {
-	const serialized = serializeIndex(entries);
-	if (entries.length > maxLines) return false;
-	if (Buffer.byteLength(serialized, "utf8") > maxBytes) return false;
-	return true;
-}