371 lines
8.1 KiB
Markdown
371 lines
8.1 KiB
Markdown
# Cherry Studio 架构快速测试指南
|
||
|
||
## 🎯 测试目标
|
||
|
||
验证 Cherry Studio 风格的 MCP 工具调用是否正常工作：
|
||
- ✅ 工具名称前缀（serverName__toolName）
|
||
- ✅ System Prompt 自动生成
|
||
- ✅ AI 自动生成参数
|
||
- ✅ 工具名称解析和执行
|
||
- ✅ 完整对话流程
|
||
|
||
## 📋 准备工作
|
||
|
||
### 1. 启动服务
|
||
|
||
**后端服务器**
|
||
```bash
|
||
cd /Users/gavin/xhs/mcp-client-vue
|
||
npm run dev:server
|
||
```
|
||
|
||
**前端应用**
|
||
```bash
|
||
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 设置"中添加测试服务器：
|
||
|
||
```json
|
||
{
|
||
"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 服务器）
|
||
|
||
**期望日志**:
|
||
```javascript
|
||
🔧 [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. 观察控制台日志
|
||
|
||
**期望日志**:
|
||
```javascript
|
||
🔧 执行工具调用: {
|
||
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 内容
|
||
|
||
在控制台执行:
|
||
```javascript
|
||
// 查看最新消息列表
|
||
const lastMessages = window.__DEBUG_MESSAGES__
|
||
console.log('System Prompt:', lastMessages[0])
|
||
```
|
||
|
||
**期望输出**:
|
||
```javascript
|
||
{
|
||
role: 'system',
|
||
content: `你是一个智能助手，可以使用以下工具完成任务：
|
||
|
||
• xiaohongshu__public_content
|
||
描述: 发布内容到小红书平台
|
||
参数:
|
||
- title [必填]: 文章标题，吸引眼球且相关
|
||
- content [必填]: 文章正文，Markdown 格式
|
||
...
|
||
|
||
使用指南：
|
||
1. 当用户需要完成某个任务时，请分析哪个工具最合适
|
||
...
|
||
|
||
当前连接的 MCP 服务器: xiaohongshu`
|
||
}
|
||
```
|
||
|
||
### 检查工具转换
|
||
|
||
在 `chatService.ts` 的 `convertToolsToOpenAIFormat` 方法中添加断点:
|
||
|
||
```typescript
|
||
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` 方法中添加断点:
|
||
|
||
```typescript
|
||
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
|
||
- ✅ 流式输出流畅
|
||
- ✅ 工具调用不阻塞
|
||
|
||
### 测试工具执行时间
|
||
|
||
观察控制台日志:
|
||
```javascript
|
||
⏱️ [callModelStream] 开始真流式处理
|
||
... (AI 生成内容)
|
||
🔧 执行工具调用: ...
|
||
⏱️ 工具执行耗时: 245ms
|
||
✅ 工具执行成功
|
||
```
|
||
|
||
**期望**:
|
||
- ✅ 工具执行 < 1s (简单工具)
|
||
- ✅ 工具执行 < 5s (复杂工具)
|
||
|
||
---
|
||
|
||
## ✅ 测试清单
|
||
|
||
完成所有测试后，确认以下项目：
|
||
|
||
- [ ] 工具名称正确添加前缀（serverName__toolName）
|
||
- [ ] System Prompt 自动生成并包含详细指南
|
||
- [ ] AI 能自动生成完整参数
|
||
- [ ] 工具名称正确解析（提取原始名称）
|
||
- [ ] 工具成功调用 MCP 服务器
|
||
- [ ] 工具结果正确返回和展示
|
||
- [ ] 多轮对话保持上下文
|
||
- [ ] 错误处理友好且明确
|
||
- [ ] 流式响应流畅不卡顿
|
||
- [ ] 控制台日志完整清晰
|
||
|
||
## 🐛 常见问题
|
||
|
||
### 问题 1: 工具没有被调用
|
||
|
||
**可能原因**:
|
||
1. 模型不支持 Function Calling
|
||
2. MCP 服务器未连接
|
||
3. 工具列表为空
|
||
|
||
**解决方法**:
|
||
```javascript
|
||
// 检查工具列表
|
||
console.log('工具数量:', tools.length)
|
||
console.log('工具列表:', tools)
|
||
|
||
// 检查 MCP 连接
|
||
console.log('MCP 服务器状态:', mcpClient.getServerInfo(mcpServerId))
|
||
```
|
||
|
||
### 问题 2: 工具名称解析失败
|
||
|
||
**可能原因**:
|
||
- 工具名称格式不是 `serverName__toolName`
|
||
|
||
**解决方法**:
|
||
```javascript
|
||
// 检查完整名称
|
||
console.log('工具完整名称:', fullFunctionName)
|
||
console.log('分割结果:', fullFunctionName.split('__'))
|
||
```
|
||
|
||
### 问题 3: System Prompt 没有生效
|
||
|
||
**可能原因**:
|
||
- 消息列表第一条不是 system 角色
|
||
|
||
**解决方法**:
|
||
```javascript
|
||
// 检查消息列表
|
||
console.log('消息列表:', messages)
|
||
console.log('第一条消息角色:', messages[0].role)
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [MCP 工具调用完整示例](./mcp-tool-calling-example.md)
|
||
- [Cherry Studio 架构实现总结](./CHERRY_STUDIO_IMPLEMENTATION.md)
|
||
- [CHANGELOG.md](../CHANGELOG.md)
|
||
|
||
---
|
||
|
||
**测试完成**: v1.0.2+ Cherry Studio 架构
|
||
**最后更新**: 2024-01
|