@zhushanwen/pi-system-prompt-trace 0.1.2 → 0.1.4

package/README.md

@@ -35,14 +35,16 @@ appendEntry("xyz:system-prompt", {
 
 存在任一 hash 基线（见下）时，首个 turn 写 `resume`（无论 session_start reason）。
 
-## 跨重启 hash 基线三路径（优先级从高到低）
+## 跨重启 hash 基线四路径（优先级从高到低，权威实现见 `src/trace.ts` onSessionStart）
 
-1. **进程内 resume**：`session_before_switch.targetSessionFile` 直读目标 session 文件，取最后一条留痕 entry 的
-   hash/version/fullText。switch 会 teardown 并重建 extension runtime，该基线经模块级 stash 跨 runtime 传递。
-2. **app 重启直 spawn resume**：`<agentDir>/system-prompt-trace-baseline.json` 自持久化小文件（sessionId →
-   hash/version），原子写入，保留最近 64 个 session。
-3. **兜底**：两路都读不到且 reason=resume → 必写一条（宁可多写不可漏记）。
+1. **进程内 resume（stash）**：`session_before_switch.targetSessionFile` 直读目标 session 文件，取最后一条留痕
+   entry 的 hash/version/fullText。switch 会 teardown 并重建 extension runtime，该基线经模块级 stash 跨 runtime 传递。
+2. **fork**：`session_start.previousSessionFile` 直读源 session 文件（暂定语义，待 P2 探针实测定）。
+3. **自持久化小文件**：`<agentDir>/system-prompt-trace-baseline.json`（sessionId → hash/version），原子写入，
+   保留最近 64 个 session。app 重启直 spawn resume / reload 等没有 switch 事件的链路由此恢复基线。
+4. **兜底必写**：三路都 miss（无任何基线）时，首个 turn 无论 session_start reason 必写一条——
+   startup/new → `initial`，resume/fork/reload → `resume`（宁可多写不可漏记）。
 
 ## 注册状态
 
-本包尚未注册进 `packages/shared/src/mandatory-extensions.json`（后续单元处理；feature tier，可禁不可卸）。
+已注册进 `packages/shared/src/mandatory-extensions.json`（feature tier，可禁不可卸）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt-trace",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "System prompt trace extension: appends xyz:system-prompt entries to the session JSONL whenever the effective system prompt is established or changes",
   "type": "module",
   "main": "index.ts",
@@ -26,14 +26,14 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1"
+    "@earendil-works/pi-coding-agent": "^0.84.4"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.3.0"
+    "@zhushanwen/pi-extension-logger": "0.4.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

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

@@ -1,11 +1,12 @@
 /**
  * A12 hash 基线跨重启恢复（spec：.cw-specs/trace-ext.json；设计 D2 复审 N2 / plan §2.1）。
  *
- * 三路径（优先级从高到低）：
+ * 四路径（优先级从高到低，口径同 trace.ts onSessionStart）：
  * 1. 进程内 resume：session_before_switch.targetSessionFile 直读目标文件取上一版 hash
  *    （switch 重建 extension runtime，基线经模块级 stash 传递——用「新闭包 + 共享 stash」模拟）
- * 2. app 重启直 spawn resume：agentDir 自持久化小文件（此链路无 switch 事件、reason=startup）
- * 3. 兜底：两路都读不到 → resume 必写一条（宁可多写不可漏记）
+ * 2. fork：previousSessionFile 直读源 session 文件（暂定语义，本文件未覆盖）
+ * 3. app 重启直 spawn resume：agentDir 自持久化小文件（此链路无 switch 事件、reason=startup）
+ * 4. 兜底：三路都读不到 → 任意 reason 必写一条（startup/new→initial，resume/fork/reload→resume）
  *
  * 用真实临时目录 + 真实 fs 函数（非 mock 投影）；appendEntry 同步模拟 pi appendCustomEntry
  * 的落盘形状（session-manager.ts）。
@@ -157,7 +158,7 @@ describe("A12 hash 基线跨重启恢复", () => {
 		expect(h.entries[1]?.parentVersionDiffSummary).toContain("+1 -0 lines");
 	});
 
-	it("路径 2（app 重启直 spawn）：自持久化小文件命中且 hash 未变 → 不写（reason=startup、无 switch 事件）", () => {
+	it("路径 3（app 重启直 spawn）：自持久化小文件命中且 hash 未变 → 不写（reason=startup、无 switch 事件）", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);
 		h.logic.onTurnStart(h.ctx); // v1 initial + 基线小文件已写
@@ -174,7 +175,7 @@ describe("A12 hash 基线跨重启恢复", () => {
 		expect(h.entries).toHaveLength(1);
 	});
 
-	it("路径 2（app 重启直 spawn）：基线命中但 prompt 已变 → 写 resume v2（无 parent 全文，diff 摘要缺省）", () => {
+	it("路径 3（app 重启直 spawn）：基线命中但 prompt 已变 → 写 resume v2（无 parent 全文，diff 摘要缺省）", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);
 		h.logic.onTurnStart(h.ctx); // v1
@@ -189,7 +190,7 @@ describe("A12 hash 基线跨重启恢复", () => {
 		expect(h.entries[1]?.parentVersionDiffSummary).toBeUndefined();
 	});
 
-	it("路径 3（兜底）：两路基线都读不到且 reason=resume → 必写一条", () => {
+	it("路径 4（兜底）：三路基线都读不到且 reason=resume → 必写一条", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("resume", undefined, h.ctx); // 无 stash、无小文件
 		h.logic.onTurnStart(h.ctx);

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

@@ -6,6 +6,8 @@
  *   从而验证 wiring 把基线小文件真的落在 getAgentDir() 下
  * - pi 用 Proxy 假体：捕获 on 注册的 handler 与 appendEntry 落点；handler 以 SDK 双参契约
  *   (event, ctx) 驱动；ctx 只需 index.ts 实际消费的字段（getSystemPrompt + sessionManager.getSessionId）
+ * - @zhushanwen/pi-extension-logger mock 三导出（getLogger / createLogger / setPiHandle），
+ *   setPiHandle 捕获 factory 注入（D3 接线契约），logger 方法收集供吞错断言
  * - switchStash 是模块级单例：beforeEach vi.resetModules 隔离用例；同 it 内二次 dynamic import
  *   模拟「switch 重建 extension runtime + 同进程模块缓存延续」的真实链路
  */
@@ -25,13 +27,14 @@ import type { SystemPromptTraceEntryData } from "../types.js";
 const P1 = "wiring prompt\nline-1";
 const P2 = "wiring prompt\nline-1\nline-2-added";
 
-const { loggerMock } = vi.hoisted(() => {
+const { loggerMock, setPiHandleMock } = vi.hoisted(() => {
 	const mock = { debug: vi.fn(), warn: vi.fn(), error: vi.fn() };
-	return { loggerMock: mock };
+	return { loggerMock: mock, setPiHandleMock: vi.fn() };
 })
 vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	getLogger: () => loggerMock,
 	createLogger: () => loggerMock,
+	setPiHandle: setPiHandleMock,
 }))
 
 const agentDirRef = vi.hoisted(() => ({ current: "" }));
@@ -138,6 +141,18 @@ describe("index.ts wiring SDK 契约", () => {
 		]);
 	});
 
+	it("factory 调用 setPiHandle(pi) 注入日志通道（缺注入时 logger.error 的 appendEntry 通道是 no-op，生产完全静默）", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		// hoisted mock 不随 resetModules 清调用历史，先清再驱动，隔离其他用例的累计调用
+		setPiHandleMock.mockClear();
+		ext(h.pi);
+		expect(setPiHandleMock).toHaveBeenCalledTimes(1);
+		// pi 是 Proxy 假体，深度相等比较不可靠，用引用相等断言
+		const injected = setPiHandleMock.mock.calls[0]?.[0];
+		expect(injected).toBe(h.pi);
+	});
+
 	it("startup（无 previousSessionFile）→ 首 turn 写 initial v1（appendEntry 形状 + 基线落 getAgentDir）；prompt 变化写 change v2 带 diff 摘要", async () => {
 		const ext = await loadExtension();
 		const h = createWiringHarness();

package/src/baseline.ts

@@ -1,10 +1,11 @@
 /**
- * 跨重启基线的文件系统侧实现（设计 D2 三路径中的路径 1/2 的读与路径 2 的写）。
+ * 跨重启基线的文件系统侧实现（四路径口径，见 trace.ts onSessionStart 解析优先级：
+ * 路径 1 stash 直读 / 路径 2 fork prev 直读的读，与路径 3 自持久化小文件的读和写）。
  *
  * - readLastPromptFromSessionFile：直读 session JSONL（进程内 resume 的 targetSessionFile、
  *   fork 暂定的 previousSessionFile），倒序找最后一条 xyz:system-prompt 留痕 entry。
- * - readPersistedBaseline / writePersistedBaseline：dataDir 自持久化小文件
- *   （app 重启直 spawn resume 时唯一可用的基线来源），原子写入。
+ * - readPersistedBaseline / writePersistedBaseline：agentDir 自持久化小文件
+ *   （app 重启直 spawn resume / reload 等无 switch 事件链路的唯一基线来源），原子写入。
  *
  * 所有函数不抛错：读失败返回 null、写失败 logger.error 后静默——基线丢失的代价只是
  * 下次 resume 多写一条留痕（设计 D2 已接受），不允许影响 agent 主流程。
@@ -148,8 +149,9 @@ export function writePersistedBaseline(
 			// 条目；对齐 quota-providers atomicWriteJson）；清理失败不掩盖原错误
 			try {
 				if (existsSync(tmpPath)) unlinkSync(tmpPath);
-			} catch {
+			} catch (cleanupErr) {
 				// 清理失败仅残留一个小文件，原错误优先上抛
+				void cleanupErr;
 			}
 			throw err;
 		}

package/src/index.ts

@@ -10,6 +10,8 @@ import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import { setPiHandle } from "@zhushanwen/pi-extension-logger";
+
 import {
 	BASELINE_FILENAME,
 	readLastPromptFromSessionFile,
@@ -53,6 +55,12 @@ function toTraceContext(pi: ExtensionAPI, ctx: ExtensionContext): TraceContext {
 }
 
 export default function systemPromptTraceExtension(pi: ExtensionAPI): void {
+	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle）。缺此注入时
+	// trace/baseline 中 logger.error 的 appendEntry 通道是 no-op，生产默认完全静默——
+	// 此前全包从未注入（文本-实现漂移审查 D3 补接线，恢复注释声称的持久化语义）。
+	// 测试环境无真实 globalPi 消费方时调用本身安全（存引用，不触发 appendEntry）。
+	setPiHandle(pi);
+
 	const baselineFilePath = join(getAgentDir(), BASELINE_FILENAME);
 
 	const env: TraceEnv = {

package/src/trace.ts

@@ -84,7 +84,7 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 			data.parentVersionDiffSummary = summarizePromptDiff(parentFullText, text);
 		}
 		ctx.appendEntry(SYSTEM_PROMPT_CUSTOM_TYPE, data);
-		// 落盘成功后才刷新自持久化基线（app 重启直 spawn resume 的唯一基线来源，设计 D2 路径 2）
+		// 落盘成功后才刷新自持久化基线（app 重启直 spawn resume / reload 的唯一基线来源，设计 D2 路径 3）
 		env.writePersistedBaseline(ctx.getSessionId(), hash, version);
 	};
 
@@ -92,7 +92,7 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 		onSessionStart(reason, previousSessionFile, ctx) {
 			sessionStartReason = normalizeSessionStartReason(reason);
 			current = null;
-			// 基线解析（设计 D2 跨重启三路径，优先级从高到低）：
+			// 基线解析（设计 D2 跨重启四路径，优先级从高到低）：
 			// 1. session_before_switch 直读目标文件（进程内 resume；stash 为模块级单例，跨 runtime 传递）
 			// 2. fork 的 previousSessionFile 直读【暂定语义，待 P2 实测定】
 			// 3. agentDir 自持久化小文件（app 重启直 spawn resume / reload——这两种链路没有 switch 事件）

package/src/types.ts

@@ -35,7 +35,7 @@ export interface PromptBaseline {
 	version: number;
 	/** 从 session 文件留痕 entry 直读时有值（可生成 diff 摘要）；自持久化小文件只有 hash+version。 */
 	fullText?: string;
-	/** 基线来源（三路径，见 trace.ts onSessionStart 的解析优先级）。 */
+	/** 基线来源（四路径口径，见 trace.ts onSessionStart 的解析优先级）。 */
 	source: "target-file" | "previous-session-file" | "persisted";
 }