# 模块化架构 - 组件清单

## 组件目录结构

```
components/
├── __init__.py           # 包入口
├── base.py              # 组件基类 + 工厂模式
├── event_bus.py         # 事件总线（消息中枢）
├── stt.py               # STT 组件（FunASR/Whisper）
├── llm.py               # LLM 组件（Agnes/OpenAI）
├── tts.py               # TTS 组件（EdgeTTS/Azure）
├── memory.py            # 记忆组件（ProfileManager）
└── agent_worker.py      # Agent 主控制器
```

---

## 核心组件说明

### 1. EventBus (event_bus.py)
- **职责**：松耦合消息总线，发布/订阅模式
- **核心方法**：
  - `subscribe(event_type, handler)` - 订阅事件
  - `publish(event_type, data)` - 发布事件
  - `start()` / `stop()` - 生命周期管理
- **事件类型**：
  - `USER_SPEECH` - 用户语音输入
  - `ASSISTANT_SPEECH` - 助手回复
  - `MEMORY_EXTRACTED` - 事实提取完成
  - `CONFLICT_DETECTED` - 检测到矛盾
  - `SYSTEM_ERROR` - 系统错误

---

### 2. BaseComponent (components/base.py)
- **职责**：所有组件的基类
- **核心方法**：
  - `initialize()` - 初始化组件
  - `start()` - 启动组件
  - `stop()` - 停止组件
  - `subscribe()` / `publish()` - 事件订阅/发布
- **状态枚举**：`INITIALIZED`, `RUNNING`, `STOPPED`, `ERROR`

---

### 3. STTComponent (components/stt.py)
- **职责**：语音转文字
- **后端**：FunASR（默认）、Whisper（备选）
- **核心方法**：
  - `transcribe(audio_data)` - 转录音频
  - `is_ready()` - 检查是否就绪

---

### 4. LLMComponent (components/llm.py)
- **职责**：大语言模型处理
- **后端**：Agnes AI（默认）、OpenAI（备选）
- **核心方法**：
  - `generate(prompt, context)` - 生成回复
  - `generate_stream(prompt, context)` - 流式生成
  - `is_ready()` - 检查是否就绪

---

### 5. TTSComponent (components/tts.py)
- **职责**：文字转语音
- **后端**：EdgeTTS（默认）、Azure TTS（备选）
- **核心方法**：
  - `speak(text)` - 合成语音
  - `is_ready()` - 检查是否就绪

---

### 6. MemoryComponent (components/memory.py)
- **职责**：记忆管理，自动从对话提取事实
- **依赖**：ProfileManager（SQLite）
- **核心方法**：
  - `extract_facts(text, speaker)` - 提取事实
  - `get_context(identity, hours)` - 获取上下文
  - `detect_conflicts(identity)` - 检测矛盾
  - `get_summary(identity, hours)` - 人物画像

---

### 7. AgentWorker (components/agent_worker.py)
- **职责**：主控制器，协调所有组件
- **流程**：
  ```
  用户语音 → STT → LLM → TTS
                ↓
           Memory（自动提取事实）
  ```
- **核心方法**：
  - `initialize()` - 初始化所有组件
  - `start()` - 启动所有组件
  - `get_stats()` - 获取运行统计

---

## 配置示例

```yaml
# config.yaml
agent:
  stt:
    backend: funasr          # funasr / whisper
    enabled: true
    endpoint: http://localhost:8080
    model: SenseVoiceSmall
  
  llm:
    backend: agnes           # agnes / openai
    enabled: true
    model: agnes-2.5-flash
  
  tts:
    backend: edge_tts        # edge_tts / azure
    enabled: true
    voice: zh-CN-XiaoxiaoNeural
  
  memory:
    enabled: true
    learn_interval: 300      # 每5分钟清理过期记忆
```

---

## 使用示例

```python
from components.agent_worker import AgentWorker
from event_bus import EventBus

# 1. 创建事件总线
event_bus = EventBus()

# 2. 创建 Agent Worker
config = {
    "agent": {
        "stt": {"backend": "funasr", "enabled": True},
        "llm": {"backend": "agnes", "enabled": True},
        "tts": {"backend": "edge_tts", "enabled": True},
        "memory": {"enabled": True}
    }
}

agent = AgentWorker(config, event_bus)

# 3. 初始化并启动
await agent.initialize()
await agent.start()

# 4. 监听对话事件
event_bus.subscribe("user_speech", lambda e: print(f"用户: {e.data['text']}"))

# 5. 发布测试事件
event_bus.publish("user_speech", {"text": "你好"})

# 6. 停止
await agent.stop()
```

---

## 扩展新组件

### 步骤 1: 创建组件类
```python
# components/vision.py
class VisionComponent(BaseComponent):
    async def _do_initialize(self):
        pass
    
    async def _run_loop(self):
        pass
    
    async def process_frame(self, image_bytes):
        # 实现视觉处理逻辑
        pass
```

### 步骤 2: 在 AgentWorker 中注册
```python
# components/agent_worker.py
self.vision = create_vision_component(self.component_configs, self.event_bus)
await self.vision.initialize()
```

### 步骤 3: 配置启用
```yaml
vision:
  enabled: true
  backend: wemm
```

---

## 错误隔离机制

| 场景 | 处理方式 |
|------|---------|
| STT 失败 | 发布 `system_error` 事件，返回空文本 |
| LLM 失败 | 发布 `system_error` 事件，返回默认回复 |
| TTS 失败 | 发布 `system_error` 事件，跳过语音播放 |
| Memory 失败 | 发布 `system_error` 事件，继续对话流程 |

---

## 文件清单

| 文件 | 行数 | 说明 |
|------|------|------|
| `event_bus.py` | ~200 | 事件总线核心 |
| `components/base.py` | ~180 | 组件基类 |
| `components/stt.py` | ~120 | STT 组件 |
| `components/llm.py` | ~180 | LLM 组件 |
| `components/tts.py` | ~120 | TTS 组件 |
| `components/memory.py` | ~180 | 记忆组件 |
| `components/agent_worker.py` | ~200 | Agent 主控制器 |

**总计**: ~1200 行，模块化设计，易于维护和扩展。