agent-cache-optimizer

v0.6.1

Published

18 days ago

OpenCode plugin for LLM prompt caching, token savings, and KV cache reuse across AI agent sessions

👤 谁适合使用？

如果你的 CLI Agent 有大型 system prompt、MCP tools、skills、CLAUDE.md、 handoff memory，或者经常变化的上下文块，这个插件适合你。

典型用户会运行 OpenCode、Claude Code、Codex CLI、Gemini CLI 或自定义 LLM Agent，并希望提升 prompt cache 命中率、减少重复计算的 input tokens、降低 API 成本。

🎯 问题

DeepSeek、Anthropic、OpenAI、Google 等 LLM 提供商都使用前缀匹配 KV 缓存：如果你的 prompt 开头和之前的请求完全一致，已计算的 KV 状态会被复用 —— 缓存命中的成本接近零。

但每个 CLI agent 都把动态内容放在 system prompt 的最前面：

┌─────────────────────────────────────────────────┐
│ ⚡ HANDOFF 块（每个会话变化）                     │  ← 缓存失效
│ ⚡ REMEMBER / MEMORY（全天持续更新）              │  ← 缓存失效
├─────────────────────────────────────────────────┤
│ ✅ CLAUDE.md（数周不变）                          │  ← 永远用不到缓存
│ ✅ Agent 定义（静态）                             │  ← 永远用不到缓存
│ ✅ MCP / Skills / Tools（静态）                   │  ← 永远用不到缓存
│ ⚡ currentDate（每天变化）                        │
│ ⚡ Memory 注入（每次查询变化）                    │
└─────────────────────────────────────────────────┘

结果：跨会话缓存复用率 = 0%。 每次会话都要重新计算整个 system prompt，即使其中 70-90% 的内容从未变化。

💡 解决方案

agent-cache-optimizer 在运行时重排 system prompt：

┌─────────────────────────────────────────────────┐
│ ✅ CLAUDE.md（稳定）          ← 缓存命中         │
│ ✅ Agent 定义（稳定）         ← 缓存命中         │
│ ✅ MCP / Skills / Tools       ← 缓存命中         │
│ ✅ Tool 定义                  ← 缓存命中         │
├─────────────────────────────────────────────────┤
│ ⚡ currentDate                                   │
│ ⚡ HANDOFF / REMEMBER / MEMORY                   │
│ ⚡ Memory 注入                                    │
└─────────────────────────────────────────────────┘

稳定块在前 → 前缀跨会话保持一致 → 40-88% 缓存复用。

🚀 安装

{
  "plugin": ["agent-cache-optimizer"]
}

添加到 ~/.config/opencode/opencode.json。OpenCode 下次启动时自动从 npm 安装。

# 或通过 CLI
opencode plugin agent-cache-optimizer --global

重启 OpenCode — 完成。 零配置。适用于 DeepSeek、Anthropic、OpenAI 等所有支持前缀匹配 KV 缓存的提供商。

验证

# 确认插件已加载
opencode debug config | grep agent-cache-optimizer

# 实时查看重排活动
tail -f ~/.cache/opencode/agent-cache-optimizer/diag.log

状态面板

OpenCode 内：

agent-cache-optimizer status

终端：

bash scriptsagent-cache-optimizer status.sh

🏗 工作原理

1. 观测（完全内容无关）

插件绝不读取 prompt 内容。只对每个 system block 做哈希，追踪哪些哈希跨调用保持不变、哪些变化：

会话 1:  [H1, CLAUDE-A, AGENT-X, TOOLS-V1, DATE-1, MEM-1]
会话 2:  [H2, CLAUDE-A, AGENT-X, TOOLS-V1, DATE-2, MEM-2]
会话 3:  [H3, CLAUDE-A, AGENT-X, TOOLS-V1, DATE-2, MEM-3]

3 次观测后:
  位置 0 的 H1/H2/H3 每次都变 → 分数 0.0（动态）
  位置 1 的 CLAUDE-A 从未变化 → 分数 1.0（稳定）
  位置 2 的 AGENT-X 从未变化 → 分数 1.0（稳定）
  ...

2. 分类与重排

                                                                  ┌──────────┐
  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐     │ 稳定     │
  │ HANDOFF  │   │ CLAUDE   │   │ TOOLS    │   │ MEMORY   │ ──▶ │ CLAUDE   │
  │ (动态)   │   │ (稳定)   │   │ (稳定)   │   │ (动态)   │     │ TOOLS    │
  └──────────┘   └──────────┘   └──────────┘   └──────────┘     │──────────│
       ⚡             ✅              ✅              ⚡           │ 动态     │
                                                                 │ HANDOFF  │
                                                                 │ MEMORY   │
                                                                 └──────────┘

3. 两阶段决策

| 阶段 | 触发条件 | 方法 | | ---------- | ---------------------- | ------------------------ | | 冷启动 | 每个 agent 前 2 次调用 | 通用位置/大小/结构启发式 | | 热状态 | 3+ 次调用 | 基于哈希的稳定性分数 |

冷启动启发式仅使用结构信号（位置、大小、分隔符、行密度）——不用任何关键词匹配，不感知任何配置。这意味着插件可以立即在任何 agent 配置下工作。

📊 性能

在真实 OpenCode orchestrator prompt（~25KB system prompt）上测试：

| 场景 | 可缓存前缀 | 改善 | | ----------------------- | ------------- | ---- | | 原始（无重排） | 0 KB (0%) | — | | 冷启动（启发式） | 21.8 KB (88%) | +88% | | 热状态（哈希，3+ 会话） | 21.8 KB (88%) | +88% |

v0.6.1 真实 DeepSeek 运行结果（2026-06-26）

v0.6.1 tag 记录了本地 OpenCode 运行中的 provider 上报缓存指标，测试时使用的过滤命令为：

cat ~/.cache/opencode/agent-cache-optimizer/diag.log \
  | grep hit \
  | grep 2026-06-26 \
  | grep deepseek__deepseek

过滤后共有 309 条 cache hit 指标样本：

| Scope | 样本数 | 观测命中率 | 最新指标 | | ---------------------------------- | ------ | ---------- | ------------------------------------------------ | | deepseek-v4-pro / orchestrator | 86 | 98.0-98.3% | 98.1% 命中率，39,084,800 cache-read tokens | | deepseek-v4-flash / fixer | 196 | 86.1-99.2% | 99.0% 命中率，21,218,432 cache-read tokens | | deepseek-v4-flash / explorer | 27 | 0.0-90.3% | 预热后 90.3% 命中率，1,229,696 cache-read tokens |

其中 explorer scope 展示了冷启动效果：第一条样本为 0.0%，provider cache 预热后提升到 90%+ 命中率。

🔌 支持的平台

| 平台 | 状态 | 适配器 | | --------------- | ----------- | -------------------------------------------------- | | OpenCode | ✅ 原生插件 | src/index.ts | | Claude Code | 📖 指南 | adapters/claude-code.md | | Codex | 🔜 计划中 | 基于 OpenCode 插件适配 | | Gemini CLI | 🔜 计划中 | Google context caching |

🛠 缓存友好度审计

检查配置文件是否存在破坏缓存的模式：

bash scripts/check-cache-friendly.sh CLAUDE.md
bash scripts/check-cache-friendly.sh --opencode
bash scripts/check-cache-friendly.sh --all

🙋 FAQ

Q: 会修改我的 prompt 内容吗？ A: 只修改 system block 的顺序。内容从不改动。

Q: 会破坏 agent 功能吗？ A: 不会。LLM 看到的是相同的 blocks，只是顺序不同。System prompt 本身是无序的。

Q: 支持非 OpenCode 的 agent 吗？ A: 核心引擎是 CLI 无关的。OpenCode 有原生插件，Claude Code 有优化指南， Codex 和 Gemini CLI 适配器在计划中。

Q: 如果 prompt 内容变化了怎么办？ A: 哈希追踪会自动适应。之前稳定的 block 如果开始变化，其分数会下降并移到动态区。如果新增了稳定 block，几次观测后就会收敛到稳定区。

Q: 支持 Anthropic prompt caching 吗？ A: 支持。chat.headers hook 会自动为 Anthropic provider 添加 prompt-caching-2024-07-31 beta header。

📄 License

MIT — 随便用、随便改、随便发、记得点 star ⭐