# 语音通话快速参考卡 🎤

## 🚀 快速开始

### 1️⃣ 重启服务器（必须！）
```bash
pkill -f "uvicorn.*main:app"
cd /path/to/lover
uvicorn main:app --host 0.0.0.0 --port 30101 --reload
```

### 2️⃣ 重新编译客户端
在 HBuilderX 中运行项目到手机/模拟器

### 3️⃣ 测试
1. 打开 App → 语音通话
2. 按住"按住说话"
3. **说 3-5 秒**
4. 松开按钮
5. 等待响应

## ✅ 成功标志

```
✅ 发送中... → 识别中... → 收到文字 → 听到声音
⏱️ 总耗时 < 30 秒
❌ 没有 "idle timeout" 错误
```

## 📊 关键参数

| 参数 | 值 | 说明 |
|------|-----|------|
| 分片大小 | 3200 bytes | 官方推荐 |
| 发送间隔 | 100ms | 官方推荐 |
| 超时时间 | 120 秒 | 服务器配置 |
| 录音时长 | 3-5 秒 | 建议值 |
| 音频格式 | PCM 16kHz | 必须 |

## 🔍 日志检查

### 客户端关键日志
```
✅ 必须看到：
📦 开始分片发送（官方推荐参数）
📊 总大小: [> 96000] bytes
✅ 所有音频片段发送完成
✅ 结束标记发送成功
📋 收到控制消息, type: reply_text
🎵 收到音频数据流
📋 收到控制消息, type: reply_end

❌ 不应该看到：
{"type":"error","msg":"idle timeout"}
```

### 服务器关键日志
```
✅ 必须看到：
ASR connection opened
ASR event end=True sentence=[文字]
Handle sentence: [文字]

❌ 不应该看到：
idle timeout
ASR error
```

## 🐛 快速故障排查

### 问题：还是 "idle timeout"
```bash
# 1. 确认服务器已重启
ps aux | grep uvicorn

# 2. 确认配置生效
cat lover/.env | grep VOICE_CALL_IDLE_TIMEOUT
# 应该显示: VOICE_CALL_IDLE_TIMEOUT=120

# 3. 确认录音时长够长（至少 3 秒）
# 查看客户端日志中的 "总大小"
# 3 秒 = 96000 bytes
# 5 秒 = 160000 bytes
```

### 问题：没有任何响应
```bash
# 检查 WebSocket 连接
# 客户端日志应该显示: WebSocket onOpen

# 检查服务器运行
curl http://192.168.1.141:30101/docs
```

### 问题：ASR 无法识别
- 在安静环境测试
- 清晰发音
- 说话时长 3-5 秒
- 避免背景噪音

## 📚 详细文档

1. `优化总结.md` - 完整的优化说明
2. `测试检查清单.md` - 详细测试步骤
3. `语音通话完整流程图.md` - 可视化流程
4. `最新优化说明.md` - 技术细节

## 💡 重要提示

### ⚠️ 必须做的事
- [x] 修改 `lover/.env` 添加超时配置
- [ ] **重启服务器**（最重要！）
- [ ] 重新编译客户端
- [ ] 测试时说话 3-5 秒（不要太短）

### ✅ 优化要点
- 分片大小: 3200 bytes（官方推荐）
- 发送间隔: 100ms（官方推荐）
- 超时时间: 120 秒（足够处理）
- 录音时长: 3-5 秒（足够识别）

## 🎯 测试目标

一次成功的对话应该：
1. 录音 3-5 秒
2. 分片发送完成
3. ASR 识别成功
4. LLM 生成回复
5. TTS 合成语音
6. 播放音频
7. 总耗时 < 30 秒
8. 无错误

## 📞 需要帮助？

提供以下信息：
- 客户端日志（完整）
- 服务器日志
- 录音大小和时长
- 错误信息

---

**快速参考** | **版本**: 2026-02-28 | **状态**: ✅ 已优化