Initial commit

TROUBLESHOOTING.md

@@ -0,0 +1,52 @@
+# VoxCPM 常见问题与修复记录
+
+本文档记录了在 Windows 环境下部署 VoxCPM 时遇到的常见问题及其修复方案。
+
+## 1. 依赖安装失败 (`editdistance` 构建错误)
+
+### 问题描述
+在执行 `pip install` 安装依赖时，`funasr` 的依赖项 `editdistance` 在 Windows + Python 3.13 环境下编译失败，报错涉及 C++ 语法错误。
+
+### 原因
+`editdistance` 缺少适配 Python 3.13 的预编译 Wheel 包，且本地编译环境（MSVC）存在兼容性问题。
+
+### 解决方案
+1.  **修改 `pyproject.toml`**：从依赖列表中暂时移除 `funasr`。
+2.  **代码适配**：在 `app.py` 中将 `funasr` 改为可选依赖（Optional Import）。如果未安装，ASR（自动语音识别）功能将自动禁用，但不影响核心 TTS 功能。
+
+```python
+try:
+    from funasr import AutoModel
+    HAS_FUNASR = True
+except ImportError:
+    HAS_FUNASR = False
+    print("Warning: funasr not installed. ASR features will be disabled.")
+    # Dummy class for type hinting
+    class AutoModel: pass
+```
+
+## 2. 模型文件加载失败 (`FileNotFoundError: audiovae.pth`)
+
+### 问题描述
+运行 `app.py` 时报错 `FileNotFoundError: [Errno 2] No such file or directory: '.../audiovae.pth'`。
+
+### 原因
+模型下载过程可能中断或不完整。原有的检查逻辑仅验证了目录和 `config.json` 是否存在，未验证核心权重文件（如 `audiovae.pth`）。
+
+### 解决方案
+优化了 `app.py` 中的 `_resolve_model_dir` 函数：
+1.  **增加完整性检查**：验证 `config.json`、`audiovae.pth` 以及权重文件（`.safetensors` 或 `.bin`）是否齐全。
+2.  **自动修复**：检测到文件缺失时，自动删除损坏的目录并重新触发 HuggingFace 下载。
+
+## 3. Gradio 界面报错与类型提示问题
+
+### 问题描述
+1.  **Linter 报错**：`AutoModel` 可能未绑定。
+2.  **API 参数错误**：`show_progress=True` 导致类型错误。
+
+### 解决方案
+1.  **类型修复**：在 `ImportError` 分支中添加 `class AutoModel: pass` 空类定义，解决静态类型检查报错。
+2.  **参数修正**：将 `run_btn.click` 中的 `show_progress=True` 修改为 `show_progress="full"`，适配新版 Gradio API。
+
+---
+*文档生成时间：2025-12-12*