@zhushanwen/pi-cache-probe 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-cache-probe",
-  "version": "0.3.0",
+  "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

@@ -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

@@ -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

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