@zhushanwen/pi-cache-probe 0.1.3 → 0.3.0

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.0",
   "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",

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

@@ -11,7 +11,7 @@
 import { createHash } from "node:crypto";
 
 /** 指纹 hash 长度（hex 字符数）。 */
-export const HASH_LEN = 16;
+const HASH_LEN = 16;
 
 /** entry schema 版本（v2：短 hash + 增量 entry）。 */
 export const SCHEMA_VERSION = 2;
@@ -46,7 +46,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 /** 递归 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(",") + "]";
@@ -89,7 +89,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

@@ -13,8 +13,8 @@
  *    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 诊断，绝不阻塞请求。