Clean up: remove junk files, update docs

- Delete: build scripts, old docs (README_BUILD, design.md, proposal.md, etc.) - Update README.md and docs/ARCHITECTURE.md to reflect new architecture - Keep run_lesson1.bat/py, start.bat, config.ini
2026-05-03 03:30:24 +08:00
parent 9e62247a60
commit cf5004cf6a
12 changed files with 139 additions and 1791 deletions
@@ -1,90 +1,92 @@
 # 架构设计

-## 1. 技术栈
+## 1. 核心原则

-| 层级 | 技术 | 选型理由 |
-|------|------|----------|
-| GUI 框架 | PySide6 (Qt for Python) | LGPL 许可，功能完备，信号槽机制适合异步更新 |
-| 打包工具 | Nuitka | 编译为 C，性能好，体积小 |
-| 状态持久化 | JSON 文件 | 简单，无需数据库依赖 |
-| 核心模块 | 复用现有脚本 | video.py, subtitle.py, llm.py, corrections.py |
-| 配置格式 | YAML/JSON | 用户友好，可读性好 |
+**CLI 和 GUI 共用同一套底层类库**，仅在表示层有差异：
+- **CLI**：命令行参数输入，日志输出到终端
+- **GUI**：PySide6 界面，参数输入界面化，日志输出到文本区

 ## 2. 项目结构

 ```
-piano-highlight-app/
+lesson-highlights/
 ├── src/
-│   ├── __init__.py
-│   ├── main.py                 # 应用入口
-│   ├── app.py                  # QMainWindow 主窗口
-│   ├── gui/                    # GUI 组件
-│   │   ├── __init__.py
-│   │   ├── config_panel.py     # 配置面板
-│   │   ├── progress_view.py    # 进度监控
-│   │   ├── title_editor.py     # 标题编辑器
-│   │   └── log_view.py         # 日志窗口
-│   ├── logic/                  # 业务逻辑
-│   │   ├── __init__.py
-│   │   ├── config_manager.py   # 配置管理
-│   │   ├── pipeline_controller.py  # 流水线控制
-│   │   ├── state_manager.py    # 状态管理
-│   │   └── worker.py           # 后台工作线程
-│   └── core/                   # 核心模块（复用）
+│   ├── main.py              # GUI 入口
+│   ├── gui.py               # GUI（参数输入 → 调用底层）
+│   ├── cli.py               # CLI 入口
+│   └── core/                # 共享底层
 │       ├── __init__.py
-│       ├── constants.py         # 常量
-│       ├── utils.py            # 工具函数
-│       ├── video.py            # 视频处理
-│       ├── subtitle.py          # 字幕处理
-│       ├── llm.py              # LLM 调用
-│       └── corrections.py       # 纠错规则
-├── assets/                     # 资源文件
-│   └── icons/
-├── requirements.txt             # 依赖
-├── pyproject.toml              # 项目配置
-├── nuitka_options.py           # Nuitka 打包配置
-└── README.md
+│       ├── 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 启动器
+├── run.bat                 # 通用 CLI 启动器
+└── run_lesson1.bat        # 预设课程示例
 ```

-## 3. 核心类设计
+## 3. 核心模块

-### StateManager（状态管理）
+### `parse_ppt_to_config()`

-负责状态持久化，支持暂停/恢复。
+一键完成 PPT → clips 配置的完整流程：

-### PipelineController（流水线控制）
+1. **PPT 解析**：提取文本和知识点
+2. **Whisper 转录**：视频 → `full_transcript.json`
+3. **LLM 校正**：批量校正 → `corrected_transcript.json`
+4. **LLM 提取片段**：根据知识点定位视频片段 → clips
+5. **重叠合并**：合并重叠片段

-管理处理流程的 6 个步骤：
-1. extract - 片段提取
-2. transcribe - 语音转录
-3. title_correct - 标题生成与纠错
-4. generate_subtitles - 字幕生成
-5. merge - 片段合并
-6. burn - 字幕烧录
+### `Pipeline`

-### Worker（后台工作线程）
+视频处理流水线：

-在独立线程中执行流水线，通过信号与 UI 通信。
+1. **extract**：按时间戳提取片段
+2. **transcribe**：逐片段 Whisper 转录
+3. **correct_titles**：LLM 标题纠正
+4. **generate_subtitles**：生成双轨字幕
+5. **merge**：合并片段
+6. **burn**：烧录字幕

-## 4. 流水线状态机
+## 4. 数据流

 ```
-Ready → Extracting → Transcribing → Title Correcting → Generating Subtitles → Merging → Burning → Completed
-                    ↑                                              ↓
-                    └───────────── 用户可暂停并编辑标题 ─────────────┘
+视频 + PPT
+    ↓
+parse_ppt_to_config()
+    ↓
+config = {
+    "video_src": ...,
+    "clips": [{"title": ..., "start": ..., "end": ...}, ...],
+    "output_dir": ...,
+    "term_corrections": {...}
+}
+    ↓
+Pipeline(config).run()
+    ↓
+final.mp4
 ```

-## 5. 信号流
+## 5. 配置来源

-| 信号 | 方向 | 说明 |
-|------|------|------|
-| config_changed | UI → Controller | 配置变更 |
-| progress_signal | Worker → UI | 进度更新 |
-| titles_ready_signal | Worker → UI | 标题列表准备好 |
-| titles_confirmed_signal | UI → Controller | 用户确认的标题 |
+API 配置统一从 `config.ini` 读取，不硬编码在代码中。

-## 6. 状态文件格式
+CLI 支持参数覆盖：
+- `--api-key`
+- `--api-host`
+- `--verbose`

-JSON 格式，包含配置、流水线状态、clips 列表等。
+## 6. 状态持久化

-详见 design.md。
+中间结果保存在 `output/intermediates/`：
+- `full_transcript.json` - 原始转录
+- `corrected_transcript.json` - LLM 校正后
+- `ppt_knowledge_and_cleaned.json` - PPT 知识点和清理后文本
+
+复用时检测 checkpoint，避免重复 LLM 调用。