[Feature] Anthropic协议下自动注入cache_control断点以启用缓存，减少模型的输入价格

[youzijiang233]

Description / 描述

OpenAI 协议的缓存是服务端自动触发的,AstrBot 在 openai_source.py 里直接从 prompt_tokens_details.cached_tokens 读到命中数即可。
但 Anthropic 协议的 Prompt Caching 是显式的:必须在请求体里给tools / system / messages 的内容块手动cache_control: {"type": "ephemeral"}断点,服务端才会按前缀缓存。
目前 anthropic_source.py 在构造请求时没有添加任何 cache_control 断点:

结果是:

• _extract_usage 里读取的 cache_read_input_tokens 实际上恒为 0;
• 多轮对话 / 长 system prompt 场景下,每次请求都按全价计费输入 token,无发缓存,
  无法享受 Anthropic 缓存读取约 0.1x 的优惠。

建议

在 Anthropic 请求构造阶段自动注入 cache_control 断点,常见放置点:

1. system prompt:在最后一个 system text block 上加断点(会连带把它前面的 tools 一起缓存)。
2. 多轮对话:在最近一轮 messages 的最后一或者二个内容块上加断点,让历史前缀被复用。

可选项

• 增加一个配置开关(如 anthropic_prompt_cache: true/false),默认关闭或开启由维护者决定;
• 仅对长度超过模型最小可缓存前缀(Claude 多为 1024~4096 token)的请求注入。

参考

Claude APIDocs-Prompt caching

• https://docs.claude.com/en/docs/build-with-claude/prompt-caching

Use Case / 使用场景

在使用 Anthropic（Claude）系列模型时，常见两类高频场景会重复发送相同的前缀内容：

1. 长 System Prompt / 人格设定：很多用户给 Bot 配置了较长的人格、世界观或规则说明（几千到上万 token）。这部分内容每轮对话都完全相同，但目前每次请求都按全价重新计费输入 token。

2. 多轮对话：群聊/私聊持续对话时，历史消息作为前缀被反复发送，轮次越多前缀越长，成本随轮次线性增长。

OpenAI 协议下这两类场景能自动命中服务端缓存（cached_tokens），但 Anthropic 协议必须在请求里显式打 cache_control 断点才会缓存。由于当前适配层没有注入断点，Anthropic 用户实际上完全享受不到 Prompt Caching：
缓存命中本可让缓存部分的输入降到约 0.1x 计费，长 system prompt + 多轮对话场景下能显著降低 API 成本和首 token 延迟。

Willing to Submit PR? / 是否愿意提交PR？

• Yes, I am willing to submit a PR. / 是的，我愿意提交 PR。

Code of Conduct

• I have read and agree to abide by the project's Code of Conduct. /