big-AGI AIX 的 OpenAI 协议同步方法论从 Wire Types、Adapter 与 Parser 到上游 API 差异排查【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI本文围绕 big-AGI 仓库中的一份内部同步指令.claude/commands/aix/sync-openai-apis.md展开完整讲解该项目如何把自己的 OpenAI 兼容层AIX 模块与上游 OpenAI API 保持同步哪些文件构成协议实现的骨架wire types / adapter / parser、Responses API 与 Chat Completions 的优先级关系、流式解析的关键假设以及“查文档 → 打真实 SSE 请求 → 逐字段对比”的完整差异排查工作流。读完后你可以掌握在这类多模型网关项目中定位协议实现、复现上游同步检查、并自行判断破坏性变更与新增能力的方法。一、这份指令解决什么问题sync-openai-apis.md 是一个面向 AI 编码助手的 Claude Code 命令.claude/commands/目录下与sync-anthropic-api.md、sync-gemini-api.md、sync-openrouter-api.md等并列它的用途是当上游 OpenAI API 发生变化新字段、新事件类型、新模型、新价格时驱动一次系统化的“实现 vs 上游文档”比对并把所有差异——尤其是破坏性变更和能改善用户体验的新能力——列出来。指令明确了本次同步的作用范围与优先级这几点直接决定了 big-AGI 的 OpenAI 兼容层长什么样优先 Responses API/v1/responses是主推协议Chat Completions/v1/chat/completions仍然支持但按 legacy 对待明确不做不支持 Realtime含 WebSocket 等API也不支持 Agentic 类 APIAgent SDK、AgentKit、ChatKit、Assistants API 等——因为 AIX 自己在服务端或客户端实现了等价能力检查深度要求必须深入到请求/响应字段的细节重点核对“必填字段、流式事件类型、新的响应形态”而不仅是顶层结构。下面按指令指定的三个核心文件逐一展开这些文件就是 OpenAI 协议实现的完整骨架。二、协议骨架三个文件各自负责什么环节文件职责线格式定义openai.wiretypes.ts用 Zod 定义请求/响应/内容片段/工具等全部线类型wire types请求组装Adapteropenai.chatCompletions.ts、openai.responsesCreate.ts把 AIX 内部统一的 ChatGenerate 请求翻译成 OpenAI 两种 API 的请求体响应解析Parseropenai.parser.ts、openai.responses.parser.ts把流式SSE或非流式响应解析回 AIX 内部粒子particle流同目录下还有 openai.responses.create.spec.md 这类上游规范快照和 sync.sh 同步脚本说明“把上游规范拉下来对照”本身是工程化的常规动作。2.1 Wire TypesZod Schema 上游 Changelog 注释openai.wiretypes.ts约 2200 行文件头部维护了一张上游变更记录表这是同步工作的直接产物——每次同步都会把命中的上游 Changelog 条目落到注释里// Implementation notes (see OpenAI changelog for upstream changes): // - 2024-12-17: Reasoning Effort - added reasoning_effort and the developer message role // - 2024-11-05: Predicted Outputs // - 2024-09-12: o1 - max_tokens is deprecated in favor of max_completion_tokens, // added completion_tokens_details // - 2024-08-06: Structured Outputs - added JSON Schema and strict schema adherence // - 2024-07-09: skipping Functions as theyre deprecated / ignoring logprobs这份注释同时记录了主动放弃的字段如logprobs、已废弃的 Functions让“为什么这里没有 X”可追溯。核心内容片段Content Parts定义在OpenAIWire_ContentParts命名空间内用z.discriminatedUnion(type, ...)组织输入侧的四种 part见 openai.wiretypes.ts#L27-L92text文本另带一个 OpenRouter 方言专属的cache_controlAnthropic 风格缓存断点OR 负责翻译image_urlurldetail: auto | low | high控制视觉理解精度input_audioBase64 音频 format: wav | mp3上游 2024-10-17 加入的音频输入;video_urlOpenRouter 扩展非标准 OpenAI 字段。输出侧则定义了ToolCallfunction调用arguments是字符串源码注释提醒模型未必生成合法 JSON调用前必须自行校验以及url_citation引用注解等。2.2 Chat Completions 请求 Schema完整参数面OpenAIWire_API_Chat_Completions.Request_schema见 openai.wiretypes.ts#L342-L461覆盖了同步时需要逐项核对的请求面摘选如下参数类型/取值说明model/messagesstring / Message[]基本输入messages 为四角色消息数组tools/tool_choice/parallel_tool_callsToolDefinition[] / ToolChoice / bool工具定义与调用策略parallel_tool_calls默认 truemax_completion_tokensint正数现行标准字段max_tokensint已废弃仅为兼容保留temperature/top_p0–2 / 0–1通用采样参数modalities/audio[text,audio,image]/ voiceformat多模态输出audio 的 voice 枚举含 ash/ballad/coral/sage/verse/alloy/echo/shimmer/marinformat 支持 wav/mp3/flac/opus/pcm16stream/stream_optionsbool /{include_usage}流式开关与用量回传reasoning_effortnone/minimal/low/medium/high/xhigh/max2024-12-17 加入max为 DeepSeek V4 扩展response_formattext / json_object / json_schema2024-08-06 Structured Outputsschema 名须匹配^[a-zA-Z0-9_-]{1,64}$web_search_optionssearch_context_size user_location网络搜索上下文与近似定位prediction{type:content, content}2024-11-05 Predicted OutputsSchema 之后还有一长串厂商方言扩展OpenRouter 的session_id/provider/max_tool_calls、Perplexity 的search_mode、Moonshot/DeepSeek 的thinking等这正体现了 wire types 文件的定位一份“OpenAI 兼容超集”以注释中的[厂商, 日期]标签标记每个扩展的来源。这种注释规范本身就是同步工作的落点——新增一个上游字段时必须能追溯到厂商与日期。三、Chat Completions Adapter请求组装与方言热修aixToOpenAIChatCompletions 是 Chat Completions 方向的翻译器文件头部的实现笔记先声明了能力边界见 openai.chatCompletions.ts#L11-L21只支持 N1top_p、parallel_tool_calls、stop等未实现doc part 以 markdown 文本内嵌、image part 以 base64 data URL 内嵌、所有 tool call 统一转为 function call。组装流程里最有工程含量的是按方言dialect打热修例如见 openai.chatCompletions.ts#L40-L100OpenAI/Azure o 系推理模型gpt-6/gpt-5/o4/o3/o1 前缀匹配去掉不支持的temperature/top_psystem 消息改用 2024-12-17 引入的developer角色max_tokens→max_completion_tokens对原生 OpenAI 与 Azure 全部改用新字段与 wire types 里的“DEPRECATED”注释呼应DeepSeek/Perplexity强制 user/assistant 角色交替、移除空消息DeepSeek V4 在有工具且未关思考时要求历史中每条 assistant 消息都带reasoning_content缺失时注入空串占位OpenRouter把客户端生成的session_id发给上游做粘性路由缓存不能跨 provider并把尾部的cache_control断点收敛到 4 个以内Anthropic 上游限制对拒收强制工具调用的模型把tool_choice: required降级为auto并插入 system 提示语补救函数调用不可用则快速失败Perplexity 等方言下若携带 tools 直接抛错而不是让上游报一个难读的错。随后构造请求体stream_options: { include_usage: true }流式时、response_format按model.strictJsonOutput决定、工具与tool_choice按模型的strictToolInvocations转换。最后还有一道_fixPairInteriorToolCalls保证“每个中间 tool call 都有配对的 tool 消息否则整个请求会被上游拒绝”。这些细节正是同步指令中“look deep in the fields of the requests”要求的具体形态一个字段的上游语义变化比如角色改名、字段废弃会同时波及 wire types、adapter 热修和 parser 三处。四、Chat Completions Parser块级流式协议的解析假设openai.parser.ts 顶部openai.parser.ts#L16-L36用注释完整陈述了它对块级流式协议chunk-based streaming的理解这也是同步时要重点验证的部分每个 chunk 含choices数组通常单项delta承载增量更新文本以delta.content字符串片段增量到达工具调用经delta.tool_calls增量到达且有固定方案首个 delta 携带完整 id 与函数名参数通常为空后续 delta 只追加参数文本——没有显式的 begin/end 标记靠时间顺序隐含工具调用的开始与结束流结束靠data: [DONE]信号不依赖finish_reason。解析入口 createOpenAIChatCompletionsChunkParser 在真正 Zod 解析前做了一组“防御性分流”每一条都对应同步时观察到的真实上游行为Keepalive 事件2025-01-13 上游加入{type:keepalive,...}静默跳过混淆占位 chunk无choices但带obfuscation的消息直接跳过否则会打断解析器error字段按 openai.error-severity.ts 的严重度分级转成方言终止事件而不是粗暴抛错Azure 特例空 id/model 且带prompt_annotations/prompt_filter_results的 chunk 忽略OpenRouter在 Zod 剥掉未知字段之前先从原始 JSON 里摘出provider路由信息用于展示尾部成本事件如x-opencode-type: inference-cost先收割 token/费用指标再跳过。之后才是ChunkResponse_schema.parse严格解析并记录timeToFirstEvent等性能指标。可以看到 parser 的演进史每条注释都带上游日期/厂商与 wire types 头部注释是同一套同步流程的两个出口。五、Responses API 侧方言差异表与事件流解析因为指令明确“Responses API 优先”openai.responsesCreate.ts 和 openai.responses.parser.ts 承载了主协议。Adapter 侧用一张方言差异表RspDialectQuirks见 openai.responsesCreate.ts#L26-L67取代零散的 if-else把“共享信封、各自校验器”的 OpenAI 兼容生态结构化差异项含义典型方言值vndNamespace连续性状态加密推理项、消息阶段的_vnd命名空间openai / sakanaai / xai / metaaiemitMessagePhase回放 assistant 消息时带phase字段Azure 为 false能力滞后webSearchTool托管 web_search 工具的形态full / bare / noneAzure 为 none“Hosted tool web_search is not supported”toolChoiceOnlyAutotool_choice 只接受 autometaai 严格校验器minOutputTokens校验器接受的最小 max_output_tokensmetaai 为 16每张表行都带日期标注如 Azure 的滞后截至 2025-11-18 仍成立这正是同步指令“点出所有协议差异”的输出形式。Parser 侧则按 Responses API 的事件类型状态机推进response.output_text.delta、response.output_text.done、response.output_text_annotation.added等见 openai.responses.parser.ts#L603-L660并对新旧两种 annotation 事件名做向后兼容。一个值得注意的上游怪癖处理是 “failed 响应打捞”openai.responses.parser.ts#L74-L89OpenAI 可能把一个实际已完整生成并流式发完的响应整体标记为failedTPM 限流检查发生在生成中途而非准入时解析器以 output 中每个 item 的status: completed作为“生成已完成”的权威信号把这类响应按成功处理。注释里标注了 2026-07-03 的 5/5 复现实测——这种“文档滞后、靠真实 SSE 才能发现”的行为恰好是同步指令里“live endpoint 是 ground-truth”一节的注脚。六、同步工作流信息源、活体探测与差异清单指令的后半部分给出了完整、可复用的同步操作手册这部分对任何维护 OpenAI 兼容层的团队都通用1信息源优先级逐级降级主源Responses API 参考优先、Chat Completions 参考、Changelog、模型列表、定价页用官方页面的 Copy Page 按钮下载 markdown便于 diff主源被挡时改用OpenAI 官方 Node.js SDK、Python SDK、OpenAPI 规范仓库或搜索“openai api changelog / new models / new prices”这类关键词获取近期公告全部被挡时如实说明尝试过什么并请人工提供文档——严禁在拿不到上游信息时编造。2活体端点探测额外信号如果本地.env.api-keys中存在OPENAI_API_KEY直接对真实端点打一发流式请求并检查原始 SSEPOST https://api.openai.com/v1/responseslegacy 则用/v1/chat/completions请求体带stream: true。文档可能滞后而原始 SSE 是新字段、事件类型、响应形态与错误格式的最终事实来源。指令同时强调绝不提交或回显密钥。3差异核对与输出要求深查请求与响应的字段级差异必填字段、流式事件类型、新的响应形态、协议本身的变更包括流式消息的最终解析与重组方式优先报告破坏性变更和能改善用户体验的新能力——前者必须尽快修后者进入实现待办指令的 frontmatter 支持$ARGUMENTS占位argument-hint 为 “specific feature to check”可以把检查范围收窄到某个具体特性。对照仓库现状可以验证这套流程的落地效果wire types 文件头的 Changelog 日期注释、wiretypes 内每个方言扩展的[厂商, 日期]标签、parser 里带日期注释的防御分支、以及_upstream/目录下的上游规范快照与sync.sh都是这个循环反复运转留下的痕迹。七、小结一套可迁移的协议同步方法big-AGI 的 OpenAI 同步指令把“跟上上游 API”从一次性的手工活变成了可重复的工程流程其要点可以概括为实现分三层且各司其职——Zod wire types 定义线格式含方言超集与日期注释、adapter 组装请求按方言打热修并快速失败、parser 消费响应先防御分流、再严格解析、以 item 级状态为权威协议优先级明确——Responses API 为主、Chat Completions 为 legacyRealtime 与 Agentic API 明确不接由 AIX 自研能力覆盖信息源分级 活体 SSE 兜底——文档、SDK、OpenAPI 规范逐级降级真实流式请求是文档滞后时的 ground-truth输出以“破坏性变更优先”排序——必填字段、流式事件类型、新响应形态是必查项所有上游观察都必须带厂商与日期标注沉淀回源码注释。维护同类项目时可直接复用这套结构先定位本项目的 wire types / adapter / parser 三件套再按“文档 → 活体探测 → 字段级 diff → 注释落回源码”的闭环执行同步。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
big-AGI AIX 的 OpenAI 协议同步方法论：从 Wire Types、Adapter 与 Parser 到上游 API 差异排查
big-AGI AIX 的 OpenAI 协议同步方法论从 Wire Types、Adapter 与 Parser 到上游 API 差异排查【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI本文围绕 big-AGI 仓库中的一份内部同步指令.claude/commands/aix/sync-openai-apis.md展开完整讲解该项目如何把自己的 OpenAI 兼容层AIX 模块与上游 OpenAI API 保持同步哪些文件构成协议实现的骨架wire types / adapter / parser、Responses API 与 Chat Completions 的优先级关系、流式解析的关键假设以及“查文档 → 打真实 SSE 请求 → 逐字段对比”的完整差异排查工作流。读完后你可以掌握在这类多模型网关项目中定位协议实现、复现上游同步检查、并自行判断破坏性变更与新增能力的方法。一、这份指令解决什么问题sync-openai-apis.md 是一个面向 AI 编码助手的 Claude Code 命令.claude/commands/目录下与sync-anthropic-api.md、sync-gemini-api.md、sync-openrouter-api.md等并列它的用途是当上游 OpenAI API 发生变化新字段、新事件类型、新模型、新价格时驱动一次系统化的“实现 vs 上游文档”比对并把所有差异——尤其是破坏性变更和能改善用户体验的新能力——列出来。指令明确了本次同步的作用范围与优先级这几点直接决定了 big-AGI 的 OpenAI 兼容层长什么样优先 Responses API/v1/responses是主推协议Chat Completions/v1/chat/completions仍然支持但按 legacy 对待明确不做不支持 Realtime含 WebSocket 等API也不支持 Agentic 类 APIAgent SDK、AgentKit、ChatKit、Assistants API 等——因为 AIX 自己在服务端或客户端实现了等价能力检查深度要求必须深入到请求/响应字段的细节重点核对“必填字段、流式事件类型、新的响应形态”而不仅是顶层结构。下面按指令指定的三个核心文件逐一展开这些文件就是 OpenAI 协议实现的完整骨架。二、协议骨架三个文件各自负责什么环节文件职责线格式定义openai.wiretypes.ts用 Zod 定义请求/响应/内容片段/工具等全部线类型wire types请求组装Adapteropenai.chatCompletions.ts、openai.responsesCreate.ts把 AIX 内部统一的 ChatGenerate 请求翻译成 OpenAI 两种 API 的请求体响应解析Parseropenai.parser.ts、openai.responses.parser.ts把流式SSE或非流式响应解析回 AIX 内部粒子particle流同目录下还有 openai.responses.create.spec.md 这类上游规范快照和 sync.sh 同步脚本说明“把上游规范拉下来对照”本身是工程化的常规动作。2.1 Wire TypesZod Schema 上游 Changelog 注释openai.wiretypes.ts约 2200 行文件头部维护了一张上游变更记录表这是同步工作的直接产物——每次同步都会把命中的上游 Changelog 条目落到注释里// Implementation notes (see OpenAI changelog for upstream changes): // - 2024-12-17: Reasoning Effort - added reasoning_effort and the developer message role // - 2024-11-05: Predicted Outputs // - 2024-09-12: o1 - max_tokens is deprecated in favor of max_completion_tokens, // added completion_tokens_details // - 2024-08-06: Structured Outputs - added JSON Schema and strict schema adherence // - 2024-07-09: skipping Functions as theyre deprecated / ignoring logprobs这份注释同时记录了主动放弃的字段如logprobs、已废弃的 Functions让“为什么这里没有 X”可追溯。核心内容片段Content Parts定义在OpenAIWire_ContentParts命名空间内用z.discriminatedUnion(type, ...)组织输入侧的四种 part见 openai.wiretypes.ts#L27-L92text文本另带一个 OpenRouter 方言专属的cache_controlAnthropic 风格缓存断点OR 负责翻译image_urlurldetail: auto | low | high控制视觉理解精度input_audioBase64 音频 format: wav | mp3上游 2024-10-17 加入的音频输入;video_urlOpenRouter 扩展非标准 OpenAI 字段。输出侧则定义了ToolCallfunction调用arguments是字符串源码注释提醒模型未必生成合法 JSON调用前必须自行校验以及url_citation引用注解等。2.2 Chat Completions 请求 Schema完整参数面OpenAIWire_API_Chat_Completions.Request_schema见 openai.wiretypes.ts#L342-L461覆盖了同步时需要逐项核对的请求面摘选如下参数类型/取值说明model/messagesstring / Message[]基本输入messages 为四角色消息数组tools/tool_choice/parallel_tool_callsToolDefinition[] / ToolChoice / bool工具定义与调用策略parallel_tool_calls默认 truemax_completion_tokensint正数现行标准字段max_tokensint已废弃仅为兼容保留temperature/top_p0–2 / 0–1通用采样参数modalities/audio[text,audio,image]/ voiceformat多模态输出audio 的 voice 枚举含 ash/ballad/coral/sage/verse/alloy/echo/shimmer/marinformat 支持 wav/mp3/flac/opus/pcm16stream/stream_optionsbool /{include_usage}流式开关与用量回传reasoning_effortnone/minimal/low/medium/high/xhigh/max2024-12-17 加入max为 DeepSeek V4 扩展response_formattext / json_object / json_schema2024-08-06 Structured Outputsschema 名须匹配^[a-zA-Z0-9_-]{1,64}$web_search_optionssearch_context_size user_location网络搜索上下文与近似定位prediction{type:content, content}2024-11-05 Predicted OutputsSchema 之后还有一长串厂商方言扩展OpenRouter 的session_id/provider/max_tool_calls、Perplexity 的search_mode、Moonshot/DeepSeek 的thinking等这正体现了 wire types 文件的定位一份“OpenAI 兼容超集”以注释中的[厂商, 日期]标签标记每个扩展的来源。这种注释规范本身就是同步工作的落点——新增一个上游字段时必须能追溯到厂商与日期。三、Chat Completions Adapter请求组装与方言热修aixToOpenAIChatCompletions 是 Chat Completions 方向的翻译器文件头部的实现笔记先声明了能力边界见 openai.chatCompletions.ts#L11-L21只支持 N1top_p、parallel_tool_calls、stop等未实现doc part 以 markdown 文本内嵌、image part 以 base64 data URL 内嵌、所有 tool call 统一转为 function call。组装流程里最有工程含量的是按方言dialect打热修例如见 openai.chatCompletions.ts#L40-L100OpenAI/Azure o 系推理模型gpt-6/gpt-5/o4/o3/o1 前缀匹配去掉不支持的temperature/top_psystem 消息改用 2024-12-17 引入的developer角色max_tokens→max_completion_tokens对原生 OpenAI 与 Azure 全部改用新字段与 wire types 里的“DEPRECATED”注释呼应DeepSeek/Perplexity强制 user/assistant 角色交替、移除空消息DeepSeek V4 在有工具且未关思考时要求历史中每条 assistant 消息都带reasoning_content缺失时注入空串占位OpenRouter把客户端生成的session_id发给上游做粘性路由缓存不能跨 provider并把尾部的cache_control断点收敛到 4 个以内Anthropic 上游限制对拒收强制工具调用的模型把tool_choice: required降级为auto并插入 system 提示语补救函数调用不可用则快速失败Perplexity 等方言下若携带 tools 直接抛错而不是让上游报一个难读的错。随后构造请求体stream_options: { include_usage: true }流式时、response_format按model.strictJsonOutput决定、工具与tool_choice按模型的strictToolInvocations转换。最后还有一道_fixPairInteriorToolCalls保证“每个中间 tool call 都有配对的 tool 消息否则整个请求会被上游拒绝”。这些细节正是同步指令中“look deep in the fields of the requests”要求的具体形态一个字段的上游语义变化比如角色改名、字段废弃会同时波及 wire types、adapter 热修和 parser 三处。四、Chat Completions Parser块级流式协议的解析假设openai.parser.ts 顶部openai.parser.ts#L16-L36用注释完整陈述了它对块级流式协议chunk-based streaming的理解这也是同步时要重点验证的部分每个 chunk 含choices数组通常单项delta承载增量更新文本以delta.content字符串片段增量到达工具调用经delta.tool_calls增量到达且有固定方案首个 delta 携带完整 id 与函数名参数通常为空后续 delta 只追加参数文本——没有显式的 begin/end 标记靠时间顺序隐含工具调用的开始与结束流结束靠data: [DONE]信号不依赖finish_reason。解析入口 createOpenAIChatCompletionsChunkParser 在真正 Zod 解析前做了一组“防御性分流”每一条都对应同步时观察到的真实上游行为Keepalive 事件2025-01-13 上游加入{type:keepalive,...}静默跳过混淆占位 chunk无choices但带obfuscation的消息直接跳过否则会打断解析器error字段按 openai.error-severity.ts 的严重度分级转成方言终止事件而不是粗暴抛错Azure 特例空 id/model 且带prompt_annotations/prompt_filter_results的 chunk 忽略OpenRouter在 Zod 剥掉未知字段之前先从原始 JSON 里摘出provider路由信息用于展示尾部成本事件如x-opencode-type: inference-cost先收割 token/费用指标再跳过。之后才是ChunkResponse_schema.parse严格解析并记录timeToFirstEvent等性能指标。可以看到 parser 的演进史每条注释都带上游日期/厂商与 wire types 头部注释是同一套同步流程的两个出口。五、Responses API 侧方言差异表与事件流解析因为指令明确“Responses API 优先”openai.responsesCreate.ts 和 openai.responses.parser.ts 承载了主协议。Adapter 侧用一张方言差异表RspDialectQuirks见 openai.responsesCreate.ts#L26-L67取代零散的 if-else把“共享信封、各自校验器”的 OpenAI 兼容生态结构化差异项含义典型方言值vndNamespace连续性状态加密推理项、消息阶段的_vnd命名空间openai / sakanaai / xai / metaaiemitMessagePhase回放 assistant 消息时带phase字段Azure 为 false能力滞后webSearchTool托管 web_search 工具的形态full / bare / noneAzure 为 none“Hosted tool web_search is not supported”toolChoiceOnlyAutotool_choice 只接受 autometaai 严格校验器minOutputTokens校验器接受的最小 max_output_tokensmetaai 为 16每张表行都带日期标注如 Azure 的滞后截至 2025-11-18 仍成立这正是同步指令“点出所有协议差异”的输出形式。Parser 侧则按 Responses API 的事件类型状态机推进response.output_text.delta、response.output_text.done、response.output_text_annotation.added等见 openai.responses.parser.ts#L603-L660并对新旧两种 annotation 事件名做向后兼容。一个值得注意的上游怪癖处理是 “failed 响应打捞”openai.responses.parser.ts#L74-L89OpenAI 可能把一个实际已完整生成并流式发完的响应整体标记为failedTPM 限流检查发生在生成中途而非准入时解析器以 output 中每个 item 的status: completed作为“生成已完成”的权威信号把这类响应按成功处理。注释里标注了 2026-07-03 的 5/5 复现实测——这种“文档滞后、靠真实 SSE 才能发现”的行为恰好是同步指令里“live endpoint 是 ground-truth”一节的注脚。六、同步工作流信息源、活体探测与差异清单指令的后半部分给出了完整、可复用的同步操作手册这部分对任何维护 OpenAI 兼容层的团队都通用1信息源优先级逐级降级主源Responses API 参考优先、Chat Completions 参考、Changelog、模型列表、定价页用官方页面的 Copy Page 按钮下载 markdown便于 diff主源被挡时改用OpenAI 官方 Node.js SDK、Python SDK、OpenAPI 规范仓库或搜索“openai api changelog / new models / new prices”这类关键词获取近期公告全部被挡时如实说明尝试过什么并请人工提供文档——严禁在拿不到上游信息时编造。2活体端点探测额外信号如果本地.env.api-keys中存在OPENAI_API_KEY直接对真实端点打一发流式请求并检查原始 SSEPOST https://api.openai.com/v1/responseslegacy 则用/v1/chat/completions请求体带stream: true。文档可能滞后而原始 SSE 是新字段、事件类型、响应形态与错误格式的最终事实来源。指令同时强调绝不提交或回显密钥。3差异核对与输出要求深查请求与响应的字段级差异必填字段、流式事件类型、新的响应形态、协议本身的变更包括流式消息的最终解析与重组方式优先报告破坏性变更和能改善用户体验的新能力——前者必须尽快修后者进入实现待办指令的 frontmatter 支持$ARGUMENTS占位argument-hint 为 “specific feature to check”可以把检查范围收窄到某个具体特性。对照仓库现状可以验证这套流程的落地效果wire types 文件头的 Changelog 日期注释、wiretypes 内每个方言扩展的[厂商, 日期]标签、parser 里带日期注释的防御分支、以及_upstream/目录下的上游规范快照与sync.sh都是这个循环反复运转留下的痕迹。七、小结一套可迁移的协议同步方法big-AGI 的 OpenAI 同步指令把“跟上上游 API”从一次性的手工活变成了可重复的工程流程其要点可以概括为实现分三层且各司其职——Zod wire types 定义线格式含方言超集与日期注释、adapter 组装请求按方言打热修并快速失败、parser 消费响应先防御分流、再严格解析、以 item 级状态为权威协议优先级明确——Responses API 为主、Chat Completions 为 legacyRealtime 与 Agentic API 明确不接由 AIX 自研能力覆盖信息源分级 活体 SSE 兜底——文档、SDK、OpenAPI 规范逐级降级真实流式请求是文档滞后时的 ground-truth输出以“破坏性变更优先”排序——必填字段、流式事件类型、新响应形态是必查项所有上游观察都必须带厂商与日期标注沉淀回源码注释。维护同类项目时可直接复用这套结构先定位本项目的 wire types / adapter / parser 三件套再按“文档 → 活体探测 → 字段级 diff → 注释落回源码”的闭环执行同步。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
