update at 2025-10-15 15:07:45

2025-10-15 15:07:45 +08:00
parent eb8fb51283
commit 901d00e4e1
21 changed files with 4030 additions and 57 deletions
--- a/docs/MCP_TOOL_DEBUG_GUIDE.md
+++ b/docs/MCP_TOOL_DEBUG_GUIDE.md
@@ -0,0 +1,350 @@
+# MCP 工具调用调试指南
+
+## 问题现象
+
+用户界面显示工具调用成功：
+```
+🔧 正在调用工具: publish_content...
+✅ 工具执行完成
+🤖 正在生成回复...
+已为您发布一篇仅自己可见的笔记，主题为《如何制作酸菜鱼》...
+```
+
+但实际上：
+- Server 端日志没有收到调用请求
+- 内容没有真正发布
+
+## 调试步骤
+
+### 1. 检查工具调用是否被触发
+
+打开浏览器控制台（F12），查找以下关键日志：
+
+```javascript
+// 应该看到：
+🔍 [callModelStream] 检查工具调用: {
+  hasData: true,
+  hasToolCalls: true,
+  toolCallsCount: 1,
+  hasMcpServerId: true,
+  mcpServerId: "xhs-sse",
+  toolCalls: [...]
+}
+```
+
+**如果看到 `toolCallsCount: 0` 或 `hasToolCalls: false`**：
+- 问题：AI 模型没有返回工具调用
+- 可能原因：
+  1. 模型不支持 Function Calling
+  2. System Prompt 没有正确注入
+  3. 工具格式不正确
+
+### 2. 检查 SSE 流中的工具调用
+
+查找 SSE 解析日志：
+
+```javascript
+// 应该看到：
+🔧 [makeChatRequestStream] SSE检测到 tool_calls: [
+  {
+    index: 0,
+    id: "call_abc123",
+    type: "function",
+    function: {
+      name: "xiaohongshu__publish_content",
+      arguments: "{\"title\":..."
+    }
+  }
+]
+
+🔧 [makeChatRequestStream] 创建新工具调用 [0]: {...}
+🔧 [makeChatRequestStream] 更新工具名 [0]: xiaohongshu__publish_content
+🔧 [makeChatRequestStream] 累积参数 [0]: {"title":...
+```
+
+**如果没有看到这些日志**：
+- 问题：SSE 流中没有 tool_calls 数据
+- 可能原因：
+  1. AI 服务商返回格式不标准
+  2. SSE 解析逻辑有问题
+  3. 模型真的没有决定调用工具
+
+### 3. 检查工具调用收集
+
+查找最终收集日志：
+
+```javascript
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 [makeChatRequestStream] 最终收集到工具调用: 1 个
+   工具 [0]: {
+     id: "call_abc123",
+     name: "xiaohongshu__publish_content",
+     arguments: "{\"title\":\"🐟 超详细！...\",\"content\":\"...\",...}"
+   }
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**如果看到 `没有检测到工具调用`**：
+- 问题：工具调用数据没有被正确累积
+- 检查：`toolCallsMap` 是否为空
+
+### 4. 检查工具名称解析
+
+查找工具执行详情：
+
+```javascript
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 [executeToolCalls] 工具调用详情:
+   - 完整工具名: xiaohongshu__publish_content
+   - 提取工具名: publish_content
+   - MCP服务器ID: xhs-sse
+   - 参数: {
+       "title": "🐟 超详细！...",
+       "content": "...",
+       "tags": [...],
+       "category": "美食"
+     }
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**如果工具名称解析错误**：
+- 检查：`split('__')` 逻辑
+- 检查：是否有 `__` 分隔符
+
+### 5. 检查 MCP 协议调用
+
+查找 MCP 客户端日志：
+
+```javascript
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 [MCPClientService.callTool] 准备调用工具
+   - 服务器ID: xhs-sse
+   - 工具名称: publish_content
+   - 参数: {
+       "title": "...",
+       "content": "...",
+       ...
+     }
+   - MCP协议调用: tools/call
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**如果没有看到这个日志**：
+- 问题：根本没有执行到 `MCPClientService.callTool`
+- 原因：前面的步骤出错了
+
+**如果看到调用失败**：
+```javascript
+❌ [MCPClientService.callTool] 工具调用失败
+   - 工具名称: publish_content
+   - 错误信息: Error: ...
+```
+- 检查错误信息
+- 检查 MCP 服务器是否正常运行
+- 检查参数格式是否正确
+
+### 6. 检查服务器端日志
+
+在 MCP Server 端查看：
+
+```bash
+# 应该看到类似日志：
+[INFO] 收到工具调用请求: publish_content
+[INFO] 参数: {"title": "...", ...}
+[INFO] 开始发布内容...
+[INFO] 发布成功，返回结果
+```
+
+**如果服务器端没有日志**：
+- 问题：请求根本没有到达服务器
+- 可能原因：
+  1. 连接已断开
+  2. MCP 协议调用格式错误
+  3. 传输层问题（HTTP/SSE）
+
+## 常见问题排查
+
+### 问题 1: 显示成功但没有实际调用
+
+**症状**：
+- UI 显示 ✅ 工具执行完成
+- AI 返回友好的成功消息
+- 但 Server 端没有收到请求
+
+**排查**：
+1. 检查浏览器控制台，查找 `[MCPClientService.callTool]` 日志
+2. 如果没有这个日志，说明根本没有调用 MCP
+3. 检查是否进入了错误处理分支（假成功）
+
+**可能原因**：
+```typescript
+// 错误处理中可能返回了假的成功结果
+try {
+  const result = await this.mcpClient.callTool(...)
+  return result
+} catch (error) {
+  // 这里可能返回了假的成功对象
+  return { success: true } // ❌ 错误！
+}
+```
+
+### 问题 2: AI 没有调用工具
+
+**症状**：
+- 控制台显示 `没有检测到工具调用`
+- AI 直接回答了问题，没有使用工具
+
+**排查**：
+1. 检查 System Prompt 是否正确注入
+2. 检查工具列表是否正确传递给 AI
+3. 检查 AI 模型是否支持 Function Calling
+
+**解决方法**：
+```typescript
+// 确保 System Prompt 被添加
+if (tools.length > 0 && messages.length > 0 && messages[0].role !== 'system') {
+  const systemPrompt = this.createSystemPromptWithTools(tools, mcpServerName)
+  messages = [
+    { role: 'system', content: systemPrompt },
+    ...messages
+  ]
+}
+
+// 确保工具被传递
+await modelServiceManager.sendChatRequestStream(
+  service.id,
+  messages,
+  selectedModel,
+  onChunk,
+  tools.length > 0 ? tools : undefined // ✅ 正确传递
+)
+```
+
+### 问题 3: 工具名称格式错误
+
+**症状**：
+```
+❌ 工具调用失败: 工具 xiaohongshu__publish_content 不存在
+```
+
+**排查**：
+- 检查工具名称是否包含 `__` 前缀
+- 检查解析后的工具名是否正确
+
+**解决方法**：
+```typescript
+// 正确的解析逻辑
+const fullFunctionName = "xiaohongshu__publish_content"
+const toolName = fullFunctionName.includes('__') 
+  ? fullFunctionName.split('__')[1]  // publish_content ✅
+  : fullFunctionName
+
+// 使用原始名称调用 MCP
+await this.mcpClient.callTool(mcpServerId, toolName, functionArgs)
+```
+
+### 问题 4: 参数格式错误
+
+**症状**：
+```
+❌ 工具调用失败: 参数格式不正确
+```
+
+**排查**：
+1. 检查 `functionArgs` 是否正确解析
+2. 检查 JSON 格式是否有效
+
+**解决方法**：
+```typescript
+// 确保参数被正确解析
+const functionArgs = JSON.parse(toolCall.function.arguments)
+
+// 打印参数查看
+console.log('参数:', JSON.stringify(functionArgs, null, 2))
+```
+
+### 问题 5: MCP 服务器未连接
+
+**症状**：
+```
+❌ 工具调用失败: 服务器 xhs-sse 未连接
+```
+
+**排查**：
+1. 在 MCP 设置中检查服务器状态
+2. 尝试重新连接
+3. 检查服务器进程是否运行
+
+**解决方法**：
+1. 重启 MCP 服务器
+2. 在 UI 中重新连接
+3. 检查连接配置是否正确
+
+## 调试流程图
+
+```
+用户发送消息
+    ↓
+[检查点 1] System Prompt 是否注入？
+    ↓ Yes
+[检查点 2] 工具列表是否传递给 AI？
+    ↓ Yes
+AI 处理并返回 SSE 流
+    ↓
+[检查点 3] SSE 流中是否有 tool_calls？
+    ↓ Yes
+[检查点 4] tool_calls 是否正确收集？
+    ↓ Yes
+[检查点 5] 工具名称是否正确解析？
+    ↓ Yes
+[检查点 6] MCP Client 是否调用？
+    ↓ Yes
+[检查点 7] MCP Server 是否收到请求？
+    ↓ Yes
+[检查点 8] MCP Server 是否返回结果？
+    ↓ Yes
+✅ 成功！
+```
+
+## 增强的日志输出
+
+现在代码中已经添加了详细的日志，按顺序查找：
+
+1. **工具收集阶段**：
+```
+🔧 [makeChatRequestStream] SSE检测到 tool_calls
+🔧 [makeChatRequestStream] 创建新工具调用
+🔧 [makeChatRequestStream] 更新工具名
+🔧 [makeChatRequestStream] 累积参数
+🔧 [makeChatRequestStream] 最终收集到工具调用: X 个
+```
+
+2. **工具检查阶段**：
+```
+🔍 [callModelStream] 检查工具调用
+🔧 [callModelStream] 开始执行工具调用
+```
+
+3. **工具执行阶段**：
+```
+🔧 [executeToolCalls] 工具调用详情
+🔧 [MCPClientService.callTool] 准备调用工具
+✅ [MCPClientService.callTool] 工具调用成功
+```
+
+## 下一步
+
+如果通过上述调试仍然找不到问题，请：
+
+1. **复制完整的控制台日志**
+2. **复制 MCP Server 端的日志**
+3. **提供以下信息**：
+   - 使用的 AI 模型
+   - MCP 服务器类型
+   - 连接方式（HTTP/SSE）
+   - 完整的错误信息
+
+---
+
+**更新时间**: 2024-01-15  
+**版本**: v1.0.2+ Debug