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 是否一致。不记录认证头或其他请求头正文。稳定标识提供路由亲和条件，实际命中仍取决于前缀和上游缓存。
 

docs/releases/2.5.0.md

@@ -0,0 +1,46 @@
+# ARTEMIS 2.5.0
+
+本版汇总正式 2.4.5 之后的动作执行、模型流式调用和缓存可观测性改进。Flash 和 Pro 可在一次调用中完成需要紧接着执行的界面操作，异常参数流有更准确的诊断与收尾；执行模式弹窗增加缓存 Token 与加权命中率。
+
+## 通用动作序列
+
+- 新增 `action_sequence`，由 AI 组合点击、等待、拖动和临时控件准备步骤，可用于自动隐藏面板等多种界面，不绑定某个应用或某个缩放按钮。
+- 新增 `ensure_visible`：使用实际观察到的控件 resource ID 判断面板是否已展开；未展开时点击一次入口，并在有限时间内等待目标出现。准备与后续操作留在同一次调用中，减少模型往返超过控件显示时间的问题。
+- 序列点击可按实际 resource ID 重新解析当前边界；缺失或存在歧义时拒绝输入。重复点击可在一个成员内连续完成，每次重新检查目标。仍支持明确声明坐标空间的坐标点击。
+- 输入前校验整组成员，受现有快速动作上限约束。执行遇到首个失败即停止，回执保留已完成、跳过及未执行成员和已完成点击次数；部分执行后不能盲目重放整组动作。
+
+## 滑块与时间轴拖动
+
+- 新增 `drag`，明确区分截图原始像素和 0..1000 归一化坐标，支持拖动持续时间及面板可见性前置检查。
+- 可直接提供起终点，也可使用当前截图中两个已观察的数值刻度计算目标位置；分别支持移动滑块和在固定指示线下平移刻度。边界、无效刻度、零位移和不可达目标在输入前拒绝。
+- Flash、Pro、检查与验收流程同步认识新动作，截图标注和历史摘要保留实际动作回执及坐标空间，避免把跳过或拒绝的动作当成执行成功。
+- 对最大值、最小值和时间定位加强证据要求：手柄接近端点、事件卡片时间或一次未变化的截图不能独立证明已到极限，需核对实际输入回执和最终刻度或原生数值。
+
+刻度校准依赖当前画面的测量，不能替代业务结果验证；惯性滚动、界面重绘和应用自身限制仍可能影响最终位置。
+
+## 模型参数流与取消处理
+
+- 将 `action_sequence`、`drag` 接入小型内置动作的 16384 字符参数流保护。异常参数不进入设备输入，沿用有限的新响应重试及备用端点策略；不会因此创建全局模型暂停。
+- 分批聚合流式片段，减少半截 JSON 反复解析的开销；参数检查、诊断和界面输出仍逐片段进行，原异步历史压缩路径保留。最终完整性与 JSON 校验不放宽。
+- 参数超限后先关闭 HTTP 流再等待重试；低于长度上限但一直未完成的参数，仍由请求超时、任务超时和用户停止中断。关闭有独立等待上限，关闭失败留有记录，不把用户停止变成可重试超时。
+- 在现有请求诊断中增加原始 Responses SSE 与 SDK 两个边界的有界统计：参数空白、增量长度、连续相同增量、事件序号跳变和非递增、取消阶段、关闭结果以及各阶段耗时。临时帧在关闭时释放，日志不保存参数正文。
+- 记录实际请求与响应回显的工具约束，区分 `strict` 省略、false 和 true；本地 Pydantic 严格校验不等于上游严格生成。不会直接将所有工具改成 strict=true，也不将通道可能忽略的输出 token 上限当成可靠保障。
+
+已有异常样本在官方上游返回时就持续增长；本版修复本地消费和收尾问题，补齐诊断与保护，尚不能宣称模型或上游服务的参数膨胀已根治。详见[参数流诊断说明](../llm-stream-diagnostics.md)。
+
+## 缓存路由与运行信息
+
+- 默认请求继续为同一会话、角色与模型发送一致的 `prompt_cache_key`、`Thread-Id` 和 `Session-Id`。仅显式传入会话请求头时，未指定的正文缓存键和另一种会话头沿用该值，兼容大小写及下划线写法；不修改共享 HTTP 客户端的默认头，保留显式覆盖。
+- 执行模式弹窗显示本任务累计缓存 Token 和按输入 Token 加权的命中率，支持 Flash、Pro、探索及历史任务。运行中每 3 秒刷新；加载、失败与无有效用量分别显示。缓存 Token 包含在输入总量中，不重复计入合计。
+- 补充[网关亲和规则说明](../ai-automation.md#网关亲和规则)：会话键可用于选中渠道，请求诊断编号不应作为缓存亲和键。统计以实际服务端用量为准；稳定路由不等于已命中缓存，本版未修改生产网关配置或承诺固定收益。
+
+## 兼容性与验证范围
+
+- 新动作需要 ARTEMIS 2.5.0；原有动作与插件清单保持兼容。2.4.5 的插件开发 SDK 随主程序继续提供，远程 `artemis-client`、市场插件和第三方依赖本次不升版。
+- 升级主程序不会自动更新或授权插件，不改写已保存的模型、接口、重试或功能配置。
+- Python 默认回归、质量检查、前端回归及最终 ZIP 在独立空 npm 缓存下的官方源和国内镜像安装、生产构建结果，随附件 `INSTALL-VERIFICATION.md` 提供，记录实际运行时、源码提交及 ZIP SHA256。
+- 本次发布不新增真实设备或付费模型测试。此前实测中保留了未通过或无法判定的任务，工具调用成功不等于业务稳定性验收通过；不以一次成功宣称自动隐藏控件问题已全部解决。
+
+## 升级
+
+已有安装请等待任务结束，运行 `update-cn.bat` 或 `update.bat`，然后重启 ARTEMIS；Codex 用户同时重新加载 MCP。新安装下载 `artemis-2.5.0-source.zip`，按 `SHA256SUMS.txt` 校验后启动，不直接覆盖旧安装目录。