feat: 添加调试日志记录功能，增强工具调用和响应的匹配逻辑，更新相关文档和测试用例

Author: cuipengfei

.gitignore

@@ -38,3 +38,11 @@ tmp/litellm-gemini-study/translation-mechanisms.md
 tmp/google-ai-streamGenerateContent-docs.md
 tmp/review_v2.md
 gemini-plan.md
+debug-logs/debug-gemini-2025-09-24T16-05-00-806Z-750wa1-compressed.log
+debug-logs/debug-gemini-2025-09-24T16-05-00-806Z-750wa1.log
+debug-logs/debug-gemini-2025-09-24T16-05-16-625Z-w596rn-compressed.log
+debug-logs/debug-gemini-2025-09-24T16-05-16-625Z-w596rn.log
+debug-logs/debug-gemini-2025-09-24T16-05-20-120Z-m6ebiq-compressed.log
+debug-logs/debug-gemini-2025-09-24T16-05-20-120Z-m6ebiq.log
+debug-logs/debug-gemini-2025-09-24T16-05-24-000Z-nuggbx-compressed.log
+debug-logs/debug-gemini-2025-09-24T16-05-24-000Z-nuggbx.log

CLAUDE.md

@@ -75,6 +75,10 @@ Gemini integration
     - 逐块处理：`processAndWriteChunk/handleStreamingResponse`: `handler.ts:194-238, 241-282`
   - 工具调用的增量参数：不完整 JSON `arguments` 跳过当次块，等待后续完整块
     - `processToolCalls`: `translation.ts:537-577`
+  - **工具响应处理**：确保 tool call 与 response 1:1 映射
+    - `ensureToolCallResponseMatch`: `translation.ts` 对 tool responses 按 `tool_call_id` 去重
+    - 问题：OpenAI 可能返回重复的 tool responses，导致 Gemini 1:1 映射要求失败
+    - 解决：简单去重逻辑，保留每个 `tool_call_id` 的第一个响应
   - 终止原因映射
     - OpenAI → Gemini: `mapOpenAIFinishReasonToGemini` in `src/routes/generate-content/utils.ts:3-23`
     - Gemini → OpenAI: `mapGeminiFinishReasonToOpenAI` in `utils.ts:26-50`
@@ -105,11 +109,22 @@ Error handling
 
 - 常见 Gemini 问题
   - `invalid_tool_call_format`：工具声明缺失或参数为空；确保 `tools` 与 `tool_choice` 按需出现，并有非空 `parameters`
+  - **Tool call/response 1:1 映射错误**："Please ensure that the number of function response parts is equal to the number of function call parts" - 通常由重复的 `tool_call_id` 响应引起，需要去重而不是拆分
   - 嵌套 `functionResponse`：Gemini CLI 会发送嵌套数组，需用 `processFunctionResponseArray` 处理
   - `tool_call_id` 关联：用函数名暂存并在用户回应时取回，保持一致性
   - 取消的 tool call：清理掉未完成的 `assistant+tool_calls` 信息
   - `HTTPError`：多半是 OpenAI 侧 payload 校验失败
 
+- Debug 日志分析方法
+  - 使用 `DebugLogger` 自动生成 debug-logs/ 文件夹中的请求日志
+  - 压缩大日志文件便于分析：用 `compress-logs.js` 脚本删除重复内容
+  - 分析时用 PowerShell/脚本统计 function calls vs responses 数量：检查 `functionCall` 与 `functionResponse` 计数，以及翻译后的 `tool_calls` 与 tool responses 计数
+  - **调试方法论**：
+    - **数据先行**：从实际 debug logs 出发，不要基于理论假设
+    - **验证而非猜测**：每次修改后必须通过新 debug logs 验证效果
+    - **简单解决方案优先**：去重 > 拆分，避免过度复杂化
+    - **承认错误**：当证据显示修复制造了新问题时，快速重新思考
+
 - 快速自检
   - `bun run lint && bun run typecheck && bun run build`
   - `curl http://localhost:4142/v1/models` 查看真实支持的模型集合

src/lib/debug-logger.ts

@@ -0,0 +1,80 @@
+import { existsSync, mkdirSync } from "node:fs"
+import { writeFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import type { GeminiRequest } from "~/routes/generate-content/types"
+import type { ChatCompletionsPayload } from "~/services/copilot/create-chat-completions"
+
+interface DebugLogData {
+  timestamp: string
+  requestId: string
+  originalGeminiPayload: GeminiRequest
+  translatedOpenAIPayload: ChatCompletionsPayload | null
+  error?: string
+  processingTime?: number
+}
+
+export class DebugLogger {
+  private static instance: DebugLogger | undefined
+  private logDir: string
+
+  private constructor() {
+    this.logDir = process.env.DEBUG_LOG_DIR || join(process.cwd(), "debug-logs")
+    this.ensureLogDir()
+  }
+
+  static getInstance(): DebugLogger {
+    if (!DebugLogger.instance) {
+      DebugLogger.instance = new DebugLogger()
+    }
+    return DebugLogger.instance
+  }
+
+  private ensureLogDir(): void {
+    if (!existsSync(this.logDir)) {
+      mkdirSync(this.logDir, { recursive: true })
+    }
+  }
+
+  private generateLogFileName(requestId: string): string {
+    const timestamp = new Date().toISOString().replaceAll(/[:.]/g, "-")
+    return join(this.logDir, `debug-gemini-${timestamp}-${requestId}.log`)
+  }
+
+  async logRequest(data: {
+    requestId: string
+    geminiPayload: GeminiRequest
+    openAIPayload?: ChatCompletionsPayload | null
+    error?: string
+    processingTime?: number
+  }): Promise<void> {
+    const logData: DebugLogData = {
+      timestamp: new Date().toISOString(),
+      requestId: data.requestId,
+      originalGeminiPayload: data.geminiPayload,
+      translatedOpenAIPayload: data.openAIPayload ?? null,
+      error: data.error,
+      processingTime: data.processingTime,
+    }
+
+    const logPath = this.generateLogFileName(data.requestId)
+
+    try {
+      await writeFile(logPath, JSON.stringify(logData, null, 2), "utf8")
+      console.log(`[DEBUG] Logged request data to: ${logPath}`)
+    } catch (writeError) {
+      console.error(`[DEBUG] Failed to write log file ${logPath}:`, writeError)
+    }
+  }
+
+  // For backward compatibility during development
+  static async logGeminiRequest(
+    geminiPayload: GeminiRequest,
+    openAIPayload?: ChatCompletionsPayload,
+    error?: string,
+  ): Promise<void> {
+    const logger = DebugLogger.getInstance()
+    const requestId = Math.random().toString(36).slice(2, 8)
+    await logger.logRequest({ requestId, geminiPayload, openAIPayload, error })
+  }
+}

src/routes/generate-content/handler.ts

@@ -4,6 +4,7 @@ import type { SSEStreamingApi } from "hono/streaming"
 import { streamSSE } from "hono/streaming"
 
 import { awaitApproval } from "~/lib/approval"
+import { DebugLogger } from "~/lib/debug-logger"
 import { checkRateLimit } from "~/lib/rate-limit"
 import { state } from "~/lib/state"
 import { getTokenCount } from "~/lib/tokenizer"
@@ -295,6 +296,14 @@ export async function handleGeminiStreamGeneration(c: Context) {
 
   const openAIPayload = translateGeminiToOpenAIStream(geminiPayload, model)
 
+  // Log request for debugging (async, non-blocking) - only if debug logging is enabled
+  if (process.env.DEBUG_GEMINI_REQUESTS === "true") {
+    DebugLogger.logGeminiRequest(geminiPayload, openAIPayload).catch(
+      (error: unknown) => {
+        console.error("[DEBUG] Failed to log request:", error)
+      },
+    )
+  }
   if (state.manualApprove) {
     await awaitApproval()
   }

src/routes/generate-content/translation.ts

@@ -111,14 +111,24 @@ function processFunctionResponseArray(
   for (const responseItem of responseArray) {
     if ("functionResponse" in responseItem) {
       const functionName = responseItem.functionResponse.name
-      const toolCallId = pendingToolCalls.get(functionName)
-      if (toolCallId) {
+      // Find tool call ID by searching through the map
+      let matchedToolCallId: string | undefined
+      for (const [
+        toolCallId,
+        mappedFunctionName,
+      ] of pendingToolCalls.entries()) {
+        if (mappedFunctionName === functionName) {
+          matchedToolCallId = toolCallId
+          break
+        }
+      }
+      if (matchedToolCallId) {
         messages.push({
           role: "tool",
-          tool_call_id: toolCallId,
+          tool_call_id: matchedToolCallId,
           content: JSON.stringify(responseItem.functionResponse.response),
         })
-        pendingToolCalls.delete(functionName)
+        pendingToolCalls.delete(matchedToolCallId)
       }
     }
   }
@@ -150,14 +160,21 @@ function processFunctionResponses(
 ): void {
   for (const funcResponse of functionResponses) {
     const functionName = funcResponse.functionResponse.name
-    const toolCallId = pendingToolCalls.get(functionName)
-    if (toolCallId) {
+    // Find tool call ID by searching through the map
+    let matchedToolCallId: string | undefined
+    for (const [toolCallId, mappedFunctionName] of pendingToolCalls.entries()) {
+      if (mappedFunctionName === functionName) {
+        matchedToolCallId = toolCallId
+        break
+      }
+    }
+    if (matchedToolCallId) {
       messages.push({
         role: "tool",
-        tool_call_id: toolCallId,
+        tool_call_id: matchedToolCallId,
         content: JSON.stringify(funcResponse.functionResponse.response),
       })
-      pendingToolCalls.delete(functionName)
+      pendingToolCalls.delete(matchedToolCallId)
     }
   }
 }
@@ -175,7 +192,8 @@ function processFunctionCalls(options: {
   const toolCalls = functionCalls.map((call) => {
     const toolCallId = generateToolCallId(call.functionCall.name)
     // Remember this tool call for later matching with responses
-    pendingToolCalls.set(call.functionCall.name, toolCallId)
+    // Use tool_call_id as key to avoid duplicate function name overwrites
+    pendingToolCalls.set(toolCallId, call.functionCall.name)
 
     return {
       id: toolCallId,
@@ -207,6 +225,8 @@ function mergeConsecutiveSameRoleMessages(
       && lastMessage.role === message.role
       && !lastMessage.tool_calls
       && !message.tool_calls
+      && !(lastMessage as { tool_call_id?: string }).tool_call_id // Don't merge tool responses
+      && !(message as { tool_call_id?: string }).tool_call_id // Don't merge tool responses
     ) {
       // Merge with previous message of same role
       if (
@@ -247,7 +267,7 @@ function removeIncompleteAssistantMessages(messages: Array<Message>): void {
   }
 }
 
-function translateGeminiContentsToOpenAI(
+export function translateGeminiContentsToOpenAI(
   contents: Array<
     | GeminiContent
     | Array<{
@@ -257,7 +277,7 @@ function translateGeminiContentsToOpenAI(
   systemInstruction?: GeminiContent,
 ): Array<Message> {
   const messages: Array<Message> = []
-  const pendingToolCalls = new Map<string, string>() // function name -> tool_call_id
+  const pendingToolCalls = new Map<string, string>() // tool_call_id -> function_name
 
   // Add system instruction first if present
   if (systemInstruction) {
@@ -309,8 +329,11 @@ function translateGeminiContentsToOpenAI(
   // Post-process: Remove incomplete assistant messages from cancelled tool calls
   removeIncompleteAssistantMessages(messages)
 
+  // Post-process: Deduplicate tool responses (remove duplicate tool_call_ids)
+  const matchedMessages = ensureToolCallResponseMatch(messages)
+
   // Post-process: Merge consecutive messages with same role (based on LiteLLM research)
-  return mergeConsecutiveSameRoleMessages(messages)
+  return mergeConsecutiveSameRoleMessages(matchedMessages)
 }
 
 function synthesizeToolsFromContents(
@@ -466,6 +489,32 @@ function translateGeminiToolConfigToOpenAI(
 
 // Response translation: OpenAI -> Gemini
 
+// Helper function to deduplicate tool responses - remove duplicate tool_call_ids
+// The problem was our logic was CREATING duplicates instead of preventing them
+
+function ensureToolCallResponseMatch(messages: Array<Message>): Array<Message> {
+  const result: Array<Message> = []
+  const seenToolCallIds = new Set<string>() // Track processed tool_call_ids to avoid duplicates
+
+  for (const message of messages) {
+    if (message.role === "tool" && message.tool_call_id) {
+      const toolCallId = message.tool_call_id
+
+      // Only keep the FIRST response for each tool_call_id (deduplicate)
+      if (!seenToolCallIds.has(toolCallId)) {
+        seenToolCallIds.add(toolCallId)
+        result.push(message)
+      }
+      // Skip any duplicate responses for the same tool_call_id
+    } else {
+      // Keep all non-tool messages as-is
+      result.push(message)
+    }
+  }
+
+  return result
+}
+
 export function translateOpenAIToGemini(
   response: ChatCompletionResponse,
 ): GeminiResponse {
@@ -561,7 +610,12 @@ function processToolCalls(
   const parts: Array<GeminiPart> = []
 
   for (const toolCall of toolCalls) {
-    if (!toolCall.function?.name) {
+    // Enhanced validation: check for empty/whitespace-only names
+    if (
+      !toolCall.function?.name
+      || typeof toolCall.function.name !== "string"
+      || toolCall.function.name.trim() === ""
+    ) {
       continue
     }
 
@@ -723,6 +777,22 @@ export function translateOpenAIChunkToGemini(chunk: ChatCompletionChunk): {
     return null
   }
 
+  // Additional validation - if we only have function call parts with empty names,
+  // skip this chunk entirely to prevent invalid tool call responses
+  const hasOnlyEmptyToolCalls =
+    parts.length > 0
+    && parts.every((part) => {
+      if ("functionCall" in part) {
+        return !part.functionCall.name || part.functionCall.name.trim() === ""
+      }
+      return false
+    })
+    && parts.some((part) => "functionCall" in part)
+
+  if (hasOnlyEmptyToolCalls && !choice.finish_reason) {
+    return null
+  }
+
   const shouldInclude = shouldIncludeFinishReason(choice)
   const mappedFinishReason =
     shouldInclude ?