# 模块化架构审查报告

## ✅ 已完成

| 组件 | 状态 | 说明 |
|------|------|------|
| EventBus | ✅ | 事件总线核心，发布/订阅模式 |
| BaseComponent | ✅ | 组件基类，生命周期管理 |
| LLM 组件 | ✅ | 已接入 Agnes AI API |
| TTS 组件 | ✅ | 已接入 EdgeTTS |
| Memory 组件 | ✅ | ProfileManager + LLM 事实提取 |
| Agent Worker | ✅ | 主控制器，事件协调 |

## ⚠️ 需要修复

### 1. STT 组件 - 占位实现
当前是空实现，需要接入真实 FunASR HTTP API：

```python
# 需实现：
- 连接 http://localhost:8080/stream
- 上传 WAV 音频
- 返回转录文本
- 支持 SenseVoiceSmall / Paraformer
```

### 2. 缺少 VAD 组件
TEN VAD 是语音检测核心，必须添加：

```python
class TENVADComponent(BaseComponent):
    async def detect_speech(self, audio_frame: np.ndarray) -> bool:
        """检测是否为语音帧"""
    
    async def get_audio_segments(self) -> list:
        """获取完整语音片段"""
```

**TEN VAD 参数（已验证）**：
- hop_size=256, threshold=0.5
- 延迟 P50=0.226ms, P99=0.336ms
- 比 Silero VAD 快 30%

### 3. 缺少 AudioPlayQueue
TTS 输出后需要播放队列管理：

```python
class AudioPlayQueue:
    async def play(self, audio_data: bytes) -> None:
        """播放音频"""
    
    async def stop(self) -> None:
        """停止播放（打断）"""
    
    async def clear(self) -> None:
        """清空队列"""
```

### 4. 缺少打断逻辑 (Barge-in)
三层架构：
1. 语义判停 - IntentClassifier
2. 关键词匹配 - 唤醒词检测
3. 状态机兜底 - 原子性取消例程

```python
# agent_worker.py 需添加：
async def interrupt(self):
    """打断当前对话"""
    await self.tts.stop()
    # 清空播放队列
    # 重新进入监听
```

---

## 📋 优先级排序

| 优先级 | 任务 | 影响 |
|--------|------|------|
| P0 | 补齐 STT 真实实现 | 核心功能 |
| P0 | 添加 TEN VAD 组件 | 语音检测 |
| P1 | 添加 AudioPlayQueue | 音频播放 |
| P1 | 实现打断逻辑 | 用户体验 |
| P2 | 健康检查接口 | 运维 |
| P2 | 配置验证 | 稳定性 |

---

## 🔧 建议修复方案

### STT 组件 - 接入 FunASR HTTP API
参考 `scripts/ten_vad_funasr.py` 中的调用方式：

```python
import httpx
import io
import wave

class FunASRSTT(STTComponent):
    async def transcribe(self, audio_bytes: bytes) -> str:
        buf = io.BytesIO()
        with wave.open(buf, "w") as wf:
            wf.setnchannels(1)
            wf.setsampwidth(2)
            wf.setframerate(16000)
            wf.writeframes(audio_bytes)
        
        response = self._client.post(
            "/stream",
            files={"file": ("audio.wav", buf.getvalue(), "audio/wav")}
        )
        return response.json().get("text", "")
```

### VAD 组件 - TEN VAD
参考 `scripts/ten_vad_recorder.py`：

```python
from ten_vad import TenVAD

class TENVADComponent(BaseComponent):
    def __init__(self, config, event_bus):
        self.vad = TenVAD(hop_size=256, threshold=0.5)
    
    async def detect(self, frame: np.ndarray) -> bool:
        """frame: int16, shape=[256]"""
        prob, _ = self.vad.process(frame)
        return prob > 0.5
```

---

## 📊 完成度评估

| 模块 | 完成度 |
|------|--------|
| EventBus 核心 | 100% |
| 组件框架 | 100% |
| LLM 组件 | 100% |
| TTS 组件 | 100% |
| Memory 组件 | 90% |
| STT 组件 | 20% (待接入) |
| VAD 组件 | 0% (缺失) |
| AudioPlayQueue | 0% (缺失) |
| 打断逻辑 | 0% (缺失) |
| **总体** | **约 55%** |

---

## 🎯 下一步行动

1. **立即修复** STT 组件，接入 FunASR HTTP API
2. **创建** TEN VAD 组件
3. **创建** AudioPlayQueue 组件
4. **实现** 打断逻辑到 AgentWorker