# TTS项目开发规范

## 📁 项目结构规范

```
/root/tts/
├── 🎯 核心功能目录
│   ├── fish-speech/          # Fish Speech官方源码（核心TTS引擎）
│   ├── VoxCPM/              # VoxCPM官方源码（备用TTS引擎）
│   └── F5-TTS/              # F5-TTS官方源码（实验性引擎）
│
├── 🛠️ 开发脚本目录
│   └── scripts/
│       ├── generate/        # 音频生成脚本（核心功能）
│       └── tools/           # 辅助工具脚本
│
├── 📚 文档目录
│   └── docs/               # 项目文档
│
├── 🔊 音频目录
│   ├── audio/              # 分类音频文件
│   │   ├── reference/      # 参考音频
│   │   └── output/         # 生成音频
│   └── audio_files/        # 历史音频文件
│
└── 📦 素材目录
    └── material/           # 训练素材和配置
```

## 🎯 核心脚本清单

### 必须保留的核心脚本（12个）

#### 🎵 音频生成脚本 (`scripts/generate/`)
1. **`fish_speech_cli.py`** - 主要CLI工具 ⭐⭐⭐
2. **`generate_final.py`** - 最终生成脚本 ⭐⭐⭐
3. **`real_fish_speech.py`** - 真实Fish Speech实现 ⭐⭐⭐
4. **`fish_speech_direct_cli.py`** - 直接CLI工具 ⭐⭐
5. **`create_30s_demo.py`** - 30秒音频演示 ⭐⭐
6. **`final_cli_demo.py`** - 最终CLI演示 ⭐⭐
7. **`generate_default_voice.py`** - 默认音色生成 ⭐⭐
8. **`generate_with_app.py`** - 应用接口生成 ⭐⭐

#### 🛠️ 工具脚本 (`scripts/tools/`)
9. **`final_summary.py`** - 最终总结工具 ⭐⭐⭐
10. **`check_audio.py`** - 音频检查工具 ⭐⭐
11. **`verify_env.py`** - 环境验证工具 ⭐⭐

#### 📚 文档文件 (`docs/`)
12. **`CLI_COMMANDS.md`** - CLI使用指南 ⭐⭐⭐

## 🚫 禁止保留的文件类型

### ❌ 立即删除的文件类别
1. **测试脚本** - 文件名包含 `test_`、`debug_`、`simple_`
2. **概念验证** - 文件名包含 `concept_`、`demo_`
3. **临时脚本** - 文件名包含 `temp_`、`tmp_`
4. **重复实现** - 功能相同的多个版本
5. **空文件** - 大小为0字节的文件
6. **过渡版本** - 标记为 `old_`、`backup_` 的文件

## 📋 开发流程规范

### 🔄 开发新功能时
1. **需求分析** → 在 `docs/` 创建需求文档
2. **设计阶段** → 确定脚本归属 (`generate/` 或 `tools/`)
3. **命名规范** → 使用清晰的描述性名称
4. **代码实现** → 遵循现有代码风格
5. **测试验证** → 使用临时脚本测试，完成后删除
6. **文档更新** → 更新相关使用文档

### 📝 脚本命名规范
```bash
# ✅ 正确命名
fish_speech_cli.py          # 功能_工具类型.扩展名
generate_final.py           # 功能_版本.扩展名
check_audio.py              # 动作_对象.扩展名

# ❌ 错误命名
test_123.py                 # 无意义的数字
temp_script.py              # 临时文件标识
demo_v1_old.py              # 版本混乱
```

### 🏗️ 代码组织规范

#### 脚本结构模板
```python
#!/usr/bin/env python3
"""
[脚本功能描述]

Author: [作者]
Date: [日期]
Version: [版本号]

Usage:
    python script_name.py [参数]
"""

import os
import sys
import argparse
from pathlib import Path

# 配置常量
PROJECT_ROOT = Path(__file__).parent.parent.parent
AUDIO_OUTPUT_DIR = PROJECT_ROOT / "audio" / "output"

def main():
    """主函数"""
    pass

if __name__ == "__main__":
    main()
```

## 🔧 环境配置规范

### 📦 依赖管理
- **核心依赖**: Fish Speech、VoxCPM官方依赖
- **开发依赖**: pytest、black、flake8
- **环境隔离**: 使用虚拟环境

### 🌍 环境变量
```bash
TTS_PROJECT_ROOT=/root/tts
FISH_SPEECH_MODEL_PATH=/root/tts/fish-speech
DEFAULT_AUDIO_OUTPUT=/root/tts/audio/output
```

## 📊 质量控制规范

### ✅ 代码质量检查
1. **功能完整性** - 确保实现预期功能
2. **错误处理** - 包含异常处理机制
3. **日志记录** - 关键操作有日志输出
4. **参数验证** - 输入参数有效性检查
5. **资源清理** - 临时文件和资源释放

### 🧪 测试要求
1. **单元测试** - 核心函数功能测试
2. **集成测试** - 完整流程测试
3. **边界测试** - 极端情况处理
4. **性能测试** - 生成速度和质量评估

## 📈 版本管理规范

### 🏷️ 版本号规则
- **主版本号**: 重大功能变更 (1.x.x → 2.x.x)
- **次版本号**: 新功能添加 (1.0.x → 1.1.x)
- **修订号**: Bug修复 (1.0.0 → 1.0.1)

### 📝 更新日志格式
```markdown
## [1.2.0] - 2024-XX-XX

### 新增
- 新增批量生成功能
- 新增音频格式转换

### 修复
- 修复内存泄漏问题
- 修复参数解析错误

### 删除
- 移除废弃的旧版本CLI
```

## 🎯 项目目标

### 🏆 核心目标
1. **高质量TTS** - 提供清晰、自然的语音合成
2. **易用性** - 简单的命令行接口
3. **可扩展** - 支持多种TTS引擎
4. **高性能** - 快速生成，低资源占用

### 📋 发展路线
- **Phase 1**: 完善Fish Speech集成
- **Phase 2**: 添加Web界面
- **Phase 3**: 支持实时流式TTS
- **Phase 4**: 多语言支持

---

## 📞 联系和支持

- **技术问题**: 查看docs/目录相关文档
- **Bug报告**: 在项目Issues中提交
- **功能建议**: 在项目Discussions中讨论

---

*最后更新: 2024-12-25*
*版本: v1.0.0*