# cache_control 透传 — 设计

> 调用方标在 content block 上的 `cache_control` 如何原样到达 Anthropic Messages
> API 请求体，使 prompt 缓存断点落在调用方指定的位置，而不是 provider 猜的位置。

## 1. 问题

像 GUI-Agent-Harness 的 screenspot 定位器这样的调用方，清楚自己 prompt 里哪一段是
稳定的：一大段固定规则，后面跟动态文本和截图。它希望缓存断点就打在这段稳定前缀之后。

没有透传时，写进 content dict 的 `cache_control` 会在 OpenProgram 内部被丢弃，
唯一生效的断点是 provider 自动加在最后一块上的那个。而最后一块是图或动态文本，
每次请求都不同，缓存永远不会命中。

适用范围：只对 **anthropic** 一类 provider 有效——原生 Anthropic API、经代理的
Claude Code 订阅、以及任何 anthropic-messages 接口。OpenAI / codex 一类用的是
自动前缀缓存，不读 `cache_control`，这个字段对它们是惰性的。

## 2. 透传路径

`cache_control` 是一个可选字段，原样穿过三层。

**内容类型**（`openprogram/providers/types.py`）。`TextContent` 与 `ImageContent`
各带一个 `cache_control: dict | None = None`。视频和音频没有——目前没有调用方标它们。
该值是一个不透明 dict，如 `{"type": "ephemeral"}`，也可能带 `ttl`。OpenProgram
不解析也不校验其内容；调用方写什么，Anthropic 就收到什么。

**上下文构建**（`openprogram/agentic_programming/runtime.py` 的
`_build_pi_context`）。把调用方的 `content: list[dict]` 转成 `TextContent` /
`ImageContent` 对象时，每块的 `cache_control` 一并复制到对象上。`role == "system"`
的 text block 是例外：它被单独抽成 `system_text`，不带逐块断点，因为 system 的断点
由 Anthropic provider 的 `_build_system` 另行安排。

**wire 构建**（`openprogram/providers/anthropic/anthropic.py` 的 `_build_messages`）。
从内容对象重建 API block 时，对象上带了 `cache_control` 就写进生成的 dict。这只涉及
`UserMessage` 的 list content 分支；字符串 content 分支、`AssistantMessage`、
`ToolResultMessage` 不存在调用方逐块标记，不受影响。

不传 `cache_control` 的调用，生成的请求体与该字段存在之前完全一致，所有现有调用方
零影响。

## 3. 自动断点与调用方断点

provider 仍然会自行在一条消息的最后一块上打断点。协调二者的规则是：

> 一条消息里只要有任意一块带了调用方标的 `cache_control`，provider 就完全不再给
> 这条消息的最后一块自动打断点。

判断方式是 `caller_marked = any("cache_control" in b for b in content_blocks)`。
这比「只是不覆盖最后一块」更彻底。当调用方把断点标在靠前的稳定前缀上时，动态尾块上
的自动断点会白占四个名额中的一个，还会把缓存边界推到每次都变的那段内容之后。
干脆抑制掉，调用方的意图就成了这条消息里唯一的断点。

## 4. 调用方必须遵守的边界

**最小可缓存前缀**。一个断点只有在它之前的内容至少 1024 token（Haiku 是 2048）时
才真的缓存。低于这个量，Anthropic **静默忽略**——不报错，也不命中。标了一段短前缀
的调用方会看到 `cache_read` 一直是 0，然后去排查一个并不存在的透传 bug。

**每请求最多 4 个断点**。OpenProgram 自己已经加了大约两个（system 块和最后一块）。
超过 4 个 Anthropic 直接返回 400。调用方大约只剩两个名额。

**代理是否透传**。claude-code 订阅走 Meridian 代理时，若代理把 body 里的
`cache_control` 剥掉，无论 OpenProgram 发出什么，`cache_read` 都是 0。这是代理层的
性质，需要单独验证；对同一段固定前缀连发两次、看第二次返回的 `cache_read` 是否 > 0，
可以把 OpenProgram 和代理一起验掉。

**其它 provider**。OpenAI 与 codex 的 block 构建是逐字段读的（`openai_completions`
和 `_shared/transform_messages` 里的 `.text` / `.data`），responses 与 codex 路径上
那两处 `model_dump()` dump 的是选项对象而非内容块，所以这个新的可选字段不会泄漏进
它们的请求体。`TextContent.model_dump()` round-trip 也是干净的，持久化不受影响。

## 5. 属于调用方而非 OpenProgram 的部分

把 prompt 拆成「固定规则做第一个 text block 并标记它」是调用方的改动——对 screenspot
而言在 `GUI-Agent-Harness/screenspot_locator.py`。OpenAI / codex 一类的前缀缓存优化
只需要调用方把稳定前缀前置，完全不用改 OpenProgram。

## 附录：实现状态

已在 `providers/types.py`、`runtime._build_pi_context`、`anthropic._build_messages`
三处实现，含 §3 的自动断点抑制规则。测试见
`tests/unit/test_cache_control_passthrough.py`（6 例）：runtime 到 Anthropic body
的全链路透传、图片透传、不传时 body 字节级不变、无调用方断点时自动断点照常生效、
调用方标最后一块时不被覆盖、调用方标靠前块时自动断点被抑制。§4 中「非 Anthropic
provider 零泄漏」这一条已通过阅读 OpenAI 与 codex 的 block 构建路径核实。代理透传是
唯一尚未实测的边界。