Claude-thermos: 防止 Claude Code 中的 Prompt Cache 过期

Claude-thermos: 防止 Claude Code 中的 Prompt Cache 过期

Claude-thermos 通过保持 prompt cache 活跃来降低 API 成本

claude-thermos 是一个旨在消除 Claude Code 会话中“缓存税”的实用工具。它能防止当主代理（main agent）被子代理（subagent）阻塞超过五分钟时，prompt caches 发生静默过期，否则这可能会占到用户总 API 账单的约 20%。

问题所在：子代理执行期间的缓存过期

Claude Code 的 prompt cache 具有 5 分钟的生存时间（TTL）。虽然缓存的历史记录按输入价格的 0.1x 提供服务，但缓存未命中（cache miss）会迫使对话历史以 1.25x 的写入率进行完整的重新编码。在长会话中，这会变得极其昂贵，因为单个折叠（collapses）可能会重新写入 200K 到 500K 个 token。

缓存过期的主要触发因素不是用户不活动，而是子代理的行为。由于子代理使用不同的系统提示词（system prompts）和工具集，它们会创建不同的缓存前缀。当子代理运行时，主代理的缓存前缀保持不变。如果子代理的任务执行时间超过五分钟，主代理的缓存就会过期。当子代理将控制权交还给主代理时，主代理必须重新编码整个历史记录，从而导致高昂的成本。

claude-thermos 如何维护缓存

claude-thermos 通过将 ANTHROPIC_BASE_URL 指向回环端口（loopback port）来作为本地反向代理运行。它通过以下四个步骤管理缓存：

  1. 观察 (Observation)：代理监控 /v1/messages 流量，将请求分组为会话和“谱系”（lineages，由模型、工具集和系统文本定义）。它将第一个带有工具的谱系识别为主代理。
  2. 检测 (Detection)：它识别“危险窗口”，即主谱系处于闲置状态而子代理正在积极运行的时期。
  3. 预热 (Warming)：在 5 分钟 TTL 过期之前，代理直接向 Anthropic API 发送一个“预热请求”。该请求使用完全相同的可缓存前缀，但设置 max_tokens: 1 并禁用流式传输（streaming）。
  4. 刷新 (Refresh)：单个 token 会被丢弃；其目的是预填充（prefill），这会以廉价的读取率 (0.1x) 刷新完整的缓存前缀，从而避免昂贵的重写 (1.25x)。

安装与使用

claude-thermos 需要 Python 3.11+，并且系统 PATH 中已安装 claude CLI。可以使用 uvx 执行：

  • 标准运行：uvx claude-thermos（替代 claude 命令）
  • 带参数运行：uvx claude-thermos -p "fix the bug"（参数直接传递给 Claude CLI）

配置微调

用户可以调整以下可选标志来微调预热行为：

标志 默认值 含义
--idle 270 主代理在开始预热前必须闲置的秒数
--interval 270 含义：预热周期之间的秒数
--max-cycles 4 每个闲置阶段的最大预热次数 (auto 为无限)
--subagent-window 540 子代理被视为“仍处于活动状态”的秒数

若要在不更改命令的情况下禁用特定运行的预热，请设置环境变量 CLAUDE_WARMER_DISABLE=1。

追踪节省的成本

每个会话都会在 ~/.claude-thermos/logs/<session_id>/ 中生成日志，包含一个 events.jsonl 流和一个 summary.json 汇总文件。summary.json 文件提供以下指标：

  • warms_fired：发送的预热请求总数。
  • cache_read_total：预热期间读取的 token 数。
  • rewrite_avoided_tokens：如果缓存过期则会重新写入的 token 数。
  • net_savings：避免重写的成本 (1.25x) 与预热成本 (0.1x) 之间的差值，以基础输入 token 为单位衡量。

要计算实际节省的美元金额，请将 net_savings 值乘以模型的每输入 token 价格。

社区讨论与反方观点

社区对该工具的反馈集中在对缓存 TTL 的争论以及“预热”请求的伦理问题上。

缓存 TTL 差异

几位用户指出，对于 Pro 和 Max 计划，缓存过期时间可能是一小时而不是五分钟。

"我直接检查了 pro/Max 计划的调用，截至今天它们有 1 小时的缓存有效期... 如果你支付的是 API 费率，你可以自己选择 5 分钟或 1 小时。"

如果某些层级的缓存 TTL 确实是一小时，那么 claude-thermos 使用的 5 分钟预热间隔对于这些特定用户来说可能是多余或浪费的。

资源使用与伦理

一些用户表示担心，自动预热请求可能会导致“公地悲剧”，在不提供功能性输出的情况下增加 Anthropic 基础设施的负载。

"这只是让其他人的成本变得更高，对吧？... 我也不会要求自己时刻排在队列最前面。"

相反，其他用户认为，该工具迫使供应商解决有缺陷的缓存机制，这种机制惩罚了那些在需要子代理的代理工作流（agentic workflows）中使用的用户。

Sources