feat(openai): 对齐 GPT-5.6 模型族与 Codex 请求协议

[MMEXA]

目标与范围

对齐 GPT-5.6 Sol、Terra、Luna 模型族以及 Codex Responses、Responses Compact、Search 的请求协议、模型能力、服务层级、计费事实和管理配置。实现遵循 Aether 的格式注册、请求规划、候选调度、Usage 归一化和结构化计价链路，各入口共享同一组协议能力与校验规则。

GPT-5.6 模型与推理能力

• 注册 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 的 Codex 模型卡，覆盖上下文窗口、可见性、优先级、最低客户端版本、默认推理强度、可用推理档位、Responses Lite、服务层级、工具能力和提示缓存能力。
• OpenAI 请求契约统一处理 none、low、medium、high、xhigh、max；模型卡按各自声明的 effort 集合执行精确校验，GPT-5.6 Codex 模型的可用档位从 low 起。
• Responses 的 reasoning.mode 支持 standard|pro，effort 缺省值为 medium；reasoning.context 支持 auto|current_turn|all_turns。
• Codex ultra 是客户端推理预设，提供商请求统一映射为 max；其余自定义强度保持精确字符串语义。
• reasoning.summary 的传输值限定为 auto|concise|detailed；配置值 none 表达字段缺省，并同步省略 stream_options.reasoning_summary_delivery。
• 模型卡能力字段 supports_reasoning_summary_parameter 控制 summary 投影；能力值为 false 时，effort、context、reasoning 包络和加密 reasoning 内容仍按各自能力处理。
• 远程 /models 元数据进入统一能力解析器，采用区分大小写的精确匹配和最长前缀匹配。远程字段覆盖对应内置字段，缺失字段复用内置能力，未知模型使用保守能力集合。

Codex Responses 请求

• 模型目录请求携带 client_version=0.144.1；Codex 提供商边界使用 user-agent: codex_cli_rs/0.144.1 与 originator: codex_cli_rs。
• 提供商身份头按大小写无关语义去重并写入规范键，普通 OpenAI SDK 客户端身份头不会进入 Codex 上游请求。
• 普通 Responses 在 tool_choice 缺省时写入 auto，显式值保持调用方语义；store=false、加密 reasoning include、服务层级过滤、开发者指令、工具投影、图片 detail 清理和内部请求头均由统一 Codex 请求契约生成。
• Responses Lite 使用 reasoning.context=all_turns，保留 function、namespace、custom 工具以及客户端 tool search 语义。
• 请求规划器集中决定 zstd level 3 压缩；prompt_cache_key 只采用显式配置或线程标识；input item id 透明保留客户端提供的值。

Claude 工具错误到 Responses 的协议映射

• Canonical ToolResult.is_error 保留为格式无关的内部语义；OpenAI Responses 的 function_call_output 只写入协议字段 type、call_id、output。
• 错误结果通过合法 output 表达：非空内容编码为 [tool error]\n<detail>，空内容编码为 [tool error]。字符串、对象和多段 Claude 内容遵循同一规则。
• Claude 多段工具结果中的文本进入 function_call_output.output，图片和文件继续使用既有的额外 user content 投影，错误标识不会改变媒体可表示性与顺序。
• 普通 Responses 与 Responses Compact 共享请求 input 构造；Canonical Response 到 Responses 输出构造复用相同编码函数。is_error=false 的输出保持现有语义。

Responses Compact

Compact 采用独立的精确字段投影，传输体仅包含：

• model
• input
• instructions
• tools
• parallel_tool_calls
• reasoning
• service_tier
• prompt_cache_key
• text

store、client_metadata、include、stream、stream_options、tool_choice 不进入 Compact 传输体。body rules 无权向终态请求引入投影集合之外的字段。Compact 使用同步 unary 响应、Codex OAuth 通道和 x-codex-turn-state，请求侧不启用 zstd 与 SSE headers。

Codex Search

• OpenAiSearch 作为正式 FormatId 注册，公开入口为 /v1/alpha/search，Codex 上游路径为 /backend-api/codex/alpha/search。
• Search 请求按类型投影顶层字段 id、model、reasoning、input、commands、settings、max_output_tokens；结构化子对象使用明确 allowlist，input 支持字符串与 Responses item 数组。
• Search 沿用 Codex OAuth、账户、FedRAMP、会话和客户端身份头，不启用 Responses Lite、Responses beta、SSE 或请求压缩。
• 上游响应按同步 JSON/字节语义透传。4xx 与 429 为终态响应；5xx 与传输错误进入候选故障转移，语义与 Codex Search 客户端保持一致。
• Responses 对 Search 的兼容关系通过统一格式权限函数表达为单向 companion permission，提供商密钥范围、候选查询、模型映射、管理端模型测试和端点计数共同复用该规则。授权快照在动态组策略确定后统一交由数据层计算用户与密钥范围的有效交集。路由身份和端点身份仍按精确格式匹配。
• 固定 Search 端点由提供商启动协调器维护，仅作用于 Codex 提供商；继承默认路径的端点跟随协议默认值，自定义路径保持管理配置语义，密钥格式范围不由端点协调过程改写。
• 管理端密钥统计区分显式范围与固定提供商继承范围：显式范围及 null 无限制范围按全部现存端点计算，停用端点仍能展示密钥关联；Codex OAuth 等继承型密钥只继承启用端点。Responses → Search 单向覆盖和 [] 拒绝全部语义在两类统计中保持一致。

超时配置与执行链路

• 普通非流式请求默认超时为 300s，用户可配置上限为 1200s。
• 流式首字节默认超时为 30s，可配置上限为 300s。
• Compact 使用独立的 1200s 同步执行默认值。
• 配置上限只负责输入校验；显式配置的 900s、1200s 会沿执行计划、Gateway 内嵌 relay、独立 tunnel 与 owner relay 元数据原值传递，执行层不进行 300s 或 600s 静默截断。
• owner relay 元数据缺失、非法或发生整数截断时返回明确的 400，不会转为无界请求或替换成其他超时值。

该边界允许 Flex 任务采用官方示例中的 timeout=900，同时保持普通请求和流式请求的默认行为。

Gateway 自动并发编译边界

• Gateway 运行时按 CPU 并行度与文件描述符预算计算自动请求并发上限，显式 max_in_flight_requests 仍具有配置优先级。
• automatic_gateway_request_concurrency_for_parallelism 只为确定性单元测试提供无文件描述符输入的便捷入口，使用 #[cfg(test)] 限定到测试构建。生产二进制继续调用容量与文件描述符共同参与的运行时函数。
• 自动并发的缩放、上限和文件描述符预算测试保持通过，生产二进制的 dead-code 校验与运行逻辑各自使用准确的编译边界。

Usage 生命周期一致性

• 同步执行 active、流式 response-start 等非终态事件可由后台运行时异步写入，failed、cancelled、completed 终态保持单调，不受晚到的 pending 或 streaming 覆盖。
• failed|cancelled / void 只接受 completed / pending 作为权威恢复事实；该规则允许最终成功结果纠正失败记录，同时拒绝 active 占位、response-start 和非待结算完成事件重开终态。
• Memory、SQLite、MySQL、PostgreSQL 共用同一恢复谓词。PostgreSQL 的 void usage 与 settlement snapshot 重置也受该谓词约束，四种存储实现保持相同状态语义。
• 请求候选与 Usage 均遵循非终态不能覆盖终态的生命周期原则；终态恢复依赖完成事实，不依赖任务调度顺序或轮询时长。

服务层级、提示缓存与计费

• 请求层级、提供商实际层级、结算层级分别建模并贯穿 Usage、管理接口和用户接口。响应缺少实际层级时保持缺省，结算事实不会由请求意图代填。
• Chat 与 Responses 的同步响应、SSE、同步转流和跨格式矩阵均可捕获提供商实际层级。结算按实际层级选择 processing-tier 价格目录。
• fast 指令映射为 OpenAI priority 请求事实；processing tier 支持标准、priority、flex 以及配置中声明的扩展层级。
• 标准与 Flex 在 272000 token 使用短上下文价格，272001 token 起使用长上下文价格。Priority 仅配置官方支持的短上下文区间，超出区间返回无计价规则。
• GPT-5.6 价格元组按“输入 / cache read / cache write / 输出”，单位为 USD / 1M tokens：

模型	短上下文 Standard	短上下文 Flex	短上下文 Priority
Sol	5 / 0.5 / 6.25 / 30	2.5 / 0.25 / 3.125 / 15	10 / 1 / 12.5 / 60
Terra	2.5 / 0.25 / 3.125 / 15	1.25 / 0.125 / 1.5625 / 7.5	5 / 0.5 / 6.25 / 30
Luna	1 / 0.1 / 1.25 / 6	0.5 / 0.05 / 0.625 / 3	2 / 0.2 / 2.5 / 12

模型	长上下文 Standard	长上下文 Flex
Sol	10 / 1 / 12.5 / 45	5 / 0.5 / 6.25 / 22.5
Terra	5 / 0.5 / 6.25 / 22.5	2.5 / 0.25 / 3.125 / 11.25
Luna	2 / 0.2 / 2.5 / 9	1 / 0.1 / 1.25 / 4.5

• 固定价格、输入、输出、cache creation、cache read、有限上下文区间和 endpoint rate multiplier 由 aether-billing 的统一计价能力解析。
• 余额容量检查位于最终 ExecutionPlan 形成后、上游网络请求前，并依据请求可达的价格目录与上下文区间计算可证明的费用上界。
• prompt_cache_options 支持 mode=implicit|explicit 和 ttl=30m。最终出站 body.model 是能力解析的第一事实源；有效 TTL 进入受控 Usage metadata，授权估算和终态结算使用同一事实。
• cache creation 与 cache read 的 token 数取自提供商响应，TTL 只选择价格目录，不推导缓存写入量或命中量。

结构化价格导入与管理界面

• models.dev 的基础价格、上下文阶梯、cache read 与 cache write 进入统一 TieredPricingConfig；tier.size 按起始边界转换为 Aether 的包含式 up_to。
• size=0 从首个上下文阶梯开始；重复边界、负数、非安全整数和非有限价格按失败关闭处理。实验模式缺少完整适用范围时不会被推导为 processing-tier 目录。
• 模型定价编辑器支持 processing tier、固定价格、token 分段、缓存价格与有限终止区间；表单使用独立结构副本。
• 端点表单、协议筛选、优先级管理、模型映射和模型测试共享格式权限与协议默认路径规则。
• Usage 列表和详情分别显示请求层级、实际层级与结算层级；推理指令界面支持完整 effort 集合、自定义后缀和 ultra -> max 映射。

架构决策

1. 协议是一等类型。 Search 进入格式注册、路由、权限、候选调度和传输适配器，避免在 URL 或模型名分支中维护隐式特例。

2. 能力与格式规则各有单一入口。 模型映射后的实际模型、远程模型卡和内置模型卡统一形成能力对象，reasoning、服务层级、缓存和工具校验共同消费该对象。Gateway 的纯格式分类、权限覆盖和列表交集统一通过 ai_serving pure facade 暴露。

3. 传输投影按协议封闭。 Responses、Compact、Search 各自定义终态字段集合；共享规范化发生在投影前，body rules 不能突破协议边界。

4. 兼容权限与端点身份分离。 单向 companion permission 只表达授权覆盖关系，路由选择和上游端点仍保持精确身份，防止格式兼容演变为协议替换。

5. 超时默认值与配置上限分离。 默认行为属于协议运行语义，上限属于管理配置约束；执行层只传递经过校验的显式值。

6. 计费使用响应事实。 请求 service tier 表达意图，响应 service tier 决定结算；价格目录用结构化上下文区间表达官方边界，缺少适用规则时显式失败。

7. 前后端共享可解释规则。 前端以相同格式权限、默认路径和 pricing tier 结构组织配置，后端仍是终态校验和执行事实的权威边界。

8. 生命周期以因果事实收敛。 后台写入可以并行执行，非终态事件不能反向覆盖终态；完成事件保留纠正 void failure 的能力，状态正确性不依赖运行时调度先后。

9. 工具错误由目标协议的合法载荷表达。 Canonical 层保存来源协议语义，Responses 边界使用 output 字符串传递成功或失败信息，不向 wire item 添加目标协议未定义的字段。请求、Compact 和响应构造共享同一编码真源。

对齐依据

• OpenAI Function Calling：提交与格式化工具结果
• OpenAI GPT-5.6 Sol
• OpenAI GPT-5.6 Terra
• OpenAI GPT-5.6 Luna
• OpenAI Reasoning 指南
• OpenAI Prompt Caching 指南
• OpenAI API 价格
• OpenAI Flex Processing
• OpenAI Priority Processing
• OpenAI Responses Compact
• Codex Search 请求类型
• Codex Search 端点与重试策略
• Codex 公共 Search 路径
• Codex Compact 请求投影
• Codex Compact 远程回归测试
• Codex 请求执行与超时语义
• models.dev SDK 价格结构

验证

• cargo fmt --all -- --check
• git diff --check origin/main
• cargo clippy -p aether-gateway --lib --bins --examples -- -D warnings
• cargo clippy -p aether-data --all-targets -- -D warnings
• cargo clippy --workspace --exclude aether-gateway --exclude aether-data --all-targets -- -D warnings
• aether-ai-formats 单元测试：699 项通过，覆盖 Claude 错误工具结果的字符串、空内容、对象、多段文本与图片，以及普通 Responses、Responses Compact 和响应构造
• aether-data 单元测试：483 项通过
• provider-transport 单元测试：357 项通过
• scheduler-core 单元测试：86 项通过
• Gateway 全量测试由 PR CI 执行；自动请求并发的缩放、上限与文件描述符预算 2 项定向测试通过
• Search Gateway 端到端测试覆盖请求投影、201 透传、400 终态、500 故障转移与显式 900s 超时传递
• owner relay 非法超时元数据回归测试通过
• owner relay 10 项模块测试通过，正向转发使用正式 RequestMeta envelope 并校验 trace、header 与完整原始字节
• 超时配置契约 4 项测试通过
• Gateway 格式权限与端点计数定向测试通过
• 管理端端点计数纯函数 3 项测试通过，覆盖单向权限、停用端点显式范围、固定 Codex OAuth 活动范围
• Gateway 授权策略模块 17 项测试通过，覆盖组策略、密钥范围、admin、standalone key、用户缺失与仓库缺失分支
• Gateway ai_serving 依赖边界架构守卫通过
• upstream 前端 Vitest：107 个测试文件、580 项测试通过
• MMEXA 前端 Vitest：97 个测试文件、557 项测试通过
• upstream 与 MMEXA 前端 TypeScript 检查和生产构建通过
• PostgreSQL、MySQL、SQLite 数据库 smoke 由 PR CI 执行

Codex 重置请求体

• 管理端消费接口使用 idempotency_key 表达确认操作的稳定身份；前端使用 crypto.randomUUID() 生成该值并随请求传入。
• codex_reset_credit_consume 纳入管理写路由的统一 body 缓冲矩阵，JSON 请求体在本地管理路由执行前完成读取与规范化。
• Provider Pool 将管理接口字段映射为 Codex 上游 redeem_request_id，请求目标为 /backend-api/wham/rate-limit-reset-credits/consume。
• 请求体校验发生在 Provider、Key、OAuth 和上游传输之前；OAuth 有效期不参与 idempotency_key 校验。

决策依据

1. 幂等身份由操作发起方生成。 管理界面能够区分一次确认操作，并可在网络重试时复用同一身份；后端负责验证和协议映射。
2. 管理写路由统一声明 body 所有权。 请求缓冲属于 Frontdoor 路由契约，处理器消费已经规范化的 body，与其他管理写接口保持一致。

参考资料

• Codex rate-limit reset credits 客户端实现

验证

• Gateway admin_codex_reset_credit_consume_buffers_idempotency_key_body 路由契约测试通过。
• PR CI 覆盖格式、Clippy、Gateway/Workspace/Data 测试与 SQLite/PostgreSQL/MySQL smoke。

Codex Remote Compact 与 Responses Compaction V2

• openai:responses 的格式权限覆盖 openai:responses:compact，使已授权 Responses 的用户、用户组、API Key 与 provider key 能够调用 Responses Compact 端点；openai:responses:compact 保持更窄的独立范围，不反向授权普通 Responses。
• Responses Compact 端点保留独立传输契约与精确字段投影。Codex 0.144.1 的 Responses Compaction V2 则使用标准 openai:responses 传输，并在 input 中携带 type: "compaction_trigger" 项；端点、API format 与上游 URL 均保持为普通 Responses。
• provider_model_mappings.operations 提供可选操作作用域。缺省映射覆盖全部操作，["compact"] 仅匹配压缩；相同优先级下，匹配操作作用域的映射优先于通用映射。
• 请求规划、候选物化、调度枚举和最终候选页面缓存共同携带操作语义。原始候选行缓存仅保存可用数据集合，作用域判断在解析阶段完成；解析结果缓存键包含操作，普通 Responses 与压缩不会互相复用候选结果。
• Usage 的 request_type 复用同一识别函数，进行态与终态记录均可表达 compact。

决策依据

传输协议和请求操作分离：协议层继续使用 Aether 已有的 Responses 注册、权限和路由链路，操作层只为显式配置的模型映射与可观测性提供选择条件。模型选择由管理配置决定，不根据 URL、模型名称或客户端身份隐式改写请求。

验证

• cargo fmt --all -- --check 通过。
• cargo clippy -p aether-gateway --lib --bins --examples -- -D warnings 通过。
• resolves_compaction_trigger_as_compact_operation_on_responses_transport、operation_scoped_mapping_overrides_generic_mapping_for_compaction、paged_preselection_prefers_operation_scoped_mapping_for_compaction、candidate_page_cache_key_isolates_auth_model_format_and_capabilities 定向回归通过。
• ai_serving_crate_api_is_confined_to_root_seams 与 paged_preselection_prefers_operation_scoped_mapping_for_compaction 在 RUST_MIN_STACK=16777216 下通过。

参考资料

• Codex Responses Compaction V2 尝试构造
• Codex Compaction V2 与 Compact 端点一致性测试
• Codex Remote Compact 请求执行
• OpenAI Responses Compact

[fawney19]

这个 PR 的前 16 个提交已通过 e58621a 合入 main，合入点是旧 head 25c49dd。之后遗漏的 4 个实质功能已适配当前 8616fe6 workspace 并迁移到 #675；b1be370 已有 main 上的等价提交 a728c09，cf0d957 仅为同步 merge，因此没有重复迁移。#675 保留了原作者及原提交追踪信息。为避免再次合并已经进入 main 的历史，现关闭本 PR，由 #675 替代。