@zhushanwen/pi-system-prompt-trace 0.1.7 → 0.2.0

package/README.md

@@ -2,12 +2,12 @@
 
 Session Trace 单元 1（留痕 extension）。system prompt 在 pi 中每次运行时动态重建、默认不落盘——本包在
 system prompt 确立或变化时向 session JSONL 追加留痕 entry，让「resume/reload/换配置前后 prompt 到底是什么」
-可追溯（设计：`docs/page-design/session-trace/design.md` D2）。
+可追溯。
 
 ## 落盘格式
 
 ```ts
-appendEntry("xyz:system-prompt", {
+appendEntry("taiji:system-prompt", {
   version: number;                    // session 内单调递增，首条 1
   hash: string;                       // sha256(fullText) 十六进制
   reason: "initial" | "resume" | "change";
@@ -31,7 +31,7 @@ appendEntry("xyz:system-prompt", {
 |---|---|---|
 | startup / new | initial | 定案 |
 | resume | resume | 定案 |
-| fork / reload | resume | 定案（M0 探针 P2 实测：fork 档读源文件最后留痕，落盘 reason 维持 resume；执行记录见设计 §6.5） |
+| fork / reload | resume | 定案（fork 档读源文件最后留痕，落盘 reason 维持 resume） |
 
 存在 hash 基线（见下）且 prompt 未变时，首个 turn 不写（去重）；需写时（hash 已变）恒写 `resume`（无论 session_start reason）。
 
@@ -39,13 +39,12 @@ appendEntry("xyz:system-prompt", {
 
 1. **进程内 resume（stash）**：`session_before_switch.targetSessionFile` 直读目标 session 文件，取最后一条留痕
    entry 的 hash/version/fullText。switch 会 teardown 并重建 extension runtime，该基线经模块级 stash 跨 runtime 传递。
-2. **fork**：`session_start.previousSessionFile` 直读源 session 文件，取源文件最后一条留痕（D2 v5 定案——
-   常态 /fork 时点 fork 新文件未落盘，不可直读新文件；源文件缺失/未落盘/读取失败 → 视为无基线）。
+2. **fork**：`session_start.previousSessionFile` 直读源 session 文件，取源文件最后一条留痕（常态
+   /fork 时点 fork 新文件未落盘，不可直读新文件；源文件缺失/未落盘/读取失败 → 视为无基线）。
 3. **直读当前 session 文件**：`ctx.sessionManager.getSessionFile()` 直读 JSONL 最后一条留痕，覆盖 reload /
    重启直 spawn resume / new 兜底等没有 switch 事件的链路（文件不存在或无留痕 → 视为无基线）。
 
-原第三档「自持久化小文件 system-prompt-trace-baseline.json」已随 ext-simplify-02 删除——终态唯一持久化源 =
-session JSONL 自身；存量文件成为无读写方孤儿，可安全手动删除（含 `*.tmp_*` 残留）。
+唯一持久化源 = session JSONL 自身。
 
 三档都 miss（无任何基线）时兜底必写：首个 turn 无论 session_start reason 必写一条——
 startup/new → `initial`，resume/fork/reload → `resume`（宁可多写不可漏记）。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-system-prompt-trace",
-  "version": "0.1.7",
-  "description": "System prompt trace extension: appends xyz:system-prompt entries to the session JSONL whenever the effective system prompt is established or changes",
+  "version": "0.2.0",
+  "description": "System prompt trace extension: appends taiji:system-prompt entries to the session JSONL whenever the effective system prompt is established or changes",
   "type": "module",
   "main": "index.ts",
   "keywords": [
@@ -17,7 +17,7 @@
     "src/**/*.ts",
     "README.md"
   ],
-  "xyz-agent": {
+  "taiji": {
     "role": "taiji"
   },
   "pi": {
@@ -33,8 +33,8 @@
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.4.0",
-    "@zhushanwen/pi-extension-logger": "0.6.0"
+    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/pi-extension-logger": "0.6.1"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/__tests__/baseline.a12.test.ts

@@ -72,6 +72,8 @@ function makeHarness(initialPrompt: string, opts?: { noSessionFile?: boolean }):
 
 	const env: TraceEnv = {
 		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath),
+		// F1b：A12 聚焦基线恢复，不涉回落事实（回落专测在 a11 / wiring）
+		getPresetFallback: () => undefined,
 	};
 
 	const ctx: TraceContext = {

package/src/__tests__/index-wiring.test.ts

@@ -20,7 +20,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
+import { isSystemPromptTraceEntryData, PRESET_FALLBACK_ENV_KEYS, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
 import type { SystemPromptTraceEntryData } from "../types.js";
 
 // trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
@@ -337,6 +337,61 @@ describe("index.ts wiring SDK 契约", () => {
 		});
 	});
 
+	it("F1b wiring：process.env 两键齐备 → entry 带 presetFallback（from/to）；既有字段不削弱", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		process.env[PRESET_FALLBACK_ENV_KEYS.FROM] = "custom:gone-uuid";
+		process.env[PRESET_FALLBACK_ENV_KEYS.TO] = "builtin:full";
+		try {
+			ext(h.pi);
+			const ctx = createCtx(() => P1, "sess-w-fb");
+			await emit(h, "session_start", { type: "session_start", reason: "startup" }, ctx);
+			await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
+		} finally {
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.FROM];
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.TO];
+		}
+		expect(h.entries).toHaveLength(1);
+		expect(entryData(h, 0).presetFallback).toEqual({ from: "custom:gone-uuid", to: "builtin:full" });
+		expect(entryData(h, 0)).toMatchObject({
+			version: 1,
+			reason: "initial",
+			fullText: P1,
+			charCount: P1.length,
+			hash: computePromptHash(P1),
+		});
+	});
+
+	it("F1b wiring：env 未注入 / 两键为空串（runtime 显式清除）→ entry 不含 presetFallback（无假披露）", async () => {
+		const ext = await loadExtension();
+		// 态 1：未注入
+		delete process.env[PRESET_FALLBACK_ENV_KEYS.FROM];
+		delete process.env[PRESET_FALLBACK_ENV_KEYS.TO];
+		const hAbsent = createWiringHarness();
+		ext(hAbsent.pi);
+		const ctxAbsent = createCtx(() => P1, "sess-w-fb-absent");
+		await emit(hAbsent, "session_start", { type: "session_start", reason: "startup" }, ctxAbsent);
+		await emit(hAbsent, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctxAbsent);
+		expect(hAbsent.entries).toHaveLength(1);
+		expect(Object.prototype.hasOwnProperty.call(entryData(hAbsent, 0), "presetFallback")).toBe(false);
+
+		// 态 2：空串（runtime 未回落时写空串显式清除继承值）——不得当回落事实
+		process.env[PRESET_FALLBACK_ENV_KEYS.FROM] = "";
+		process.env[PRESET_FALLBACK_ENV_KEYS.TO] = "";
+		const hEmpty = createWiringHarness();
+		try {
+			ext(hEmpty.pi);
+			const ctxEmpty = createCtx(() => P1, "sess-w-fb-empty");
+			await emit(hEmpty, "session_start", { type: "session_start", reason: "startup" }, ctxEmpty);
+			await emit(hEmpty, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctxEmpty);
+		} finally {
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.FROM];
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.TO];
+		}
+		expect(hEmpty.entries).toHaveLength(1);
+		expect(Object.prototype.hasOwnProperty.call(entryData(hEmpty, 0), "presetFallback")).toBe(false);
+	});
+
 	it("getSystemPrompt 抛错 → handler 吞掉不写 entry（留痕是诊断旁路，不影响 agent 主流程）", async () => {
 		const ext = await loadExtension();
 		const h = createWiringHarness();

package/src/__tests__/trace.a11.test.ts

@@ -18,7 +18,7 @@ import { describe, expect, it } from "vitest";
 import { createSystemPromptTrace } from "../trace.js";
 import type { SystemPromptTrace, TraceContext, TraceEnv } from "../trace.js";
 import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
-import type { SystemPromptTraceEntryData, SwitchStash } from "../types.js";
+import type { PresetFallbackFact, SystemPromptTraceEntryData, SwitchStash } from "../types.js";
 
 // trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
 const computePromptHash = (text: string): string =>
@@ -37,13 +37,15 @@ interface Harness {
 	newLogic(): SystemPromptTrace;
 }
 
-function makeHarness(initialPrompt: string): Harness {
+function makeHarness(initialPrompt: string, presetFallback?: PresetFallbackFact): Harness {
 	const entries: SystemPromptTraceEntryData[] = [];
 	let prompt = initialPrompt;
 	const stash: SwitchStash = { pending: null };
 	// A11 不涉文件路径：三档基线全部 miss（直读 / fork prev 文件路径均不可读），隔离验证时机/去重/映射逻辑
 	const env: TraceEnv = {
 		readLastPromptFromFile: () => null,
+		// F1b：默认无回落事实；需要时经参数注入（进程 env 语义的 fake）
+		getPresetFallback: () => presetFallback,
 	};
 	const ctx: TraceContext = {
 		getSystemPrompt: () => prompt,
@@ -134,6 +136,34 @@ describe("A11 留痕时机与去重", () => {
 		expect(entry.parentVersionDiffSummary).toContain("+ [Available Models]");
 	});
 
+	it("F1b 模式回落事实：env 携带 from/to → 本进程每条 entry 均带 presetFallback（resume 快照与 change 一致），既有字段不削弱", () => {
+		const fact: PresetFallbackFact = { from: "custom:gone-uuid", to: "builtin:full" };
+		const h = makeHarness(P1, fact);
+		h.logic.onSessionStart("resume", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx); // v1 resume
+		h.setPrompt(P2);
+		h.logic.onTurnStart(h.ctx); // v2 change
+		expect(h.entries).toHaveLength(2);
+		expect(h.entries[0]?.presetFallback).toEqual(fact);
+		expect(h.entries[1]?.presetFallback).toEqual(fact);
+		// 既有形状与语义不受影响
+		expect(h.entries[0]).toMatchObject({
+			version: 1, reason: "resume", fullText: P1, charCount: P1.length, hash: computePromptHash(P1),
+		});
+		expect(h.entries[1]).toMatchObject({
+			version: 2, reason: "change", fullText: P2, charCount: P2.length, hash: computePromptHash(P2),
+		});
+	});
+
+	it("F1b 无回落（getPresetFallback → undefined）→ entry 无 presetFallback 字段（形状向后兼容）", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(1);
+		expect(h.entries[0]?.presetFallback).toBeUndefined();
+		expect(Object.prototype.hasOwnProperty.call(h.entries[0], "presetFallback")).toBe(false);
+	});
+
 	it("prompt 变回旧值再写 change v3（时间线保留真实历史，只对当前版本去重）", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);

package/src/baseline.ts

@@ -4,7 +4,7 @@
  *
  * readLastPromptFromSessionFile 是三档统一的读取入口：直读 session JSONL
  * （进程内 resume 的 targetSessionFile、fork 的 previousSessionFile、reload / 直启 resume
- * 的 getSessionFile() 目标文件），倒序找最后一条 xyz:system-prompt 留痕 entry。
+ * 的 getSessionFile() 目标文件），倒序找最后一条 taiji:system-prompt 留痕 entry。
  *
  * 所有函数不抛错：读失败返回 null——基线丢失的代价只是
  * 下次 resume 多写一条留痕（设计 D2 已接受），不允许影响 agent 主流程。
@@ -19,7 +19,7 @@ import type { PromptBaseline } from "./types.js";
 
 /**
  * 解析单行 session JSONL 为留痕 entry data（运行时 guard；任何形状不符 / JSON 损坏返回 null）。
- * pi 落盘形状：{"type":"custom","customType":"xyz:system-prompt","data":{...},...}
+ * pi 落盘形状：{"type":"custom","customType":"taiji:system-prompt","data":{...},...}
  * （session-manager.ts:1122 appendCustomEntry）。
  */
 function parseTraceEntryData(line: string): { hash: string; version: number; fullText: string } | null {

package/src/index.ts

@@ -19,6 +19,7 @@ import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 import { readLastPromptFromSessionFile } from "./baseline.js";
 import { createSystemPromptTrace } from "./trace.js";
 import type { TraceContext, TraceEnv } from "./trace.js";
+import { readPresetFallbackFromEnv } from "./types.js";
 import type { SwitchStash } from "./types.js";
 
 // 模块级单例：session_before_switch（旧 runtime）→ session_start（新 runtime）之间传递
@@ -45,6 +46,9 @@ export default function systemPromptTraceExtension(pi: ExtensionAPI): void {
 
 	const env: TraceEnv = {
 		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath),
+		// F1b（E4 trace 披露面）：模式回落事实由 runtime 经 spawn 出站 env 携带。
+		// 工厂调用时读一次（进程 env 生命期内不变）；未回落 → 空串 → undefined。
+		getPresetFallback: () => readPresetFallbackFromEnv(),
 	};
 
 	const logic = createSystemPromptTrace(env, switchStash);

package/src/trace.ts

@@ -20,6 +20,7 @@ const logger = getLogger("pi-system-prompt-trace");
 import { summarizePromptDiff } from "./diff.js";
 import { mapReasonForFirstWrite, SYSTEM_PROMPT_CUSTOM_TYPE } from "./types.js";
 import type {
+	PresetFallbackFact,
 	PromptBaseline,
 	SwitchStash,
 	SystemPromptTraceEntryData,
@@ -38,6 +39,13 @@ export interface TraceContext {
 /** 文件系统侧依赖（wiring 用真实 fs；测试注入临时目录实现）。 */
 export interface TraceEnv {
 	readLastPromptFromFile(filePath: string): PromptBaseline | null;
+	/**
+	 * 本次 pi 进程启动时的模式回落事实（F1b，E4 trace 披露面）；未回落 / 未注入 → undefined。
+	 *
+	 * 进程 env 在生命期内不变，故工厂构造时读一次即可；为空字符串（runtime 的「显式
+	 * 清除」形态）时同样返回 undefined——不得把空串当回落事实。
+	 */
+	getPresetFallback(): PresetFallbackFact | undefined;
 }
 
 export interface SystemPromptTrace {
@@ -65,6 +73,10 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 	let sessionStartReason: SessionStartEvent["reason"] | null = null;
 	let baseline: PromptBaseline | null = null;
 	let current: CurrentPrompt | null = null;
+	// F1b（设计 `mode-system-composer-density` §7.5 E4 trace 披露面）：
+	// 本次 pi 进程的模式回落事实由 spawn 出站 env 携带，进程生命期内恒定，构造时读一次。
+	// 未回落 / 未注入 → undefined，entry 的 presetFallback 字段不出现（既有形状向后兼容）。
+	const presetFallback = env.getPresetFallback();
 
 	const write = (
 		ctx: TraceContext,
@@ -84,6 +96,11 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 		if (parentFullText !== undefined) {
 			data.parentVersionDiffSummary = summarizePromptDiff(parentFullText, text);
 		}
+		// 回落事实随本进程写出的每条 entry 携带：本次 pi 运行确实以回落档启动，
+		// resume 快照与后续 change 同属该运行，披露一致（事件语义 = 本次运行口径）。
+		if (presetFallback !== undefined) {
+			data.presetFallback = presetFallback;
+		}
 		ctx.appendEntry(SYSTEM_PROMPT_CUSTOM_TYPE, data);
 	};
 

package/src/types.ts

@@ -8,13 +8,60 @@
 import { isRecord } from "@zhushanwen/pi-ext-guards";
 import type { SessionStartEvent } from "@earendil-works/pi-coding-agent";
 
-/** 留痕 entry 的 customType（xyz: 前缀 = xyz-agent 自定义命名空间）。 */
-export const SYSTEM_PROMPT_CUSTOM_TYPE = "xyz:system-prompt";
+/** 留痕 entry 的 customType（taiji: 前缀 = taiji 自定义命名空间）。 */
+export const SYSTEM_PROMPT_CUSTOM_TYPE = "taiji:system-prompt";
+
+/**
+ * 模式回落事实 env 名（字面量镜像 `packages/shared/src/constants.ts` 的
+ * `PRESET_FALLBACK_ENV_KEYS`）。
+ *
+ * extension 独立发布体系不依赖 `@taiji/shared`，只能按字面量镜像——单侧改名即断链
+ * （消息见 write 产出的 `presetFallback` 字段消失）。一致性由机器守卫断言：
+ * `.githooks/check_env_whitelist_sync.py` 规则 3 A8（漂移即红）。写入方 =
+ * `packages/runtime/src/services/session/launch-params.ts` 的 `buildPresetFallbackEnv`。
+ */
+export const PRESET_FALLBACK_ENV_KEYS = {
+	FROM: "TAIJI_PRESET_FALLBACK_FROM",
+	TO: "TAIJI_PRESET_FALLBACK_TO",
+} as const;
+
+/**
+ * 模式回落事实（F1b，设计 `mode-system-composer-density` §7.5 E4
+ * 的 trace 披露面）。
+ *
+ * 语义 = 本次 pi 进程启动时，sidecar 里的模式定义已不可得，runtime 已回落
+ * `builtin:full` 启动（工具面从模式的受限面弹回全工具）——记录在 trace entry 里，
+ * 事后审计从 `taiji:system-prompt` 即可得知「提示词为何变了」。
+ */
+export interface PresetFallbackFact {
+	/** 原（悬空）模式 id。 */
+	from: string;
+	/** 回落目标模式 id（现行恒 `builtin:full`）。 */
+	to: string;
+}
+
+/**
+ * 从进程 env 读取模式回落事实（wiring 侧唯一 env 读取点；trace.ts 逻辑经 DI 消费）。
+ *
+ * - FROM 非空 → 返回 `{ from, to }`（TO 缺失时给空串——形状稳定，不抛错）；
+ * - FROM 缺失 / 空串 → undefined（未回落，或未注入；空串是 runtime 的「显式清除」
+ *   语义，见 `buildPresetFallbackEnv`）。
+ *
+ * 不抛错：env 是外部输入，任何形态异常都退化为「无回落事实」，不阻断留痕。
+ */
+export function readPresetFallbackFromEnv(
+	env: NodeJS.ProcessEnv = process.env,
+): PresetFallbackFact | undefined {
+	const from = env[PRESET_FALLBACK_ENV_KEYS.FROM];
+	if (typeof from !== "string" || from === "") return undefined;
+	const to = env[PRESET_FALLBACK_ENV_KEYS.TO];
+	return { from, to: typeof to === "string" ? to : "" };
+}
 
 /** 落盘 reason 枚举（initial/resume/change，对齐 DSH request/header 语义，设计 D2）。 */
 export type TraceReason = "initial" | "resume" | "change";
 
-/** appendEntry("xyz:system-prompt", data) 的 data 形状（设计 §5 单元 1）。 */
+/** appendEntry("taiji:system-prompt", data) 的 data 形状（设计 §5 单元 1）。 */
 export interface SystemPromptTraceEntryData {
 	/** session 内单调递增（首条 1；有基线时续接基线版本 +1）。 */
 	version: number;
@@ -27,6 +74,12 @@ export interface SystemPromptTraceEntryData {
 	charCount: number;
 	/** 与上一版的行级 diff 摘要；首条留痕（无 parent）时缺省。 */
 	parentVersionDiffSummary?: string;
+	/**
+	 * 模式回落事实（F1b，E4 trace 披露面）：本次 pi 进程以「模式已删除 → 回落
+	 * builtin:full」启动时出现；未回落（正常启动）时**字段不出现**——既有 entry
+	 * 形状向后兼容。见 `PresetFallbackFact`。
+	 */
+	presetFallback?: PresetFallbackFact;
 }
 
 /** 跨重启恢复的 hash 基线（三档解析统一产自 session JSONL 留痕 entry 直读）。 */
@@ -55,6 +108,12 @@ export function isSystemPromptTraceEntryData(value: unknown): value is SystemPro
 	const reason = value["reason"];
 	const fullText = value["fullText"];
 	const charCount = value["charCount"];
+	// 可选字段（F1b）：存在时须为 { from: string, to: string }；缺失合法（向后兼容）
+	const presetFallback = value["presetFallback"];
+	if (presetFallback !== undefined) {
+		if (!isRecord(presetFallback)) return false;
+		if (typeof presetFallback["from"] !== "string" || typeof presetFallback["to"] !== "string") return false;
+	}
 	return (
 		typeof version === "number" &&
 		Number.isFinite(version) &&