DEVELOPER_GUIDE.md

# Lec2Note 开发者指南 (Developer Guide)

## 1. 项目概述
Lec2Note 致力于提供一个端到端的 **“视频讲座自动生成笔记”** 解决方案。  
通过多模态分析技术，深度融合视频画面与音频内容，生成 **图文并茂、结构清晰** 的笔记。

### 1.1 核心流程
1. **基于字幕的精细分块**：将 ASR 生成的每一句话视为独立的 *micro-chunk*，并在句末时间点精确截取关键帧。  
2. **分层合并策略**  
   - **阶段一·视觉预合并**：仅根据视觉相似度合并连续 *micro-chunks*。  
   - **阶段二·语义合并**：在视觉合并结果上再根据文本语义相似度合并。  
3. **多模态信息提取与采样**  
   - **文本**：拼接主题块包含的全部字幕文本。  
   - **图像**：采样该主题块的关键帧（最多 6 张）。  
4. **分块笔记生成**：调用多模态 LLM，为每个主题块生成独立笔记。  
5. **全局笔记合成**：再次调用 LLM，对所有分块笔记进行整合、去重与润色。

### 1.2 目标使用场景
- 学术课程录播  
- 会议 / 研讨会记录  
- 企业内部培训视频  

---

## 2. 技术栈

| 层级 | 主要技术 | 说明 |
|------|----------|------|
| **语言** | Python 3.9+ | 主代码基于 Python |
| **视频 / 图像处理** | OpenCV, Pillow | 截图、图像处理、图像相似度计算 (SSIM / pHash) |
| **OCR** | PaddleOCR / Tesseract | 提取关键帧中的幻灯片文字 |
| **ASR** | Whisper / Faster-Whisper | 生成句子级时间戳 |
| **语义分析** | Sentence Transformers | 计算文本语义相似度 |
| **LLM** | Gemini-2.5-pro | 多模态模型，生成笔记 |
| **Web 框架** | FastAPI | 提供 RESTful & WebSocket 服务 |
| **任务编排** | Prefect / Celery | 批处理与重试机制 |
| **数据库** | SQLite (dev) / PostgreSQL (prod) | 存储元数据与任务状态 |
| **容器** | Docker & Docker Compose | 一键部署 |

---

## 3. 目录结构与模块划分
```text
Lec2Note/
├── docs/                    # 设计文档 & 会议记录
├── lec2note/                # 源码包 (Python)
│   ├── ingestion/           # 音频处理 & ASR
│   ├── vision/              # 视频画面处理模块
│   │   ├── frame_extractor.py
│   │   ├── image_comparator.py
│   │   ├── image_sampler.py
│   │   └── ocr_processor.py
│   ├── segmentation/        # 分块与合并模块
│   │   ├── sentence_chunker.py
│   │   └── chunk_merger.py
│   ├── processing/          # 多模态信息融合与 LLM 生成
│   ├── synthesis/           # 全局笔记整合与导出
│   ├── assets/              # 静态模板 (Markdown/HTML)
│   └── api/                 # FastAPI 路由
├── scripts/                 # CLI 脚本 & 任务调度
├── tests/                   # PyTest 单元与集成测试
├── Dockerfile
├── docker-compose.yml
└── README.md
```

---

## 4. 核心功能说明

### 4.1 分块与合并策略
1. **生成句块**：`sentence_chunker.run()` 根据 ASR 输出生成 `{start, end, text, keyframe_path}` 的 *sentence_chunks*。  
2. **分层合并**：`chunk_merger.run()` 先视觉预合并，再语义合并，得到 *topic_chunks*。  
3. **关键帧采样**：`image_sampler.sample()` 均匀采样关键帧，最多保留 6 张。  
4. **输出**：最终得到包含文本及代表性截图的 `final_chunks`。

### 4.2 信息提取 (Extraction)
对采样后的截图进行 OCR，丰富文本信息。

### 4.3 图文融合与生成 (Processing)
- **Prompt 构建**：在文本中插入 `[IMAGE_n]` 占位符，并附上对应图像列表。  
- **LLM 调用**：`processor.generate_note_chunk()` 使用多模态 LLM 生成 Markdown 格式笔记。

### 4.4 笔记合成 (Synthesis)
`assembler.merge()` 收集所有 `note_chunk` 文本，构建新 Prompt，调用 LLM 进行去重、重排与润色，输出完整笔记。

### 4.5 API 一览

| 方法 | 路径 | 功能 |
|------|------|------|
| `POST` | `/upload` | 上传视频 → 返回任务 ID |
| `GET`  | `/status/{id}` | 查询任务进度 |
| `GET`  | `/notes/{id}` | 获取生成的图文笔记 |

### 4.6 内部模块接口

| 模块 | 关键类 / 方法 | 输入 | 输出 | 说明 |
|------|--------------|------|------|------|
| `ingestion.whisper_runner` | `WhisperRunner.transcribe()` | 音频路径 | `[{start, end, text}, …]` | 句子级 ASR 结果 |
| `vision.frame_extractor` | `FrameExtractor.capture_at()` | 视频路径, 时间戳列表 | 图片路径列表 | 精确截图 |
| `vision.image_comparator` | `ImageComparator.get_similarity()` | 两张图片路径 | 相似度 (0-1) | pHash / SSIM |
| `vision.image_sampler` | `ImageSampler.sample()` | 图片路径列表, `max_n` | 采样后路径列表 | 均匀采样 |
| `segmentation.sentence_chunker` | `SentenceChunker.run()` | 字幕列表, 视频路径 | *sentence_chunks* | 生成微型块 |
| `segmentation.chunk_merger` | `ChunkMerger.run()` | *sentence_chunks* | `final_chunks` | 分层合并 |
| `processing.processor` | `Processor.generate_note()` | `final_chunk` | `NoteChunk` | 调用 LLM |
| `synthesis.assembler` | `Assembler.merge()` | `NoteChunk` 列表 | Markdown/HTML | 全局整合 |

### 4.7 数据格式示例
```json
{
  "start": 0.0,
  "end": 25.4,
  "text": "欢迎来到 Lec2Note 课程。今天我们介绍多模态笔记生成。首先，我们会讲解系统的核心流程...",
  "representative_frames": [
    "frames/kf_3.20s.png",
    "frames/kf_15.80s.png",
    "frames/kf_22.10s.png"
  ]
}
```

### 4.8 健壮性：错误处理与重试
- **任务原子性**：每步定义为独立任务。  
- **自动重试**：针对网络/LLM 失败采用指数退避重试。  
- **失败隔离**：单任务失败不会阻断整体流程，可记录后续排查。

---

## 5. 开发环境搭建
```bash
# 克隆仓库
git clone git@github.com:your_org/lec2note.git
cd lec2note

# (可选) 创建虚拟环境
python -m venv .venv && source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 设置环境变量
export OPENAI_API_KEY="YOUR_KEY"

# 运行单元测试
pytest -q
```

### 5.1 快速运行本地 Pipeline
```bash
python -m lec2note.scripts.run_pipeline \
    --video example.mp4 \
    --output notes.md
```

---

## 6. 部署指南

### 6.1 Docker Compose
```bash
docker compose up -d --build
```