im.ttalk.agent.provider.common.cache — im.ttalk/clj-agent-provider 0.5.447

Anthropic Prompt Caching 策略层（对标 Spring AI AnthropicCacheStrategy）

======================================== 背景

Anthropic 通过在内容块上挂 cache_control 来缓存请求前缀，命中后该段 输入 token 仅按约 0.1x 计费。要点（以官方为准）：

• 渲染顺序：tools -> system -> messages。cache_control 标记的是"断点" (breakpoint)，断点之前的全部内容作为可缓存前缀。
• 单请求最多 4 个 breakpoint。
• 最小可缓存前缀与模型相关（Opus/Haiku4.5 = 4096 token，Sonnet4.x = 1024/2048）； 过短不会缓存（无报错，cache_creation_input_tokens=0）。
• 任意字节变化都会使该位置之后的缓存失效 —— 稳定内容靠前，易变内容靠后。

======================================== 策略（cache-strategy）

:none 不缓存（默认） :system 仅缓存 system :tools 仅缓存工具定义 :system-and-tools 缓存 system + tools（两个 breakpoint） :conversation 缓存到"当前用户问题之前"的对话历史 （标记最后一条消息的最后一个内容块） :tool-results 缓存到最后一个 tool_result（多轮工具循环里跨轮复用工具结果， 标记 messages 中最后一个 type=tool_result 的内容块） :system-and-conversation 同时缓存 system 与对话历史（两个 breakpoint）

ttl（:cache-ttl）两种形状：

• 标量：nil -> 默认 5 分钟；"1h" -> 1 小时；本策略的所有断点同一档（老用法）。
• 按断点给档的 map：键 :tools / :system / :conversation / :tool-results， 缺键或 nil = 5 分钟（cache_control 不带 ttl 字段）。典型： {:cache-strategy :system-and-conversation :cache-ttl {:system "1h" :conversation nil}} ⇒ 前缀（tools+system）1h、对话尾巴 5m——尾巴每轮被取代，付 1h 的 2× 写入费纯亏 （feedbacks/2026-11-10-provider-request-hook-and-two-tier-cache-ttl.md）。

服务端规则：长 TTL 的断点必须排在短 TTL 之前（渲染顺序 tools → system → messages）。 apply-anthropic-cache 在注入前校验，违者抛 ex-info（:type :invalid-cache-ttl）， 不等服务端 400。任一断点为 "1h" 时 anthropic provider 自动并入 beta extended-cache-ttl-2025-04-11（兼容端点如 MiniMax /anthropic 少了它会静默退回 5m）。

用法见 apply-anthropic-cache。

apply-anthropic-cache clj

(apply-anthropic-cache params strategy)

(apply-anthropic-cache params strategy ttl)

按策略给 Anthropic 请求参数注入 cache_control

参数:

• params: 已构建好的 Anthropic 请求参数（含 :system :tools :messages）
• strategy: :none | :system | :tools | :system-and-tools | :conversation | :tool-results | :system-and-conversation
• ttl: nil（5 分钟）| "1h"（1 小时）——所有断点同档； 或按断点给档的 map {:tools .. :system .. :conversation .. :tool-results ..}

返回: 注入 cache_control 后的 params

说明:

• :none 或未知策略 -> 原样返回。
• ttl 次序非法 / map 含未知键 -> 抛 ex-info（:type :invalid-cache-ttl），见 validate-ttl!。
• 注入后若断点数超过 4 会记到 meta，但不抛错（交由服务端校验 / 上层处理）。

breakpoint-count clj

(breakpoint-count params)

返回 params 中的 cache_control 断点数（测试 / 诊断用）

ephemeral clj

(ephemeral ttl)

构造 ephemeral cache_control

(ephemeral nil) ; => {:type "ephemeral"} (ephemeral "1h") ; => {:type "ephemeral" :ttl "1h"}

extended-ttl-beta clj

1 小时缓存 TTL 的 beta 名。官方端点已 GA（多发无害）；兼容端点缺它会静默退回 5m。

extended-ttl? clj

(extended-ttl? strategy ttl)

该策略实际打的断点里是否有 "1h"（决定要不要并入 extended-ttl-beta）。

max-breakpoints clj

Anthropic 单请求 cache_control breakpoint 上限

ttl-for clj

(ttl-for ttl slot)

断点 slot 的 TTL：ttl 是 map 就按 slot 取（缺键 = nil = 5m），否则标量即全部同档。

validate-ttl! clj

(validate-ttl! strategy ttl)

校验 ttl 对 strategy 合法，返回 ttl。

• map 只认 :tools / :system / :conversation / :tool-results 四键（拼错的键会 静默落成 5m，所以当场抛）；
• 按渲染顺序，长 TTL 的断点必须排在短 TTL 之前（服务端规则）。