请求侧缓存工程

上游前缀缓存命中的 token 价格约为未命中的 1/10。 大多数产品在响应侧「猜测相似性」；CCHarness 把智能放在请求侧—— 主动制造可缓存性，把命中率从运气变成可运营的指标。

三区模型

每个出站请求按字节稳定性拆成三区，静态内容前移、动态内容后置：

Zone S  冻结区   system prompt，会话内一次写定，字节永不变化
Zone H  历史区   append-only：已发送内容以预序列化字节入史，任何组件不得改写
Zone T  尾区     本轮新增（用户消息），下一轮落入 H 成为稳定前缀

请求体由预序列化片段按字节拼接组装，保证 provider 看到逐字节相同的前缀—— 这正是上游前缀缓存命中的前提。

缓存档位：默认 / long / short / none

自 v0.1.6 起，每个 Provider 可在「模型管理」中选择缓存档位，按协议语义控制缓存窗口：

• 默认：Anthropic 请求在系统提示块与最新一条消息上标记 cache_control: {"type":"ephemeral","ttl":"1h"}（自 v0.1.4），把缓存窗口从默认 5 分钟延长到 60 分钟——会话搁置一小时以内回来继续聊，Zone S+H 前缀依然命中；OpenAI 兼容端点只携带 prompt_cache_key 路由键，窗口由上游自动管理；
• long：延长窗口——Anthropic 维持 1 小时标记，OpenAI 端点追加 prompt_cache_retention: "24h"（GPT-5.x / 4.1 系支持，闲置后仍可命中长保留缓存）；
• short：协议默认窗口——Anthropic 发不带 ttl 的 5 分钟 ephemeral 标记（写入溢价更低），适合高频连续对话；
• none：不携带任何缓存标记与路由键（cache_control / prompt_cache_key 全部省略）， 严格网关最安全，代价是放弃前缀缓存。

system  ─▶ [{ "type": "text", "text": …, "cache_control": { "type": "ephemeral", "ttl": "1h" } }]   ← 默认 / long 档
最新消息 ─▶ 内容末块追加 cache_control（增量断点：下一轮的 Zone H 前缀由此命中）

标记位置遵循 Anthropic 断点语义：系统块为稳定断点，最新消息为增量断点， 每轮随对话推进自然前移。档位切换会重建该会话的缓存纪元——属于「预期重建」， 遥测不会把它误判为意外 miss。

协议适配方面，v0.1.6 新增 OpenAI Responses 与 Azure OpenAI（Responses）两种适配器： GPT-5.x / o 系列原生接口走 {base}/responses（顶层 instructions 携带系统提示、 历史转换为输入条目、工具表扁平化，store:false 不在服务端留存会话），Azure v1 数据面使用 api-key 请求头认证。Responses 路径同样由三区字节稳定前缀驱动——历史区片段被确定性转换为协议条目， 跨轮字节逐位相同，前缀缓存命中语义与 chat/completions 完全一致。

指纹链与纪元

• SHA-256 增量指纹链逐请求跟踪前缀演化，任何字节级劣化都无所遁形；
• 纪元（Epoch）：模型切换等事件开新纪元，遥测把「预期重建」与「意外劣化」分开统计，不让正常换模型背上缓存损失的锅；
• 重启零损失：会话重生、分支、导入全部保持字节稳定，重启后前缀原样恢复。

miss 分歧定位

provider 报 0 命中而本地指纹链完整时，按请求形态自动归因—— 链断裂 → 前缀回退 → 尾区过大 → 上游丢失，每条 miss 附处置建议， 而不是一句「缓存未命中」把你打发走。

AuxMemo 辅助调用精确缓存

标题生成、提示词优化等幂等辅助调用走 L1 内存 LRU + L2 加密磁盘双层缓存： 相同输入零 API 调用、零计费。同样的钱，多干一倍的活。

遥测面板

命中率曲线、逐请求账本、成本换算、miss 归因全部内置—— 你能看清每一个请求花了多少钱、省了多少钱、为什么没省。