lesson-highlights/proposal.md

# Piano Highlight Generator App - 需求提案

> 提案日期：2026-05-02
> 提案人：AI Dev Team
> 状态：Draft

---

## 1. 问题描述

### 1.1 现状

当前钢琴课精华视频生成器是 Python CLI 脚本集合：
- `generate_highlights.py` - 命令行程序，一次性执行完整流程
- 无图形界面，需要手动编辑 YAML 配置文件
- 无状态保持，程序中断只能从头开始
- 无人工介入点，无法在处理过程中修改标题

### 1.2 用户需求

用户希望将其重构为**可分发的桌面应用**，具备：

| 需求 | 说明 |
|------|------|
| **配置界面** | 图形化配置 API 大模型参数，无需编辑 YAML |
| **全过程监控** | 实时显示每个处理步骤的状态 |
| **状态保持** | 可在任意步骤暂停，然后继续往下进行 |
| **人工介入** | 暂停时可手动修改标题，然后再最后烧制 |

---

## 2. 用户故事

### 2.1 作为用户，我想要...

**Story 1: 配置管理**
- 打开应用后，能看到清晰的配置界面
- 可以选择/切换不同的 LLM API（当前是火山方舟，可扩展）
- 可以选择 Whisper 模型（用于音频转录）
- 配置可以保存和加载

**Story 2: 全过程监控**
- 启动处理后，能看到每个步骤的实时状态
- 看到当前正在处理哪个片段（Clip 3/14）
- 看到预估剩余时间
- 能看到每个步骤的日志输出

**Story 3: 暂停与恢复**
- 点击"暂停"按钮，处理立即停止
- 关闭应用后，下次打开能从暂停点继续
- 恢复后从最近的检查点继续，不丢失进度

**Story 4: 人工介入**
- 在标题纠正步骤，可以预览每个片段的标题
- 可以手动修改标题
- 可以跳过某些片段
- 所有修改会被保存

**Story 5: 打包分发**
- 生成一个 .exe 文件，双击即可运行
- 无需安装 Python 环境
- 可以在其他电脑上使用

---

## 3. 验收标准

### 3.1 配置界面
- [ ] 应用启动后显示配置面板
- [ ] 可以输入/编辑 API Key 和 API Host
- [ ] 可以选择 Whisper 模型（base/small/medium/large）
- [ ] 可以选择输入视频文件（文件选择对话框）
- [ ] 可以选择输出目录
- [ ] 配置可以保存到文件（JSON/YAML）
- [ ] 配置可以从文件加载

### 3.2 全过程监控
- [ ] 显示当前步骤：准备 → 提取片段 → 转录 → 标题纠正 → 合并 → 烧录
- [ ] 每一步显示进度条（百分比）
- [ ] 显示当前片段序号（如 "Clip 3/14"）
- [ ] 实时显示处理日志
- [ ] 处理完成后显示最终视频路径

### 3.3 暂停与恢复
- [ ] 有"暂停"按钮，点击后处理停止
- [ ] 暂停时状态持久化到文件
- [ ] 重新打开应用后，自动检测到未完成的任务
- [ ] 可以选择"继续"从暂停点恢复
- [ ] 也可以选择"重新开始"

### 3.4 人工介入
- [ ] 在标题纠正步骤，显示所有片段的标题列表
- [ ] 每个标题可以点击编辑
- [ ] 编辑后自动保存
- [ ] 可以预览修改后的字幕效果
- [ ] 确认后继续后续步骤

### 3.5 打包分发
- [ ] 生成 Windows 可执行文件（.exe）
- [ ] 双击运行，无须安装 Python
- [ ] 界面美观，与现代桌面应用一致

---

## 4. 技术选型

### 4.1 GUI 框架

**选择：PySide6 (Qt for Python)**

| 因素 | 结论 |
|------|------|
| 许可证 | LGPL - 可闭源商用，无需购买 |
| 功能 | 成熟完备，适合复杂桌面应用 |
| 状态管理 | 传统保留模式，天然支持暂停/恢复 |
| 多线程 | 信号槽机制完善，支持多线程安全更新 UI |
| 社区 | 文档丰富，社区活跃 |
| 打包 | Nuitka 打包体积小（~10MB），启动快 |

### 4.2 打包方案

**开发阶段**：PyInstaller（调试方便）
**正式发布**：Nuitka（体积小，性能好）

### 4.3 状态持久化

- 使用 JSON 文件存储处理进度
- 每个项目独立的状态文件
- 包含：当前步骤、已完成片段、用户修改的标题等

---

## 5. 架构设计（预览）

```
┌─────────────────────────────────────────────────────────────┐
│                      GUI Layer (PySide6)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ ConfigPanel │  │ ProgressView│  │ TitleEditor     │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Business Logic Layer                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ ConfigManager│ │PipelineCtrl │  │ StateManager    │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Core Modules (Legacy)                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │ video.py│  │subtitle │  │  llm.py │  │correction│     │
│  │         │  │  .py    │  │         │  │s.py     │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
└─────────────────────────────────────────────────────────────┘
```

### 模块职责

| 模块 | 职责 |
|------|------|
| ConfigPanel | 配置界面（API、视频路径、模型选择） |
| ProgressView | 进度监控（步骤、百分比、日志） |
| TitleEditor | 标题编辑器（预览、编辑用户修改） |
| ConfigManager | 配置加载/保存 |
| PipelineController | 流水线控制（启动/暂停/恢复/停止） |
| StateManager | 状态持久化（保存/恢复进度） |

---

## 6. 流水线步骤

与应用UI对应的处理步骤：

```
Step 0: 准备 (Ready)
    └─ 检查配置、初始化环境

Step 1: 提取片段 (Extracting)
    └─ 从视频提取 clips -> intermediates/clip{N}_fade.mp4

Step 2: 转录 (Transcribing)
    └─ Whisper 转录 -> intermediates/clip{N}.json

Step 3: 标题纠正 (Title Correcting)
    └─ LLM 分析 + 用户修改 -> intermediates/corrected_titles.json
    [人工介入点] 用户可在此步骤暂停并修改标题

Step 4: 生成字幕 (Generating Subtitles)
    └─ 生成双轨字幕 -> subs/v{N}_title.srt, v{N}_content.srt

Step 5: 合并视频 (Merging)
    └─ FFmpeg concat -> concat_merged.mp4

Step 6: 烧录字幕 (Burning)
    └─ FFmpeg burn -> v{N}_final.mp4

Step 7: 完成 (Completed)
    └─ 显示结果，清理临时文件（可选）
```

### 暂停点

用户可以在以下步骤暂停：
- Step 1 完成后（片段已提取）
- Step 2 完成后（转录已完成）
- Step 3 完成后（标题已确认）- **推荐暂停点**
- Step 4 完成后（字幕已生成）
- Step 5 完成后（视频已合并）

---

## 7. 状态数据结构

```json
{
  "version": 1,
  "project_name": "福田夜校-03月18日",
  "config": {
    "video_src": "D:/path/to/video.mp4",
    "output_dir": "D:/path/to/output",
    "api_key": "xxx",
    "api_host": "https://...",
    "whisper_model": "large"
  },
  "current_step": 3,
  "clips": [
    {
      "index": 1,
      "title_original": "弹奏",
      "title_corrected": "弹奏",
      "title_user_modified": null,
      "start": 412,
      "end": 442,
      "status": "completed",
      "clip_path": "intermediates/clip1_fade.mp4",
      "json_path": "intermediates/clip1.json"
    }
  ],
  "step_status": {
    "extracting": "completed",
    "transcribing": "completed",
    "title_correcting": "in_progress",
    "generating_subtitles": "pending",
    "merging": "pending",
    "burning": "pending"
  },
  "created_at": "2026-05-02T10:00:00",
  "updated_at": "2026-05-02T10:30:00"
}
```

---

## 8. 边界情况

| 情况 | 处理方式 |
|------|----------|
| API Key 无效 | 显示错误提示，不开始处理 |
| 视频文件不存在 | 配置检查时发现，提示用户 |
| 处理到一半崩溃 | 状态已持久化，重启后可恢复 |
| 用户取消处理 | 保存当前进度，可选择重新开始或继续 |
| Whisper 模型未下载 | 显示下载链接，或使用默认模型 |
| 输出目录磁盘空间不足 | 处理前检查，提示用户 |

---

## 9. 非功能性需求

| 需求 | 标准 |
|------|------|
| 启动时间 | < 3 秒（使用 Nuitka 打包后） |
| UI 响应性 | 所有操作在 100ms 内响应 |
| 内存占用 | < 500MB（不含视频处理） |
| 打包后体积 | < 50MB |
| 兼容性 | Windows 10/11 64-bit |

---

## 10. 后续步骤

1. **Phase 2**: 技术设计 - 详细架构设计、数据库选型、接口定义
2. **Phase 3**: 任务编排 - 拆分并行任务、创建 git worktree
3. **Phase 4**: 并行开发 - 各模块实现
4. **Phase 5**: 质量交付 - 审查、测试、打包