授课视频 → 学生笔记 + 知识图谱 + 汇总

把一批课程视频（或已有的转写文本）整理为：每门课一篇结构化学生笔记、全课程知识体系索引、mermaid 知识图谱，以及合并为单文件的笔记汇总。

适用场景

• 用户有一批课程视频（如直播回放），希望转成可检索、带时间戳和术语解释的复习笔记
• 用户已转写好 .txt/.srt，希望直接生成笔记 + 知识图谱 + 汇总
• 用户要求每期课程标题统一为「日期_主题」规则（如 20250423_量化策略启蒙）

目录约定

所有产物放在一个 transcripts/ 目录下，每门课一个子目录：

transcripts/
├── 课程名/
│   ├── 视频1.txt        # 转写纯文本（转写阶段产出）
│   ├── 视频1.srt        # 带时间戳字幕（转写阶段产出，笔记时间点索引依赖它）
│   ├── 学生笔记.md        # 笔记阶段产出（格式 # 日期_主题）
│   ├── shots/             # 截图阶段产出（按时间点抽帧的 PNG，可选）
│   └── _stat.json         # 转写统计（可选）
└── _notes_index.jsonl     # 笔记阶段产出（索引/图谱用，可重建，无需保留）

transcripts/ 默认位于本 skill 的 scripts/ 同级目录；也可用 --transcripts-dir 指定任意路径。

前置依赖

1. Python venv：含 faster-whisper、imageio-ffmpeg、opencc-python-reimplemented，以及 GPU 运行库 nvidia-cublas-cu12 / nvidia-cudnn-cu12（仅转写阶段需要）。无显卡时可改用 device=int8/cpu（慢）。
2. LLM 模型：笔记与个别索引兜底需要。优先使用 WorkBuddy 已在 ~/.workbuddy/models.json 中管理的模型（默认 deepseek-chat）；若未配置，则回退到环境变量 OPENAI_API_KEY+OPENAI_BASE_URL（或 DEEPSEEK_API_KEY+DEEPSEEK_BASE_URL）。无 GPU 转写环境时，也可仅用市场 skill（如 openai-whisper-api、markitdown-skill）完成转写，再把 transcripts/ 交给本 skill 的笔记/图谱/合并阶段。
3. 详细环境搭建与踩坑见 references/env_setup.md。

流水线（五阶段，可独立运行，阶段5可选）

阶段 1 · 转写（仅当输入是视频时）

python scripts/transcribe.py "课程文件夹绝对路径" medium cuda --output-root transcripts

• 逐视频抽音频 → faster-whisper(VAD) 转写 → 输出 .txt + .srt
• 断点续传：已有 .txt 跳过
• 可单课跑，也可用外层循环遍历课程目录批量跑

阶段 2 · 生成学生笔记

python scripts/gen_notes.py --transcripts-dir transcripts [--only "课程目录名"]

• 调 LLM 把每门课转写文本 + 时间轴整理为 学生笔记.md
• 标题格式：# YYYYMMDD_本节课主题总结（日期从目录名解析）
• 五段结构：核心知识点 / 操作纪律心法 / 关键时间点索引 / 术语词典 / 本周安排
• 末尾追加 JSON 索引块（供阶段 3 使用）
• 已有笔记跳过；无 .txt 标记 .note_notxt；失败标记 .note_failed

阶段 3 · 知识体系索引 + 知识图谱

python scripts/build_index_and_graph.py --transcripts-dir transcripts --output-dir .

• 从各课笔记重建索引（优先复用末尾 JSON 块，免 LLM）
• 模块分类由课程名/标题规则确定（不依赖 LLM，100% 确定）——模块列表与关键词在脚本 MODULES/classify_module 中，换主题时按需修改
• 产出：全课程知识体系索引.md（按十大模块归类）、课程知识图谱.md（mermaid）、课程知识图谱.html（浏览器渲染版）

阶段 4 · 合并汇总

python scripts/merge_notes.py --transcripts-dir transcripts --output 课程笔记汇总.md

• 合并所有 学生笔记.md 为单文件，带自动目录
• 标题统一：新格式直接取用；旧格式从文件夹名推导 YYYYMMDD_主题
• 正文标题自动降级嵌套，避免与原 H1 冲突

阶段 5 · 视频截图嵌入笔记（可选增强，纯本地 ffmpeg）

python scripts/screenshot.py --transcripts-dir transcripts --video-roots "E:/源视频根1;E:/源视频根2" [--only 课程名] [--keyword 关键词]

• 解析每门课笔记的「关键时间点索引」，按 [mm:ss]（支持 第X部分 分段标签）在源视频对应时间抽帧 → shots/*.png
• 在时间点行后插入 ![截图](shots/xxx.png) 引用（幂等，已插入跳过）
• --keyword 模式：额外在各课 .srt 中搜索关键词，定位 (视频, 时间) 抽帧并追加到笔记末尾「关键词相关截图」章节
• 不依赖 GPU、不依赖外部 API，仅用 ffmpeg 抽帧（默认取 imageio-ffmpeg 自带二进制，或 --ffmpeg 指定）
• 多 part 分段视频按「第X部分」自动匹配对应文件；源视频根用 --video-roots 分号分隔传入（需与 transcripts 课程名对应）

一键跑完（转写已就绪时）

python scripts/gen_notes.py --transcripts-dir transcripts
python scripts/build_index_and_graph.py --transcripts-dir transcripts --output-dir .
python scripts/merge_notes.py --transcripts-dir transcripts --output 课程笔记汇总.md

关键参数

注意事项

• 模块分类是规则匹配，针对股票课程调优；处理其他主题时改 classify_module 的关键词与 MODULES 列表
• 笔记的 SYSTEM_PROMPT 内置了 Z哥股票黑话词典，换领域时改写该 prompt
• 阶段 2/3 需要联网调 LLM；阶段 4 纯本地；阶段 5 截图也纯本地（仅需 ffmpeg，不耗 GPU）
• 截图阶段会改写 学生笔记.md（插入图片引用），建议在笔记生成（阶段2）完成后、且不再重跑 gen_notes 覆盖前执行；gen_notes 对已存在笔记默认跳过，不会丢失截图引用
• 详细环境搭建与排错见 references/env_setup.md