docs/architecture.md

# 系统架构

## 核心架构理念

本项目采用**分层、解耦**的模块化架构，旨在实现高度的**可维护性**和**可扩展性**。其核心思想是**关注点分离 (Separation of Concerns)**：

- **底层能力子系统 (`asr/`, `tts/`, `llm/`, `audio/`)**: 每个模块都是一个独立的、高内聚的功能单元（如语音识别、音频I/O）。它们不包含业务逻辑，只提供纯粹的能力。
- **服务编排层 (`services/`)**: 负责编排和调度底层子系统的能力，以实现具体的业务流程（如语音对话、状态监控）。
- **接口层 (`api/`, `cli/`)**: 作为应用的入口，负责接收外部指令，并将其委派给服务层处理。

## 数据流程图 (CLI 模式)

```
用户语音输入 → Audio Subsystem (Capture) → ASR Subsystem (Recognize) → LLM Subsystem (Generate) → TTS Subsystem (Synthesize) → Audio Subsystem (Player)
↑                                                                                                                        ↓
└─────────────────────────────────────────── 实时语音交互循环 ───────────────────────────────────────────────────────────┘
``` 


## 核心组件与分层

| 层级 | 模块/组件 | 职责描述 |
|:--- |:--- |:--- |
| **接口层** | `api/`, `cli/` | 提供 HTTP/命令行接口，作为系统入口。 |
| **服务层** | `services/` | **业务流程编排**。例如，`PlayerService` 负责处理播放任务的业务逻辑（如中断、历史记录），并调用底层播放器。 |
| **能力子系统** | `asr/` | **语音识别 (ASR)**。包含多种识别策略（如 FunASR, Whisper）及其管理。 |
| | `tts/` | **文本转语音 (TTS)**。包含多种语音合成策略（如 Kokoro, Moyo）及其管理。 |
| | `llm/` | **大语言模型 (LLM)**。负责处理文本生成逻辑。 |
| | `audio/` | **音频I/O**。提供纯粹的音频输入(`capture`)和输出(`player`)能力，不含业务逻辑。 |
| **核心框架** | `core/` | **应用骨架**。包含线程基类、全局常量、状态管理器和系统启动器。 |


## 多线程架构

系统采用多线程设计，各组件通过队列进行高效解耦通信：

- **音频捕获线程**: (`audio.AecCapture`/`audio.PyAudioCapture`) 持续捕获音频数据。
- **语音监测线程**: (`services.SpeechMonitor`) 检测用户语音活动。
- **ASR工作线程**: (`asr.models.*`) 语音识别处理。
- **LLM工作线程**: (`llm.generator`) 文本生成处理。
- **TTS工作线程**: (`tts.models.*`) 语音合成处理。
- **播放服务线程**: (`services.PlayerService`) 处理播放任务的业务逻辑。
- **音频播放线程**: (`audio.AudioPlayer`) 播放解码后的纯音频数据。