feat: add cache routing alignment and usage visibility for 2.5.0

docs/ai-automation.md

@@ -151,7 +151,17 @@ Flash、Pro（启用 transcript）和探索共用分阶段上下文。一个阶
 
 以上为适配后消息的本地指纹比较，不是网关最终序列化后的 token 前缀，也不是命中率。诊断仅持有哈希，不额外保存提示词、图片正文或凭据。实际缓存率按上游返回的 `cached_tokens / input_tokens` 加权统计，usage 缺失不能当作零命中。首次请求、阶段压缩、模型/工具切换可能降低缓存率；网关的路由、缓存保留时间和实现也会影响结果。该实现使用完整多轮消息，不依赖网关支持 `previous_response_id`，也不承诺固定命中率。
 
-执行模型、视觉摘要和历史摘要的 Responses 请求均按“探索会话（普通任务用任务 ID）＋角色＋模型”生成稳定的匿名 `prompt_cache_key`，并在 `Thread-Id`、`Session-Id` 请求头中发送相同值。标识符合 `^[-0-9A-Za-z._:]{1,128}$`；暂停继续时保持稳定，不同任务或角色隔离。网关可从头部或 JSON 字段提取路由键，不依赖特定 User-Agent，也不会伪装为 Codex。标识在每次调用时设置，不写入共享 HTTP 客户端，避免并发任务互相覆盖。显式传入的缓存键及会话请求头优先。
+执行模型、视觉摘要和历史摘要的 Responses 请求均按“探索会话（普通任务用任务 ID）＋角色＋模型”生成稳定的匿名 `prompt_cache_key`，并在 `Thread-Id`、`Session-Id` 请求头中发送相同值。标识符合 `^[-0-9A-Za-z._:]{1,128}$`；暂停继续时保持稳定，不同任务或角色隔离。网关可从头部或 JSON 字段提取路由键，不依赖特定 User-Agent，也不会伪装为 Codex。标识在每次调用时设置，不写入共享 HTTP 客户端，避免并发任务互相覆盖。显式传入的缓存键及会话请求头优先。仅指定会话请求头时，正文中缺省的缓存键依次沿用有效的 `thread-id`、`thread_id`、`session-id` 或 `session_id`（头名称不区分大小写）；补齐缺少的另一种会话头，但不添加同义别名。调用方同时显式指定不同的键时保留原值，应自行保证一致。
+
+#### 网关亲和规则
+
+网关透传 `Thread-Id` / `Thread_id`、`Session-Id` / `Session_id`，并从这些请求头或 JSON 的 `prompt_cache_key` 提取亲和键，即可覆盖 ARTEMIS 默认请求。默认这三个值相同，无需重复添加下划线头或 `X-Codex-Window-Id`。`pass_headers` 只负责透传，选中渠道和模型前缀缓存是否命中仍取决于服务端实现；不能仅凭头部存在宣称命中。
+
+`X-Client-Request-Id` 是每次尝试独立的诊断编号，可继续透传，但不要加入缓存亲和键来源。`User-Agent`、`Originator` 和 Codex 专用头也不应替代 ARTEMIS 的会话键。保留其他客户端需要的透传项即可；本版不修改生产网关规则。
+
+执行模式弹窗显示本任务所有已记录模型调用的缓存 Token 和加权命中率：`累计 cached_tokens ÷ 累计 prompt_tokens`。缓存输入已包含在输入总量中，不能再相加；不平均每次调用的百分比，也不把命中请求数当成 token 命中率。打开弹窗后运行中每 3 秒更新，历史任务读取已保存统计；没有有效输入用量时显示 `—`，请求失败有明确提示。统计以服务端上报为准，未上报的缓存量按 0 汇总，旧任务漏记的数据不会回填。
+
+模型缓存还要求可复用的上下文前缀，路由稳定不能保证命中或节费。参考 [OpenAI 官方缓存说明](https://developers.openai.com/api/docs/guides/prompt-caching)。
 
 有请求诊断的调用同时发送 `X-Client-Request-Id`，默认与 trace 内的 `request_id` 一致，便于对照 API 日志。`request_sent_at` 表示实际发送时间；`routing_header_fingerprints` 只记录发送的会话头的哈希，`client_request_id_matches` 表示关联 ID 是否一致。不记录认证头或其他请求头正文。稳定标识提供路由亲和条件，实际命中仍取决于前缀和上游缓存。