perf(gateway): add reproducible token-cost and latency baselines #2467

规划入口：#2433

源码复核基线：1190dcbbb492。开工时检查最新 master 和相关 PR；下面描述的是核查时的实际行为，不要求回退已有修复。

本轮定位、优先级与阶段

本轮交付执行底座、可靠性和度量基线；token 优化与真实收益由后续独立实验验收。整体按团队每周约 80 小时有效投入估算 6–8 周，实际日期以依赖和验收结果为准。

G8-A 的方法、验收表和基础测量可提前进行，真实运行只依赖 G7-A；G8-B 的完整成本/重放组为 P2，依赖 G4/G5-B/G6。基础对照不以增强会话完成为开工条件。

先行 PR、显式依赖与交付责任

当前认领人负责在首个基准 PR、首次执行前固定 #2433 第 5.2 节的预算、环境/负载清单和改动前 Gateway/Core 提交。G7-A 可用后的前 1–2 人日优先跑前两个基础对照并保存结果，不等待 G4/G5-B/G6。

即使基准底座晚于安全修复，也使用独立构建目录重建钉住的改动前提交，再在同一环境/方法下执行候选提交。归档机器可读结果、样本与复现命令；安全修复可先合，但性能增益声明必须有改动前/后对照。

缓存占比统一使用 cache_read_tokens / total_input_tokens。OpenAI Responses 的 input_tokens=1200 已含 cached_tokens=1000，占比约 83.3%；Anthropic Messages 若未缓存 200、创建 100、读取 900，总输入为 1200，占比 75%。保留必要原始计数和映射版本，创建内部细分不重复相加，字段未知记 unknown；协议例子和官方依据见 #2433 第 5.3 节。

目标

为“省 token、强隐私、高性能”建立可复现基线、预算表和结果格式；按声明负载预登记工程预算，以同等强制检查与任务质量约束判断收益。真实 token/费用节省比例由实测确定。

范围与代码所有权

• 独立的 Gateway benchmark/评估命令、合成 workload、结果 schema、中文/英文复现文档。复用 G7 · #2466 的真实进程 fixture，消费 G4 · #2463 的证据字段。
• 优先使用现有 evaluation 目录/工具模式，为 Gateway 增加有界入口；不为基准重构业务执行器，不重复加 instrumentation。
• 与已有 SWE-bench Pro 实验区分：本任务的受控基线不是任务质量已证实提升或真实模型节省声明。

G8-A / G8-B 的交付与预算

• G8-A： 先做验收表、负载与报告入口；G7-A 真实进程底座可用后跑前两个基础对照，不等待 G5-B/G6。外部客户端计时和资源采样可先用；usage/费用结果待 G4 接通后补齐。
• G8-B： G6 完成后增加准确重放对照，G5-B 完成后补完整容量/回收，消费 G4 真实用量。缺失的组明确未完成；阶段 PR 可先合入，完整 Issue 不以基础组代替增强组验收。
• 初始预算见 PowerContext Gateway 首轮工程计划：执行底座、可靠性与度量基线 #2433 第 5 节，均为待实测工程目标：同机真实 Core/Gateway + 固定延迟 20 ms 的本地 provider；S（输入/输出各 8 KiB，并发 1、8）增量 P99 ≤ 20 ms、完成吞吐 ≥ 同等检查直连的 90%；L（各 256 KiB，并发 1、4）增量 P99 ≤ 50 ms、吞吐 ≥ 对照 80%。
• 每组预热至少 200 次，至少 2,000 个完成样本，交错配对 3 轮；错误/超时/拒绝全部报告。CPU/RSS、逻辑字节、阶段耗时与实际平台/资源配置完整记录，容量不足的组标不支持。
• 增量定义为 P99(Gateway) - P99(同等检查直连)，测到 strict 首次内容释放。预算在运行前固定；未达标保留失败结论。后续调整需说明资源/负载依据并在下一轮前固定，不倒改历史结果。

要交付的对照

1. 同等必需检查与 strict 释放语义下的直连基线。
2. 经 Gateway、关闭可选增强，测量本地额外开销。
3. 相同 prepared 内容的准确重放，检查 prepare 次数、最终原生前缀和实际可观察变化；依赖 G6 · #2465。
4. 表示或原生缓存适配只作为单独增量；未交付则标为不适用，不能用模拟缓存命中补结果。

直连基线必须实际执行同等输入/输出检查与缓冲；裸连 provider 可另外报告，但不能拿它与有强制检查的 Gateway 直接相减后称为纯网关开销。

测量与边界

• 固定 commit、环境、协议、部署、目标、请求/响应分布、并发、冷/热、持续时间和样本量。覆盖小请求、接近真实检查上限、混合大小、慢 provider/客户端、取消和资源回收。
• 报告完成吞吐、P50/P95/P99、CPU/RSS、逻辑保留字节、错误/超时、首字节/完整响应/首次内容释放；阶段耗时按实际测量分开。
• 非流式 JSON 和合成 SSE 的首个事件不能冒充模型 TTFT；缺失值保持 unknown。
• 完整任务成本要覆盖主辅模型、prepare/工具/修复次数、input/output/cache read/cache write 和所有已知/未知尝试。供应商语义未对齐时不混算。
• 本地 provider 的 usage fixture 只验证采集与统计逻辑；不能据此发布真实 token/价格/缓存节省。真实 provider 实验使用明确授权预算单独运行，不在 CI 自动影子调用。
• 工作负载实际输入增加时，不能仅凭缓存命中称为省 token；真实任务质量未执行时明确未验收。

验收标准

• 一条命令可重复运行并输出机器可读结果和简明报告，包含失败/缺失覆盖率。
• 三个适用对照的检查/释放语义可核对；测试底座实际经过真实 Gateway/Core listener。
• G5 · #2464 的容量范围用于负载边界，超限/取消资源可回收；结果不把逻辑预算当 RSS。
• 在优化前填写适用负载下的目标预算，并报告达标/未达标；不能先看结果再倒填门槛。
• 至少保存一个声明环境的实测本地基线及复现命令；真实任务质量、模型费用、provider cache 与宿主等待分别标明执行情况。
• 报告可支持后续优化选择，但没有数据时不宣称“Rust/UDS 已高性能”或全任务成本已降低。

依赖、非目标与周期

负载设计、报告 schema 和直连对照可现在开始；可读取证据依赖 G4 · #2463，真实进程环境依赖 G7 · #2466。准确重放组依赖 G6 · #2465；完整容量/压力验收依赖 G5 · #2464，缺失的组不能标通过。

#2413/#2435 的 prefix extraction、#2414 的 reconciliation 成本、#2127 的领域预算各自负责优化，本任务可消费其结果，不重新实现。Core 内部按工作负载显式选模继续由 Discussion #2015 承接，不增加 Gateway 分类器。

预计 4–6 人日，不含收费 provider/完整宿主实验等待，不建设性能平台或自动发布系统。

源码入口

• gateway/README.md
• gateway/crates/pc-gateway-evidence/src/lib.rs
• gateway/crates/pc-gateway-transport/src/reqwest_transport.rs
• tests/evaluation
• docs/zh/rfcs/2199-powercontext-gateway.md

交付要求

• PR 保持此 Issue 的范围；涉及公共 HTTP 契约时从 openapi/powercontext.yaml 修改并重新生成，执行 make api-generate、make contract-test，不手改生成代码。
• 同步适用的中英文契约、部署说明和迁移行为。选择与变化风险匹配的 focused checks，按仓库规范完成必要检查；提交证据注明 commit、平台、命令及实际覆盖。
• 本地可控 provider、真实 Core、真实 provider、真实宿主是不同证据等级。未执行的范围明确列出；本 Issue 不要求社区贡献者承担真实模型费用。
• 验收依赖满足后才关闭 Issue；分阶段 PR 可以先合入，但不能把接口存在或 mock 通过写成端到端能力已交付。