opencodex 流式传输、推理与上下文元数据：Codex 原生对齐的保真度分析与演进

【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载opencodex 作为面向 OpenAI Codex 与 Claude Code 的通用 provider 代理其核心价值之一是把各家的流式输出文本增量、thinking/reasoning 块、工具调用、用量统计翻译成 Codex 期望的 Responses SSE 协议。本文以项目 parity 计划devlog/_fin/100_codex-native-parity/50_streaming-thinking-context.md为主线逐项剖析中间流式文本、推理块表示、上下文窗口与 token 计量元数据三个维度的对齐现状与差距并结合当前仓库源码说明这些差距的演进与闭环方式。读完本文你将掌握 opencodex 的流式桥接bridge架构、推理块在 Responses 协议中的两种表达summary 与 raw reasoning text、用量元数据的归一化规则以及路由模型上下文窗口字段的继承策略。一、评估背景Phase 100 的三大提问devlog/_fin/100_codex-native-parity/50_streaming-thinking-context.md是 opencodex Codex 原生对齐native parity计划的第 50 小节它围绕三个核心问题对当时实现做体检中间流式响应文本是否忠实Is intermediate streamed response text faithful?——翻译型 adapter 在流式传输过程中是否丢失或篡改中间文本thinking/reasoning 块是否正确表达Are thinking/reasoning blocks represented correctly?——各家 provider 的推理内容是否以 Codex 可识别的形式呈现上下文窗口与 token 计量元数据是否足够Is context-window and token accounting metadata complete enough for Codex?——Codex 的状态 UI、分析与上下文预算行为依赖的元数据是否齐全。这三大提问分别对应本文后续的三个小节最后落到一份Phase 100 建议清单。需要说明的是文档记录的是评估时点的状态当前仓库源码显示其中若干差距已经闭环本文会在对应小节给出现状对照。二、中间流式响应文本routed streaming path 的保真度2.1 统一翻译路径对于走翻译型 adaptertranslated adapters的流式响应文档给出的结论是opencodex 相当忠实reasonably faithful。整个流式路径是一条清晰的事件管线adapter.parseStream(...) - bridgeToResponsesSSE(...)parseStream位于各 adapter 内把上游方言Anthropic SSE、OpenAI Chat Completions chunk、Google 流等解析为统一的中立事件流AdapterEventbridgeToResponsesSSE位于 src/bridge/sse.ts把AsyncIterableAdapterEvent逐事件翻译成 Codex 可消费的 Responses SSE 帧并返回ReadableStreamUint8Array。这条路径在文档评估时对应旧路径 src/server.ts 与 src/bridge.ts 中的入口当前仓库已将桥接逻辑拆分到独立的 src/bridge/ 目录sse.ts、response-json.ts、errors.ts、internal.ts职责更清晰sse.ts负责流式翻译response-json.ts负责非流式 JSON 组装。2.2 bridge 输出的核心 SSE 事件序列bridge 生成 Codex 期望的标准 Responses 流式序列事件顺序如下response.created response.output_item.added response.content_part.added response.output_text.delta response.output_text.done response.content_part.done response.output_item.done response.completed在 src/bridge/sse.ts 中可以看到与之一一对应的实现细节收到首个text_delta时response.output_item.added创建一个type: message, status: in_progress的 assistant 条目随后response.content_part.added打开output_text内容块src/bridge/sse.ts每个文本片段经appendString累积并立即以response.output_text.delta转发保证低延迟src/bridge/sse.ts关闭消息时依次补发response.output_text.done携带最终完整文本与response.content_part.done携带含引用的完整 part最后response.output_item.done把条目标记为completedsrc/bridge/sse.ts。注释明确指出缺少这些.done事件Codex 永远不会提交内容块会把消息渲染成截断状态。此外bridge 还内建了流的健壮性保障翻译缓冲预算TranslatorBudget防止失控的累积内存、response.heartbeat心跳帧保持 Codex 的空闲计时器不误触发、以及流提前结束必须合成response.incomplete而非response.completed的终态纪律adapter_eof语义这些都在 src/bridge/sse.ts 与 src/bridge/internal.ts 中有据可查。2.3 最高保真路径OpenAI/Azure Responses 直通文档特别指出OpenAI/Azure 的 Responses 直通passthrough模式拥有最好的流保真度——因为 opencodex 直接把上游 Responses body 和经过净化的 headers 原样转发不做事件级重建自然不存在翻译损耗。当前仓库的实现位于 src/adapters/openai-responses/passthrough.tscreateResponsesPassthroughAdapter与FORWARD_HEADERS是直通的核心导出src/adapters/openai-responses.ts则聚合了直通适配器与stripCanonicalForwardSamplingParams等规范化工具。这意味着当目标 provider 本身就说 Responses 方言时opencodex 尽量让位给上游只做最小干预如工具名命名空间改写、推理摘要投递策略归一化等从而把保真度损失降到最低。三、Thinking / Reasoning 块的表示3.1 统一事件thinking_delta所有翻译型 adapter 产出的推理内容在进入 bridge 之前都会被归一为统一事件。文档评估时记录的归一化事件是thinking_delta当前仓库的中立事件类型定义在 src/types/request.ts 中已演进为更完整的集合thinking_delta // 提供商的思考文本增量summary 语义 reasoning_raw_delta // 提供商的原始推理文本增量raw reasoning 语义 thinking_signature // Anthropic 扩展思考块的签名需原样回放 redacted_thinking // Anthropic 不透明 redacted 块需原样回放 kiro_redacted_reasoning // Kiro 加密推理 blob需原样回放从源码看各 adapter 的映射证据非常具体Anthropic 的thinking_delta/reasoning_delta块与流式 delta 被映射为thinking_deltasrc/adapters/anthropic.tsOpenAI Chat Completions 的delta.reasoning_content被映射为reasoning_raw_deltasrc/adapters/openai-chat.tsGoogle 把thought: true的文本 part 依据语义分别映射为thinking_delta或reasoning_raw_delta避免同一推理被两个事件类型重复暴露src/adapters/google.ts。3.2 bridge 的两条推理通道summary 与 raw reasoning textbridge 对这两类事件分别生成不同的 Responses 推理条目这是理解整个小节的关键summary 通道thinking_delta→ reasoning summary事件序列为response.output_item.added // type: reasoning response.reasoning_summary_part.added response.reasoning_summary_text.delta response.reasoning_summary_text.done response.reasoning_summary_part.done response.output_item.done实现见 src/bridge/sse.ts 与关闭逻辑closeCurrentReasoningsrc/bridge/sse.ts。推理条目以summary: [{ type: summary_text, text }]收尾。raw reasoning 通道reasoning_raw_delta→ reasoning_text事件序列为response.output_item.added // type: reasoning response.reasoning_text.delta response.reasoning_text.done response.output_item.done实现见 src/bridge/sse.ts 与closeCurrentRawReasoningsrc/bridge/sse.ts推理条目以summary: [], content: [{ type: reasoning_text, text }]收尾。这正是文档中点名缺失的response.reasoning_text.delta——当前仓库源码显示该差距已闭环OpenAI 系 provider 的reasoning_content原始推理不再被迫降级为 summary而是走独立的 reasoning_text 内容通道由客户端控制原始推理的展示。src/responses/schema.ts中的 zod 校验也印证了这一双通道设计summaryTextSchemasummary_text与reasoningTextSchemareasoning_text是两个独立的内容块类型推理条目reasoningItemSchema同时允许summary与content两个可选数组还允许携带encrypted_content不透明负载src/responses/schema.ts。3.3 推理的往返round-trip与摘要隐藏文档指出opencodex 会把上一轮的推理解析为本地 assistantthinking带 JSON 签名这对有用的但不能原生往返 provider 特有的不透明推理元数据。当前仓库在这个方向做了大量深化体现在 src/bridge/sse.ts 中Anthropic 扩展思考签名往返thinking_signature与redacted_thinking被暂存随后通过ocxr1加密信封encrypted_content附在推理条目上使带签名的思考块与 redacted 块可原样回放否则含工具调用的回合会 400src/bridge/sse.tsKiro 加密推理 blob由于 Kiro 在回合末尾才下发 blobbridge 先暂存、待所有条目关闭后再 flush避免序号错位导致解析器丢弃src/bridge/sse.tshideThinkingSummary 模式当客户端要求隐藏思考摘要时可见的 reasoning 条目被抑制但文本仍以 txt-only 信封形式往返保证 GLM 交错思考interleaved thinking重放不回退src/bridge/sse.ts推理重放缓存issue #950紧邻工具调用的原始推理会被记录供后续续写回合重新挂载src/bridge/sse.ts。这些机制合起来解决了文档提出的推理不透明元数据无法原生往返问题——通过信封与重放缓存推理内容与签名能够跨回合存活。四、非流式Non-Streaming保真度差距4.1 buildResponseJSON 的局限文档评估时指出翻译型非流式响应保真度较低——buildResponseJSON()只累积文本与 usage若存在文本才输出 message 条目。当时的已知缺口包括Anthropic 非流式只处理 text/tool-use不处理 thinkingOpenAI-compatible 非流式只处理message.content与tool_callsGoogle 只映射文本与函数调用当时没有等效 thinking 通道。4.2 现状批量路径已补齐推理通道当前仓库的批量实现位于 src/bridge/response-json.tsbuildResponseJSON入口见 src/bridge.ts 的导出。与流式路径对称批量路径同样实现了flushSummaryReasoning与flushRawReasoningsrc/bridge/response-json.tsthinking_delta累积进currentSummaryReasoning最终输出summary: [{ type: summary_text, text }]的 reasoning 条目reasoning_raw_delta累积进currentRawReasoning最终输出content: [{ type: reasoning_text, text }]的 reasoning 条目hideThinkingSummary模式下则退化为 txt-only 信封签名、redacted 块、Kiro blob 的批量往返逻辑与流式路径一一对应batchSignature、batchRedacted、batchKiroRedacted截断语义与流式路径对齐max_tokens/content_filter归一为incomplete_detailsadapter 无终态事件时统一报adapter_eof防止半截 JSON 参数的工具调用被当作 completed 成功回合src/bridge/response-json.ts。也就是说文档所列的非流式缺口在当前仓库中已通过对称的批量累积器得到大幅收窄剩余差异主要在于时序语义批量路径没有in_progress中间态动画如web_search_call_begin在批量路径是 no-op见 src/bridge/response-json.ts这是协议使然而非缺陷。五、Usage 与上下文元数据5.1 OcxUsage 的演进文档评估时记录的本地 usage 类型只有两个字段inputTokens outputTokens由此带来的差距是翻译流上报的缓存/reasoning token 数为零或缺失影响状态 UI、分析与上下文预算行为。当前仓库的OcxUsagesrc/types/request.ts已大幅扩展字段及语义约定如下字段语义inputTokens总提示词大小包含缓存读取与缓存写入OpenAI Responses 约定outputTokens输出 token 数cachedInputTokens仅缓存读取token是inputTokens的子集cacheReadInputTokens/cacheCreationInputTokensprovider 分别上报读取/写入时的拆分reasoningOutputTokens推理输出 token 数contextTotalTokens响应后的绝对活动上下文大小有状态 provider 可单独暴露totalTokens等于inputTokens outputTokens绝不重复叠加缓存明细estimated是否为估算值rawUsage上游原始 usage 对象供未知字段透传openai/codex#41980 对齐Anthropic 解析站点把缓存读写拆分为cachedInputTokens与cacheCreationInputTokenssrc/adapters/anthropic.tsGoogle 的usage.thoughtsTokenCount被映射为reasoningOutputTokenssrc/adapters/google.ts。5.2 responsesUsage向 Codex 的 wire 归一化bridge 最终通过responsesUsage()src/bridge/internal.ts把OcxUsage序列化为 Codex 可消费的 Responses usage 对象输出结构为input_tokens output_tokens total_tokens input_tokens_details.cached_tokens input_tokens_details.cache_write_tokens output_tokens_details.reasoning_tokens实现细节值得注意input_tokens_details/output_tokens_details永远发射零值兜底因为 strict 的 Responses 客户端如 grok-build 钉住的 async-openai fork把它们当必填字段缺字段会让一个成功回合在response.completed之后硬退出src/bridge/internal.tscached_tokens只表达缓存读取、恒小于等于inputTokensOpenAI 语义rawUsage中未知的上游字段会与归一化值合并透传归一化值对已知键保持权威每个轮次的done事件都携带 usage错误回合也尽力携带部分消耗error事件可带usage见 src/types/request.ts保证失败请求也能记录真实 token 数。这直接回应了文档提出的缓存/推理 token 缺失差距当前仓库已通过cachedInputTokens/reasoningOutputTokens字段与responsesUsage()的 wire 归一化将其闭环Codex 的状态 UI 与上下文预算逻辑可以读到真实的缓存命中与推理消耗。5.3 模型目录的上下文窗口字段文档列出 Codex 模型元数据中的上下文窗口字段context_window max_context_window auto_compact_token_limit effective_context_window_percent truncation_policy并指出opencodex 当时不会为路由目录条目设置 provider/model 特定的上下文窗口字段路由模型要么继承原生模板限制要么在回退模式下缺失。当前仓库的处理在 src/codex/catalog/derive-entry.ts 中有了明确策略注释 #992当/models未提供上下文元数据时路由模型绝不继承原生模板的上下文窗口——先删除context_window、max_context_window、auto_compact_token_limit三个字段src/codex/catalog/derive-entry.ts再由已知元数据恢复精确值、或由启用的 Context cap 兜底填充、否则以 strict-fields 回退方案补上 128k 三元组。同时 src/codex/catalog/effort.ts 在生效时会把解析出的上下文窗口写回条目。也就是说上下文窗口字段不再是遗漏而是变成了一条先清空、再按来源精确填充的受控链路。六、响应头与错误保真度6.1 SSE headers 差距文档指出上游 Codex 能在 SSE 处理之前从响应头派生事件server model、rate limits、model etag、server reasoning included而翻译型 opencodex 流当时只设置极简 SSE headers。从当前仓库结构看头部保真度的差异依然存在翻译路径bridgeToResponsesSSE返回的ReadableStream的帧格式由sseEvent统一构造src/bridge/sse.ts属于干净但简约的事件流而直通路径src/adapters/openai-responses/passthrough.ts 的FORWARD_HEADERS保留上游认证与关键转发头。这与文档的结论一致想获得头部级保真rate limit、etag 等派生事件应优先走 Responses 直通模式。6.2 response.failed 与 response.error文档指出错误保真也不完整opencodex 发射response.failed且携带last_error但上游解析器的证据表明类型化分类读取的是response.error。当前仓库的终态发射逻辑里两类字段是同时携带的失败帧的响应体同时包含error与last_errorsrc/bridge/sse.ts非流式buildResponseJSON同理输出{ error, last_error }src/bridge/response-json.ts。错误对象统一由 src/lib/errors.ts 的classifyError/adapterFailureFromEvent构造具备 status、type、code、retryable 等结构化字段供上游解析器做类型化分类。可以说错误形状已向同时满足response.error与last_error两类读取方演进第 7 条建议对齐response.failed形状已在实现层面得到响应。七、Phase 100 建议清单与现状对照文档末尾给出了 7 条 Phase 100 建议结合当前仓库源码逐条对照如下#建议当前仓库现状1为上下文窗口与截断行为补充 provider/model 特定目录元数据已部分落地路由条目先清空再精确回填见 src/codex/catalog/derive-entry.ts 与 src/codex/catalog/effort.ts2扩展OcxUsage与 bridge 输出加入缓存输入与推理输出 token已闭环OcxUsage新增cachedInputTokens/reasoningOutputTokens等src/types/request.tsresponsesUsage()输出cached_tokens/reasoning_tokenssrc/bridge/internal.ts3决定每个 provider 的 thinking 流映射为 reasoning summary 还是 raw reasoning text已闭环双通道并存——thinking_delta→ summaryreasoning_raw_delta→reasoning_textsrc/bridge/sse.ts4构造流时强制reasoning.summary none已部分落地raw reasoning 条目的summary为空数组见closeCurrentRawReasoningsrc/bridge/sse.ts5改善翻译型非流式对齐或明确文档化为低保真已大幅改善批量路径补齐 summary/raw reasoning/signature/redacted 往返src/bridge/response-json.ts剩余差异主要是无中间态动画6尽量合成或转发 Codex 相关 headers部分达成直通模式经FORWARD_HEADERS保留关键头src/adapters/openai-responses/passthrough.ts翻译路径保持简约头7对齐翻译型response.failed形状与上游解析器预期已落地失败帧同时携带error与last_errorsrc/bridge/sse.ts八、实践要点总结追求最高流保真度优先 Responses 直通只要目标 provider 原生支持 Responses 方言直通路径src/adapters/openai-responses/passthrough.ts能保留上游 body 与净化后的 headers翻译路径则适合其余 provider。区分 summary 与 raw reasoning 两类推理thinking_delta语义上是提供商书写的思考摘要走reasoning_summary_*事件reasoning_raw_delta如 OpenAI 的reasoning_content是原始推理走reasoning_text.*事件。理解这一区分才能正确选择隐藏策略hideThinkingSummary与重放策略。用量元数据是行为而非装饰cached_tokens影响缓存计费显示reasoning_tokens影响推理消耗统计contextTotalTokens影响有状态 provider 的上下文预算务必遵循OcxUsage的inputTokens 已含缓存约定避免重复叠加。路由模型的上下文窗口需要显式管理不要盲目继承模板值应遵循先删除、再按元数据或 Context cap 精确回填的链路避免向 Codex 上报错误的窗口导致自动压缩行为偏差。终态纪律不可妥协流式路径必须恰好一个终态事件completed/failed/incompleteadapter 提前 EOF 时报incompleteadapter_eof而非伪成功失败帧同时提供error与last_error兼容不同解析器的读取习惯。若需继续深入可查阅本文引用的源码文件src/bridge/sse.ts流式桥接、src/bridge/response-json.ts非流式组装、src/types/request.tsAdapterEvent/OcxUsage类型契约、src/bridge/internal.tsusage wire 归一化以及 parity 计划的完整索引 devlog/_fin/100_codex-native-parity。赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐opencodex Codex 原生协议对齐Phase 100use_responses_lite 与 supports_websockets 传输决策分析opencodex Codex 原生协议对齐Phase 100 use_responses_lite 与 supports_websockets 传输决策opencodex 将 openai/codex PR 31684 的 upstream models.json 快照固化进 GPT-5.6 原生目录元数据对齐的实现、取舍与测试opencodex 将 openai/codex PR 31684 的 upstream models.json 快照固化进 GPT 5.6 原生目录元数据对opencodex 的 Codex Responses WebSocket 传输决策Codex 侧 WS 桥接MVP与原生上游 WS 的取舍opencodex 的 Codex Responses WebSocket 传输决策Codex 侧 WS 桥接MVP与原生上游 WS 的取舍 openco创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考