缓存机制深度对比：OpenCode vs Claude Code vs Pi Agent

Prompt Caching 已从可选优化变为必须工程化的核心能力。三大 AI 编码工具在缓存与上下文压缩上形成了三种截然不同的工程范式——理解它们的差异，直接影响长会话的 Token 成本和响应质量。 适合读者: 架构师 · 效率开发者 · 工程经理

文章概述

在 AI 编码工作流中，大部分 Token 被花在了重复内容上。每次 Agent 请求都携带系统指令、项目上下文、工具定义和对话历史前缀——这些内容在同一会话甚至跨项目中几乎不变。缓存和上下文压缩（Compaction）就是为了解决这个问题而设计的，但两者的工作方式和使用成本截然不同。

本文从“缓存 ≠ 压缩“这个核心洞察出发，分别分析三大工具的缓存和压缩实现——OpenCode 的三级缓存架构、Claude Code 的 5 级渐进压缩 Pipeline、Pi Agent 的极简可扩展 Compaction。然后提供每个工具中如何激活缓存的配置指南，以及围绕缓存能力的最佳开源项目和插件。最后，通过成本对比和趋势分析，帮助读者在不同场景下做出合理选择。

⏱ 时间有限？先读这些： 缓存 vs 压缩 → 各工具开启方式对比表 → 选型矩阵

缓存 ≠ 压缩：理解两套机制

这是理解整篇文章的第一原则。缓存和压缩做的是两件不同的事：

核心关系：压缩是缓存前缀的天敌。压缩会修改消息结构，导致 cache key 变化，使之前缓存的全部失效（Cache Miss）。Cache-Aligned Compaction 的设计目标就是“如何压缩但不破坏缓存“——这个话题在后面各工具中会多次出现。

OpenCode：三级缓存 + 阶梯式治理

缓存架构

OpenCode 拥有三大工具中最完整的多级缓存体系。自 2026 年 5 月起，cache: "auto" 已成为 默认 行为（PR #26798），无需显式配置即可自动启用缓存。缓存直接在 opencode.json 中配置：

{
  "cache": {
    "session": {
      "enabled": true,
      "maxSize": 100000,
      "maxAge": "session"
    },
    "project": {
      "enabled": true,
      "maxSize": 500000,
      "maxAge": "24h",
      "patterns": ["**/*.md", "**/AGENTS.md", "**/package.json"]
    },
    "global": {
      "enabled": true,
      "maxSize": 2000000,
      "maxAge": "7d",
      "patterns": ["~/.opencode/global/**"]
    }
  }
}

缓存断点（Breakpoints）：用户通过注释语法手动标记可复用上下文片段：

#cache-breakpoint: project-rules
AGENTS.md 中定义的所有约束规则
#cache-breakpoint: end

断点生命周期：创建 → 引用 → 更新 → 失效。具体参见 → 提示词缓存机制。

Compaction 机制

OpenCode 采用两层压缩：

• 工具输出修剪（Prune）：给旧消息打时间戳使其“不可见“（非物理删除，仍存数据库）。阈值：总工具输出 > 40K token。
• LLM 摘要压缩：隐藏的专用 Compaction Agent 生成 5 段式摘要，压缩后自动重放最后用户消息——用户完全无感知。

溢出保护通过 compaction.reserved 控制预留缓冲区。具体触发阈值、微压缩策略和保真度实测数据，参见 → 上下文压缩与Token 预算。

如何激活缓存

相关开源项目与插件

Claude Code：5 级渐进压缩 + Prompt Caching 原生集成

缓存架构

Claude Code 的缓存哲学是“最便宜的先做，最贵的最后做“。与 OpenCode 不同，它没有独立的多级缓存架构——缓存完全依赖 Anthropic API 的 Prompt Caching，并在 Compaction 策略中深度集成 cache-aware 设计。

官方在 2026 年 4 月的博文 Prompt caching is everything 中详细阐述了这一设计理念，并介绍了 cache-safe forking 等技术细节。

Anthropic Prompt Caching 机制

Claude Code 通过 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 将一个 __boundary__ 哨兵字符串插入系统提示，将指令分为：

• 静态半（哨兵前）：核心指令、工具描述、安全规则 → scope: 'global' 全局缓存
• 动态半（哨兵后）：MCP 指令、输出偏好、语言设置 → 不全局缓存

5 级渐进式压缩 Pipeline

cache-safe forking（T3 的关键创新）：不修改父会话消息，而是 fork 出一个新分支复用自己的系统提示、工具定义和消息前缀——服务端看到相同的 cache key → hits。

如何激活缓存

相关开源项目与插件

Pi Agent：极简 Compaction + Extension 自定义

缓存架构

Pi Agent 的设计哲学是“极简核心，强力扩展“——它没有内置的多级缓存，也不依赖 Provider 级 Prompt Caching。缓存管理完全通过 Compaction 实现，而 Compaction 行为可通过 Extension API 完全自定义。

Compaction 核心流程

Find Cut Point → Extract Messages → Generate Summary → Append Entry → Reload

整个过程由 pi-agent-core/harness/compaction/compaction.ts 中的 summarizeWithBudget() 驱动：

1. Find Cut Point：从最新消息向前遍历，累积 token 估算直到 keepRecentTokens（默认 20K）
2. Extract Messages：收集上一次保留边界到切点之间的消息
3. Generate Summary：调用 LLM 生成结构化摘要，传递上一次摘要作为迭代上下文
4. Append Entry：保存 CompactionEntry（含摘要和 firstKeptEntryId）
5. Reload：Session 重载，使用摘要 + firstKeptEntryId 之后的消息

Provider 模型缓存成本定义

Pi Agent 的 Provider 模型定义中可指定缓存成本字段：

// Provider 定义中的缓存字段
{
  "model": "claude-sonnet-4",
  "pricing": {
    "input": 3.0,
    "output": 15.0,
    "cacheRead": 0.3,   // 缓存读价格（0.1x）
    "cacheWrite": 3.75  // 缓存写价格（1.25x）
  }
}

这样即使 Pi Agent 不管理缓存，也能在 Token 成本统计中准确反映实际花费。

如何激活缓存

完整配置示例（~/.pi/agent/settings.json）：

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "provider": {
    "primary": { "model": "claude-sonnet-4" },
    "compaction": { "model": "gemini-2.0-flash" }
  }
}

上述配置中的 compaction.model 并非 Pi Agent 内置选项，但可通过 Extension 自定义压缩 实现——见下方示例。

自定义压缩 Extension 示例

// custom-compaction.ts — 替换默认压缩，使用更便宜的模型
import { Extension, AgentSession } from '@earendil-works/pi-coding-agent'

export default {
  name: 'custom-compaction',
  onSessionBeforeCompact: async ({ reason, session }) => {
    // reason: "manual" | "threshold" | "overflow"
    console.log(`Compaction triggered: ${reason}`)
    
    // 替换压缩器为 Gemini Flash，降低摘要成本
    session.compressor = new CustomCompressor({
      model: 'gemini-2.0-flash',
      temperature: 0.3,
      maxTokens: 2048
    })
  }
}

相关开源项目与插件

2026 年上半年 Pi Agent 的 Compaction 扩展生态经历了爆发式增长，以下是主要的社区扩展：

成本对比与选型建议

Provider Prompt Caching 定价对比（2026）

截至 2026 年中，主流 LLM Provider 的 Prompt Caching 定价已趋于标准化，但策略差异显著：

Anthropic 的高读写价差（0.1x vs 1.25x）意味着 缓存命中率是成本控制的最大杠杆。对比之下，OpenAI 的自动缓存策略虽然免去手动断点，但 5min TTL 短、无法手动管理，在大规模场景下方案不够灵活。

典型场景 Token 成本对比

选型决策矩阵

跨工具通用最佳实践

1. 先命缓存，再压缩——缓存消除重复传输（零副作用），压缩精简必要内容（有损）。优化顺序：先确保缓存命中率达标（>80%），再考虑压缩策略。

2. 在自然断点手动 /compact——比自动压缩更可控。任务完成一个阶段后手动压缩，避免 Agent 在任务中间被截断。

3. 监控缓存命中率——低于 60% 说明配置有问题。对于 Anthropic 用户，检查是否有太多动态内容破坏缓存前缀。

4. 保持配置文件简洁——CLAUDE.md 或 AGENTS.md 越稳定，缓存命中率越高。频繁变动的配置文件是缓存的最大杀手。

5. 理解 TTL 的成本含义——Anthropic 5min TTL 意味着连续工作比间歇工作更便宜。长时间中断后第一次请求缓存未命中需交全价。

趋势：Cache-Aligned Compaction 成为共识

2026 年的重要趋势是，三大工具在缓存意识上趋于一致：

• OpenCode（2026-04）实验性推出 Cache-Aligned Compaction（PR #25100），通过保持消息序列化与普通请求一致、仅在末尾追加摘要指令来复用缓存前缀
• OpenCode（2026-05）进一步将 cache: "auto" 设为默认（PR #26798），并推出系统提示拆分（PR #14743），跨仓库缓存命中率从 0% 提升至 97.6%
• Claude Code 从设计之初就采用 cache-safe forking，Full Compaction 时复用父会话缓存 key；2026 年 4 月正式发布 Prompt caching is everything 设计文档
• Pi Agent 的 Extension 架构允许社区自行实现 cache-aware 压缩策略，2026 年上半年已涌现 7+ 个专业 Compaction 扩展

底层原因：随着 Anthropic/OpenAI/Google 等 Provider 的 Prompt Caching 定价逐步标准化（读 0.1x vs 写 1.25x），缓存命中率直接决定了 AI 编码工具的实际运营成本。不 cache-aware 的 Compaction 会破坏缓存前缀，导致每次压缩后都需重新缓存——成本从 0.1x 涨回 1x，差距可达 10 倍。

可以预见，Cache-Aligned 设计将在 2026 年底前从“实验性特性“升级为所有 AI 编码工具的标准特性。未来读者在评估编码工具时，缓存命中率和 Cache-Aligned 设计将与模型能力、工具生态并列为核心决策维度。

常见反模式

只看缓存策略忽略自身场景

现象：阅读本文后直接选择“缓存策略最强的工具“做技术选型，不考虑自己的项目规模、团队习惯和工具生态。

原因：把“缓存能力“当成了选型的唯一维度。

对策：缓存策略只是 AI 编码工具评估的维度之一。工具选型应综合考虑模型能力、工具生态、团队已有的工具链、迁移成本和缓存策略。缓存再强的工具如果模型质量不满足需求，也是本末倒置。

认为缓存策略是静态的

现象：选定工具后，使用默认缓存配置不再调整，认为“默认的就是最优的“。

原因：忽略了项目规模增长和任务类型变化对缓存策略的影响。

对策：缓存策略需要随着项目演进动态调整。项目从 10K 行增长到 100K 行后，缓存模式可能需要从 OpenCode 的 Lazy Write 切换到 Full Compaction。每季度审查一次缓存配置。

忽视 Cache-Aligned 的成本含义

现象：知道 Cache-Aligned 设计是好的，但不理解它为什么直接决定了运营成本。

原因：把“缓存命中率“当作纯技术指标，没有将其与 API 调用成本关联。

对策：理解 Prompt Caching 的定价模型——命中缓存的读取成本（0.1x）远低于未命中的写入成本（1.25x）。Cache-Aligned 设计的核心价值是让每次压缩不破坏缓存，相当于保持运营成本在低位。评估工具时，可以问“它的 Compaction 是 cache-aware 的吗“。

常见错误与陷阱

跨工具缓存策略对比忽略版本差异

场景：用 OpenCode 2025 年的缓存策略（未优化）和 Claude Code 2026 年的缓存策略（已优化）做对比，得出错误的结论。

后果：选了错误的工具，或者因为过时的信息否定了某个正在改进的工具。

预防：对比时标注工具的版本号和发布时间。缓存策略的迭代速度很快——6 个月前的数据可能已经完全失效。

缓存命中率数据未归一化

场景：对比两个工具的缓存命中率时，没有控制变量——测试的任务类型、项目规模、模型不同。

后果：得到“工具 A 命中率 80%，工具 B 命中率 60%，所以工具 A 更好“的错误结论。

预防：对比缓存命中率时需要控制变量——相同的测试任务、相同的项目、相同的模型。数据归一化后才具有可比性。

忽视 Multi-layer Caching 的整体收益

场景：只关注 Prompt Caching（L3 层）的命中率，忽略了 L1/L2 层的缓存贡献。

后果：认为某一层命中率低就等于整体缓存策略差。

预防：评估缓存策略时应看整体成本和延迟，而非某一层的命中率。OpenCode 的 Multi-layer Caching 中，L1 适合短 Session、L2 适合项目级知识、L3 适合长 Session。三层协同才能最大化缓存收益。

适用场景与限制

缓存策略对比的最佳场景

• 在 OpenCode、Claude Code、Pi Agent 之间做技术选型
• 理解不同工具在缓存和压缩方面的架构差异
• 优化当前工具的缓存配置以降低运营成本

缓存策略对比的局限

• 工具版本迭代快：本文的对比基于特定版本的实现，半年后可能不再准确
• 测试环境差异：缓存命中率受项目结构、代码变更频率、任务类型的影响很大
• 定价模型持续变化：各 Provider 的 Prompt Caching 定价策略仍在快速迭代

什么时候不需要关注缓存策略

短期项目、Token 消耗在预算控制范围内的团队、或使用提供商自带优化（如 Anthropic 的 Prompt Caching 自动生效）的场景下，了解缓存原理就够了，不需要做深度优化。

关联章节

• → 提示词缓存机制（OpenCode 三级缓存架构详解）
• → 上下文压缩与Token 预算（OpenCode Compaction 完整技术栈与实测数据）
• ← 上下文工程核心（上下文工程在 L2 中的定位）
• → 记忆系统设计（记忆系统与缓存的协同工作）
• → 性能调优与成本管理（各 Provider 的 Token 定价策略）