@zhushanwen/pi-cache-probe 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # @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「服务端淘汰（不可修）」。
+前缀稳定性长期数据采集 extension。零行为影响：只在 system prompt / tools 指纹变化时向 session JSONL 写 `cache-probe` custom entry（不进 LLM 上下文），配合 `analyze.py` 把 turn 首笔 cache miss 归因为「前缀变化（可修）」vs「服务端淘汰（不可修）」。
 
 ## 组成
 
@@ -28,7 +28,7 @@ pi --continue --extension <repo>/extensions/universal/cache-probe/index.ts "<pro
 ## 归因分析
 
 ```bash
-python3 extensions/universal/cache-probe/analyze.py ~/.pi/agent/sessions ~/.xyz-agent/pi/sessions
+python3 extensions/universal/cache-probe/analyze.py ~/.pi/agent/sessions ~/.taiji/pi/sessions
 ```
 
 输出五部分：扫描概览 / 命中率基线 / 归因矩阵 / 进程边界漂移 / GO-NO-GO 决策建议。
@@ -37,10 +37,10 @@ python3 extensions/universal/cache-probe/analyze.py ~/.pi/agent/sessions ~/.xyz-
 
 - 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 单独捕获——这正是它存在的价值。
+- 真实环境实测发现：extension 链（如 subagent-workflow）存在每 turn 级的 system prompt 动态注入，由 spFull 单独捕获——这正是它存在的价值。
 
 ## 日常维护
 
 - 校验：`cd extensions/universal/cache-probe && pnpm typecheck && pnpm test`（或仓库级 `pnpm extensions:typecheck && pnpm extensions:test`）
 - 每日检查：跑一次 analyze.py，确认 `sessions_with_probe` 增长、`error entries` 为 0 或已知原因
-- 归因矩阵内有效 turn（analyze.py 第 3 部分 core 过滤：排除间隔>30min、模型切换、探针未覆盖的 turn）满 200 后，analyze.py 第 5 部分给出快照方案 GO/NO-GO 倾向；结论与后续动作记录回设计文档
+- 归因矩阵内有效 turn（analyze.py 第 3 部分 core 过滤：排除间隔>30min、模型切换、探针未覆盖的 turn）满 200 后，analyze.py 第 5 部分给出快照方案 GO/NO-GO 倾向

package/analyze.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""cache-probe 归因分析脚本（设计文档 docs/todo/cache-probe-design.md §7.2）。
+"""cache-probe 归因分析脚本（设计文档 cache-probe-design §7.2）。
 
 输入一个或多个 sessions 目录，输出：
   1. 扫描概览（含 error entry / 畸形行计数，失败要出声）

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zhushanwen/pi-cache-probe",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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",
-  "xyz-agent": {
+  "taiji": {
     "role": "universal"
   },
   "pi": {
@@ -25,6 +25,9 @@
     "index.ts",
     "analyze.py"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-ext-guards": "0.4.1"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"

package/src/__tests__/fingerprint.test.ts

@@ -74,7 +74,7 @@ describe("extractSystem（payload 四口径）", () => {
 		]);
 	});
 
-	it("Google：顶层 systemInstruction 对象", () => {
+	it("伪造对象形态：顶层 systemInstruction（实装恒传 string，仅测试构造可达）", () => {
 		expect(extractSystem({ systemInstruction: { role: "system", parts: [] } })).toEqual({
 			role: "system",
 			parts: [],

package/src/fingerprint.ts

@@ -1,5 +1,5 @@
 /**
- * cache-probe 指纹纯函数层 —— 设计文档 docs/todo/cache-probe-design.md §7.1。
+ * cache-probe 指纹纯函数层 —— 设计文档 cache-probe-design §7.1。
  *
  * entry schema v2（长期生效版，数据量精简为长期采集优化）：
  *  - hash 用 sha256 前 16 hex（64bit，同 session 内对比，碰撞概率可忽略）
@@ -10,6 +10,8 @@
 
 import { createHash } from "node:crypto";
 
+import { isRecord } from "@zhushanwen/pi-ext-guards";
+
 /** 指纹 hash 长度（hex 字符数）。 */
 const HASH_LEN = 16;
 
@@ -41,10 +43,6 @@ 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 顺序抖动产生假变化）。 */
 function stableStringify(value: unknown): string {
 	if (value === undefined) return "null";
@@ -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;

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * cache-probe — pi file-type extension（前缀稳定性长期数据采集探针）。
  *
- * 设计文档：docs/todo/cache-probe-design.md（§7.1 实现机制）。
+ * 设计文档：cache-probe-design（§7.1 实现机制）。
  *
  * 记录 9 个指纹 hash（schema v2：短 hash + 增量 entry），变化时才向 session JSONL
  * 写 custom entry（customType = "cache-probe"）。custom entry 不进 LLM 上下文，
@@ -9,7 +9,9 @@
  *  - 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（无请求即无归因价值）
  *
@@ -21,6 +23,7 @@
  */
 
 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;
 		}