@zhushanwen/pi-cache-probe 0.1.3 → 0.3.1

package/README.md

@@ -11,7 +11,7 @@
 ## entry schema v2（数据量精简，长期采集友好）
 
 - hash 为 sha256 前 16 hex；**baseline entry** 存全量 9 hash + cwd（约 250B）；**normal entry** 只存变化项增量（约 120B）；无变化 turn 零写入
-- `seq` = 进程内 turn 计数（无论写不写 entry 都递增），跳跃 = 中间有无变化 turn 或漏记
+- `seq` = 进程内 before_agent_start 触发计数，随 entry 落盘供人工排序诊断；当前无自动消费方（analyze.py 不读 seq）
 
 ## 挂载方式（长期采集）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-cache-probe",
-  "version": "0.1.3",
+  "version": "0.3.1",
   "description": "Zero-impact Pi probe extension — records system prompt / tools fingerprint hashes into session custom entries (only on change) to attribute LLM prompt-cache miss to prefix drift vs server-side eviction.",
   "type": "module",
   "main": "src/index.ts",
@@ -25,6 +25,9 @@
     "index.ts",
     "analyze.py"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-ext-guards": "0.4.0"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"

package/src/__tests__/fingerprint.test.ts

@@ -1,62 +1,57 @@
 // 测试框架：vitest
 // 运行命令：npx vitest run src/__tests__/fingerprint.test.ts
 //
-// 指纹纯函数层测试：stableStringify 稳定性 / hash 长度 / extractSystem 四口径 /
-// sentToolsOf / diffFingerprints / buildProbeEntry 的 baseline-全量、normal-增量、无变化-null。
+// 指纹纯函数层测试（经公有面 hashOf / buildProbeEntry / extractSystem / sentToolsOf）：
+// hash 稳定性（key 序 / undefined→null / 数组有序）、hash 为 16 hex、
+// buildProbeEntry 的 baseline-全量、normal-增量、无变化-null。
 
 import { describe, expect, it } from "vitest";
 
 import {
 	buildProbeEntry,
-	diffFingerprints,
 	extractSystem,
-	HASH_LEN,
 	hashOf,
 	sentToolsOf,
-	stableStringify,
 	type Fingerprints,
 } from "../fingerprint";
 
+// hash 为 16 hex 是 entry schema v2 的契约（fingerprint.ts 头注释），硬编码断言
+const HASH_HEX_LEN = 16;
+
 const fp = (over: Partial<Fingerprints> = {}): Fingerprints => ({
-	spFull: "a".repeat(HASH_LEN),
-	toolsSent: "b".repeat(HASH_LEN),
-	contextFiles: "c".repeat(HASH_LEN),
-	skills: "d".repeat(HASH_LEN),
-	toolsList: "e".repeat(HASH_LEN),
-	toolsReg: "f".repeat(HASH_LEN),
-	append: "0".repeat(HASH_LEN),
-	guidelines: "1".repeat(HASH_LEN),
-	customPrompt: "2".repeat(HASH_LEN),
+	spFull: "a".repeat(HASH_HEX_LEN),
+	toolsSent: "b".repeat(HASH_HEX_LEN),
+	contextFiles: "c".repeat(HASH_HEX_LEN),
+	skills: "d".repeat(HASH_HEX_LEN),
+	toolsList: "e".repeat(HASH_HEX_LEN),
+	toolsReg: "f".repeat(HASH_HEX_LEN),
+	append: "0".repeat(HASH_HEX_LEN),
+	guidelines: "1".repeat(HASH_HEX_LEN),
+	customPrompt: "2".repeat(HASH_HEX_LEN),
 	...over,
 });
 
-describe("stableStringify", () => {
-	it("key 顺序不同输出相同（防假变化的核心保证）", () => {
-		expect(stableStringify({ a: 1, b: { d: 4, c: 3 } })).toBe(stableStringify({ b: { c: 3, d: 4 }, a: 1 }));
-	});
-
-	it("undefined 归一为 null", () => {
-		expect(stableStringify(undefined)).toBe("null");
-		expect(stableStringify({ x: undefined })).toBe(stableStringify({ x: null }));
-	});
-
-	it("数组保序、原始值直译", () => {
-		expect(stableStringify([2, 1])).not.toBe(stableStringify([1, 2]));
-		expect(stableStringify("s")).toBe('"s"');
-		expect(stableStringify(3)).toBe("3");
-	});
-});
-
-describe("hashOf", () => {
-	it(`hash 为 ${HASH_LEN} hex 字符且同输入同输出`, () => {
+describe("hashOf（stable stringify 语义经公有面断言）", () => {
+	it("hash 为 16 hex 字符且同输入同输出", () => {
 		const h = hashOf({ a: 1 });
-		expect(h).toMatch(/^[0-9a-f]{16}$/);
+		expect(h).toMatch(new RegExp(`^[0-9a-f]{${HASH_HEX_LEN}}$`));
 		expect(hashOf({ a: 1 })).toBe(h);
 		expect(hashOf({ b: 1 })).not.toBe(h);
 	});
 
-	it("key 顺序不影响 hash", () => {
+	it("key 顺序不影响 hash（防假变化的核心保证，嵌套对象同）", () => {
 		expect(hashOf({ a: 1, b: 2 })).toBe(hashOf({ b: 2, a: 1 }));
+		expect(hashOf({ a: 1, b: { d: 4, c: 3 } })).toBe(hashOf({ b: { c: 3, d: 4 }, a: 1 }));
+	});
+
+	it("undefined 归一为 null（与显式 null 同 hash）", () => {
+		expect(hashOf(undefined)).toBe(hashOf(null));
+		expect(hashOf({ x: undefined })).toBe(hashOf({ x: null }));
+	});
+
+	it("数组保序、原始值类型不混淆", () => {
+		expect(hashOf([2, 1])).not.toBe(hashOf([1, 2]));
+		expect(hashOf("3")).not.toBe(hashOf(3));
 	});
 });
 
@@ -79,7 +74,7 @@ describe("extractSystem（payload 四口径）", () => {
 		]);
 	});
 
-	it("Google：顶层 systemInstruction 对象", () => {
+	it("伪造对象形态：顶层 systemInstruction（实装恒传 string，仅测试构造可达）", () => {
 		expect(extractSystem({ systemInstruction: { role: "system", parts: [] } })).toEqual({
 			role: "system",
 			parts: [],
@@ -101,10 +96,18 @@ describe("sentToolsOf", () => {
 	});
 });
 
-describe("diffFingerprints / buildProbeEntry", () => {
-	it("diff 只报变化项", () => {
-		expect(diffFingerprints(fp({ contextFiles: "x".repeat(HASH_LEN) }), fp())).toEqual(["contextFiles"]);
-		expect(diffFingerprints(fp(), null)).toEqual([]);
+describe("buildProbeEntry（diff 语义经 changed 数组断言）", () => {
+	it("diff 只报变化项（changed 数组 + 增量 h）", () => {
+		const e = buildProbeEntry(
+			fp({ contextFiles: "x".repeat(HASH_HEX_LEN), skills: "y".repeat(HASH_HEX_LEN) }),
+			fp(),
+			{ seq: 3, needsBaseline: false, startReason: null, cwd: "/w" },
+		);
+		expect(e?.changed).toEqual(["contextFiles", "skills"]);
+		expect(e?.h).toEqual({
+			contextFiles: "x".repeat(HASH_HEX_LEN),
+			skills: "y".repeat(HASH_HEX_LEN),
+		});
 	});
 
 	it("baseline：全量 hash + changed ['*'] + cwd + startReason", () => {
@@ -123,13 +126,13 @@ describe("diffFingerprints / buildProbeEntry", () => {
 
 	it("normal：只存变化项（增量），不带 cwd", () => {
 		const last = fp();
-		const cur = fp({ contextFiles: "x".repeat(HASH_LEN) });
+		const cur = fp({ contextFiles: "x".repeat(HASH_HEX_LEN) });
 		const e = buildProbeEntry(cur, last, { seq: 3, needsBaseline: false, startReason: null, cwd: "/w" });
 		expect(e).toEqual({
 			v: 2,
 			seq: 3,
 			changed: ["contextFiles"],
-			h: { contextFiles: "x".repeat(HASH_LEN) },
+			h: { contextFiles: "x".repeat(HASH_HEX_LEN) },
 		});
 	});
 

package/src/fingerprint.ts

@@ -10,8 +10,10 @@
 
 import { createHash } from "node:crypto";
 
+import { isRecord } from "@zhushanwen/pi-ext-guards";
+
 /** 指纹 hash 长度（hex 字符数）。 */
-export const HASH_LEN = 16;
+const HASH_LEN = 16;
 
 /** entry schema 版本（v2：短 hash + 增量 entry）。 */
 export const SCHEMA_VERSION = 2;
@@ -41,12 +43,8 @@ export interface ProbeEntryData {
 	error?: string;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object";
-}
-
 /** 递归 sort keys 的稳定序列化（undefined 归一为 null，防 key 顺序抖动产生假变化）。 */
-export function stableStringify(value: unknown): string {
+function stableStringify(value: unknown): string {
 	if (value === undefined) return "null";
 	if (value === null || typeof value !== "object") return JSON.stringify(value);
 	if (Array.isArray(value)) return "[" + value.map(stableStringify).join(",") + "]";
@@ -63,7 +61,12 @@ export function hashOf(value: unknown): string {
  *  - OpenAI 兼容：messages 内 role 为 system 或 developer
  *    （pi 源码 ai/src/api/openai-completions.ts 的 useDeveloperRole 分支）
  *  - Anthropic：顶层 system（数组）
- *  - Google：顶层 systemInstruction（对象）
+ *  - Google：顶层字段 systemInstruction 为对象形态——仅手工伪造的输入可达：
+ *    pi-ai 0.84.4 实装（google-generative-ai.js:294 / google-vertex.js:368）恒传
+ *    string（sanitizeSurrogates(context.systemPrompt)），isRecord 分支对 string
+ *    恒不命中，故实装流量下 Google 侧返回 null（spFull 观测恒 no-system）。
+ *    归因是「提取只认对象形态」而非「Google 请求没有 system」，勿把下方
+ *    isRecord(systemInstruction) 分支误读为 Google 口径主通路。
  */
 export function extractSystem(payload: unknown): unknown | null {
 	if (!isRecord(payload)) return null;
@@ -89,7 +92,7 @@ export function sentToolsOf(payload: unknown): unknown[] | null {
 	return Array.isArray(tools) ? tools : null;
 }
 
-export function diffFingerprints(cur: Fingerprints, last: Fingerprints | null): FingerprintKey[] {
+function diffFingerprints(cur: Fingerprints, last: Fingerprints | null): FingerprintKey[] {
 	if (last === null) return [];
 	return (Object.keys(cur) as FingerprintKey[]).filter((k) => last[k] !== cur[k]);
 }

package/src/index.ts

@@ -9,18 +9,21 @@
  *  - before_agent_start（每 turn 1 次）：算 7 个输入侧 hash 暂存 pending
  *    （systemPromptOptions 各字段 + getAllTools 注册表）
  *  - before_provider_request（每笔 LLM 请求，仅消费 turn 首笔）：从最终 payload
- *    提取 spFull（system 消息，兼容 system/developer/anthropic/google 口径）与
+ *    提取 spFull（system 消息，兼容 system/developer/anthropic/google 口径；
+ *    google 口径实装流量恒 no-system——pi-ai 恒传 string，该分支仅手工伪造
+ *    对象输入可达，详见 fingerprint.ts extractSystem 注释）与
  *    toolsSent（tools 数组），与 pending 合并对比，变化/基线时 appendEntry
  *  - agent_end：turn 内无 provider 请求则丢弃 pending（无请求即无归因价值）
  *
- * seq = 进程内 before_agent_start 触发计数（无论是否写 entry 都递增），
- * 脚本靠 seq 跳跃区分「无变化 turn」与「漏记」。
+ * seq = 进程内 before_agent_start 触发计数，随 entry 落盘供人工排序诊断；
+ * 当前无自动消费方（analyze.py 不读 seq）。
  *
  * Fail-safe：handler 全程捕获，异常时写 error entry（缺口可见非静默）并重置为
  * 需基线状态；appendEntry 自身失败仅 stderr 诊断，绝不阻塞请求。
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 import {
 	buildProbeEntry,
@@ -60,12 +63,12 @@ export default function (pi: ExtensionAPI): void {
 			// 输入侧 7 hash 计算在 fingerprint.ts 纯函数层（handler 只做编排与 fail-safe）
 			pending = computePendingFingerprint(event?.systemPromptOptions, pi.getAllTools());
 		} catch (err) {
-			stderr(`before_agent_start failed: ${err instanceof Error ? err.message : String(err)}`);
+			stderr(`before_agent_start failed: ${toErrorMessage(err)}`);
 			pending = null;
 			try {
-				pi.appendEntry(CUSTOM_TYPE, { v: SCHEMA_VERSION, seq, error: String(err instanceof Error ? err.message : err) });
+				pi.appendEntry(CUSTOM_TYPE, { v: SCHEMA_VERSION, seq, error: toErrorMessage(err) });
 			} catch (appendErr) {
-				stderr(`appendEntry failed: ${appendErr instanceof Error ? appendErr.message : String(appendErr)}`);
+				stderr(`appendEntry failed: ${toErrorMessage(appendErr)}`);
 			}
 			needsBaseline = true;
 		}
@@ -88,12 +91,12 @@ export default function (pi: ExtensionAPI): void {
 			last = cur;
 			needsBaseline = false;
 		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
+			const msg = toErrorMessage(err);
 			stderr(`before_provider_request failed: ${msg}`);
 			try {
 				pi.appendEntry(CUSTOM_TYPE, { v: SCHEMA_VERSION, seq, error: msg });
 			} catch (appendErr) {
-				stderr(`appendEntry failed: ${appendErr instanceof Error ? appendErr.message : String(appendErr)}`);
+				stderr(`appendEntry failed: ${toErrorMessage(appendErr)}`);
 			}
 			needsBaseline = true;
 		}