# Piano Highlight Generator - GUI 修正功能设计

## 背景

现有 GUI 仅有"选文件+开始处理"的功能，跑完后用户无法对结果进行修正。本设计在跑完之后提供知识点编辑和字幕编辑能力，支持增删改，并自动判断如何应用修改。

## 名词定义

- **clip**：底层实现细节，表示一个视频片段（start/end/title_segments）
- **知识点**：用户感知的单位，即 clip 的 title
- **标题**：v1_title.srt，知识点名称的大字叠加层
- **字幕**：v1_content.srt，实际转录文本的小字叠加层

## 用户流程

```
PPT解析 → 跑流程 → GUI显示结果
                        ↓
              ┌─────────┴─────────┐
         编辑知识点             编辑字幕
         （改/删/增标题）         （改/删文本）
              ↓                      ↓
    系统自动判断如何重生成      直接应用用户修改
    （删json/重新匹配/处理重叠）  （跳过LLM校正）
              ↓                      ↓
              └──────┬─────────────┘
                     ↓
                  自动重烧
                     ↓
               用户用播放器查看
```

## 知识点编辑

### 用户操作

- **改标题**：直接编辑文字
- **删 clip**：删除该 clip
- **新增知识点**：输入新标题（PPT 里没有的也行）

### 系统行为

| 操作 | 底层动作 |
|------|---------|
| 改 clip N 标题 | 删 `clipN.json` → 用新标题在 transcript 里重新匹配 start/end → 处理重叠 → 重烧 |
| 删 clip N | 从 generated_config.yaml 删掉该 clip → 删 `clipN.json` + `clipN.mp4` → 重烧 |
| 新增知识点 | 用新标题在 transcript 里匹配 start/end → 判断是否合并到相邻 clip（重叠处理）→ 重烧 |

### 重叠处理

新增/修改后如果与现有 clip 重叠，系统自动：
1. 合并重叠片段
2. 生成 title_segments（按 transcript 关键词首次出现时间切分）
3. 每个标题最多显示 title_duration 秒

## 字幕编辑

### 用户操作

直接编辑字幕文件中的文本（v1_content.srt）。

### 系统行为

- **改字幕文本**：以用户修改为准，跳过 LLM 校正，直接重烧
- **删字幕条目**：用户删除某条，系统保留，其他正常重烧
- **改时间轴**：不支持（时间轴由底层逻辑决定）

## 底层原子化支撑

底层需要提供以下能力，供 GUI 调用：

```
reextract_clip_title(clip_index, new_title)
  → 删 clipN.json → 重新匹配 → 更新 generated_config.yaml

delete_clip(clip_index)
  → 从 config 删 → 删 json/mp4

add_clip_by_title(new_title)
  → 在 transcript 里匹配 → 判断合并/新增 → 更新 config

reburn_titles()
  → 只重烧标题轨（已有 json）

reburn_subtitles(user_texts)
  → 直接用用户文本烧录字幕，跳过 LLM 校正
```

CLI 的 `burn_only.py` 已经部分支撑"直接重烧"的能力，需要增强以支持按原子操作重烧。

## 数据流

```
generated_config.yaml  ← 唯一的 clips 配置源（用户编辑后同步更新）
intermediates/clip*.json  ← 转录缓存（按需删除重生成）
subs/v1_title.srt     ← 标题轨（可手动编辑后重烧）
subs/v1_content.srt   ← 字幕轨（用户直接改文本）
```

## 架构原则

1. **CLI/GUI 底层复用**：所有原子操作在 core/ 里，CLI 和 GUI 都调用同一套
2. **config 是唯一真源**：`generated_config.yaml` 是 clips 事实，GUI 编辑后写回此文件
3. **按需重生成**：只删除/重生成受影响的 clip，不动其他
4. **字幕以用户为准**：字幕文本修改跳过 LLM 校正

## 实施步骤

1. 底层原子化：core/ 增加 `reextract_clip`, `delete_clip`, `add_clip_by_title` 函数
2. CLI burn_only 支持部分重烧（支持只烧标题或只烧字幕）
3. GUI 增加编辑界面：clip 列表 + 字幕列表
4. 集成测试