tts/docs/PROJECT_DEVELOPMENT_RULES.md

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. 文档更新 → 更新相关使用文档

📝 脚本命名规范

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

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

🏗️ 代码组织规范

脚本结构模板

#!/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
• 环境隔离: 使用虚拟环境

🌍 环境变量

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)

📝 更新日志格式

## [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