life-echo/api/docs/WebSocket快速测试指南.md

# Life Echo WebSocket 快速测试指南

## 🚀 快速开始

### 1. 连接地址
```
ws://localhost:8000/ws/conversation/{conversation_id}
```

### 2. 生成对话ID
```bash
# Python
python -c "import uuid; print(uuid.uuid4())"

# 或使用在线工具：https://www.uuidgenerator.net/
```

### 3. 在 Apifox 中操作

1. **新建 WebSocket 请求**
   - 协议：WebSocket
   - URL：`ws://localhost:8000/ws/conversation/你的对话ID`

2. **点击连接**
   - 应该立即收到 `connect` 消息

3. **发送音频块**
   ```json
   {
     "type": "audio_chunk",
     "conversation_id": "你的对话ID",
     "data": {
       "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQAAAAA="
     }
   }
   ```

4. **接收响应**（按顺序）
   - `transcript` - 语音转文字
   - `agent_response` - Agent 回应
   - `tts_audio` - TTS 音频

5. **结束对话**
   ```json
   {
     "type": "end_conversation",
     "conversation_id": "你的对话ID"
   }
   ```

---

## 📋 消息类型速查

### 客户端发送

| 类型 | 说明 | JSON 示例 |
|------|------|-----------|
| `audio_chunk` | 发送音频 | `{"type":"audio_chunk","data":{"audio_base64":"..."}}` |
| `end_conversation` | 结束对话 | `{"type":"end_conversation"}` |

### 服务端返回

| 类型 | 说明 | 包含字段 |
|------|------|---------|
| `connect` | 连接确认 | `data.status` |
| `transcript` | 语音转文字 | `data.text` |
| `agent_response` | Agent 回应 | `data.text` |
| `tts_audio` | TTS 音频 | `data.audio_base64` |
| `end_conversation` | 结束确认 | `data.status` |
| `error` | 错误信息 | `data.message` |

---

## 🧪 测试场景

### 场景1：基础对话
1. 连接 → 2. 发送音频 → 3. 接收3条响应 → 4. 结束对话

### 场景2：多轮对话
重复场景1的步骤2-3多次

### 场景3：错误处理
发送无效的 `audio_base64` 数据，查看 `error` 消息

---

## ⚠️ 常见问题

**Q: 连接失败？**  
A: 检查后端服务是否运行：`curl http://localhost:8000/health`

**Q: 收不到响应？**  
A: 检查消息格式和必需字段，查看后端日志

**Q: 音频处理失败？**  
A: 检查音频格式和 Base64 编码，确保 ASR/TTS 服务配置正确

---

## 📝 完整文档

详细测试文档请参考：`WebSocket测试文档.md`