Add detailed installation guide and restructure README setup section

- Create `docs/installation.md` with comprehensive installation instructions, system requirements, and troubleshooting steps.
- Update README to condense installation steps and link to the full guide.

README.md

@@ -99,58 +99,30 @@ VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端
 - **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)
 - **存储空间**: 至少 20GB 可用空间 (用于模型文件)
 
-### 安装步骤
+### 快速安装
 
-1. **克隆项目**
 ```bash
+# 1. 克隆项目
 git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
 cd VoiceDialogue
-```
 
-2. **创建并激活虚拟环境**
-```bash
-# 使用 uv (推荐)
+# 2. 创建虚拟环境（推荐）
 pip install uv
 uv venv
 source .venv/bin/activate
 
-# 或使用 conda
-conda create -n voicedialogue python=3.11
-conda activate voicedialogue
-
-# 或使用 venv
-python -m venv voicedialogue
-source voicedialogue/bin/activate
-```
-
-3. **安装项目依赖**
-```bash
-# 使用 uv (推荐)
+# 3. 安装依赖
 WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync
 
-# 或使用 pip
-WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" pip install -r requirements.txt
-```
-
-4. **安装音频处理工具**
-```bash
-# macOS
+# 4. 安装系统依赖
 brew install ffmpeg
-```
 
-5. **安装额外依赖**
-```bash
-# 安装 kokoro-onnx
-uv pip install kokoro-onnx
-# 或
-pip install kokoro-onnx
-
-# 重新安装指定版本的 numpy
-uv pip install numpy==1.26.4
-# 或
-pip install numpy==1.26.4
+# 5. 启动系统
+python main.py
 ```
 
+> 📖 **详细安装指南**: 如需了解完整的安装步骤、系统要求和故障排除，请查看 **[安装指南](docs/installation.md)**
+
 ### 🖥️ 应用模式
 
 #### 1. 命令行模式 (默认)

docs/installation.md

@@ -0,0 +1,149 @@
+# VoiceDialogue 安装指南
+
+本文档提供 VoiceDialogue 智能语音对话系统的详细安装说明。
+
+## 系统要求
+
+在开始安装之前，请确保您的系统满足以下要求：
+
+- **操作系统**: macOS 14+ (推荐)
+- **Python 版本**: 3.9 或更高版本
+- **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)
+- **存储空间**: 至少 20GB 可用空间 (用于模型文件)
+
+## 安装步骤
+
+### 1. 克隆项目
+
+```bash
+git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
+cd VoiceDialogue
+```
+
+### 2. 创建并激活虚拟环境
+
+建议使用虚拟环境来避免依赖冲突：
+
+```bash
+# 使用 uv (推荐)
+pip install uv
+uv venv
+source .venv/bin/activate
+
+# 或使用 conda
+conda create -n voicedialogue python=3.11
+conda activate voicedialogue
+
+# 或使用 venv
+python -m venv voicedialogue
+source voicedialogue/bin/activate
+```
+
+### 3. 安装项目依赖
+
+```bash
+# 使用 uv (推荐)
+WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync
+
+# 或使用 pip
+WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" pip install -r requirements.txt
+```
+
+### 4. 安装音频处理工具
+
+```bash
+# macOS
+brew install ffmpeg
+```
+
+### 5. 安装额外依赖
+
+```bash
+# 安装 kokoro-onnx
+uv pip install kokoro-onnx
+# 或
+pip install kokoro-onnx
+
+# 重新安装指定版本的 numpy
+uv pip install numpy==1.26.4
+# 或
+pip install numpy==1.26.4
+```
+
+## 验证安装
+
+安装完成后，可以通过以下命令验证安装是否成功：
+
+```bash
+# 查看帮助信息
+python main.py --help
+
+# 启动系统（默认使用中文，沈逸角色）
+python main.py
+```
+
+如果看到 "服务启动成功" 提示，说明安装成功。
+
+## 故障排除
+
+### 1. 模型下载失败
+- **问题**: 网络连接超时或模型下载失败。
+- **解决方案**: 设置 Hugging Face 镜像。
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+pip install -U huggingface_hub
+```
+
+### 2. 音频设备问题
+- **问题**: 找不到音频设备或权限被拒绝。
+- **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。
+
+### 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. FFmpeg 相关错误
+- **问题**: 音频处理失败或编解码错误。
+- **解决方案**: 确保正确安装 FFmpeg：
+```bash
+# 检查 FFmpeg 安装
+ffmpeg -version
+
+# 重新安装 FFmpeg
+# macOS
+brew reinstall ffmpeg
+```
+
+### 6. Python 版本兼容性
+- **问题**: Python 版本过低导致的兼容性问题。
+- **解决方案**: 确保使用 Python 3.11+ 版本：
+```bash
+python --version
+# 如果版本过低，请升级或使用虚拟环境
+```
+
+## 下一步
+
+安装完成后，您可以：
+
+1. [查看使用指南](../README.md#🖥️-应用模式) 了解如何使用系统
+2. [查看配置选项](../README.md#⚙️-配置选项) 了解如何自定义配置
+3. [查看系统架构](../README.md#🔧-系统架构) 了解系统工作原理
+
+如果遇到其他问题，请查看 [完整故障排除指南](../README.md#🛠️-故障排除) 或提交 Issue。