字幕转学习笔记
将原始字幕文本整理为结构清晰、便于复习的 Markdown 学习笔记。
核心原则
- 保留原意：不添加个人理解，不扩展课程内容外的知识
- 结构化呈现：按知识点分段，提炼层级标题，让笔记可快速浏览
- 知识增强：标注关键概念，生成章节摘要，帮助复习时抓住重点
- 内容详细：笔记要足够详细，包含完整的代码示例、步骤拆解、表格对比，不能过度精简
- 输出即文件：每个字幕文件生成一个同名的
.md文件 - 并发处理：当用户有多个字幕文件时，必须并发处理每个文件，避免上下文互相干扰
处理流程
1. 读取输入
接收原始字幕文本。格式可能是：
- 纯文本（每行一句，如语音转写结果）
- SRT/VTT 格式（带时间码）
- 其他文本格式
无论何种格式，提取有效内容文本，忽略时间码、行号等元数据。
2. 内容分段
按话题转折切分，而非按时间或固定长度。
识别话题转换的信号：
- 讲师明确说"接下来"、"下面"、"那了解了...之后"
- 概念切换（从 A 概念转到 B 概念）
- 从理论讲解切换到代码演示
- 从演示切换到总结
每个段落应围绕一个核心主题，长度适中（通常 3-10 个要点）。
3. 添加层级标题
从段落内容中提炼标题，不要泛泛的"第一部分"。
标题层级规则（必须严格执行）：
- #：课程总标题（从文件名或内容推断）
- ##：主要章节/大知识点，必须使用中文数字编号：## 一、章节标题、## 二、章节标题，以此类推
- ###：子主题/细分知识点，使用阿拉伯数字编号：### 1. 子主题标题、### 2. 子主题标题
标题要具体，能概括该段核心内容。所有笔记的编号风格必须统一，不允许混用不同编号格式。生成笔记时必须检查并确保编号符合上述规则。
4. 要点提取与内容详细化
将段落内容转化为 bullet list，每个要点一行。
- 保留讲师的核心论述，去除口语化过渡
- 代码相关的内容：
- 简短的代码片段（如
@app.get()、/book/{id}）用 inline code 标记 - 完整的代码示例（多行代码）使用代码块（```python）展示，包含必要的导入和上下文
- 关键数据、返回值、路径等用 inline code 标记
- 步骤拆解使用有序列表或表格，确保读者能复现操作
- 对比类内容使用 Markdown 表格展示
5. 关键概念标注
识别并标注以下类型的术语：
- 专业术语：框架/库名（如 FastAPI）、编程概念（如路由、装饰器）
- 方法/函数：如 Path()、get()
- 重要参数/属性：如 gt、lt、min_length
- 人名/工具名：如 Python、Pydantic（如果出现）
标注方式：
- 术语首次出现时加粗：**路由**
- 紧跟简要注释（1-2 句话），用括号或独立行说明：
- **路由**：URL 地址与处理函数之间的映射关系
- 如果课程内对术语有明确定义，优先使用课程内的解释
6. 生成章节摘要
在每个 ## 大章节末尾添加要点总结（必须严格执行，不能遗漏）：
> 💡 **要点总结**：
> - 核心概念 1
> - 核心概念 2
> - 注意事项
摘要要精炼，是该章节最核心、最可能考/最常用到的 2-4 点。生成笔记后必须检查每个 ## 章节末尾是否都有要点总结，缺少的要补上。
7. 并发处理多个文件
当用户一次提供多个字幕文件时：
- 必须并发处理：为每个字幕文件启动独立的处理任务（subagent 或并行线程）
- 隔离上下文：每个文件独立处理，处理文件 A 时不参考文件 B 的内容
- 统一输出：所有生成的
.md文件放在同一输出目录 - 禁止串行处理：不要先处理完一个再处理下一个，避免前面的内容影响后面的分段和标题提炼
批量文件处理策略（文件数量 > 5 时）：
如果用户提供的字幕文件很多（如 10 个、50 个、100 个），无法一次性全部并发，必须使用脚本进行分批调度：
- 扫描文件：运行
scripts/scan_subtitles.py <目录>获取所有字幕文件列表 - 生成分批计划：运行
scripts/batch_processor.py <扫描结果.json> [每批大小]生成分批计划 - 按批执行：
- 第 1 轮：并发处理第 1 批的 5 个文件（各自独立 subagent）
- 第 2 轮：并发处理第 2 批的 5 个文件
- ...以此类推 - 每轮内部完全并发：每批的文件各自启动独立 subagent，互不干扰
- 轮次之间串行：等上一批全部完成后，再启动下一批
具体执行步骤：
# 1. 扫描字幕文件
python scripts/scan_subtitles.py /path/to/subtitles > files.json
# 2. 生成分批计划（每批 5 个）
python scripts/batch_processor.py files.json 5 > batches.json
# 3. 按 batches.json 中的计划逐批并发处理
示例（68 个文件）：
轮次 1: [文件1] [文件2] [文件3] [文件4] [文件5] ← 5 个并发 subagent
轮次 2: [文件6] [文件7] [文件8] [文件9] [文件10] ← 5 个并发 subagent
...
轮次 14: [文件66] [文件67] [文件68] ← 3 个并发 subagent
这样既能保证每个文件独立处理、不受其他文件上下文干扰，又能高效处理大量文件。
8. 输出文件
- 输出格式：Markdown (
.md) - 文件名：与输入字幕文件同名，仅扩展名改为
.md - 例：
04-FastAPI基础入门-路由.txt→04-FastAPI基础入门-路由.md - 文件位置：
- 必须放在独立的输出目录中，不能与原始字幕文件混放在同一目录
- 默认输出目录为字幕文件所在目录下的
notes/子目录 - 例：字幕在
/workspace/subtitles/，则笔记输出到/workspace/subtitles/notes/ - 如果用户指定了输出目录，则使用用户指定的目录
输出模板
# [课程标题]
## [章节一名称]
- 要点 1
- 要点 2，涉及 `代码片段`
- **关键概念**：概念解释
> 💡 **要点总结**：
> - 总结 1
> - 总结 2
## [章节二名称]
...
注意事项
- 不要添加课程外的延伸知识或链接
- 不要过度精简导致丢失关键信息
- 代码片段尽量保持原样，只修正明显的语音识别错误（如将"艾特"还原为
@） - 如果识别到讲师布置的练习/作业，单独放在一个
### 练习小节 - 如果内容中有明显的语音识别错误（如 "pass" 应为 "Path"），在注释中标注
> ❓ 语音识别：原文为"pass"，实际应为 "Path"
```
