opencodex Web Search 原生保真度实战：强制回答引导、实时搜索状态与多查询批处理

【免费下载链接】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 项目中 Web Search 原生保真度native web-search fidelity三阶段工作的第二阶段如何在代理proxy模式下让 Codex 客户端呈现出与原生 Responses API 一致的搜索体验。读完本文你将掌握三个核心能力通过迭代局部iteration-local的 developer 提示词引导强制回答引用搜索结果将单一搜索事件拆分为 begin/end 两个生命周期事件让 Searching the web 状态真实覆盖 sidecar 调用时长以及支持模型批量提交多个查询并渲染原生action.search.queries。所有机制均有源码与测试佐证可直接对照仓库深入阅读。本文对应的原始设计文档为 devlog/_fin/260630_native-sidecar-parity/30_phase2_websearch-fidelity.md属于 260630_native-sidecar-parity 系列中 Web 搜索侧车sidecar原生对齐 的第二个阶段。背景为什么需要 原生保真度opencodex 作为 OpenAI Codex 的通用代理universal provider proxy允许任意 LLM 通过 Codex CLI / App / SDK 使用。当模型不支持原生web_search工具时代理会注入一个合成函数工具web_search见 synthetic-tool.ts拦截模型调用后通过托管 sidecar 执行真实搜索再把结果作为toolResult回注给模型主循环见 src/web-search/loop.ts。这一 拦截-执行-回注 架构引入了三个与原生体验不一致的缺口正是 Phase 2 要修复的对象强制回答forced-answer不引用搜索结果弱模型在forceAnswer阶段可能给出与搜索结果无关的单薄回答用户感知为 搜索没起作用搜索状态不可见搜索实际执行数秒但客户端从未展示 Searching the web 的进行中状态不支持多查询原生action.search.queries复数字段未被支持代理只携带单数query。设计文档中三个 PABCDPlan-Act-Build-Check-Debug周期分别对应这三个缺口。注意结果本身故意不做渲染native 只显示查询单元格这三项都属于活动单元格activity-cell保真度问题。Cycle 1强制回答必须反映搜索结果loop.ts问题搜索结果只以toolResult形式注入模型。在强制回答阶段forceAnswer此时web_search工具已被移除模型无法再发起搜索一个弱模型可能生成没有提及搜索结果的单薄答案用户会认为 搜索什么都没做。变更在 src/web-search/loop.ts 的runWithWebSearch中当forceAnswer为true且至少执行过一次真实搜索executedSearchCount 0时向强制阶段请求的messages注入一条瞬态 developer 角色提示词指示模型基于已收集的 web 结果作答并引用来源。关键实现细节源码印证提示词构造于forcedAnswerNudge()函数loop.ts内容明确要求基于上面已收集的 web 搜索结果回答问题以结果实际内容为准引用可用来源不要声称缺少结果中包含的信息也不要编造未返回的来源注入位置在prepareIterationEvents生成器内loop.tsiterMessages forceAnswer executedSearchCount 0 ? [...messages, forcedAnswerNudge()] : messages迭代局部性nudge 只拼入本次请求的iterParsed.context.messages绝不写入持久化的messages数组。虽然forceAnswer本身是终态仍将其限制在迭代内以保证安全配套的forcedAnswerRetryNudge()loop.ts用于强制回答为空后的单次恢复 pass此时所有工具被移除toolChoice: none提示模型直接输出文本或说明缺失信息。范围外OUT of scope不修改formatWebSearchResult、来源数量上限或搜索执行路径。验收标准与测试新增循环级测试强制回答 passmaxSearches已耗尽时适配器收到的请求中包含 developer nudge且仅当真实搜索发生过零真实搜索仅空查询 / 达到上限 / 重复占位时不注入nudge。测试实现位于 tests/web-search/web-search.test.ts 的web-search forced-answer nudge测试组capturingAdapter逐 pass 记录适配器收到的消息断言第一轮搜索轮无 developer 消息、第二轮强制回答轮末尾恰好一条 developer nudge且parsed.context.messages长度不变——证明 nudge 是迭代局部的第二个用例以空查询{ query: }触发占位路径断言所有 pass 均无 nudge因为executedSearches保持为空。Cycle 2实时 in_progress → completed 生命周期bridge.ts loop.ts问题原实现中loop 缓冲全部内容后在最后一次性重放[...searchEvents, ...finalEvents]而 bridge 紧挨着发出added(in_progress)done(completed)两帧。由于所有模型调用和 sidecar 调用在 SSE 开始前都已结束Searching the web 状态在实际往往持续数秒的sidecar 调用期间从未显示用户看到的只有一闪而过的状态对。变更把单一的web_search_callAdapterEvent 拆分为两个生命周期事件让 loop 在真实墙钟时刻发出beginstatusin_progress无 action 字段在runWebSearch之前发出endstatuscompleted/failed携带action.search.query在其返回之后发出。loop 不再收集搜索事件到最后统一前置而是与真实 sidecar 时间交错地实时流式发出 begin/end。设计细节拆事件 保留 eager-error 契约原文档给出了明确的架构约束均被测试固化必须保留的硬契约迭代 1 的模型 fetch 失败 / 流开始前的 turn 中止必须返回带真实 HTTP 状态码的jsonError502 / 499 / 上游状态。sidecar-abort.test.ts在首次 fetch 期间中止并断言response.status 502sidecarweb_search失败不致命通过recordSidecarOutcome记录loop 仍返回 200 SSE由模型作答。测试 web-search loop forwards sidecar outcomes 断言 200。事件拆分方案src/types/request.ts 中的 AdapterEvent 定义web_search_call_begin { id }→ bridge 发出output_item.addedstatusin_progressweb_search_call_end { id, query, status }→ bridge 发出output_item.donestatuscompleted/failed并带action.search由于只有 loop 发出这些事件无需为兼容保留旧的合并事件可干净迁移。SSE 主体重构为 async generatorloop.ts 的produce()只有第一次模型调用被急切执行firstPrepared await prepareIterationDrained(false)loop.ts其 fetch/parse 错误仍返回jsonError若第一次调用为终态无搜索照原样流式输出 passthrough若要搜索则向 bridge 提供生成器从首次调用拦截到的 web_search 调用开始emit begin → 等待真实runWebSearchsidecar → emit end然后在生成器内执行下一轮模型迭代并重复最后 yield 终态 passthrough第 2 轮迭代的模型调用失败此时已在实时流内、状态码已 200以流内error事件呈现bridge 已把error映射为终态 failed。这是唯一的行为变更且没有测试为迭代 2 断言非 200。Bridge 侧的实现印证流式路径在 src/bridge/sse.tsweb_search_call_begin先关闭其他打开的 item分配输出索引emitresponse.output_item.addeditem 为{ type: web_search_call, id: ws_..., status: in_progress }并保持打开直至匹配的 end 或终态关闭web_search_call_end若没有对应的 begin防御性先合成 added 帧随后closeCurrentWebSearch(status, queries, sources)emitresponse.output_item.doneitem 带action: webSearchAction(queries)与可选的sources终态兜底流以 error/incomplete/截断结束而搜索仍在途时以failed关闭单元格避免 Codex 客户端永远旋转 Searching the web 指示器sse.ts。批量/非流式路径在 src/bridge/response-json.tsweb_search_call_begin是无操作该路径没有 in_progress 动画阶段web_search_call_end把单元格作为单一终态 item 推入output[]。验收标准细化与测试搜索的 begin 帧在 sidecar promise 仍 pending 时发出用延迟 sidecar fetch 断言顺序end 帧在其 resolve 之后迭代 1 的硬失败 / 中止仍返回 jsonError 502既有测试保持绿色sidecar 失败仍产出可完成的 200 流。对应测试tests/web-search/web-search.test.ts 的 the in_progress added frame is emitted BEFORE the sidecar search resolves——用一个sidecarGatePromise 门控 sidecar 响应逐帧读取 SSE断言order[0]是response.output_item.added:in_progress且仅在看到该帧后才释放门证明旋转指示器是真实存活的而非背靠背闪现。Cycle 3原生多查询types.ts bridge.ts loop.ts问题原生语义允许单个web_search_call携带action.search.queries复数当模型把相关查询批量合并进一次调用时使用。原实现只接受/携带单数query。变更合成工具src/web-search/synthetic-tool.tsbuildWebSearchTool()的web_search函数同时接受querystring或queriesstring[]描述为 一次运行一个或多个相关查询参数解析loop.ts 的parseQueries从模型参数解析规范queries: string[]——queries[]存在且非空则用之否则[query]非空则用之否则[]空查询占位。非字符串/空条目被丢弃畸形 JSON 得到[]。WebSearchCall携带{ id, queries }执行与配对loop.ts 的runSearchCall一个 call 可含多个查询。为保持函数调用配对有效一个 tool call → 一个 tool result每个查询依次经 sidecar 执行预算感知各自计入maxSearches/failedQueries去重集合然后注入一个assistant toolCall参数{ queries }和一个聚合 toolResult。只发出一个begin 与一个end 单元格end 携带全部尝试过的queries使 Codex 渲染原生 Searchedfirst... 样式结果聚合src/web-search/format-result.ts 的formatWebSearchResults把多个 (query, outcome) 块渲染为单一 tool_result 字符串——prose 模式用带标签的块[1/N]前缀结构化模式用单个 JSON{ results: [...] }。单查询路径完全委托formatWebSearchResult逐字节保持原样back-compat。聚合结果受全局预算钳制MAX_ANSWER_CHARS 4000、MAX_SOURCES 8、MAX_TOTAL_CHARS 8000format-result.ts防止批量查询撑爆主模型上下文类型与桥接src/bridge/internal.ts 的webSearchActionweb_search_call_end携带可选queries: string[]bridge 在流式与非流式两个路径都发出action: { type: search, query, queries }query取第一个对齐 codex-rs 的WebSearchAction::Search { query, queries }。值得注意的双字段设计webSearchAction无条件同时输出query第一个为空时与queries为空时[first]。原文档注释说明这是 承重load-bearing设计——DeepSeek 原生 Responses 解析器把queries当作必填字段而 Console Go 的上游校验器把query当作必填字段缺任一会导致历史重放 400。这一权衡多查询批次的省略号标签让步于跨端可用性在源码注释中被明确禁止回退issue #3071 / #930。验收标准与测试一个含两个查询的批量调用运行两次 sidecar 搜索注入一个 toolCall 一个 toolResult发出一个单元格其action.search.queries含两个查询、query为第一个单数query调用行为不变预算每个查询都计入maxSearches。测试见 tests/web-search/web-search.test.tsa single call with queries[] runs each query and emits ONE cell carrying all queries——脚本适配器发出{ queries: [rust async, tokio runtime] }从 sidecar 请求体捕获两个查询确认都实际执行断言response.completed的output[]中恰好一个web_search_call单元格且action匹配{ type: search, queries: [rust async, tokio runtime] }。贯穿三个 Cycle 的设计契约小结契约来源验证nudge 仅当真实搜索发生过executedSearchCount 0且为迭代局部loop.tsweb-search.test.ts迭代 1 硬失败 / 中止 →jsonError带真实状态码502/499/上游状态loop.tssidecar-abort.test.ts断言 502sidecar 失败不致命 → 记录后仍 200 SSErecordSidecarOutcome经 loop.ts 传入 executorweb-search loop forwards sidecar outcomes 断言 200begin 帧先于 sidecar resolveend 帧后于sse.tsweb-search.test.tsdeferred gate单查询路径逐字节兼容format-result.ts批量测试断言cells.length 1action同时携带query与queries双字段internal.ts重放兼容测试issue #930 / #3071相关文件导航设计文档devlog/_fin/260630_native-sidecar-parity/30_phase2_websearch-fidelity.md同系列前序阶段见 10_phase1_websearch-native-ui.md 与 00_research.md主循环src/web-search/loop.ts合成工具定义src/web-search/synthetic-tool.ts结果格式化src/web-search/format-result.ts事件类型定义src/types/request.ts流式桥接src/bridge/sse.ts批量桥接src/bridge/response-json.ts测试tests/web-search/web-search.test.ts桥接相关见 web-search-passthrough-bridge.test.ts以上实现均位于当前仓库可直接阅读源码与测试深入验证每个验收标准的落地方式。赞分享【免费下载链接】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点击查看免费下载相关推荐终极指南Karakeep如何通过TypeScript严格模式实现类型安全终极指南Karakeep如何通过TypeScript严格模式实现类型安全 Karakeep作为一款自托管的全能书签应用融合了链接、笔记和图片管理功能并借助数据库OLAP大数据后端Higress ai-search 插件实战为 AI 模型接入多引擎实时搜索增强Higress ai search 插件实战为 AI 模型接入多引擎实时搜索增强 本篇技术指南围绕 Higress 开源 AI 网关的 ai search 插API网关后端云原生LLM 网关人工智能MCP 服务OpenClaw Kimi 搜索Moonshot Web SearchAI 合成答案、引用与 grounding 机制深度指南OpenClaw Kimi 搜索Moonshot Web SearchAI 合成答案、引用与 grounding 机制深度指南 Kimi 是 OpenClAI 应用AI Agent交互助手后端即时通讯网关创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考