@yandy0725/pi-memory 1.4.0 → 2.1.0

package/src/model-resolver.ts

@@ -10,7 +10,7 @@ interface ModelEntry {
 /**
  * Resolve a model string to a Model instance.
  * Tries exact "provider/modelId" match (only available models), then fuzzy match.
- * Returns the Model on success, or undefined on failure (caller falls back to parent model).
+ * Returns the Model on success, or undefined（调用方报错，不回退父模型）。
  */
 export function resolveModel(input: string, registry: ModelRegistry): Model<any> | undefined {
 	if (!input) return undefined;

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;
-}

package/src/topic-file.ts

@@ -1,119 +0,0 @@
-export interface TopicMeta {
-	name: string;
-	description: string;
-	type: string;
-	updated: string;
-}
-
-export const ALLOWED_TYPES = ["user", "feedback", "project", "reference"] as const;
-
-export function buildFrontmatter(meta: TopicMeta): string {
-	return [
-		"---",
-		`name: ${meta.name}`,
-		`description: ${meta.description}`,
-		`type: ${meta.type}`,
-		`updated: ${meta.updated}`,
-		"---",
-		"",
-		"",
-	].join("\n");
-}
-
-export function parseFrontmatter(raw: string): TopicMeta | null {
-	if (!raw.startsWith("---\n")) return null;
-	const endIdx = raw.indexOf("\n---\n", 4);
-	if (endIdx === -1) return null;
-	const block = raw.slice(4, endIdx);
-	const meta: Record<string, string> = {};
-	for (const line of block.split("\n")) {
-		const m = line.match(/^(\w+):\s*(.*)$/);
-		if (m) meta[m[1]] = m[2].trim();
-	}
-	if (!meta.name || !meta.description || !meta.type || !meta.updated) return null;
-	if (!(ALLOWED_TYPES as readonly string[]).includes(meta.type)) return null;
-	return meta as unknown as TopicMeta;
-}
-
-export function appendContent(existing: string | null, entryTitle: string, content: string): string {
-	const section = `## ${entryTitle}\n\n${content}`;
-	if (!existing || existing.trim() === "") return section;
-	return `${existing.trimEnd()}\n\n${section}\n`;
-}
-
-export function updateFrontmatterDate(raw: string, date: string): string {
-	return raw.replace(/^(---\n(?:.*\n)*?)updated: .+(\n---)/m, `$1updated: ${date}$2`);
-}
-
-export function replaceFrontmatterField(raw: string, field: string, value: string): string {
-	const regex = new RegExp(`^(---\n(?:.*\n)*?)${field}: .+(\n)`, "m");
-	return raw.replace(regex, (_full: string, prefix: string, nl: string) => `${prefix}${field}: ${value}${nl}`);
-}
-
-export function removeEntrySection(raw: string, title: string): string {
-	const marker = `## ${title}`;
-	// find start of this entry block
-	const startIdx = raw.indexOf(`\n${marker}\n`) !== -1 ? raw.indexOf(`\n${marker}\n`) : raw.indexOf(marker);
-	if (startIdx === -1) throw new Error(`Entry "${title}" not found`);
-
-	// find start of next ## or EOF
-	const afterHeader = raw.indexOf("\n", startIdx + marker.length);
-	const nextH2 = raw.indexOf("\n## ", afterHeader + 1);
-	const endIdx = nextH2 === -1 ? raw.length : nextH2;
-
-	// remove including preceding blank lines
-	let cutStart = startIdx;
-	while (cutStart > 0 && raw[cutStart - 1] === "\n") cutStart--;
-	// also strip one more \n if present (the blank line separator)
-	if (cutStart > 0 && raw[cutStart - 1] === "\n") cutStart--;
-
-	let result = raw.slice(0, cutStart) + raw.slice(endIdx);
-	// ensure exactly one trailing newline
-	result = result.replace(/\n{3,}$/, "\n\n").replace(/\n{2,}$/, "\n");
-	if (!result.endsWith("\n")) result += "\n";
-	return result;
-}
-
-export function hasEntries(raw: string): boolean {
-	return /^## /m.test(raw);
-}
-
-export interface ParsedEntry {
-	title: string;
-	content: string;
-}
-
-export function parseEntries(raw: string): ParsedEntry[] {
-	const entries: ParsedEntry[] = [];
-	const lines = raw.split("\n");
-	let currentTitle = "";
-	let currentContent: string[] = [];
-	let inEntry = false;
-	let inFrontmatter = false;
-
-	for (const line of lines) {
-		if (line === "---") {
-			inFrontmatter = !inFrontmatter;
-			continue;
-		}
-		if (inFrontmatter) continue;
-
-		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;
-}