@zhushanwen/pi-cache-probe 0.3.1 → 0.3.3

package/README.md

@@ -1,16 +1,16 @@
 # @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「服务端淘汰（不可修）」。
 
 ## 组成
 
 - `src/index.ts` — 探针工厂（9 个指纹 hash：7 个输入侧来自 `systemPromptOptions` + `getAllTools()`，`spFull`/`toolsSent` 来自 `before_provider_request` 的最终 payload）
 - `src/fingerprint.ts` — 指纹纯函数层（stable stringify / hash / entry 构建）
-- `analyze.py` — 归因分析脚本（只读，单数据源扫 session 文件）
+- `analyze.py` — 归因分析脚本（只读，扫一个或多个 session 目录）
 
 ## entry schema v2（数据量精简，长期采集友好）
 
-- hash 为 sha256 前 16 hex；**baseline entry** 存全量 9 hash + cwd（约 250B）；**normal entry** 只存变化项增量（约 120B）；无变化 turn 零写入
+- hash 为 sha256 前 16 hex；**baseline entry** 存全量 9 hash + cwd + startReason（实测单行约 550B，随 cwd 长度浮动）；**normal entry** 只存变化项增量（单部位变化实测单行约 200B）；无变化 turn 零写入
 - `seq` = 进程内 before_agent_start 触发计数，随 entry 落盘供人工排序诊断；当前无自动消费方（analyze.py 不读 seq）
 
 ## 挂载方式（长期采集）
@@ -28,19 +28,23 @@ 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
+# pi CLI 会话 + taiji runtime 会话（<dataDir>/agent/sessions，getSessionsDir 口径）
+python3 extensions/universal/cache-probe/analyze.py ~/.pi/agent/sessions ~/.taiji/agent/sessions
+# 可选 --since YYYY-MM-DD：只分析 mtime 在该日期之后的 session
 ```
 
 输出五部分：扫描概览 / 命中率基线 / 归因矩阵 / 进程边界漂移 / GO-NO-GO 决策建议。
 
+归因解读：第 3 部分只统计间隔 <30min、模型未切换、探针覆盖的 turn 首笔 miss，按前缀是否变化分档——「前缀变化（可修）」档指向可固化的前缀漂移；「前缀未变仍 miss」档指向服务端淘汰 / 链盲区（不可修）。第 5 部分：归因矩阵有效 turn 满 200 后，按「前缀变化贡献的 miss token 占比」给倾向——占比 ≥50% → GO，≤30% → NO-GO，之间为混合成因需人工决策。
+
 ## 已知限制（实测查明）
 
-- pi CLI 启动路径（`--session` / `--continue`）的 session_start reason 恒为 `startup`（`resume` 仅运行时 switch session 出现）——跨进程识别靠 baseline 标记 + 时间戳 gap，漂移检测靠 hash 对比，均不受影响。
+- pi CLI 启动路径（`--session` / `--continue` / `--resume`）的 session_start reason 恒为 `startup`（pi 侧只做 SessionManager.open/continueRecent，不走运行时 switch 路径；`resume` / `new` / `fork` 仅运行时 switch/fork 出现，`reload` 仅 /reload 出现）——跨进程识别靠 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.1",
+  "version": "0.3.3",
   "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": {
@@ -26,7 +26,7 @@
     "analyze.py"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.4.0"
+    "@zhushanwen/pi-ext-guards": "0.4.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

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 内对比，碰撞概率可忽略）

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 上下文，