| # 系统架构 | |
| ## 核心架构理念 | |
| 本项目采用**分层、解耦**的模块化架构，旨在实现高度的**可维护性**和**可扩展性**。其核心思想是**关注点分离 (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`) 播放解码后的纯音频数据。 | |