@zhushanwen/pi-cache-probe 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @zhushanwen/pi-cache-probe
+
+前缀稳定性长期数据采集 extension（设计文档：`docs/todo/cache-probe-design.md`）。零行为影响：只在 system prompt / tools 指纹变化时向 session JSONL 写 `cache-probe` custom entry（不进 LLM 上下文），配合 `analyze.py` 把 turn 首笔 cache miss 归因为「前缀变化（可修）」vs「服务端淘汰（不可修）」。
+
+## 组成
+
+- `src/index.ts` — 探针工厂（9 个指纹 hash：7 个输入侧来自 `systemPromptOptions` + `getAllTools()`，`spFull`/`toolsSent` 来自 `before_provider_request` 的最终 payload）
+- `src/fingerprint.ts` — 指纹纯函数层（stable stringify / hash / entry 构建）
+- `analyze.py` — 归因分析脚本（只读，单数据源扫 session 文件）
+
+## entry schema v2（数据量精简，长期采集友好）
+
+- hash 为 sha256 前 16 hex；**baseline entry** 存全量 9 hash + cwd（约 250B）；**normal entry** 只存变化项增量（约 120B）；无变化 turn 零写入
+- `seq` = 进程内 turn 计数（无论写不写 entry 都递增），跳跃 = 中间有无变化 turn 或漏记
+
+## 挂载方式（长期采集）
+
+dev-link 本地源码（live edit，推荐日常使用）：
+
+```bash
+# 见 .agents/skills/dev-link/；或直接用 pi 指定入口
+pi --extension <repo>/extensions/cache-probe/index.ts "<prompt>"
+pi --continue --extension <repo>/extensions/cache-probe/index.ts "<prompt>"
+```
+
+探针经 `--extension` 加载位于 extension 链头（pi 固定顺序），但 spFull/toolsSent 从 `before_provider_request` 的最终请求体提取，是 LLM 实际收到的前缀，不受链位置影响。
+
+## 归因分析
+
+```bash
+python3 extensions/cache-probe/analyze.py ~/.pi/agent/sessions ~/.xyz-agent/pi/sessions
+```
+
+输出五部分：扫描概览 / 命中率基线 / 归因矩阵 / 进程边界漂移 / GO-NO-GO 决策建议。
+
+## 已知限制（实测查明）
+
+- pi CLI 启动路径（`--session` / `--continue`）的 session_start reason 恒为 `startup`（`resume` 仅运行时 switch session 出现）——跨进程识别靠 baseline 标记 + 时间戳 gap，漂移检测靠 hash 对比，均不受影响。
+- 同进程内修改 AGENTS.md 不进 system prompt（pi 启动快照），contextFiles 漂移只出现在跨进程边界——pi 的行为，不是探针缺陷。
+- 真实环境实测发现：extension 链（model-switch / subagent-workflow 等）存在每 turn 级的 system prompt 动态注入，由 spFull 单独捕获——这正是它存在的价值。
+
+## 日常维护
+
+- 校验：`cd extensions/cache-probe && pnpm typecheck && pnpm test`（或仓库级 `pnpm extensions:typecheck && pnpm extensions:test`）
+- 每日检查：跑一次 analyze.py，确认 `sessions_with_probe` 增长、`error entries` 为 0 或已知原因
+- 采集满 200 turn 后 analyze.py 第 5 部分给出快照方案 GO/NO-GO 倾向；结论与后续动作记录回设计文档

package/analyze.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""cache-probe 归因分析脚本（设计文档 docs/todo/cache-probe-design.md §7.2）。
+
+输入一个或多个 sessions 目录，输出：
+  1. 扫描概览（含 error entry / 畸形行计数，失败要出声）
+  2. 命中率基线（与设计文档 §3.1 同口径，供交叉验证）
+  3. 归因矩阵：gap<30min + 模型未切换 的 turn 首笔 miss，按前缀变化与否分档
+  4. 进程边界（baseline entry）前后指纹漂移统计
+  5. 快照方案 GO/NO-GO 决策建议
+
+entry schema v2：normal entry 只存变化项（增量），本脚本回放合并为全量指纹。
+
+用法：python3 extensions/cache-probe/analyze.py ~/.pi/agent/sessions [--since 2026-08-01]
+只读，不修改任何文件。
+"""
+import argparse
+import json
+import os
+import sys
+from collections import defaultdict
+from datetime import datetime
+
+SKIP_PAT = ("var-folders", "private-tmp")
+GAP_BUCKETS = [(0, 300, "a.<5min"), (300, 1800, "b.5-30min"),
+               (1800, 43200, "c.30min-12h"), (43200, float("inf"), "d.>12h")]
+
+
+def parse_ts(s):
+    if not s:
+        return None
+    for fmt in ("%Y-%m-%dT%H:%M:%S.%f%z", "%Y-%m-%dT%H:%M:%S%z"):
+        try:
+            return datetime.strptime(s.replace("Z", "+0000"), fmt).timestamp()
+        except ValueError:
+            continue
+    return None
+
+
+def bucket_of(sec):
+    for lo, hi, name in GAP_BUCKETS:
+        if lo <= sec < hi:
+            return name
+    return None
+
+
+def is_real_user(msg):
+    c = msg.get("content")
+    return isinstance(c, list) and any(b.get("type") == "text" for b in c)
+
+
+def iter_session_files(roots, since_ts):
+    for root in roots:
+        if not os.path.isdir(root):
+            print(f"[WARN] 目录不存在，跳过：{root}")
+            continue
+        for dirpath, _dirs, files in os.walk(root):
+            if any(p in dirpath for p in SKIP_PAT):
+                continue
+            for fn in files:
+                if not fn.endswith(".jsonl"):
+                    continue
+                path = os.path.join(dirpath, fn)
+                try:
+                    if since_ts and os.path.getmtime(path) < since_ts:
+                        continue
+                except OSError:
+                    continue
+                yield path
+
+
+def load_entries(path, counters):
+    entries = []
+    try:
+        with open(path, encoding="utf-8") as fp:
+            for line in fp:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    counters["malformed_lines"] += 1
+    except OSError:
+        counters["unreadable_files"] += 1
+        return []
+    return entries
+
+
+def main():
+    ap = argparse.ArgumentParser(description="cache-probe 归因分析")
+    ap.add_argument("roots", nargs="+", help="sessions 目录（可多个）")
+    ap.add_argument("--since", default=None, help="只分析 mtime 在该日期之后的 session（YYYY-MM-DD）")
+    args = ap.parse_args()
+    since_ts = datetime.strptime(args.since, "%Y-%m-%d").timestamp() if args.since else 0
+
+    counters = defaultdict(int)
+    turn_rows = []          # (model, gap_bucket, model_chg, think_chg, prefix_chg, parts, cr, miss)
+    baseline_pairs = []     # (start_reason, changed_parts)
+    files = list(iter_session_files(args.roots, since_ts))
+    counters["sessions"] = len(files)
+
+    for path in files:
+        entries = load_entries(path, counters)
+        if not entries:
+            continue
+        current_hashes = None
+        prev_snapshot = None
+        seen_user_turn = False
+        # 切换标记作用域 = 自上一条真实用户发言以来的变化；user 发言时冻结到该 turn，
+        # 防止「无 LLM 请求的 turn」把标记泄漏到下一 turn（保守低估样本方向的 bug）
+        pending_model = pending_think = False
+        turn_model_chg = turn_think_chg = False
+        last_ts = None
+        gap_bucket = "new"
+        seen_first = False
+        has_probe_turn = False
+        for e in entries:
+            ts = parse_ts(e.get("timestamp"))
+            t = e.get("type")
+            if t == "model_change" and seen_user_turn:
+                pending_model = True
+            elif t == "thinking_level_change" and seen_user_turn:
+                pending_think = True
+            elif t == "custom" and e.get("customType") == "cache-probe":
+                data = e.get("data") or {}
+                if data.get("error"):
+                    counters["error_entries"] += 1
+                elif isinstance(data.get("h"), dict):
+                    if data.get("baseline") and current_hashes is not None:
+                        changed = [k for k, v in data["h"].items() if current_hashes.get(k) != v]
+                        baseline_pairs.append((data.get("startReason"), changed))
+                    # v2 增量 merge：baseline 全量覆盖；normal 增量合并
+                    current_hashes = {**(current_hashes or {}), **data["h"]}
+            elif t == "message":
+                m = e.get("message", {})
+                role = m.get("role")
+                if role == "user" and is_real_user(m):
+                    seen_user_turn = True
+                    turn_model_chg, turn_think_chg = pending_model, pending_think
+                    pending_model = pending_think = False
+                    if last_ts is not None and ts is not None:
+                        gap_bucket = bucket_of(ts - last_ts) or "d.>12h"
+                    else:
+                        gap_bucket = "new"
+                    seen_first = False
+                elif role == "assistant" and not seen_first:
+                    u = m.get("usage") or {}
+                    cr = u.get("cacheRead", 0) or 0
+                    miss = (u.get("input", 0) or 0) + (u.get("cacheWrite", 0) or 0)
+                    if cr or miss:
+                        prefix_chg = None
+                        parts = []
+                        if current_hashes is not None:
+                            has_probe_turn = True
+                            if prev_snapshot is not None:
+                                parts = [k for k, v in current_hashes.items()
+                                         if prev_snapshot.get(k) != v]
+                                prefix_chg = len(parts) > 0
+                        turn_rows.append((m.get("model", "?"), gap_bucket, turn_model_chg,
+                                          turn_think_chg, prefix_chg, parts, cr, miss))
+                        prev_snapshot = current_hashes
+                        seen_first = True
+            if ts is not None:
+                last_ts = ts
+        if has_probe_turn:
+            counters["sessions_with_probe"] += 1
+
+    # ---- 输出 ----
+    print("=" * 72)
+    print("1. 扫描概览")
+    print("=" * 72)
+    print(f"  sessions: {counters['sessions']}（含 cache-probe 数据 {counters['sessions_with_probe']}）")
+    print(f"  turns: {len(turn_rows)}   error entries: {counters['error_entries']}")
+    print(f"  畸形行: {counters['malformed_lines']}   不可读文件: {counters['unreadable_files']}")
+    think_turns = [r for r in turn_rows if r[3]]
+    if think_turns:
+        cr = sum(r[6] for r in think_turns)
+        tot = cr + sum(r[7] for r in think_turns)
+        print(f"  think 切换 turn: {len(think_turns)}（命中率 {cr / tot * 100:.1f}%，历史实测 ≈ 基线，仅监控不参与归因过滤）")
+
+    print()
+    print("=" * 72)
+    print("2. 命中率基线（全部 turn 首笔，按中断时长；对照设计文档 §3.1 口径）")
+    print("=" * 72)
+    by_gap = defaultdict(lambda: [0, 0])
+    for _m, g, _mc, _tc, _pc, _p, cr, miss in turn_rows:
+        by_gap[g][0] += cr
+        by_gap[g][1] += miss
+    print(f"  {'gap':12s} {'命中':>16s} {'未命中':>16s} {'命中率':>8s}")
+    for g in sorted(by_gap):
+        cr, miss = by_gap[g]
+        tot = cr + miss
+        if tot:
+            print(f"  {g:12s} {cr:>16,d} {miss:>16,d} {cr / tot * 100:>7.1f}%")
+
+    print()
+    print("=" * 72)
+    print("3. 归因矩阵：gap<30min + 模型未切换 的 turn 首笔（探针覆盖的 turn）")
+    print("=" * 72)
+    core = [r for r in turn_rows if r[1] in ("a.<5min", "b.5-30min") and not r[2] and r[4] is not None]
+    groups = [
+        (True, "前缀变化（可修）", [r for r in core if r[4]]),
+        (False, "前缀未变仍 miss（服务端淘汰/链盲区并存）", [r for r in core if not r[4]]),
+    ]
+    miss_chg = miss_same = 0
+    for is_chg, name, rows in groups:
+        cr = sum(r[6] for r in rows)
+        miss = sum(r[7] for r in rows)
+        tot = cr + miss
+        hit = cr / tot * 100 if tot else 0.0
+        if is_chg:
+            miss_chg = miss
+        else:
+            miss_same = miss
+        print(f"  {name}")
+        print(f"    turns={len(rows)}  命中={cr:,d}  未命中={miss:,d}  命中率={hit:.1f}%")
+    part_hist = defaultdict(int)
+    for r in core:
+        if r[4]:
+            for p in r[5]:
+                part_hist[p] += 1
+    if part_hist:
+        print("  变化部位 Top：")
+        for p, n in sorted(part_hist.items(), key=lambda kv: -kv[1])[:8]:
+            print(f"    {p}: {n} 次")
+
+    print()
+    print("=" * 72)
+    print("4. 进程边界漂移（baseline entry 与前一条指纹对比）")
+    print("=" * 72)
+    if baseline_pairs:
+        drift = [p for _r, parts in baseline_pairs if parts for p in parts]
+        n_no_drift = sum(1 for _r, parts in baseline_pairs if not parts)
+        print(f"  边界事件 {len(baseline_pairs)} 次：漂移 {len(baseline_pairs) - n_no_drift} 次，未漂移 {n_no_drift} 次")
+        hist = defaultdict(int)
+        for p in drift:
+            hist[p] += 1
+        for p, n in sorted(hist.items(), key=lambda kv: -kv[1])[:8]:
+            print(f"    漂移部位 {p}: {n} 次")
+        reasons = defaultdict(int)
+        for r, _parts in baseline_pairs:
+            reasons[r or "unknown"] += 1
+        print(f"  startReason 分布：{dict(reasons)}")
+    else:
+        print("  暂无 baseline 对比数据（需跨进程场景积累）")
+
+    print()
+    print("=" * 72)
+    print("5. 决策建议（快照方案 GO/NO-GO 倾向）")
+    print("=" * 72)
+    n_core = len(core)
+    if n_core < 200:
+        print(f"  样本不足（归因矩阵 turn 数 {n_core} < 200），继续收集。终止标准见 README.md。")
+    elif miss_chg + miss_same == 0:
+        print("  归因矩阵内无 miss token，无需快照方案。")
+    else:
+        share = miss_chg / (miss_chg + miss_same)
+        if share >= 0.5:
+            top = max(part_hist, key=part_hist.get) if part_hist else "?"
+            print(f"  前缀变化贡献 miss 的 {share * 100:.0f}% → GO 倾向：优先固化「{top}」相关前缀。")
+        elif share <= 0.3:
+            print(f"  前缀变化仅贡献 miss 的 {share * 100:.0f}% → NO-GO 倾向：主因在服务端淘汰/链盲区，快照收益有限。")
+        else:
+            print(f"  前缀变化贡献 miss 的 {share * 100:.0f}% → 混合成因，结合部位分布与价差人工决策。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@zhushanwen/pi-cache-probe",
+  "version": "0.1.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",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "extension",
+    "cache",
+    "observability",
+    "prompt-caching"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts",
+    "analyze.py"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/fingerprint.test.ts

@@ -0,0 +1,139 @@
+// 测试框架：vitest
+// 运行命令：npx vitest run src/__tests__/fingerprint.test.ts
+//
+// 指纹纯函数层测试：stableStringify 稳定性 / hash 长度 / extractSystem 四口径 /
+// sentToolsOf / diffFingerprints / buildProbeEntry 的 baseline-全量、normal-增量、无变化-null。
+
+import { describe, expect, it } from "vitest";
+
+import {
+	buildProbeEntry,
+	diffFingerprints,
+	extractSystem,
+	HASH_LEN,
+	hashOf,
+	sentToolsOf,
+	stableStringify,
+	type Fingerprints,
+} from "../fingerprint";
+
+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),
+	...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 字符且同输入同输出`, () => {
+		const h = hashOf({ a: 1 });
+		expect(h).toMatch(/^[0-9a-f]{16}$/);
+		expect(hashOf({ a: 1 })).toBe(h);
+		expect(hashOf({ b: 1 })).not.toBe(h);
+	});
+
+	it("key 顺序不影响 hash", () => {
+		expect(hashOf({ a: 1, b: 2 })).toBe(hashOf({ b: 2, a: 1 }));
+	});
+});
+
+describe("extractSystem（payload 四口径）", () => {
+	it("OpenAI 兼容：messages 内 role=system", () => {
+		expect(extractSystem({ messages: [{ role: "system", content: "s" }, { role: "user", content: "u" }] })).toEqual([
+			{ role: "system", content: "s" },
+		]);
+	});
+
+	it("OpenAI 兼容：role=developer（pi useDeveloperRole 分支，实测命中）", () => {
+		expect(extractSystem({ messages: [{ role: "developer", content: "s" }] })).toEqual([
+			{ role: "developer", content: "s" },
+		]);
+	});
+
+	it("Anthropic：顶层 system 数组", () => {
+		expect(extractSystem({ system: [{ type: "text", text: "s" }], messages: [] })).toEqual([
+			{ type: "text", text: "s" },
+		]);
+	});
+
+	it("Google：顶层 systemInstruction 对象", () => {
+		expect(extractSystem({ systemInstruction: { role: "system", parts: [] } })).toEqual({
+			role: "system",
+			parts: [],
+		});
+	});
+
+	it("无 system 内容返回 null", () => {
+		expect(extractSystem({ messages: [{ role: "user", content: "u" }] })).toBeNull();
+		expect(extractSystem(null)).toBeNull();
+		expect(extractSystem("str")).toBeNull();
+	});
+});
+
+describe("sentToolsOf", () => {
+	it("有 tools 返回数组，缺失返回 null", () => {
+		expect(sentToolsOf({ tools: [{ name: "read" }] })).toEqual([{ name: "read" }]);
+		expect(sentToolsOf({})).toBeNull();
+		expect(sentToolsOf(null)).toBeNull();
+	});
+});
+
+describe("diffFingerprints / buildProbeEntry", () => {
+	it("diff 只报变化项", () => {
+		expect(diffFingerprints(fp({ contextFiles: "x".repeat(HASH_LEN) }), fp())).toEqual(["contextFiles"]);
+		expect(diffFingerprints(fp(), null)).toEqual([]);
+	});
+
+	it("baseline：全量 hash + changed ['*'] + cwd + startReason", () => {
+		const cur = fp();
+		const e = buildProbeEntry(cur, null, { seq: 1, needsBaseline: true, startReason: "startup", cwd: "/w" });
+		expect(e).toEqual({
+			v: 2,
+			seq: 1,
+			baseline: true,
+			startReason: "startup",
+			cwd: "/w",
+			changed: ["*"],
+			h: cur,
+		});
+	});
+
+	it("normal：只存变化项（增量），不带 cwd", () => {
+		const last = fp();
+		const cur = fp({ contextFiles: "x".repeat(HASH_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) },
+		});
+	});
+
+	it("无变化返回 null（不写 entry）", () => {
+		expect(buildProbeEntry(fp(), fp(), { seq: 2, needsBaseline: false, startReason: null, cwd: "/w" })).toBeNull();
+	});
+});

package/src/__tests__/state-machine.test.ts

@@ -0,0 +1,165 @@
+// 测试框架：vitest
+// 运行命令：npx vitest run src/__tests__/state-machine.test.ts
+//
+// SDK 契约测试（extension-conventions.md「SDK 接口契约」条款）：用最小 mock 的
+// ExtensionAPI 走完整事件序列，断言 cache-probe 对 pi SDK 的调用契约与状态机行为：
+// baseline / 无变化不写 entry / 增量 entry / error 恢复 / agent_end 丢弃 pending /
+// appendEntry 失败不崩 / session_start 重置。
+
+/* eslint-disable taste/no-unsafe-cast */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import cacheProbe from "../index";
+
+interface HandlerMap {
+	session_start?: (e: unknown) => void | Promise<void>;
+	before_agent_start?: (e: unknown) => void | Promise<void>;
+	before_provider_request?: (e: unknown) => void | Promise<void>;
+	agent_end?: (e: unknown) => void | Promise<void>;
+}
+
+interface MockSetup {
+	pi: ExtensionAPI;
+	handlers: HandlerMap;
+	entries: Array<{ customType: string; data: Record<string, unknown> }>;
+	getAllTools: ReturnType<typeof vi.fn>;
+}
+
+function options(over: Record<string, unknown> = {}) {
+	return {
+		cwd: "/w",
+		contextFiles: [{ path: "/w/AGENTS.md", content: "base" }],
+		skills: [{ name: "s1" }],
+		selectedTools: ["read"],
+		toolSnippets: { read: "r" },
+		appendSystemPrompt: "append",
+		promptGuidelines: ["g"],
+		customPrompt: undefined,
+		...over,
+	};
+}
+
+function payload(systemContent = "sys") {
+	return {
+		model: "m",
+		messages: [{ role: "developer", content: systemContent }, { role: "user", content: "u" }],
+		tools: [{ name: "read", description: "d", parameters: { type: "object" } }],
+	};
+}
+
+function createMockPi(): MockSetup {
+	const handlers: HandlerMap = {};
+	const entries: MockSetup["entries"] = [];
+	const getAllTools = vi.fn(() => [
+		{ name: "read", description: "d", parameters: { type: "object" }, promptGuidelines: undefined },
+	]);
+	const pi = {
+		on: vi.fn((type: string, handler: (e: unknown) => unknown) => {
+			handlers[type as keyof HandlerMap] = handler as HandlerMap[keyof HandlerMap];
+		}),
+		appendEntry: vi.fn((customType: string, data: Record<string, unknown>) => {
+			entries.push({ customType, data });
+			return String(entries.length);
+		}),
+		getAllTools,
+	};
+	return { pi: pi as unknown as ExtensionAPI, handlers, entries, getAllTools };
+}
+
+async function runTurn(setup: MockSetup, opts: Record<string, unknown>, payloadArg = payload()) {
+	await setup.handlers.before_agent_start!({ type: "before_agent_start", systemPrompt: "s", systemPromptOptions: opts });
+	await setup.handlers.before_provider_request!({ type: "before_provider_request", payload: payloadArg });
+}
+
+describe("cache-probe 状态机（SDK 契约）", () => {
+	let setup: MockSetup;
+	beforeEach(() => {
+		setup = createMockPi();
+		cacheProbe(setup.pi);
+	});
+
+	it("注册 4 个事件 handler，不注册 tool / 不发消息（零行为影响）", () => {
+		expect(setup.handlers.session_start).toBeDefined();
+		expect(setup.handlers.before_agent_start).toBeDefined();
+		expect(setup.handlers.before_provider_request).toBeDefined();
+		expect(setup.handlers.agent_end).toBeDefined();
+	});
+
+	it("进程首笔请求写 baseline（v2、全量 9 key、16 hex、cwd、startReason）", async () => {
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await runTurn(setup, options());
+		expect(setup.entries).toHaveLength(1);
+		const e = setup.entries[0];
+		expect(e.customType).toBe("cache-probe");
+		expect(e.data).toMatchObject({ v: 2, seq: 1, baseline: true, startReason: "startup", cwd: "/w", changed: ["*"] });
+		const h = e.data.h as Record<string, string>;
+		expect(Object.keys(h).sort()).toEqual(
+			["append", "contextFiles", "customPrompt", "guidelines", "skills", "spFull", "toolsList", "toolsReg", "toolsSent"].sort(),
+		);
+		expect(Object.values(h).every((v) => /^[0-9a-f]{16}$/.test(v))).toBe(true);
+	});
+
+	it("同状态连续 turn 不写 entry；变化只写增量 entry（省数据量的核心）", async () => {
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await runTurn(setup, options());
+		await runTurn(setup, options());
+		await runTurn(setup, options());
+		expect(setup.entries).toHaveLength(1); // 3 turn 仅 baseline
+		await runTurn(setup, options({ contextFiles: [{ path: "/w/AGENTS.md", content: "changed" }] }));
+		expect(setup.entries).toHaveLength(2);
+		expect(setup.entries[1].data).toMatchObject({ v: 2, seq: 4, changed: ["contextFiles"] });
+		expect(Object.keys(setup.entries[1].data.h as object)).toEqual(["contextFiles"]);
+	});
+
+	it("payload 侧变化（spFull）单独可检测（extension 链注入场景）", async () => {
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await runTurn(setup, options(), payload("sys-1"));
+		await runTurn(setup, options(), payload("sys-2"));
+		expect(setup.entries).toHaveLength(2);
+		expect(setup.entries[1].data.changed).toEqual(["spFull"]);
+	});
+
+	it("agent_end 后 pending 被丢弃：无 turn 上下文的 provider 请求不写 entry", async () => {
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await runTurn(setup, options());
+		await setup.handlers.before_agent_start!({ type: "before_agent_start", systemPrompt: "s", systemPromptOptions: options() });
+		await setup.handlers.agent_end!({ type: "agent_end" }); // turn 取消，未发请求
+		await setup.handlers.before_provider_request!({ type: "before_provider_request", payload: payload() });
+		expect(setup.entries).toHaveLength(1);
+	});
+
+	it("session_start 重置：跨进程写新 baseline", async () => {
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await runTurn(setup, options());
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await runTurn(setup, options());
+		expect(setup.entries).toHaveLength(2);
+		expect(setup.entries[1].data.baseline).toBe(true);
+	});
+
+	it("handler 异常写 error entry 且下一 turn 恢复 baseline", async () => {
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		setup.getAllTools.mockImplementationOnce(() => {
+			throw new Error("injected");
+		});
+		await setup.handlers.before_agent_start!({ type: "before_agent_start", systemPrompt: "s", systemPromptOptions: options() });
+		await setup.handlers.before_provider_request!({ type: "before_provider_request", payload: payload() });
+		expect(setup.entries).toHaveLength(1);
+		expect(setup.entries[0].data).toMatchObject({ v: 2, seq: 1, error: "injected" });
+		// 下一 turn 恢复：needsBaseline 已置位
+		await runTurn(setup, options());
+		expect(setup.entries).toHaveLength(2);
+		expect(setup.entries[1].data.baseline).toBe(true);
+	});
+
+	it("appendEntry 失败不崩（stderr 诊断吞掉）", async () => {
+		const pi = setup.pi as unknown as { appendEntry: ReturnType<typeof vi.fn> };
+		pi.appendEntry.mockImplementation(() => {
+			throw new Error("disk full");
+		});
+		await setup.handlers.session_start!({ type: "session_start", reason: "startup" });
+		await expect(runTurn(setup, options())).resolves.toBeUndefined();
+	});
+});

package/src/fingerprint.ts

@@ -0,0 +1,175 @@
+/**
+ * cache-probe 指纹纯函数层 —— 设计文档 docs/todo/cache-probe-design.md §7.1。
+ *
+ * entry schema v2（长期生效版，数据量精简为长期采集优化）：
+ *  - hash 用 sha256 前 16 hex（64bit，同 session 内对比，碰撞概率可忽略）
+ *  - baseline entry 存全量 9 hash + cwd + startReason
+ *  - normal entry 只存变化项（增量 merge，脚本侧回放合并）
+ *  - error entry 只存 v/seq/error
+ */
+
+import { createHash } from "node:crypto";
+
+/** 指纹 hash 长度（hex 字符数）。 */
+export const HASH_LEN = 16;
+
+/** entry schema 版本（v2：短 hash + 增量 entry）。 */
+export const SCHEMA_VERSION = 2;
+
+export type FingerprintKey =
+	| "spFull"
+	| "toolsSent"
+	| "contextFiles"
+	| "skills"
+	| "toolsList"
+	| "toolsReg"
+	| "append"
+	| "guidelines"
+	| "customPrompt";
+
+export type Fingerprints = Record<FingerprintKey, string>;
+
+export interface ProbeEntryData {
+	v: typeof SCHEMA_VERSION;
+	seq: number;
+	baseline?: true;
+	startReason?: string;
+	cwd?: string;
+	changed?: string[];
+	/** baseline 存全量；normal 只存变化项。 */
+	h?: Partial<Fingerprints>;
+	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 {
+	if (value === undefined) return "null";
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return "[" + value.map(stableStringify).join(",") + "]";
+	const keys = Object.keys(value).sort();
+	return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify((value as Record<string, unknown>)[k])).join(",") + "}";
+}
+
+export function hashOf(value: unknown): string {
+	return createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, HASH_LEN);
+}
+
+/**
+ * 从 provider payload 提取 system 内容（最终视角）。三种口径：
+ *  - OpenAI 兼容：messages 内 role 为 system 或 developer
+ *    （pi 源码 ai/src/api/openai-completions.ts 的 useDeveloperRole 分支）
+ *  - Anthropic：顶层 system（数组）
+ *  - Google：顶层 systemInstruction（对象）
+ */
+export function extractSystem(payload: unknown): unknown | null {
+	if (!isRecord(payload)) return null;
+	const system = payload["system"];
+	if (Array.isArray(system)) return system;
+	const systemInstruction = payload["systemInstruction"];
+	if (isRecord(systemInstruction)) return systemInstruction;
+	const messages = payload["messages"];
+	if (Array.isArray(messages)) {
+		const sys = messages.filter(
+			(m): m is Record<string, unknown> =>
+				isRecord(m) && (m["role"] === "system" || m["role"] === "developer"),
+		);
+		if (sys.length > 0) return sys;
+	}
+	return null;
+}
+
+/** 从 provider payload 提取最终发送的 tools 数组；缺失返回 null。 */
+export function sentToolsOf(payload: unknown): unknown[] | null {
+	if (!isRecord(payload)) return null;
+	const tools = payload["tools"];
+	return Array.isArray(tools) ? tools : null;
+}
+
+export function diffFingerprints(cur: Fingerprints, last: Fingerprints | null): FingerprintKey[] {
+	if (last === null) return [];
+	return (Object.keys(cur) as FingerprintKey[]).filter((k) => last[k] !== cur[k]);
+}
+
+/** systemPromptOptions 的结构子集（探针只读这些字段；宽松类型避免纯函数层耦合 SDK）。 */
+export interface SystemPromptOptionsLike {
+	cwd?: string | null;
+	contextFiles?: unknown;
+	skills?: unknown;
+	selectedTools?: unknown;
+	toolSnippets?: unknown;
+	appendSystemPrompt?: unknown;
+	promptGuidelines?: unknown;
+	customPrompt?: unknown;
+}
+
+/** before_agent_start 暂存的输入侧指纹（payload 侧 spFull/toolsSent 到 provider 请求时补齐）。 */
+export interface PendingFingerprint {
+	cwd: string | null;
+	parts: Omit<Fingerprints, "spFull" | "toolsSent">;
+}
+
+/** getAllTools 注册表条目归一（非对象/缺字段归 null，形态稳定后参与 toolsReg hash）。 */
+function normalizeTool(t: unknown): { name: unknown; description: unknown; parameters: unknown; promptGuidelines: unknown } {
+	if (!isRecord(t)) return { name: null, description: null, parameters: null, promptGuidelines: null };
+	return {
+		name: t["name"] ?? null,
+		description: t["description"] ?? null,
+		parameters: t["parameters"] ?? null,
+		promptGuidelines: t["promptGuidelines"] ?? null,
+	};
+}
+
+/**
+ * before_agent_start 输入侧 7 hash 计算（handler 只做编排，纯函数便于单测）。
+ * null 容忍语义与 turn 侧一致：缺省字段归一为 null 再 hash，防 undefined/null 抖动产生假变化。
+ */
+export function computePendingFingerprint(
+	o: SystemPromptOptionsLike | null | undefined,
+	tools: readonly unknown[] | null | undefined,
+): PendingFingerprint {
+	const opts = o ?? {};
+	return {
+		cwd: opts.cwd ?? null,
+		parts: {
+			contextFiles: hashOf(opts.contextFiles ?? null),
+			skills: hashOf(opts.skills ?? null),
+			toolsList: hashOf([opts.selectedTools ?? null, opts.toolSnippets ?? null]),
+			append: hashOf(opts.appendSystemPrompt ?? null),
+			guidelines: hashOf(opts.promptGuidelines ?? null),
+			customPrompt: hashOf(opts.customPrompt ?? null),
+			toolsReg: hashOf((tools ?? []).map(normalizeTool)),
+		},
+	};
+}
+
+/**
+ * 构建待写入的 probe entry；无变化返回 null（不写 entry，session 零膨胀）。
+ * baseline 全量；normal 增量。cwd 仅 baseline 携带（cwd 变化必然带动 contextFiles 变化，
+ * 变化事实由 changed 体现，诊断回溯最近 baseline）。
+ */
+export function buildProbeEntry(
+	cur: Fingerprints,
+	last: Fingerprints | null,
+	meta: { seq: number; needsBaseline: boolean; startReason: string | null; cwd: string | null },
+): ProbeEntryData | null {
+	if (meta.needsBaseline || last === null) {
+		return {
+			v: SCHEMA_VERSION,
+			seq: meta.seq,
+			baseline: true,
+			startReason: meta.startReason ?? undefined,
+			cwd: meta.cwd ?? undefined,
+			changed: ["*"],
+			h: cur,
+		};
+	}
+	const changed = diffFingerprints(cur, last);
+	if (changed.length === 0) return null;
+	const delta: Partial<Fingerprints> = {};
+	for (const k of changed) delta[k] = cur[k];
+	return { v: SCHEMA_VERSION, seq: meta.seq, changed, h: delta };
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * cache-probe — pi file-type extension（前缀稳定性长期数据采集探针）。
+ *
+ * 设计文档：docs/todo/cache-probe-design.md（§7.1 实现机制）。
+ *
+ * 记录 9 个指纹 hash（schema v2：短 hash + 增量 entry），变化时才向 session JSONL
+ * 写 custom entry（customType = "cache-probe"）。custom entry 不进 LLM 上下文，
+ * 探针零行为影响：
+ *  - before_agent_start（每 turn 1 次）：算 7 个输入侧 hash 暂存 pending
+ *    （systemPromptOptions 各字段 + getAllTools 注册表）
+ *  - before_provider_request（每笔 LLM 请求，仅消费 turn 首笔）：从最终 payload
+ *    提取 spFull（system 消息，兼容 system/developer/anthropic/google 口径）与
+ *    toolsSent（tools 数组），与 pending 合并对比，变化/基线时 appendEntry
+ *  - agent_end：turn 内无 provider 请求则丢弃 pending（无请求即无归因价值）
+ *
+ * seq = 进程内 before_agent_start 触发计数（无论是否写 entry 都递增），
+ * 脚本靠 seq 跳跃区分「无变化 turn」与「漏记」。
+ *
+ * Fail-safe：handler 全程捕获，异常时写 error entry（缺口可见非静默）并重置为
+ * 需基线状态；appendEntry 自身失败仅 stderr 诊断，绝不阻塞请求。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+	buildProbeEntry,
+	computePendingFingerprint,
+	extractSystem,
+	hashOf,
+	SCHEMA_VERSION,
+	sentToolsOf,
+	type Fingerprints,
+	type PendingFingerprint,
+} from "./fingerprint";
+
+const CUSTOM_TYPE = "cache-probe";
+
+function stderr(msg: string): void {
+	// stderr 已销毁（EPIPE）时错误走流 error 事件而非同步 throw，无需兜底 catch
+	process.stderr.write(`[cache-probe] ${msg}\n`);
+}
+
+export default function (pi: ExtensionAPI): void {
+	let seq = 0;
+	let needsBaseline = true; // 初始 true 兜底 extension 加载晚于 session_start 的情况
+	let startReason: string | null = null;
+	let last: Fingerprints | null = null;
+	let pending: PendingFingerprint | null = null;
+
+	pi.on("session_start", (event) => {
+		needsBaseline = true;
+		startReason = event?.reason ?? null;
+		last = null;
+		pending = null;
+	});
+
+	pi.on("before_agent_start", (event) => {
+		seq += 1;
+		try {
+			// 输入侧 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)}`);
+			pending = null;
+			try {
+				pi.appendEntry(CUSTOM_TYPE, { v: SCHEMA_VERSION, seq, error: String(err instanceof Error ? err.message : err) });
+			} catch (appendErr) {
+				stderr(`appendEntry failed: ${appendErr instanceof Error ? appendErr.message : String(appendErr)}`);
+			}
+			needsBaseline = true;
+		}
+	});
+
+	pi.on("before_provider_request", (event) => {
+		if (!pending) return; // turn 首笔已被消费，或本 turn 无 before_agent_start 上下文
+		const { cwd, parts } = pending;
+		pending = null;
+		try {
+			const payload = event?.payload;
+			const system = extractSystem(payload);
+			const cur: Fingerprints = {
+				...parts,
+				spFull: system === null ? "no-system" : hashOf(system),
+				toolsSent: sentToolsOf(payload) === null ? "no-tools" : hashOf(sentToolsOf(payload)),
+			};
+			const entry = buildProbeEntry(cur, last, { seq, needsBaseline, startReason, cwd });
+			if (entry) pi.appendEntry(CUSTOM_TYPE, entry);
+			last = cur;
+			needsBaseline = false;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(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)}`);
+			}
+			needsBaseline = true;
+		}
+	});
+
+	// turn 内没有任何 provider 请求（用户取消等）则丢弃 pending，防跨 turn 污染
+	pi.on("agent_end", () => {
+		pending = null;
+	});
+}