fix(pi): 按端点适配 SuperGrok 搜索工具

[zqchris]

这次改了什么

摘要

修复 Pi + SuperGrok 请求在 xAI endpoint 之间混用服务端搜索工具协议导致 422。真实上游探测确认 Chat Completions 的旧 live_search 已不可用，官方工具文档也已转向 Agent Tools / Responses：Pi 原生订阅转发现在对 /v1/chat/completions 清除误入的 x_search / live_search，保留普通 function tools 与合法 tool_choice；/v1/responses 继续规范化并只保留一个 x_search。

变更类型

• feat 新功能
• fix 缺陷修复
• refactor / perf 重构或性能优化
• docs / test / chore 文档、测试或工程维护
• 其他：

范围

• 关联 Issue / 需求：Closes bug: [xAI provider] 422 unknown variant 'x_search' when using Grok with web search (should now be 'live_search') #2927
• 本 PR 包含：Pi 原生 SuperGrok 转发的 endpoint 识别；Chat Completions 搜索工具清理；Responses 的 x_search 注入、归一化与去重；Responses 单一 function tool 的 tool_choice 合法化；最终请求体回归测试。
• 明确不包含：不全局改名；不修改 Claude Code / Codex / BYOM 链路；不包含 fix(pi): 补全第三方供应商协议适配 #2860 的第三方供应商适配、fix(pi): SuperGrok Grok 4.6 可热切，并收紧 live catalog 刷新 #2818 的 Grok 4.6 目录/热切换、fix(desktop): 修复 Gateway/LiteLLM Grok 的 ModelInput 422 #2909 的 Responses input[] 清洗。
• 用户可见变化：旧目录、旧任务或异常协议映射若仍把 Grok 请求送到 Chat Completions，不会再因携带 x_search / live_search 被工具 schema 拒绝；普通 function tools 不受影响。Grok 4.6 正常使用 Responses + x_search 依赖 fix(pi): SuperGrok Grok 4.6 可热切，并收紧 live catalog 刷新 #2818 将其 catalog 协议设为 openai-responses。
• 是否存在 breaking change：无。

UI 变化

• 引用的设计规范：不涉及；仅修改 Desktop main 进程请求体转换与测试，无 renderer、视觉、交互或文案变化。

怎么验证的

自动验证

pnpm --filter desktop exec vitest run src/main/maker-host/__tests__/piNativeSubscriptionForwarding.test.ts
结果：通过，11/11 tests passed

pnpm --filter desktop run --if-present typecheck
结果：通过

pnpm test:unit:related
结果：通过，apps/desktop related unit passed

pnpm check:dco
结果：通过，2 commits signed off

git diff --check
结果：通过

手工验证

不涉及 UI。通过测试中的 fetch recorder 检查最终发往上游的完整 JSON 请求体：

• Chat Completions 同时误入 x_search / live_search 时只保留原 function tool，并保留对应 tool_choice；
• Chat Completions 原本没有搜索工具时不主动添加，原始请求体字节不变；
• Grok 4.6 Responses 将旧 live_search / 重复搜索声明归一化为单一 x_search，function tool 与单函数收窄保持。

未执行的验证

未做真实 SuperGrok 账号 E2E：没有启动 Desktop dev 或向真实 xAI 账号发起计费请求。完整用户路径还依赖 #2818 合入后让 Grok 4.6 正常走 openai-responses；具备 SuperGrok 账号时应在两项改动同时存在的构建中选择 Pi + Grok 4.6，验证请求走 /v1/responses、不再返回 422，且 X 搜索可用。

风险

风险分类

• 无已知风险
• SQLite / migration
• system prompt
• 协议兼容
• 权限 / 安全 / 用户数据
• 存量插件兼容（批准状态 / 指纹 / manifest 校验 / 安装布局 / 包格式）
• 原生层 / fingerprint / OTA
• 跨平台差异
• 其他：上游请求体工具类型过滤与归一化

影响与回滚

• 影响范围：仅 Pi 原生 xAI/SuperGrok 订阅转发；转换由实际 /v1/responses 或 /v1/chat/completions endpoint 决定。Claude Code、Codex、BYOM 与共享 Responses 工具定义不变。缓存率、system prompt、事件流、模型路由和 usage 计量不受影响。
• 回滚 / 降级方式：回退本 PR 即恢复旧转发行为；回退后 Chat Completions 仍可能因误入 x_search / live_search 返回 422/410。

提交前检查

• 已 review 完整 diff
• 每个 commit 都带 DCO 签名（git commit -s，见 DCO）
• UI 改动已在「UI 变化」注明引用的设计规范章节（不涉及 UI 则跳过）
• 未提交凭证、令牌或授权文件
• 已补充必要文档
• 已确认测试结果或说明未执行原因

[greptile-apps]

Greptile Summary

此 PR 按实际 xAI 上游端点区分工具协议，避免 Pi 原生 SuperGrok 请求因混用搜索工具格式而被拒绝。

• Chat Completions 请求会移除不受支持的 x_search 与 live_search，并协调剩余工具控制字段。
• Responses 请求会将旧搜索声明规范化为单一 x_search，保留原生搜索配置并处理对应的 tool_choice。
• 新增最终上游请求体测试，覆盖搜索工具过滤、去重、选择规范化以及无须转换时的原始请求保留。

Confidence Score: 5/5

当前未发现仍需阻止合并的故障，PR 看起来可以安全合并。

未发现仍然存在的阻塞性故障。

Important Files Changed

Filename	Overview
apps/desktop/src/main/maker-host/anthropic-responses-bridge-host.ts	根据上游端点选择 wire protocol，并分别清理 Chat Completions 搜索工具或规范化 Responses 搜索工具。
apps/desktop/src/main/maker-host/tests/piNativeSubscriptionForwarding.test.ts	增加 Pi 原生 xAI 请求最终载荷的回归覆盖，包括过滤、去重、选择协调及原始请求保留。

_{Reviews (6): Last reviewed commit: "fix(pi): normalize xAI search tool choic..." | Re-trigger Greptile}

[nanaco666]

这里需要调整一下修复方向：当前把 Chat Completions 下的 x_search 转成裸 { type: "live_search" }，仍然不能解决真实上游请求。

我在 2026-08-18 对 https://api.x.ai/v1/chat/completions 做了不计费的 schema 探测：

• { type: "live_search" } 返回 422：缺少必填字段 sources；
• 补成 { type: "live_search", sources: [{ type: "x" }] } 后返回 410 Gone：Live search is deprecated. Please switch to the Agent Tools API。

官方当前工具文档也已经转向 Agent Tools / Responses：
https://docs.x.ai/docs/guides/tools/overview

建议把本 PR 收敛为以下方案：

1. /v1/chat/completions：删除误入的 x_search / live_search，保留 Pi 原有 function tools 与 tool_choice，不要追加任何 xAI 服务端搜索工具；这条路径只作为旧目录、旧任务或异常协议映射的防御性兜底。
2. /v1/responses：保持现有 x_search 注入、去重和 function-tool 收窄逻辑。
3. 将 grok-4.6 的 Pi 模型协议明确设为 openai-responses，让正常请求直接走 Responses + x_search。这一部分看起来已由 fix(pi): SuperGrok Grok 4.6 可热切，并收紧 live catalog 刷新 #2818 的 catalog addition / 热刷新覆盖，可避免在两个 PR 重复实现；需要确认合入顺序和旧任务刷新/重启行为。

建议补三组回归：

• 通用 Grok + Chat Completions + 误入 x_search：最终只保留 function tools，不出现 x_search/live_search；
• 通用 Grok + Chat Completions，原本没有搜索工具：不得主动添加搜索工具；
• Grok 4.6 + Responses：仍追加且只追加一个 x_search。

这样可以把两个问题分开：模型目录决定 Grok 4.6 正常走 Responses；endpoint 门控负责阻止 Responses 工具再次污染 Chat Completions。

[MagicLizi]

审查通过。wireProtocol 透传正确，x_search/live_search 按端点归一化且不留重复声明，tool_choice 窄化正确适配了 Chat Completions 的嵌套 function 形态。

[MagicLizi]

@zqchris 👋 这个 PR 目前与 main 有合并冲突,auto-review 因此暂时跳过、没法继续审查 / 合并。

请在本地 merge 最新的 origin/main 解决冲突后推送;冲突解除后,下一轮 auto-review 会自动重新处理这个 PR。

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a3b26015a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[MagicLizi]

Code Review — P1 ×1

P1: apps/desktop/src/main/maker-host/anthropic-responses-bridge-host.ts:556-575 — 搜索工具去重逻辑依赖数组顺序，可能静默丢弃真实配置

withNativeXaiServerSideTools 里的去重逻辑是 first-seen-wins：当 live_search（无选项的旧拼写）排在带 from_date 的真实 x_search 之前时，旧条目先占位被转为裸 { type: 'x_search' }，后续带选项的真实条目被作为 duplicate 丢弃。结果是日期限定等搜索参数静默丢失，用户无任何报错提示。

测试本身断言了这个行为（expect([{ type: 'x_search' }])，选项消失），但从函数注释意图来看（"preserving real declarations, normalizing stale spellings"），应该优先保留带选项的真实 x_search 条目，仅在没有真实条目时才 fallback 到转换 live_search。

建议修复方向：先扫描是否存在带选项的 x_search，有则保留；只在无真实 x_search 时才把 live_search 转换为裸 x_search。

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2332a848fc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[MagicLizi]

代码审查通过。

修复 Pi + SuperGrok 搜索工具在 xAI 不同端点之间的协议兼容问题：Chat Completions 清除不支持的搜索工具声明，Responses 规范化并去重。测试覆盖完整，逻辑清晰。

[MagicLizi]

干得漂亮 🎯 xAI 搜索工具在两种端点之间的兼容问题解决得很彻底,参数化测试把所有排列组合覆盖到了。