update at 2025-10-15 15:07:45
This commit is contained in:
douboer
370
docs/QUICK_TEST_GUIDE.md
Normal file
370
docs/QUICK_TEST_GUIDE.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user