map-client-vue/docs/QUICK_TEST_GUIDE.md

Cherry Studio 架构快速测试指南

🎯 测试目标

验证 Cherry Studio 风格的 MCP 工具调用是否正常工作：

• ✅ 工具名称前缀（serverName__toolName）
• ✅ System Prompt 自动生成
• ✅ AI 自动生成参数
• ✅ 工具名称解析和执行
• ✅ 完整对话流程

📋 准备工作

1. 启动服务

后端服务器

cd /Users/gavin/xhs/mcp-client-vue
npm run dev:server

前端应用

cd web
npm run dev

2. 配置 AI 模型服务

在"模型服务"中添加支持 Function Calling 的服务：

• OpenAI: GPT-4, GPT-3.5-Turbo
• 阿里云: qwen-turbo-latest, qwen-plus
• 火山引擎: doubao-pro

确保服务状态显示"已连接"✅

3. 配置 MCP 服务器（示例）

在"MCP 设置"中添加测试服务器：

{
  "name": "xiaohongshu",
  "command": "node",
  "args": ["path/to/xiaohongshu-mcp-server.js"],
  "env": {}
}

或者使用现有的 MCP 服务器。

🧪 测试用例

测试 1: 基本工具调用 ⭐️⭐️⭐️

目的: 验证完整流程

步骤:

1. 选择支持 Function Calling 的模型（如 GPT-4）
2. 选择 MCP 服务器（如 xiaohongshu）
3. 输入: 帮我发布小红书文章，内容是：如何制作一道酸菜鱼

期望结果:

AI 回复: 
✅ 文章已成功发布到小红书！

📝 标题：🐟 超详细！家常酸菜鱼做法，10分钟学会！
🔗 链接：https://www.xiaohongshu.com/discovery/item/...
📊 当前浏览：0 | 点赞：0

你的酸菜鱼教程已经上线啦！记得定期查看数据哦~ 🎉

验证点:

• ✅ AI 自动创作了完整文章（标题、正文、标签、分类）
• ✅ 工具被成功调用
• ✅ 返回友好的结果展示

---

测试 2: System Prompt 验证 ⭐️⭐️

目的: 确认 System Prompt 被正确添加

步骤:

1. 打开浏览器开发者工具（F12）
2. 切换到 Console 标签页
3. 发送任意消息（选择了 MCP 服务器）

期望日志:

🔧 [callModelStream] 获取 MCP 服务器工具: xiaohongshu
🔧 [callModelStream] MCP 服务器名称: xiaohongshu
🔧 [callModelStream] MCP 原始工具列表: [{name: 'public_content', ...}]
🔧 [callModelStream] 转换后的工具: 1 个 [{function: {name: 'xiaohongshu__public_content', ...}}]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 [callModelStream] 最终选择:
   服务: OpenAI (openai)
   模型: gpt-4
   MCP: xiaohongshu
   工具: 1 个
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

验证点:

• ✅ 工具数量正确
• ✅ 工具名称带前缀（xiaohongshu__public_content）
• ✅ 服务器名称正确提取

---

测试 3: 工具名称解析 ⭐️⭐️⭐️

目的: 验证工具名称前缀解析逻辑

步骤:

1. 发送需要调用工具的消息
2. 观察控制台日志

期望日志:

🔧 执行工具调用: {
  fullName: 'xiaohongshu__public_content',
  id: 'call_abc123',
  arguments: {
    title: '...',
    content: '...',
    tags: [...],
    category: '...'
  }
}
🎯 提取工具名称: public_content
✅ 工具执行成功: {...}

验证点:

• ✅ 完整名称: xiaohongshu__public_content
• ✅ 提取名称: public_content
• ✅ 使用原始名称调用 MCP

---

测试 4: 多轮对话 ⭐️⭐️

目的: 验证工具结果继续对话

步骤:

用户: 帮我发布文章，主题是春季穿搭
AI: [调用工具] ✅ 已发布...

用户: 这个文章现在有多少浏览量？
AI: [理解上下文，可能再次调用工具查询]

验证点:

• ✅ AI 记住之前的工具调用结果
• ✅ 可以基于结果继续对话
• ✅ 上下文保持完整

---

测试 5: 错误处理 ⭐️

目的: 验证错误场景处理

步骤:

1. 断开 MCP 服务器
2. 发送需要工具的消息

期望结果:

AI 回复: 
❌ 工具执行失败：服务器未连接

请检查：
1. MCP 服务器是否正常运行
2. 网络连接是否正常
3. 工具配置是否正确

你可以在"MCP 设置"中重新连接服务器。

验证点:

• ✅ 友好的错误提示
• ✅ 明确的解决建议
• ✅ 不会崩溃或卡住

---

🔍 高级验证

检查 System Prompt 内容

在控制台执行:

// 查看最新消息列表
const lastMessages = window.__DEBUG_MESSAGES__
console.log('System Prompt:', lastMessages[0])

期望输出:

{
  role: 'system',
  content: `你是一个智能助手，可以使用以下工具完成任务：

• xiaohongshu__public_content
  描述: 发布内容到小红书平台
  参数:
  - title [必填]: 文章标题，吸引眼球且相关
  - content [必填]: 文章正文，Markdown 格式
  ...

使用指南：
1. 当用户需要完成某个任务时，请分析哪个工具最合适
...

当前连接的 MCP 服务器: xiaohongshu`
}

检查工具转换

在 chatService.ts 的 convertToolsToOpenAIFormat 方法中添加断点:

private convertToolsToOpenAIFormat(mcpTools: any[], serverName: string): any[] {
  debugger; // 在这里设置断点
  return mcpTools.map(tool => ({
    type: 'function',
    function: {
      name: `${serverName}__${tool.name}`,
      ...
    }
  }))
}

验证:

• mcpTools: 原始 MCP 工具列表
• serverName: 服务器名称（如 "xiaohongshu"）
• 返回值: 工具名称应为 xiaohongshu__public_content

检查工具解析

在 chatService.ts 的 executeToolCalls 方法中添加断点:

const parts = fullFunctionName.split('__')
debugger; // 在这里设置断点

if (parts.length !== 2) {
  console.error('工具名称格式错误')
  return
}

const toolName = parts[1]

验证:

• fullFunctionName: "xiaohongshu__public_content"
• parts: ["xiaohongshu", "public_content"]
• toolName: "public_content"

---

📊 性能测试

测试流式响应速度

测试方法:

1. 打开 Network 标签页
2. 发送消息
3. 观察 SSE 流

期望:

• ✅ 首字延迟 < 2s
• ✅ 流式输出流畅
• ✅ 工具调用不阻塞

测试工具执行时间

观察控制台日志:

⏱️ [callModelStream] 开始真流式处理
... (AI 生成内容)
🔧 执行工具调用: ...
⏱️ 工具执行耗时: 245ms
✅ 工具执行成功

期望:

• ✅ 工具执行 < 1s (简单工具)
• ✅ 工具执行 < 5s (复杂工具)

---

✅ 测试清单

完成所有测试后，确认以下项目：

• 工具名称正确添加前缀（serverName__toolName）
• System Prompt 自动生成并包含详细指南
• AI 能自动生成完整参数
• 工具名称正确解析（提取原始名称）
• 工具成功调用 MCP 服务器
• 工具结果正确返回和展示
• 多轮对话保持上下文
• 错误处理友好且明确
• 流式响应流畅不卡顿
• 控制台日志完整清晰

🐛 常见问题

问题 1: 工具没有被调用

可能原因:

1. 模型不支持 Function Calling
2. MCP 服务器未连接
3. 工具列表为空

解决方法:

// 检查工具列表
console.log('工具数量:', tools.length)
console.log('工具列表:', tools)

// 检查 MCP 连接
console.log('MCP 服务器状态:', mcpClient.getServerInfo(mcpServerId))

问题 2: 工具名称解析失败

可能原因:

• 工具名称格式不是 serverName__toolName

解决方法:

// 检查完整名称
console.log('工具完整名称:', fullFunctionName)
console.log('分割结果:', fullFunctionName.split('__'))

问题 3: System Prompt 没有生效

可能原因:

• 消息列表第一条不是 system 角色

解决方法:

// 检查消息列表
console.log('消息列表:', messages)
console.log('第一条消息角色:', messages[0].role)

---

📚 相关文档

• MCP 工具调用完整示例
• Cherry Studio 架构实现总结
• CHANGELOG.md

---

测试完成: v1.0.2+ Cherry Studio 架构
最后更新: 2024-01