@zhushanwen/pi-system-prompt-trace 0.1.0

package/src/diff.ts

@@ -0,0 +1,109 @@
+/**
+ * 行级 diff 摘要生成器（parentVersionDiffSummary 字段）。
+ *
+ * 设计定位：entry 内的摘要是对用户友好的「一眼看出改了什么」；Trace 视图 inspector 在渲染时
+ * 会用相邻两条留痕 entry 的 fullText 重算完整 diff，这里只需轻量摘要，不追求 patch 级精确。
+ */
+
+/** 摘要采样行数上限（防巨型 prompt 差异把 entry 撑爆）。 */
+const MAX_SAMPLE_LINES = 8;
+/** 单行截断长度（字符）。 */
+const MAX_SAMPLE_CHARS = 80;
+/** LCS DP 面积上限：超过退化为 multiset 计数（O(n·m) → O(n+m)，防巨型 prompt 爆内存）。 */
+const MAX_LCS_CELLS = 4_000_000;
+
+/** 生成 oldText → newText 的行级 diff 摘要："+A -R lines" 头 + 最多 8 条采样行。 */
+export function summarizePromptDiff(oldText: string, newText: string): string {
+	const oldLines = oldText.split("\n");
+	const newLines = newText.split("\n");
+	const { removed, added } =
+		oldLines.length * newLines.length <= MAX_LCS_CELLS
+			? lcsLineDiff(oldLines, newLines)
+			: multisetLineDiff(oldLines, newLines);
+
+	const header = `+${added.length} -${removed.length} lines`;
+	const samples: string[] = [];
+	// 交替取样（added 优先）：注入类变化（只增不减）时全部展示新增行，混合变化时两类都可见
+	let ai = 0;
+	let ri = 0;
+	while (samples.length < MAX_SAMPLE_LINES && (ai < added.length || ri < removed.length)) {
+		if (ai < added.length) {
+			samples.push(`+ ${truncate(added[ai])}`);
+			ai++;
+		}
+		if (samples.length < MAX_SAMPLE_LINES && ri < removed.length) {
+			samples.push(`- ${truncate(removed[ri])}`);
+			ri++;
+		}
+	}
+	return samples.length === 0 ? header : [header, ...samples].join("\n");
+}
+
+/** LCS 回溯行 diff：产出与文本顺序一致的 removed/added 序列（采样时更有可读性）。 */
+function lcsLineDiff(a: readonly string[], b: readonly string[]): { removed: string[]; added: string[] } {
+	const m = a.length;
+	const n = b.length;
+	const width = n + 1;
+	const dp = new Uint32Array((m + 1) * width);
+	for (let i = m - 1; i >= 0; i--) {
+		for (let j = n - 1; j >= 0; j--) {
+			dp[i * width + j] =
+				a[i] === b[j]
+					? dp[(i + 1) * width + j + 1] + 1
+					: Math.max(dp[(i + 1) * width + j], dp[i * width + j + 1]);
+		}
+	}
+	const removed: string[] = [];
+	const added: string[] = [];
+	let i = 0;
+	let j = 0;
+	while (i < m && j < n) {
+		if (a[i] === b[j]) {
+			i++;
+			j++;
+		} else if (dp[(i + 1) * width + j] >= dp[i * width + j + 1]) {
+			removed.push(a[i]);
+			i++;
+		} else {
+			added.push(b[j]);
+			j++;
+		}
+	}
+	while (i < m) {
+		removed.push(a[i]);
+		i++;
+	}
+	while (j < n) {
+		added.push(b[j]);
+		j++;
+	}
+	return { removed, added };
+}
+
+/** multiset 行计数 diff（LCS 面积超限的降级路径）：行内容匹配抵消，剩余计入 added/removed。 */
+function multisetLineDiff(a: readonly string[], b: readonly string[]): { removed: string[]; added: string[] } {
+	const counts = new Map<string, number>();
+	for (const line of a) {
+		counts.set(line, (counts.get(line) ?? 0) + 1);
+	}
+	const added: string[] = [];
+	for (const line of b) {
+		const c = counts.get(line) ?? 0;
+		if (c > 0) {
+			counts.set(line, c - 1);
+		} else {
+			added.push(line);
+		}
+	}
+	const removed: string[] = [];
+	for (const [line, c] of counts) {
+		for (let k = 0; k < c; k++) {
+			removed.push(line);
+		}
+	}
+	return { removed, added };
+}
+
+function truncate(line: string): string {
+	return line.length > MAX_SAMPLE_CHARS ? line.slice(0, MAX_SAMPLE_CHARS - 1) + "…" : line;
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * pi extension wiring：把 ExtensionContext 适配进 trace.ts 状态机并订阅三个事件。
+ *
+ * 事件宽松类型（参考 rename-session TurnEndLikeEvent 先例）：pi 的 on() 重载对严格事件类型
+ * 做参数逆变匹配，收窄字段的本地接口更稳；字段在逻辑侧运行时归一化（normalizeSessionStartReason）。
+ */
+
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+	BASELINE_FILENAME,
+	readLastPromptFromSessionFile,
+	readPersistedBaseline,
+	writePersistedBaseline,
+} from "./baseline.js";
+import { createSystemPromptTrace } from "./trace.js";
+import type { TraceContext, TraceEnv } from "./trace.js";
+import type { SwitchStash } from "./types.js";
+
+interface SessionStartLikeEvent {
+	type: "session_start";
+	reason: string;
+	previousSessionFile?: string;
+}
+
+interface SessionBeforeSwitchLikeEvent {
+	type: "session_before_switch";
+	reason: string;
+	targetSessionFile?: string;
+}
+
+interface TurnStartLikeEvent {
+	type: "turn_start";
+	turnIndex: number;
+	timestamp: number;
+}
+
+// 模块级单例：session_before_switch（旧 runtime）→ session_start（新 runtime）之间传递
+// targetSessionFile 直读基线。switch 会 teardown 并重建 extension runtime，闭包状态不跨
+// runtime 存活（见 types.ts SwitchStash 注释），只有模块缓存在进程内延续。
+const switchStash: SwitchStash = { pending: null };
+
+function toTraceContext(pi: ExtensionAPI, ctx: ExtensionContext): TraceContext {
+	// appendEntry 在 ExtensionAPI（pi 对象）上；getSystemPrompt/sessionManager 在 ExtensionContext 上
+	return {
+		getSystemPrompt: () => ctx.getSystemPrompt(),
+		appendEntry: (customType, data) => pi.appendEntry(customType, data),
+		getSessionId: () => ctx.sessionManager.getSessionId(),
+	};
+}
+
+export default function systemPromptTraceExtension(pi: ExtensionAPI): void {
+	const baselineFilePath = join(getAgentDir(), BASELINE_FILENAME);
+
+	const env: TraceEnv = {
+		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath, "target-file"),
+		readPersistedBaseline: (sessionId) => readPersistedBaseline(baselineFilePath, sessionId),
+		writePersistedBaseline: (sessionId, hash, version) =>
+			writePersistedBaseline(baselineFilePath, sessionId, hash, version),
+	};
+
+	const logic = createSystemPromptTrace(env, switchStash);
+
+	pi.on("session_start", async (event: SessionStartLikeEvent, ctx: ExtensionContext) => {
+		logic.onSessionStart(
+			event.reason,
+			typeof event.previousSessionFile === "string" ? event.previousSessionFile : undefined,
+			toTraceContext(pi, ctx),
+		);
+	});
+
+	pi.on("session_before_switch", async (event: SessionBeforeSwitchLikeEvent) => {
+		logic.onSessionBeforeSwitch(
+			event.reason,
+			typeof event.targetSessionFile === "string" ? event.targetSessionFile : undefined,
+		);
+	});
+
+	pi.on("turn_start", async (_event: TurnStartLikeEvent, ctx: ExtensionContext) => {
+		logic.onTurnStart(toTraceContext(pi, ctx));
+	});
+}

package/src/trace.ts

@@ -0,0 +1,153 @@
+/**
+ * 留痕状态机（纯逻辑，文件系统与 pi 上下文经 env/ctx 注入，可脱离 pi 单测）。
+ *
+ * 写入时机（设计 D2 校正）：
+ * - 不在 session_start 写——该事件 emit 早于 resources_discover 的 prompt 重建，快照必不完整、
+ *   首 turn 必误报一次 change；
+ * - 首个 turn_start 写 initial/resume——此时 getSystemPrompt() 已含 before_agent_start 注入
+ *   （pi 的事件链：用户消息 handler 先 await emitBeforeAgentStart（agent-session.ts:1243-1244），
+ *   再 agent_start → turn_start 事件分发（agent-session.ts:739-746））；
+ * - 后续每个 turn_start 做 hash 对比，变化才写 change。
+ */
+
+import { createHash } from "node:crypto";
+
+import { summarizePromptDiff } from "./diff.js";
+import {
+	mapReasonForFirstWrite,
+	normalizeSessionStartReason,
+	SYSTEM_PROMPT_CUSTOM_TYPE,
+} from "./types.js";
+import type {
+	PromptBaseline,
+	SessionStartReason,
+	SwitchStash,
+	SystemPromptTraceEntryData,
+	TraceReason,
+} from "./types.js";
+
+/** 逻辑所需的 per-call pi 上下文（wiring 从 ExtensionContext + ExtensionAPI 适配；测试注入 fake）。 */
+export interface TraceContext {
+	getSystemPrompt(): string;
+	appendEntry(customType: string, data: unknown): void;
+	getSessionId(): string;
+}
+
+/** 文件系统侧依赖（wiring 用真实 fs + agentDir；测试注入临时目录实现）。 */
+export interface TraceEnv {
+	readLastPromptFromFile(filePath: string): PromptBaseline | null;
+	readPersistedBaseline(sessionId: string): PromptBaseline | null;
+	writePersistedBaseline(sessionId: string, hash: string, version: number): void;
+}
+
+export interface SystemPromptTrace {
+	onSessionStart(reason: string, previousSessionFile: string | undefined, ctx: TraceContext): void;
+	onSessionBeforeSwitch(reason: string, targetSessionFile: string | undefined): void;
+	onTurnStart(ctx: TraceContext): void;
+}
+
+/** 当前已确立的 prompt 版本（写过或基线去重命中后确立）。 */
+interface CurrentPrompt {
+	version: number;
+	hash: string;
+	fullText: string;
+}
+
+export function computePromptHash(text: string): string {
+	return createHash("sha256").update(text, "utf-8").digest("hex");
+}
+
+export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): SystemPromptTrace {
+	let sessionStartReason: SessionStartReason | null = null;
+	let baseline: PromptBaseline | null = null;
+	let current: CurrentPrompt | null = null;
+
+	const write = (
+		ctx: TraceContext,
+		text: string,
+		hash: string,
+		reason: TraceReason,
+		version: number,
+		parentFullText: string | undefined,
+	): void => {
+		const data: SystemPromptTraceEntryData = {
+			version,
+			hash,
+			reason,
+			fullText: text,
+			charCount: text.length,
+		};
+		if (parentFullText !== undefined) {
+			data.parentVersionDiffSummary = summarizePromptDiff(parentFullText, text);
+		}
+		ctx.appendEntry(SYSTEM_PROMPT_CUSTOM_TYPE, data);
+		// 落盘成功后才刷新自持久化基线（app 重启直 spawn resume 的唯一基线来源，设计 D2 路径 2）
+		env.writePersistedBaseline(ctx.getSessionId(), hash, version);
+	};
+
+	return {
+		onSessionStart(reason, previousSessionFile, ctx) {
+			sessionStartReason = normalizeSessionStartReason(reason);
+			current = null;
+			// 基线解析（设计 D2 跨重启三路径，优先级从高到低）：
+			// 1. session_before_switch 直读目标文件（进程内 resume；stash 为模块级单例，跨 runtime 传递）
+			// 2. fork 的 previousSessionFile 直读【暂定语义，待 P2 实测定】
+			// 3. agentDir 自持久化小文件（app 重启直 spawn resume / reload——这两种链路没有 switch 事件）
+			// 4. 全 miss → null：首个 turn 按 reason 映射写 initial/resume（resume 必写 = 兜底路径）
+			// stash 无论是否采用都消费：cancelled switch 的残留基线不允许污染下一次 session_start
+			const stashed = stash.pending;
+			stash.pending = null;
+			if (stashed !== null && sessionStartReason === "resume") {
+				baseline = stashed;
+			} else if (sessionStartReason === "fork" && previousSessionFile !== undefined) {
+				const fromPrev = env.readLastPromptFromFile(previousSessionFile);
+				baseline = fromPrev === null ? null : { ...fromPrev, source: "previous-session-file" };
+			} else {
+				baseline = env.readPersistedBaseline(ctx.getSessionId());
+			}
+		},
+
+		onSessionBeforeSwitch(reason, targetSessionFile) {
+			// 只有 resume 的目标文件承载同 session 历史；new 的目标是全新空文件。
+			// 该 handler 在旧 runtime 里执行，结果写入模块级 stash 供新 runtime 的
+			// session_start 消费（switch 会重建 extension runtime，见 types.ts SwitchStash 注释）。
+			stash.pending =
+				reason === "resume" && targetSessionFile !== undefined
+					? env.readLastPromptFromFile(targetSessionFile)
+					: null;
+		},
+
+		onTurnStart(ctx) {
+			try {
+				const text = ctx.getSystemPrompt();
+				const hash = computePromptHash(text);
+				if (current !== null) {
+					// 后续 turn：hash 对比去重（设计 D2），变化才写 change
+					if (hash === current.hash) return;
+					write(ctx, text, hash, "change", current.version + 1, current.fullText);
+					current = { version: current.version + 1, hash, fullText: text };
+					return;
+				}
+				// 本 session_start 周期的首个 turn_start
+				if (baseline !== null && baseline.hash === hash) {
+					// 跨重启基线命中且未变化：不写，但确立 current 供后续 turn 继续对比；
+					// 顺带刷新自持久化基线（updatedAt 续命 + 小文件丢失时自愈）
+					current = { version: baseline.version, hash, fullText: text };
+					env.writePersistedBaseline(ctx.getSessionId(), hash, baseline.version);
+					return;
+				}
+				// 必写：有基线 → resume（该 session 已有历史版本，这是重开点的快照，version 续接）；
+				// 无基线 → 按 SessionStartEvent.reason 映射（startup/new→initial，resume→resume 兜底必写）
+				const version = baseline === null ? 1 : baseline.version + 1;
+				const reason: TraceReason =
+					baseline === null ? mapReasonForFirstWrite(sessionStartReason ?? "startup") : "resume";
+				const parentFullText = baseline === null ? undefined : baseline.fullText;
+				write(ctx, text, hash, reason, version, parentFullText);
+				current = { version, hash, fullText: text };
+			} catch (e) {
+				// 留痕是诊断性旁路：任何失败都不允许影响 agent 主流程（错误进 pi stdout，随日志落盘）
+				console.error("[pi-system-prompt-trace] turn_start handler failed:", e);
+			}
+		},
+	};
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+/**
+ * 共享类型、常量与 reason 映射。
+ *
+ * 留痕 entry 是 custom 类型（不进 LLM context，零模型侧影响，设计 D2），
+ * 数据形状见 SystemPromptTraceEntryData。
+ */
+
+/** 留痕 entry 的 customType（xyz: 前缀 = xyz-agent 自定义命名空间）。 */
+export const SYSTEM_PROMPT_CUSTOM_TYPE = "xyz:system-prompt";
+
+/** pi SessionStartEvent.reason 原生 5 值（pi 源码 core/extensions/types.ts:565）。 */
+export type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork";
+
+/** 落盘 reason 枚举（initial/resume/change，对齐 DSH request/header 语义，设计 D2）。 */
+export type TraceReason = "initial" | "resume" | "change";
+
+/** appendEntry("xyz:system-prompt", data) 的 data 形状（设计 §5 单元 1）。 */
+export interface SystemPromptTraceEntryData {
+	/** session 内单调递增（首条 1；有基线时续接基线版本 +1）。 */
+	version: number;
+	/** sha256(fullText) 十六进制——hash 对比去重与跨重启基线的依据。 */
+	hash: string;
+	reason: TraceReason;
+	/** 完整 system prompt（每条 ~12KB，hash 去重后典型 session 只写 1-3 次，设计 D2 权衡）。 */
+	fullText: string;
+	/** fullText.length（UTF-16 码元数）。 */
+	charCount: number;
+	/** 与上一版的行级 diff 摘要；无 parent 全文（自持久化基线只有 hash/首条）时缺省。 */
+	parentVersionDiffSummary?: string;
+}
+
+/** 跨重启恢复的 hash 基线。 */
+export interface PromptBaseline {
+	hash: string;
+	version: number;
+	/** 从 session 文件留痕 entry 直读时有值（可生成 diff 摘要）；自持久化小文件只有 hash+version。 */
+	fullText?: string;
+	/** 基线来源（三路径，见 trace.ts onSessionStart 的解析优先级）。 */
+	source: "target-file" | "previous-session-file" | "persisted";
+}
+
+/**
+ * session_before_switch → session_start 之间传递的直读基线。
+ * 必须是模块级单例对象而非闭包变量：switchSession 会 teardown 并重建 extension runtime
+ * （pi agent-session-runtime.ts teardownCurrent → createRuntime 重新调用 factory），
+ * 闭包状态不跨 runtime 存活，只有模块缓存（extensions/loader.ts extensionCache）在进程内延续。
+ */
+export interface SwitchStash {
+	pending: PromptBaseline | null;
+}
+
+/** 运行时类型 guard（taste/no-unsafe-cast：断言必须有运行时 guard，这里干脆不用断言）。 */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/** 留痕 entry data 的运行时 guard（读 JSONL / 测试断言复用）。 */
+export function isSystemPromptTraceEntryData(value: unknown): value is SystemPromptTraceEntryData {
+	if (!isRecord(value)) return false;
+	const version = value["version"];
+	const hash = value["hash"];
+	const reason = value["reason"];
+	const fullText = value["fullText"];
+	const charCount = value["charCount"];
+	return (
+		typeof version === "number" &&
+		Number.isFinite(version) &&
+		typeof hash === "string" &&
+		(reason === "initial" || reason === "resume" || reason === "change") &&
+		typeof fullText === "string" &&
+		typeof charCount === "number"
+	);
+}
+
+const SESSION_START_REASONS: readonly SessionStartReason[] = [
+	"startup",
+	"reload",
+	"new",
+	"resume",
+	"fork",
+];
+
+/** 事件侧 reason 归一化：untyped extension 传入非 5 值时按 startup 处理（最保守：无基线则 initial）。 */
+export function normalizeSessionStartReason(raw: string): SessionStartReason {
+	return SESSION_START_REASONS.find((r) => r === raw) ?? "startup";
+}
+
+/**
+ * 无基线时 SessionStartEvent.reason → 落盘 reason 的映射（A11）。
+ *
+ * - startup / new → initial（新 session 首建快照）
+ * - resume → resume（重开快照）
+ * - fork / reload → resume【暂定，待 P2 实测定（A13 探针），测试显式标注】：
+ *   fork 的新文件携带源 session 的历史 entry（版本链延续，且 xyz-agent 的 fork 实际经
+ *   switchSession 走 resume 链路），reload 是同 session 的 extension 运行时重建——
+ *   两者语义上都更接近「重开」而非「首建」。
+ *
+ * 注意：只要恢复了任一 hash 基线，首个 turn 一律写 resume（见 trace.ts），不走本映射。
+ */
+export function mapReasonForFirstWrite(reason: SessionStartReason): TraceReason {
+	switch (reason) {
+		case "startup":
+		case "new":
+			return "initial";
+		case "resume":
+		case "fork":
+		case "reload":
+			return "resume";
+	}
+}