lesson-highlights/docs/ARCHITECTURE.md

架构设计

1. 核心原则

CLI 和 GUI 共用同一套底层类库，仅在表示层有差异：

• CLI：命令行参数输入，日志输出到终端
• GUI：PySide6 界面，参数输入界面化，日志输出到文本区

2. 项目结构

lesson-highlights/
├── config.py              # 统一配置（所有路径/API只改这里）
├── run.py                 # 完整流水线入口
├── burn_only.py           # 快速烧录入口（跳过转录/字幕生成）
├── run.bat                # 运行完整流程
├── burn.bat               # 快速重烧字幕
├── src/
│   ├── main.py            # GUI 入口
│   ├── gui.py             # GUI（参数输入 → 调用底层）
│   ├── cli.py             # CLI 入口
│   └── core/              # 共享底层
│       ├── __init__.py
│       ├── ppt_parser.py  # PPT 解析 + LLM clips 提取
│       ├── pipeline.py    # 视频处理流水线
│       ├── subtitle.py    # 字幕生成
│       ├── video.py       # 视频处理（提取/合并/烧录）
│       ├── llm.py         # LLM 调用
│       ├── corrections.py  # 术语纠正
│       ├── constants.py   # 常量配置
│       └── errors.py      # 错误处理
├── config.ini             # API 配置（不提交 git）
├── config.ini.example    # 配置模板
├── start.bat             # GUI 启动器
└── docs/
    └── USAGE.md          # 使用指南

3. 核心模块

parse_ppt_to_config()

一键完成 PPT → clips 配置的完整流程：

1. PPT 解析：提取文本和知识点
2. Whisper 转录：视频 → full_transcript.json
3. LLM 校正：批量校正 → corrected_transcript.json
4. LLM 提取片段：根据知识点定位视频片段 → clips
5. 重叠合并：合并重叠片段

Pipeline

视频处理流水线：

1. extract：按时间戳提取片段
2. transcribe：逐片段 Whisper 转录
3. correct_titles：LLM 标题纠正
4. generate_subtitles：生成双轨字幕
5. merge：合并片段
6. burn：烧录字幕

4. 数据流

视频 + PPT
    ↓
parse_ppt_to_config()
    ↓
config = {
    "video_src": ...,
    "clips": [{"title": ..., "start": ..., "end": ...}, ...],
    "output_dir": ...,
    "term_corrections": {...}
}
    ↓
Pipeline(config).run()
    ↓
final.mp4

5. 配置来源

API 配置统一从 config.ini 读取，不硬编码在代码中。

CLI 支持参数覆盖：

• --api-key
• --api-host
• --verbose

6. 状态持久化

中间结果保存在 output/intermediates/：

• full_transcript.json - 原始转录
• corrected_transcript.json - LLM 校正后
• ppt_knowledge_and_cleaned.json - PPT 知识点和清理后文本

复用时检测 checkpoint，避免重复 LLM 调用。