Document API usage, system architecture, configuration, and troubleshooting

- Add `docs/api-guide.md` for API usage and endpoints details.
- Create `docs/architecture.md` to explain the system's data flow and multi-threaded design.
- Add `docs/configuration.md` covering CLI/API parameters, LLM, ASR, and TTS customization.
- Add `docs/contributing.md` with community contribution guidelines.
- Add `docs/features.md` highlighting core functionalities like real-time audio processing, LLM, and TTS.
- Add `docs/project-structure.md` for a detailed directory layout.
- Create `docs/troubleshooting.md` for common issue fixes and optimization tips.
- Update README to condense features while linking to the new documentation.

README.md

@@ -30,407 +30,86 @@ library_name: transformers
 
 一个集成了语音识别(ASR)、大语言模型(LLM)和文本转语音(TTS)的实时语音对话系统
 
-[快速开始](#-快速开始) • [功能特性](#-主要特性) • [配置说明](#-配置选项) • [系统架构](#-系统架构) • [故障排除](#-故障排除)
+[快速开始](#-快速开始) • [文档导航](#-文档导航) • [贡献指南](docs/contributing.md)
 
 </div>
 
 ## 🎯 项目简介
 
-VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，支持：
+VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，具备实时、高精度、多角色的特点。
 
-- 🎤 **实时语音识别** - 基于 FunASR 和 Whisper 的高精度语音转文本
-- 🤖 **智能对话生成** - 集成 Qwen2.5 等多种大语言模型
-- 🔊 **高质量语音合成** - 基于 GPT-SoVITs 和 Kokoro TTS 的多角色语音生成
-- 🌐 **Web API 服务** - 提供 HTTP 接口，方便与其他应用集成
-- 🔇 **回声消除** - 内置音频处理技术，支持实时语音交互
-- ⚡ **低延迟处理** - 优化的音频流处理管道，实现流畅对话体验
+- 🎤 **实时语音识别**: 高精度中英文语音转录
+- 🤖 **智能对话生成**: 集成 Qwen2.5 等大语言模型
+- 🔊 **高质量语音合成**: 支持多角色、多风格的语音输出
+- 🌐 **Web API 服务**: 提供 HTTP 接口，方便集成
+- ⚡ **低延迟处理**: 优化的音频流处理管道
 
-## ✨ 主要特性
-
-### 🎵 音频处理
-- **回声消除音频捕获** - 自动消除回声干扰，提升语音质量
-- **语音活动检测(VAD)** - 智能检测用户说话状态，自动开始/停止录制
-- **实时音频流处理** - 低延迟音频播放和处理
-
-### 🗣️ 语音识别
-- **智能语音识别引擎** - 中文使用FunASR高精度识别，其他语言使用Whisper模型
-- **自动语言切换** - 根据启动参数自动选择最优识别引擎
-- **实时转录处理** - 流式语音转文本处理，降低响应延迟
-
-### 🧠 语言模型
-- **Qwen2.5 (14B)** - 内置阿里巴巴开源的中文优化模型
-- **LangChain 集成** - 方便扩展和支持更多语言模型
-- **自定义系统提示词** - 可在代码中配置 AI 助手的行为风格
-
-### 🎭 语音合成
-项目集成了两种先进的语音合成技术，支持动态说话人管理：
-
-#### GPT-SoVITs 技术（中文角色）
-基于 GPT-SoVITs 的中文语音合成，支持以下角色：
-- **罗翔** (Luo Xiang) - 法学教授风格，具有幽默风趣和深入浅出的讲解风格
-- **马保国** (Ma Baoguo) - 太极大师风格，带有标志性的口音和语调特色
-- **沈逸** (Shen Yi) - 学者风格，具有理性分析风格和富有磁性的嗓音
-- **杨幂** (Yang Mi) - 明星风格，拥有清甜动人的声线和自然流畅的表达方式
-- **周杰伦** (Zhou Jielun) - 歌手风格，具有标志性的说话风格和音乐气质
-- **马云** (Ma Yun) - 企业家风格，富有激情的演讲风格和商业洞察表达方式
-
-#### Kokoro TTS 技术（英文角色）
-基于 Kokoro TTS 的英文语音合成，支持以下角色：
-- **Heart** - 温暖亲切的英语女性语音，声音富有感情色彩
-- **Bella** - 优质的英语女性语音，具有清晰自然的发音和良好的表现力
-- **Nicole** - 高质量的英语女性语音，发音清晰准确，语调自然流畅
-
-#### 技术特点
-- **智能引擎选择** - 系统根据内容语言自动选择最适合的TTS引擎
-- **动态说话人管理** - 支持运行时动态加载和切换说话人
-- **高质量合成** - 采用先进的神经网络技术，生成自然流畅的语音
-- **可扩展架构** - 模块化设计，方便添加更多语音角色和TTS引擎
-
-### ⚙️ 服务模式
-- **命令行模式 (CLI)** - 在终端中直接运行，提供实时语音交互体验
-- **API 服务模式** - 启动一个 FastAPI Web 服务器，提供 HTTP 接口进行交互
+> 想要了解更多？请查看 [功能特性详解](docs/features.md)。
 
 ## 🚀 快速开始
 
-### 系统要求
-
-- **操作系统**: macOS 14+ (推荐)
-- **Python 版本**: 3.9 或更高版本
-- **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)
-- **存储空间**: 至少 20GB 可用空间 (用于模型文件)
-
-### 快速安装
+### 1. 安装
 
 ```bash
-# 1. 克隆项目
+# 克隆项目
 git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
 cd VoiceDialogue
 
-# 2. 创建虚拟环境（推荐）
+# 安装依赖 (推荐使用 uv)
 pip install uv
 uv venv
 source .venv/bin/activate
 
-# 3. 安装依赖
 WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync
 
-# 4. 安装系统依赖
-brew install ffmpeg
+# 安装额外的依赖
+## 1. 安装 kokoro-onnx
+uv pip install kokoro-onnx
+## 2. 重新安装指定版本的 numpy
+uv pip install numpy==1.26.4
 
-# 5. 启动系统
-python main.py
-```
 
-> 📖 **详细安装指南**: 如需了解完整的安装步骤、系统要求和故障排除，请查看 **[安装指南](docs/installation.md)**
+# 安装音频工具 (macOS)
+brew install ffmpeg
+```
 
-### 🖥️ 应用模式
+> 📖 **需要更详细的步骤？** 请查阅 **[安装指南](docs/installation.md)**，其中包含系统要求和常见问题。
 
-#### 1. 命令行模式 (默认)
+### 2. 运行
 
-直接在终端进行实时语音对话。
+#### 命令行模式 (CLI)
 
 ```bash
-# 启动语音对话系统 (默认使用中文，沈逸角色)
+# 启动语音对话 (默认中文)
 python main.py
-# 或使用 uv
-uv run main.py
 
-# 指定语言和角色
+# 启动并指定语言和角色
 python main.py --language en --speaker Heart
-
-# 查看所有可用参数
-python main.py --help
 ```
 
-**首次运行说明**：
-- 看到 "服务启动成功" 提示后即可开始说话
-- 系统会自动检测语音活动并进行识别和回复
-
-#### 2. API 服务模式
-
-启动一个 Web 服务器，通过 HTTP 请求进行交互。
+#### API 服务模式
 
 ```bash
 # 启动 API 服务器
 python main.py --mode api
-# 或使用 uv
-uv run main.py --mode api
-
-# 指定不同端口和启用热重载
-python main.py --mode api --port 9000 --reload
-```
-
-**API 服务特性**：
-- API 文档地址: `http://localhost:8000/docs`
-- 支持 TTS 模型管理（查看、加载、删除）
-- 实时模型状态监控
-- RESTful API 设计
-
-#### 3. 桌面应用模式 (Electron)
-提供图形界面的桌面应用程序。
-
-
-## ⚙️ 配置选项
-
-### 启动参数
-
-通过 `main.py` 的命令行参数可以方便地进行配置：
-
-| 参数 | 缩写 | 可选值 | 默认值 | 描述 |
-|---|---|---|---|---|
-| `--mode` | `-m` | `cli`, `api` | `cli` | 设置运行模式 |
-| `--language`| `-l` | `zh`, `en` | `zh` | (CLI模式) 设置用户语言 |
-| `--speaker` | `-s` | (动态获取) | `沈逸` | (CLI模式) 设置TTS语音角色 |
-| `--host` | | IP地址 | `0.0.0.0` | (API模式) 服务器主机 |
-| `--port` | `-p` | 端口号 | `8000` | (API模式) 服务器端口 |
-| `--reload`| | 无 | `False` | (API模式) 启用热重载 |
-
-**支持的说话人角色**（动态加载）: 
-- **中文角色**：`罗翔`, `马保国`, `沈逸`, `杨幂`, `周杰伦`, `马云`
-- **英文角色**：`Heart`, `Bella`, `Nicole`
-
-### 高级配置
-
-#### 大语言模型 (LLM)
-
-- **模型路径和参数**: LLM 的模型和推理参数目前在代码中硬编码，方便快速启动。
-- **文件位置**: `src/VoiceDialogue/services/text/generator.py`
-- **自定义**: 你可以修改 `LLMResponseGenerator` 类中的配置。
-
-#### 语音识别 (ASR)
-
-- **引擎自动选择**: 系统会根据 `--language` 参数自动选择最合适的 ASR 引擎。
-- **模型配置**: ASR 模型的具体配置位于 `src/VoiceDialogue/services/speech/recognizers/manager.py`。
-
-#### 系统提示词 (System Prompt)
-
-- **功能**: 定义 AI 角色的行为和说话风格。
-- **文件位置**: `src/VoiceDialogue/services/text/generator.py`
-- **自定义**: 你可以修改系统提示词变量的值。
-
-### 构建完整应用
-项目提供了完整的构建脚本，可以一键构建包含Python后端和Electron前端的完整应用：
-
-1. 首先，激活当前 Python 环境
-
-```bash
-source .venv/bin/activate
-# 或使用 conda
-conda activate voicedialogue
-```
-
-2. 使用构建脚本
-
-```bash
-# 使用构建脚本（推荐）
-bash scripts/build.sh
-
-# 或分别构建
-bash scripts/build-python.sh  # 构建Python后端
-bash scripts/build-electron.sh # 构建Electron前端
-
-# 清理构建产物
-bash scripts/clean.sh
-```
-
-
-## 📁 项目结构
-
-```text
-VoiceDialogue/
-├── src/
-│   └── voice_dialogue/                # 主要源代码目录
-│       ├── __init__.py               # 包初始化文件
-│       ├── cli/                      # 命令行界面模块
-│       │   └── args.py               # 命令行参数解析
-│       ├── api/                      # Web API 模块 (FastAPI)
-│       │   ├── app.py                # FastAPI 应用实例
-│       │   ├── server.py             # uvicorn 服务器
-│       │   ├── core/                 # API 核心配置
-│       │   ├── routes/               # API 路由
-│       │   ├── schemas/              # 数据模型
-│       │   ├── dependencies/         # API 依赖项
-│       │   └── middleware/           # 中间件
-│       ├── config/                   # 配置管理
-│       │   ├── paths.py              # 路径配置
-│       │   └── speaker_config.py     # 说话人配置
-│       ├── core/                     # 核心模块
-│       │   ├── constants.py          # 全局常量和队列
-│       │   └── launcher.py           # 系统启动器
-│       ├── models/                   # 数据模型和任务
-│       ├── services/                 # 服务模块
-│       │   ├── audio/                # 音频处理服务
-│       │   ├── speech/               # 语音识别服务
-│       │   └── text/                 # 文本生成服务
-│       └── utils/                    # 工具函数
-├── electron-app/                     # Electron 桌面应用
-│   ├── main.js                       # Electron 主进程
-│   ├── preload.js                    # 预加载脚本
-│   ├── loading.html                  # 加载页面
-│   ├── utils.js                      # 工具函数
-│   ├── package.json                  # Electron 依赖配置
-│   ├── assets/                       # Electron 资源文件
-│   ├── build/                        # 构建配置
-│   └── python-dist/                  # Python 分发包
-├── scripts/                          # 构建和部署脚本
-│   ├── build.sh                      # 主构建脚本
-│   ├── build-python.sh               # Python 打包脚本
-│   ├── build-electron.sh             # Electron 打包脚本
-│   └── clean.sh                      # 清理脚本
-├── third_party/                      # 第三方库
-│   ├── moyoyo_tts/                   # GPT-SoVITs TTS 引擎
-│   └── AECAudioRecorder/             # 回声消除音频录制器
-├── assets/                           # 资源文件
-├── dist/                             # 分发包输出目录
-├── build/                            # 构建临时文件
-├── tests/                            # 测试文件
-├── docs/                             # 文档目录
-├── main.py                           # 项目启动入口
-├── pyproject.toml                    # 项目配置文件 (uv)
-├── requirements.txt                  # Python 依赖
-├── uv.lock                           # uv 锁定文件
-├── .python-version                   # Python 版本配置
-└── README.md                         # 项目说明文档
-```
-
-## 🔧 系统架构
-
-### 数据流程图 (CLI 模式)
-```
-用户语音输入 → 回声消除 → 语音活动检测 → 语音转录 (ASR) → LLM生成回复 → TTS合成 → 音频输出
-↑                                                                              ↓
-└─────────────────────────────── 实时语音交互循环 ────────────────────────────────┘
 ```
+> 详细使用方法请参考 [配置指南](docs/configuration.md) 和 [API 服务指南](docs/api-guide.md)。
 
+## 📚 文档导航
 
-### 核心组件说明
-
-| 组件 | 功能描述 | 技术实现 |
-|------|----------|----------|
-| **EchoCancellingAudioCapture** | 回声消除音频捕获 | 实时音频流捕获与预处理 |
-| **SpeechStateMonitor** | 语音活动检测 | VAD 算法检测用户说话状态 |
-| **ASRWorker** | 语音识别转录 | FunASR / Whisper 模型推理 |
-| **LLMResponseGenerator** | 智能文本生成 | Qwen2.5 (llama.cpp) 对话生成 |
-| **TTSAudioGenerator** | 语音合成 | GPT-SoVITs / Kokoro TTS 文本转语音 |
-| **AudioStreamPlayer** | 音频流播放 | 实时音频输出播放 |
-| **FastAPI App** | API服务 | 提供HTTP接口，封装核心服务 |
-
-### 多线程架构
-
-系统采用多线程设计，各组件通过队列进行通信：
-
-- **音频采集线程**: 持续捕获音频数据
-- **语音监测线程**: 检测用户语音活动
-- **ASR线程**: 语音识别处理
-- **LLM线程**: 文本生成处理
-- **TTS线程**: 语音合成处理
-- **音频播放线程**: 音频输出播放
-
-## 🛠️ 故障排除
-
-### 1. 模型下载失败
-- **问题**: 网络连接超时或模型下载失败。
-- **解决方案**: 设置 Hugging Face 镜像。
-```bash
-export HF_ENDPOINT=https://hf-mirror.com
-pip install -U huggingface_hub
-```
-
-### 2. 音频设备问题
-- **问题**: 找不到音频设备或权限被拒绝。
-- **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。
-- **Linux 解决方案**: `sudo usermod -a -G audio $USER`，然后重新登录。
-
-### 3. 内存不足错误 (OOM)
-- **问题**: `CUDA out of memory` 或 RAM 不足。
-- **解决方案**: LLM 是主要的内存消耗者。你可以通过修改 `src/VoiceDialogue/services/text/generator.py` 来降低资源消耗：
-    - **更换模型**: 将模型路径指向一个更小的模型（如 7B Q4 量化模型）。
-    - **减少批处理大小**: 减小模型参数中的 `n_batch` 值（如 `256`）。
-    - **减少上下文长度**: 减小 `n_ctx` 的值（如 `1024`）。
-
-### 4. 依赖包冲突
-- **问题**: 包版本冲突或导入错误。
-- **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。
-```bash
-# 使用 conda
-conda deactivate
-conda env remove -n voicedialogue
-
-# 使用 uv
-rm -rf .venv
-uv venv
-```
-
-### 5. 说话人角色不存在
-- **问题**: 指定的说话人不在支持列表中。
-- **解决方案**: 使用 `python src/VoiceDialogue/main.py --help` 查看所有可用的说话人角色。
-
-### 6. FFmpeg 相关错误
-- **问题**: 音频处理失败或编解码错误。
-- **解决方案**: 确保正确安装 FFmpeg：
-```bash
-# 检查 FFmpeg 安装
-ffmpeg -version
-
-# 重新安装 FFmpeg
-# macOS
-brew reinstall ffmpeg
-
-```
-
-### 7. Python 版本兼容性
-- **问题**: Python 版本过低导致的兼容性问题。
-- **解决方案**: 确保使用 Python 3.11+ 版本：
-```bash
-python --version
-# 如果版本过低，请升级或使用虚拟环境
-```
-
-### 8. 桌面应用相关问题
-- **问题**: Electron 应用启动失败或功能异常。
-- **解决方案**: 
-  - 确保 Node.js 版本 >= 16
-  - 重新安装依赖：`cd electron-app && npm install`
-  - 检查 Python 后端是否正常运行
-
-### 9. 构建打包问题
-- **问题**: 使用构建脚本失败。
-- **解决方案**: 
-  - 确保有执行权限：`chmod +x scripts/*.sh`
-  - 检查所有依赖是否安装完成
-  - 查看具体错误日志进行调试
-
-  
-## 📊 性能优化建议
-
-### 硬件优化
-- **内存**: 推荐 32GB RAM 以获得最佳性能
-- **存储**: 使用 SSD 硬盘可显著提升模型加载速度
-- **CPU**: 多核处理器有助于多线程处理
-
-### 软件优化
-- **模型选择**: 根据硬件配置选择合适大小的模型
-- **批处理优化**: 调整 LLM 的 `n_batch` 参数
-- **音频缓冲**: 根据延迟要求调整音频缓冲区大小
+- 📖 **[安装指南](docs/installation.md)**: 详细的安装步骤和系统要求。
+- ⚙️ **[配置指南](docs/configuration.md)**: 如何配置系统参数和高级选项。
+- 🎭 **[功能特性](docs/features.md)**: 深入了解项目的所有功能。
+- 🌐 **[API 指南](docs/api-guide.md)**: 如何使用和集成 API 服务。
+- 🏗️ **[系统架构](docs/architecture.md)**: 了解系统的内部工作原理。
+- 📁 **[项目结构](docs/project-structure.md)**: 浏览项目代码和文件组织。
+- 🛠️ **[故障排除](docs/troubleshooting.md)**: 常见问题和解决方案。
+- 🤝 **[贡献指南](docs/contributing.md)**: 如何为项目做出贡献。
 
 ## 📄 许可证
 
 本项目采用 MIT 许可证开源。
 
-## 🤝 贡献指南
-
-欢迎提交 Pull Request 和 Issue！
-
-1. Fork 本仓库
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 开启 Pull Request
-
----
-
-<div align="center">
-
-**如果这个项目对您有帮助，请给我们一个 ⭐️!**
+## 🙏 致谢
 
-</div>
+如果这个项目对您有帮助，请给我们一个 ⭐️!

docs/api-guide.md

@@ -0,0 +1,49 @@
+# API 服务指南
+
+VoiceDialogue 支持通过 API 服务模式运行，启动一个 FastAPI Web 服务器，提供 HTTP 接口进行交互。
+
+## 启动 API 服务
+
+```bash
+# 启动 API 服务器
+python main.py --mode api
+# 或使用 uv
+uv run main.py --mode api
+
+# 指定不同端口和启用热重载
+python main.py --mode api --port 9000 --reload
+```
+
+## API 服务特性
+
+- **API 文档地址**: 启动服务后，可在 `http://localhost:8000/docs` 查看交互式 API 文档 (Swagger UI)。
+- **TTS 模型管理**: 支持通过 API 查看、加载、删除 TTS 模型。
+- **实时模型状态监控**: 提供接口查询当前加载的模型和系统状态。
+- **RESTful API 设计**: 采用标准的 RESTful 设计，方便与其他应用集成。
+
+## 主要接口
+
+### TTS模型管理
+
+* `GET /api/v1/tts/models` - 获取所有可用的TTS模型列表
+* `POST /api/v1/tts/models/load` - 加载指定的TTS模型
+* `GET /api/v1/tts/models/{model_id}/status` - 查看模型下载和加载状态
+* `DELETE /api/v1/tts/models/{model_id}` - 删除已下载的模型
+
+### 语音识别管理
+
+* `GET /api/v1/asr/languages` - 获取支持的识别语言列表
+* `POST /api/v1/asr/instance/create` - 创建指定语言的ASR实例
+
+### 系统控制
+
+* `GET /api/v1/system/status` - 获取系统整体状态
+* `POST /api/v1/system/start` - 启动语音对话系统
+* `POST /api/v1/system/stop` - 停止语音对话系统
+* `POST /api/v1/system/restart` - 重启语音对话系统
+
+### 实时通信
+
+* `WebSocket /api/v1/ws` - WebSocket连接，接收实时系统消息
+
+更多详细信息请参考启动服务后的在线API文档。 

docs/architecture.md

@@ -0,0 +1,32 @@
+# 系统架构
+
+## 数据流程图 (CLI 模式)
+```
+用户语音输入 → 回声消除 → 语音活动检测 → 语音转录 (ASR) → LLM生成回复 → TTS合成 → 音频输出
+↑                                                                              ↓
+└─────────────────────────────── 实时语音交互循环 ────────────────────────────────┘
+```
+
+## 核心组件说明
+
+| 组件 | 功能描述 | 技术实现 |
+|------|----------|----------|
+| **EchoCancellingAudioCapture** | 回声消除音频捕获 | 实时音频流捕获与预处理 |
+| **SpeechStateMonitor** | 语音活动检测 | VAD 算法检测用户说话状态 |
+| **ASRWorker** | 语音识别转录 | FunASR / Whisper 模型推理 |
+| **LLMResponseGenerator** | 智能文本生成 | Qwen2.5 (llama.cpp) 对话生成 |
+| **TTSAudioGenerator** | 语音合成 | GPT-SoVITs / Kokoro TTS 文本转语音 |
+| **AudioStreamPlayer** | 音频流播放 | 实时音频输出播放 |
+| **FastAPI App** | API服务 | 提供HTTP接口，封装核心服务 |
+
+## 多线程架构
+
+系统采用多线程设计，各组件通过队列进行通信：
+
+- **音频采集线程**: 持续捕获音频数据
+- **语音监测线程**: 检测用户语音活动
+- **ASR线程**: 语音识别处理
+- **LLM线程**: 文本生成处理
+- **TTS线程**: 语音合成处理
+- **音频播放线程**: 音频输出播放
+``` 

docs/configuration.md

@@ -0,0 +1,66 @@
+# 配置指南
+
+本文档介绍如何配置 VoiceDialogue 系统。
+
+## 启动参数
+
+通过 `main.py` 的命令行参数可以方便地进行配置：
+
+| 参数 | 缩写 | 可选值 | 默认值 | 描述 |
+|---|---|---|---|---|
+| `--mode` | `-m` | `cli`, `api` | `cli` | 设置运行模式 |
+| `--language`| `-l` | `zh`, `en` | `zh` | (CLI模式) 设置用户语言 |
+| `--speaker` | `-s` | (动态获取) | `沈逸` | (CLI模式) 设置TTS语音角色 |
+| `--host` | | IP地址 | `0.0.0.0` | (API模式) 服务器主机 |
+| `--port` | `-p` | 端口号 | `8000` | (API模式) 服务器端口 |
+| `--reload`| | 无 | `False` | (API模式) 启用热重载 |
+
+**支持的说话人角色**（动态加载）:
+
+- **中文角色**：`罗翔`, `马保国`, `沈逸`, `杨幂`, `周杰伦`, `马云`
+- **英文角色**：`Heart`, `Bella`, `Nicole`
+
+## 高级配置
+
+### 大语言模型 (LLM)
+
+- **模型路径和参数**: LLM 的模型和推理参数目前在代码中硬编码，方便快速启动。
+- **文件位置**: `src/VoiceDialogue/services/text/generator.py`
+- **自定义**: 你可以修改 `LLMResponseGenerator` 类中的配置。
+
+### 语音识别 (ASR)
+
+- **引擎自动选择**: 系统会根据 `--language` 参数自动选择最合适的 ASR 引擎。
+- **模型配置**: ASR 模型的具体配置位于 `src/VoiceDialogue/services/speech/recognizers/manager.py`。
+
+### 系统提示词 (System Prompt)
+
+- **功能**: 定义 AI 角色的行为和说话风格。
+- **文件位置**: `src/VoiceDialogue/services/text/generator.py`
+- **自定义**: 你可以修改系统提示词变量的值。
+
+## 构建完整应用
+
+项目提供了完整的构建脚本，可以一键构建包含Python后端和Electron前端的完整应用：
+
+1. 首先，激活当前 Python 环境
+
+   ```bash
+   source .venv/bin/activate
+   # 或使用 conda
+   conda activate voicedialogue
+   ```
+
+2. 使用构建脚本
+
+   ```bash
+   # 使用构建脚本（推荐）
+   bash scripts/build.sh
+
+   # 或分别构建
+   bash scripts/build-python.sh  # 构建Python后端
+   bash scripts/build-electron.sh # 构建Electron前端
+
+   # 清理构建产物
+   bash scripts/clean.sh
+   ``` 

docs/contributing.md

@@ -0,0 +1,19 @@
+# 贡献指南
+
+我们非常欢迎社区的贡献！
+
+## 贡献流程
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+## 开发规范
+- 请确保你的代码遵循项目现有的风格。
+- 添加或修改功能时，请更新相关的文档。
+- 提交前请确保所有测试都能通过。
+
+## 问题反馈
+如果你发现了 Bug 或者有功能建议，欢迎通过 [Issues](https://huggingface.co/MoYoYoTech/VoiceDialogue/issues) 提交。 

docs/features.md

@@ -0,0 +1,47 @@
+# 功能特性
+
+VoiceDialogue 系统集成了多项先进技术，提供端到端的语音交互体验。
+
+## 🎵 音频处理
+- **回声消除音频捕获** - 自动消除回声干扰，提升语音质量
+- **语音活动检测(VAD)** - 智能检测用户说话状态，自动开始/停止录制
+- **实时音频流处理** - 低延迟音频播放和处理
+
+## 🗣️ 语音识别
+- **智能语音识别引擎** - 中文使用FunASR高精度识别，其他语言使用Whisper模型
+- **自动语言切换** - 根据启动参数自动选择最优识别引擎
+- **实时转录处理** - 流式语音转文本处理，降低响应延迟
+
+## 🧠 语言模型
+- **Qwen2.5 (14B)** - 内置阿里巴巴开源的中文优化模型
+- **LangChain 集成** - 方便扩展和支持更多语言模型
+- **自定义系统提示词** - 可在代码中配置 AI 助手的行为风格
+
+## 🎭 语音合成
+项目集成了两种先进的语音合成技术，支持动态说话人管理：
+
+#### GPT-SoVITs 技术（中文角色）
+基于 GPT-SoVITs 的中文语音合成，支持以下角色：
+- **罗翔** (Luo Xiang) - 法学教授风格，具有幽默风趣和深入浅出的讲解风格
+- **马保国** (Ma Baoguo) - 太极大师风格，带有标志性的口音和语调特色
+- **沈逸** (Shen Yi) - 学者风格，具有理性分析风格和富有磁性的嗓音
+- **杨幂** (Yang Mi) - 明星风格，拥有清甜动人的声线和自然流畅的表达方式
+- **周杰伦** (Zhou Jielun) - 歌手风格，具有标志性的说话风格和音乐气质
+- **马云** (Ma Yun) - 企业家风格，富有激情的演讲风格和商业洞察表达方式
+
+#### Kokoro TTS 技术（英文角色）
+基于 Kokoro TTS 的英文语音合成，支持以下角色：
+- **Heart** - 温暖亲切的英语女性语音，声音富有感情色彩
+- **Bella** - 优质的英语女性语音，具有清晰自然的发音和良好的表现力
+- **Nicole** - 高质量的英语女性语音，发音清晰准确，语调自然流畅
+
+#### 技术特点
+- **智能引擎选择** - 系统根据内容语言自动选择最适合的TTS引擎
+- **动态说话人管理** - 支持运行时动态加载和切换说话人
+- **高质量合成** - 采用先进的神经网络技术，生成自然流畅的语音
+- **可扩展架构** - 模块化设计，方便添加更多语音角色和TTS引擎
+
+## ⚙️ 服务模式
+- **命令行模式 (CLI)** - 在终端中直接运行，提供实时语音交互体验
+- **API 服务模式** - 启动一个 FastAPI Web 服务器，提供 HTTP 接口进行交互
+- **桌面应用模式 (Electron)** - 提供图形界面的桌面应用程序。 

docs/project-structure.md

@@ -0,0 +1,58 @@
+# 项目结构
+
+```text
+VoiceDialogue/
+├── src/
+│   └── voice_dialogue/                # 主要源代码目录
+│       ├── __init__.py               # 包初始化文件
+│       ├── cli/                      # 命令行界面模块
+│       │   └── args.py               # 命令行参数解析
+│       ├── api/                      # Web API 模块 (FastAPI)
+│       │   ├── app.py                # FastAPI 应用实例
+│       │   ├── server.py             # uvicorn 服务器
+│       │   ├── core/                 # API 核心配置
+│       │   ├── routes/               # API 路由
+│       │   ├── schemas/              # 数据模型
+│       │   ├── dependencies/         # API 依赖项
+│       │   └── middleware/           # 中间件
+│       ├── config/                   # 配置管理
+│       │   ├── paths.py              # 路径配置
+│       │   └── speaker_config.py     # 说话人配置
+│       ├── core/                     # 核心模块
+│       │   ├── constants.py          # 全局常量和队列
+│       │   └── launcher.py           # 系统启动器
+│       ├── models/                   # 数据模型和任务
+│       ├── services/                 # 服务模块
+│       │   ├── audio/                # 音频处理服务
+│       │   ├── speech/               # 语音识别服务
+│       │   └── text/                 # 文本生成服务
+│       └── utils/                    # 工具函数
+├── electron-app/                     # Electron 桌面应用
+│   ├── main.js                       # Electron 主进程
+│   ├── preload.js                    # 预加载脚本
+│   ├── loading.html                  # 加载页面
+│   ├── utils.js                      # 工具函数
+│   ├── package.json                  # Electron 依赖配置
+│   ├── assets/                       # Electron 资源文件
+│   ├── build/                        # 构建配置
+│   └── python-dist/                  # Python 分发包
+├── scripts/                          # 构建和部署脚本
+│   ├── build.sh                      # 主构建脚本
+│   ├── build-python.sh               # Python 打包脚本
+│   ├── build-electron.sh             # Electron 打包脚本
+│   └── clean.sh                      # 清理脚本
+├── third_party/                      # 第三方库
+│   ├── moyoyo_tts/                   # GPT-SoVITs TTS 引擎
+│   └── AECAudioRecorder/             # 回声消除音频录制器
+├── assets/                           # 资源文件
+├── dist/                             # 分发包输出目录
+├── build/                            # 构建临时文件
+├── tests/                            # 测试文件
+├── docs/                             # 文档目录
+├── main.py                           # 项目启动入口
+├── pyproject.toml                    # 项目配置文件 (uv)
+├── requirements.txt                  # Python 依赖
+├── uv.lock                           # uv 锁定文件
+├── .python-version                   # Python 版本配置
+└── README.md                         # 项目说明文档
+```

docs/troubleshooting.md

@@ -0,0 +1,87 @@
+# 故障排除与性能优化
+
+## 🛠️ 故障排除
+
+### 1. 模型下载失败
+- **问题**: 网络连接超时或模型下载失败。
+- **解决方案**: 设置 Hugging Face 镜像。
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+pip install -U huggingface_hub
+```
+
+### 2. 音频设备问题
+- **问题**: 找不到音频设备或权限被拒绝。
+- **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。
+- **Linux 解决方案**: `sudo usermod -a -G audio $USER`，然后重新登录。
+
+### 3. 内存不足错误 (OOM)
+- **问题**: `CUDA out of memory` 或 RAM 不足。
+- **解决方案**: LLM 是主要的内存消耗者。你可以通过修改 `src/VoiceDialogue/services/text/generator.py` 来降低资源消耗：
+    - **更换模型**: 将模型路径指向一个更小的模型（如 7B Q4 量化模型）。
+    - **减少批处理大小**: 减小模型参数中的 `n_batch` 值（如 `256`）。
+    - **减少上下文长度**: 减小 `n_ctx` 的值（如 `1024`）。
+
+### 4. 依赖包冲突
+- **问题**: 包版本冲突或导入错误。
+- **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。
+```bash
+# 使用 conda
+conda deactivate
+conda env remove -n voicedialogue
+
+# 使用 uv
+deactivate
+rm -rf .venv
+```
+
+### 5. 说话人角色不存在
+- **问题**: 指定的说话人不在支持列表中。
+- **解决方案**: 使用 `python main.py --help` 查看所有可用的说话人角色。
+
+### 6. FFmpeg 相关错误
+- **问题**: 音频处理失败或编解码错误。
+- **解决方案**: 确保正确安装 FFmpeg：
+```bash
+# 检查 FFmpeg 安装
+ffmpeg -version
+
+# 重新安装 FFmpeg
+# macOS
+brew reinstall ffmpeg
+
+```
+
+### 7. Python 版本兼容性
+- **问题**: Python 版本过低导致的兼容性问题。
+- **解决方案**: 确保使用 Python 3.9+ 版本：
+```bash
+python --version
+# 如果版本过低，请升级或使用虚拟环境
+```
+
+### 8. 桌面应用相关问题
+- **问题**: Electron 应用启动失败或功能异常。
+- **解决方案**: 
+  - 确保 Node.js 版本 >= 16
+  - 重新安装依赖：`cd electron-app && npm install`
+  - 检查 Python 后端是否正常运行
+
+### 9. 构建打包问题
+- **问题**: 使用构建脚本失败。
+- **解决方案**: 
+  - 确保有执行权限：`chmod +x scripts/*.sh`
+  - 检查所有依赖是否安装完成
+  - 查看具体错误日志进行调试
+
+## 📊 性能优化建议
+
+### 硬件优化
+- **内存**: 推荐 32GB RAM 以获得最佳性能
+- **存储**: 使用 SSD 硬盘可显著提升模型加载速度
+- **CPU**: 多核处理器有助于多线程处理
+
+### 软件优化
+- **模型选择**: 根据硬件配置选择合适大小的模型
+- **批处理优化**: 调整 LLM 的 `n_batch` 参数
+- **音频缓冲**: 根据延迟要求调整音频缓冲区大小