cache-guardian

English · 中文文档

Pi Agent 扩展：最大化 prompt cache 命中率，减少 token 成本。

Pi Agent 有完善的事件系统和扩展 API，但默认没有针对 provider prompt cache 做优化。当多个扩展在 before_agent_start 中注入内容时，system prompt 的字节级漂移会导致缓存前缀完全失效——实测中从 75% 直接崩到 0%。

cache-guardian 解决这一问题，并将 pi-cache-optimizer 和 DeepSeek-Reasonix 中的缓存优化技术整合到一个统一的扩展中。

核心机制

1. Golden 冻结（最关键）

第一轮完整处理后的 system prompt 捕获为 golden 副本。后续轮次无条件恢复为 golden，确保 system prompt 字节级一致。

2. Prompt reorder

将 system prompt 中最稳定的内容（自定义提示、工具说明、指导原则、上下文文件、技能索引）排到最前面。Provider 的 prefix 缓存从开头匹配，稳定内容在前越长，命中率越高。

3. Skills 压缩

4 个技能时，将 Pi 的 4 行 XML 块（<name>/<description>/<location>）压缩为一行索引。31 个技能时可将 13.3 KB 缩减到 ~1 KB，同时保持模型可发现性。

4. Session-overview churn strip

移除 trellis 的 <session-overview> 中每轮变化的字段（RECENT COMMITS、Working directory 状态、Line count），让剩余字段成为缓存友好前缀。

5. 兼容自动检测

• OpenAI prompt_cache_retention 被 400 拒绝时自动剥离
• Anthropic TTL 排序被 400 拒绝时自动降级
• prompt_cache_key 注入（OpenAI 兼容接口）

6. 缓存守护

PI_CACHE_GUARD=1 时，session 结束时聚合命中率低于阈值（默认 90%）则发出警告。

7. 缓存统计

每轮自动记录 cacheRead/cacheWrite/input，/cache-guardian 命令查看完整统计。

安装

npm（推荐）

pi install npm:pi-cache-guardian

Pi 自动安装并加载，无需设置变更。

直接复制

git clone https://github.com/icefairy/pi-cache-guardian.git
cp pi-cache-guardian/extensions/cache-guardian.ts ~/.pi/agent/extensions/

环境变量

| 变量 | 默认值 | 说明 | | ------ | -------- | ------ | | PI_CACHE_GUARD_VERBOSE | 0 | 每轮打印缓存统计到 stderr | | PI_CACHE_GUARD | 0 | session 结束时启用缓存守护警告 | | PI_CACHE_GUARD_THRESHOLD | 90 | 缓存守护命中率阈值 | | PI_CACHE_GUARD_NO_SKILL_COMPRESSION | 0 | 禁用 skills 压缩 | | PI_CACHE_GUARD_NO_PROMPT_REWRITE | 0 | 禁用 prompt reorder（仅做冻结） |

命令

/cache-guardian          # 显示当前 session 缓存统计
/cache-guardian disable  # 禁用扩展（本进程，重启后恢复）
/cache-guardian enable   # 重新启用
/cache-guardian reset    # 重置所有统计和兼容状态

测试结论

测试方法

10 轮"读文件"对话，模型 agentrium/deepseek-v4-flash，关闭 compaction 和 retry。同一脚本分别用无扩展和有扩展运行，从每轮 assistant 消息的 usage 字段提取 cacheRead/cacheWrite/input。

结果

| 场景 | 未命中 | 缓存命中 | 总输入 | 聚合命中率 | |------|--------|----------|--------|-----------| | 无扩展 | 5256 | 8192 | 13448 | 61% | | 有扩展 | 3967 | 8192 | 12159 | 67% |

稳定段（T3-T10，缓存预热后）

| 场景 | 每轮未命中 | 缓存命中 | 命中率 | | ------ | ----------- | --------- | ------- | | 无扩展 | 341 | 1024 | 75% | | 有扩展 | 201 | 1024 | 84% |

提升

• 未命中 token 减少 1289 个（25%）
• 稳定段命中率 +9 pts（75% → 84%）
• 无功能受损

参考

• DeepSeek-Reasonix: TestReleaseCacheHitGuard CI 门禁（90% 阈值）
• pi-cache-optimizer（jiangge）: prompt reorder + skills 压缩 + churn strip
• Anthropic prompt caching: cache_control: { type: "ephemeral" } 前缀匹配