docs/fix_claude_code_tool_use.md

针对 Claude Code "Field required" 错误的修复方案文档

1. 问题背景

在使用 Claude Code CLI 并通过 Antigravity-Manager 代理时，经常会出现以下报错： messages.X.content.0.text.text: Field required

根本原因： Claude Code 在进行工具调用（Tool Use）时，发送或接收的消息块中可能包含空的 text 字段（例如 {"text": ""} 或 {"text": " "}）。

• Google Gemini API：严禁在请求的 parts 中包含空的文本块。
• Anthropic 协议转换：在转换过程中，如果未能对空字符串进行 trim() 和有效性校验，就会导致上游 API 拒绝请求。

2. 针对性修改方案

本次修复主要涉及 src-tauri/src/proxy/mappers/claude/ 目录下的两个核心文件：

A. 请求端过滤 (src-tauri/src/proxy/mappers/claude/request.rs)

修改说明：在将 Claude 消息转换为 Google 格式时，对所有 ContentBlock::Text 和降级的思维块（Thinking）进行严格过滤。

• **修改点 1 (build_contents 函数)**：
  • 现状：仅检查了是否等于 (no content) 占位符。
  • 修复：引入 !text.trim().is_empty()，确保所有发送给 Google 的文本块都包含实际内容。
• **修改点 2 (思维块降级)**：
  • 现状：当思维模式被禁用或块顺序异常时，思维块会被转换为 text 块。
  • 修复：确保降级过程中排除掉仅含空格的文本，并对内容进行 trim() 处理。

B. 响应端优化 (src-tauri/src/proxy/mappers/claude/streaming.rs)

修改说明：优化流式响应转换逻辑，防止向客户端发送诱发状态机异常的空块。

• **修改点 1 (emit_finish 函数)**：
  • 现状：在处理 Web 搜索（Grounding）结果时，会初始化一个 text 块。
  • 修复：只有当搜索摘要 grounding_text.trim() 确实非空时，才允许发送该内容块分片。
• **修改点 2 (process_text 处理器)**：
  • 修复：增强了对 trailing_signature（签名暂存）场景下的逻辑鲁棒性，确保不会产生无意义的“幽灵”文本块。

3. 已应用的代码详情 (Git Diff 摘要)

Request Mapper:

// 修复前
if text != "(no content)" { ... }

// 修复后
if text != "(no content)" && !text.trim().is_empty() { ... }

Streaming State:

// 修复前
if !grounding_text.is_empty() { ... }

// 修复后
let trimmed_grounding = grounding_text.trim();
if !trimmed_grounding.is_empty() { ... }

4. 验证与部署建议

1. 分步确认：通过代理日志观察，确保不再出现 messages.X.text: Field required 的 HTTP 400 警告。
2. 连续对话测试：进行一次涉及文件读写的复杂任务（例如 claude fix bug），确认在 tool_use 返回后，Claude Code 能正常发送下一轮请求。
3. 编译命令：

   npm run tauri dev
   

---

文档由 Antigravity AI 助手生成，用于记录 fix/claude-code-tool-use-empty-text 分支的变更细节。