# 🎯 LiveKit Voice AI - 分段测试计划

## 📋 测试总览

| 阶段 | 内容 | 预计时间 | 状态 | 通过率 |
|------|------|----------|------|--------|
| **Phase 1** | 单组件测试 | 30min | ✅ 已完成 | 7/7 (100%) |
| **Phase 2** | 集成测试 | 1h | 🔄 进行中 | 3/3 (100%) |
| **Phase 3** | 打断逻辑测试 | 1.5h | ⏳ 待开始 | 0/3 |
| **Phase 4** | 真实音频流测试 | 2h | ⏳ 待开始 | 0/3 |
| **Phase 5** | LiveKit Room 集成 | 2h | ✅ 就绪 | - |
| **Phase 6** | 移动端测试 | 3h | ⏳ 待开始 | 0/3 |

**总体进度**: 2.5/6 完成 (42%)

---

## ✅ Phase 1: 单组件测试（已完成）

### 测试结果
```
📊 测试结果: 7/7 通过
```

| 组件 | 状态 | 备注 |
|------|------|------|
| EventBus | ✅ | 事件发布/订阅正常 |
| STT (FunASR) | ✅ | HTTP API 就绪，localhost:8080 |
| LLM (Agnes) | ✅ | API 已连接（Key 失效，占位模式） |
| TTS (Edge) | ✅ | Edge TTS 正常工作 |
| VAD (TEN) | ✅ | **已安装，性能优异** |
| Memory | ✅ | SQLite 事实提取成功 |
| Agent Worker | ✅ | 8 组件集成完成 |

### TEN VAD 性能测试
```
✅ ten-vad 已安装
处理 16000 samples (1秒)
耗时: 15.56ms
平均延迟: 0.251ms/frame
帧数: 62

对比 Silero VAD:
- TEN VAD: 0.251ms/frame
- Silero VAD: 0.337ms/frame
- 提升: ~25%
```

---

## 🔄 Phase 2: 集成测试（进行中）

### 已完成
- [x] STT 组件初始化成功
- [x] LLM 组件初始化成功
- [x] TTS 组件初始化成功
- [x] 所有组件健康检查通过

### 待完成
- [ ] STT → LLM Pipeline 端到端测试
- [ ] LLM → TTS Pipeline 端到端测试
- [ ] 记忆系统事实提取测试

### 下一步
更新 Agnes AI API Key 后进行完整 Pipeline 测试。

---

## ⏳ Phase 3: 打断逻辑测试

### 测试目标
验证三层打断机制：
1. **第一层**: VAD 触发（已实现框架）
2. **第二层**: 关键词匹配（待实现）
3. **第三层**: 状态机兜底（已实现）

### 测试用例

#### 3.1 状态机打断
```python
# 测试 AudioPlayQueue.interrupt()
async def test_state_machine_interrupt():
    audio_queue = AudioPlayQueue(event_bus)
    await audio_queue.initialize()
    
    # 开始播放
    audio_queue.queue.append(b"\x00" * 16000)
    audio_queue._is_playing = True
    
    # 发送打断
    await audio_queue.interrupt()
    
    assert not audio_queue._is_playing, "打断后仍在播放"
    assert len(audio_queue.queue) == 0, "队列未清空"
```

#### 3.2 VAD 触发打断
```python
# 测试 VAD → INTERRUPT 事件
async def test_vad_interrupt():
    # 模拟 VAD 检测
    await event_bus.publish(EventType.VOICE_DETECTED, {"is_speech": True})
    
    # 验证打断请求
    assert agent_worker._interrupt_requested, "打断请求未设置"
```

#### 3.3 完整打断流程
```python
# 测试: 用户说话 → VAD → STT → 打断 → 重新处理
async def test_full_interrupt_flow():
    # 1. Agent 正在播放
    # 2. 用户说话（触发 VAD）
    # 3. 打断发生
    # 4. 状态重置
```

---

## ⏳ Phase 4: 真实音频流测试

### 前置条件
- [ ] PyAudio 安装
- [ ] 麦克风可用
- [ ] 扬声器可用

### 测试用例

#### 4.1 录音质量测试
```python
async def test_mic_recording():
    recorder = AudioRecorder(sample_rate=16000)
    await recorder.start()
    await asyncio.sleep(5.0)
    audio_data = await recorder.stop()
    
    assert len(audio_data) > 0, "录音为空"
    assert audio_data.max() > 0.01, "录音音量过低"
```

#### 4.2 播放质量测试
```python
async def test_speaker_playback():
    audio_path = await tts.synthesize("测试音频")
    player = AudioPlayer()
    await player.play(audio_path)
    await asyncio.sleep(3.0)
    assert not player.is_playing
```

#### 4.3 端到端延迟测试
```python
async def test_end_to_end_latency():
    start_time = time.time()
    
    text_input = "你好"
    response = await llm.generate(text_input)
    audio_url = await tts.synthesize(response)
    
    total_latency = time.time() - start_time
    assert total_latency < 5.0, f"延迟过高: {total_latency:.2f}s"
```

---

## ✅ Phase 5: LiveKit Room 集成（就绪）

### 服务状态
```
✅ LiveKit Server: Up 8 days
   端口: 7880 (HTTP), 7881 (HTTPS/WebRTC)
   状态: healthy
```

### 测试用例

#### 5.1 Room 连接测试
```typescript
const room = new Room();
await room.connect('http://localhost:7880', token);
assert(room.isConnected);
assert(room.participants.size >= 1);
```

#### 5.2 Agent Worker 集成
```python
await agent_worker.start()
await agent_worker.join_room("test-room")
# 监听音频输入并处理
```

#### 5.3 多参与者测试
```python
# 创建多个参与者，测试协作
participants = [await create_participant(f"user-{i}") for i in range(3)]
await agent_worker.join_room("test-room")
# 模拟对话轮转
```

---

## ⏳ Phase 6: 移动端测试

### 前置条件
- [ ] Expo 开发服务器运行
- [ ] 移动端应用已构建
- [ ] 测试设备可用

### 测试用例

#### 6.1 客户端连接测试
```typescript
async function test_mobile_connection() {
  const room = new Room();
  await room.connect('http://localhost:7880', generateToken());
  assert(room.isConnected);
}
```

#### 6.2 语音通话测试
```typescript
async function test_voice_call() {
  await Audio.requestPermissionsAsync();
  const recording = new Audio.Recording();
  await recording.prepareToRecordAsync(recordingPresets);
  await recording.startAsync();
  await sleep(3000);
  await recording.stopAndUnloadAsync();
  assert(recording.getURI());
}
```

#### 6.3 打断交互测试
```typescript
async function test_mobile_interrupt() {
  const isPlaying = await agentWorker.isPlaying();
  assert(isPlaying);
  
  const interruptDetected = await simulateSpeechInterrupt();
  assert(interruptDetected);
  
  const stillPlaying = await agentWorker.isPlaying();
  assert(!stillPlaying);
}
```

---

## 🔧 环境准备检查清单

### ✅ 已完成
- [x] FunASR STT 服务运行中 (PID 9348, localhost:8080)
- [x] LiveKit Server 运行中 (Docker, 端口 7880-7881)
- [x] TEN VAD 已安装并测试通过 (0.251ms/frame)
- [x] 单组件测试通过 (7/7)
- [x] 组件健康检查通过

### ⚠️ 需要处理
- [ ] **更新 Agnes AI API Key**（当前 401 错误）
- [ ] 修复 `run_tests.py` 类型错误
- [ ] 安装 PyAudio（可选，用于真实音频测试）

---

## 📊 测试优先级矩阵

| 优先级 | 测试项 | 阻塞因素 | 预计耗时 |
|--------|--------|----------|----------|
| **P0** | Phase 2.1-2.3 Pipeline 测试 | API Key 失效 | 30min |
| **P0** | Phase 3 打断逻辑测试 | 无 | 1h |
| **P1** | Phase 4.1 录音质量测试 | PyAudio 安装 | 30min |
| **P1** | Phase 4.2 播放质量测试 | 扬声器配置 | 30min |
| **P1** | Phase 4.3 端到端延迟 | 无 | 1h |
| **P2** | Phase 5.1-5.3 Room 测试 | LiveKit Token | 2h |
| **P2** | Phase 6.1-6.3 移动端测试 | Expo 构建 | 3h |

---

## 🎯 下一步行动

### 立即执行
1. **更新 API Key**:
   ```bash
   echo "OPENAI_API_KEY=[REDACTED]" > .env.dev
   ```

2. **运行集成测试**:
   ```bash
   cd /Users/leo/.hermes/workspace/livekit-agents
   ~/s2s-env/bin/python run_tests.py
   ```

3. **测试打断逻辑**:
   ```bash
   ~/s2s-env/bin/python -c "
   from components.audio_play_queue import AudioPlayQueue
   from event_bus import EventBus
   import asyncio
   
   async def test():
       eb = EventBus()
       await eb.start()
       aq = AudioPlayQueue({}, eb)
       await aq.initialize()
       print('AudioPlayQueue 测试通过')
       await eb.stop()
   
   asyncio.run(test())
   "
   ```

### 短期优化
- [ ] 完善 `run_tests.py` 中的类型注解
- [ ] 添加更多边界测试用例
- [ ] 实现 CI/CD 自动测试

---

**报告生成时间**: 2026-09-21 16:15:00  
**下次更新**: Phase 2 完成后