# 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