授课视频 → 学生笔记 + 知识图谱 + 汇总
把一批课程视频（或已有的转写文本）整理为：每门课一篇结构化学生笔记、全课程知识体系索引、mermaid 知识图谱，以及合并为单文件的笔记汇总。
适用场景
- 用户有一批课程视频（如直播回放），希望转成可检索、带时间戳和术语解释的复习笔记
- 用户已转写好
.txt/.srt，希望直接生成笔记 + 知识图谱 + 汇总 - 用户要求每期课程标题统一为「日期_主题」规则（如
20250423_量化策略启蒙）
目录约定
所有产物放在一个 transcripts/ 目录下，每门课一个子目录：
transcripts/
├── 课程名/
│ ├── 视频1.txt # 转写纯文本（转写阶段产出）
│ ├── 视频1.srt # 带时间戳字幕（转写阶段产出，笔记时间点索引依赖它）
│ ├── 学生笔记.md # 笔记阶段产出（格式 # 日期_主题）
│ ├── shots/ # 截图阶段产出（按时间点抽帧的 PNG，可选）
│ └── _stat.json # 转写统计（可选）
└── _notes_index.jsonl # 笔记阶段产出（索引/图谱用，可重建，无需保留）
transcripts/ 默认位于本 skill 的 scripts/ 同级目录；也可用 --transcripts-dir 指定任意路径。
前置依赖
- Python venv：含
faster-whisper、imageio-ffmpeg、opencc-python-reimplemented，以及 GPU 运行库nvidia-cublas-cu12/nvidia-cudnn-cu12（仅转写阶段需要）。无显卡时可改用device=int8/cpu（慢）。 - 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 的笔记/图谱/合并阶段。 - 详细环境搭建与踩坑见
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 - 在时间点行后插入
引用（幂等，已插入跳过） --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
关键参数
| 脚本 | 参数 | 默认 | 说明 |
|---|---|---|---|
| 全部 | --transcripts-dir |
scripts/transcripts |
课程目录根 |
| gen_notes | --model |
deepseek-chat |
指定 models.json 中的模型 id |
| gen_notes | --only |
无 | 只处理一门课（调试用） |
| build | --output-dir |
transcripts 的父目录 | 索引/图谱输出位置 |
| merge | --output |
父目录/课程笔记汇总.md |
汇总文件名 |
| transcribe | --model/--device/--output-root |
medium/cuda/scripts/transcripts | 模型、设备、输出根 |
| screenshot | --video-roots |
E:/Z哥2025;C:/Users/7/Desktop/袁武/Z哥2026 |
源视频根（分号分隔，按课程名匹配） |
| screenshot | --keyword |
无 | 额外按关键词在 .srt 中定位抽帧 |
注意事项
- 模块分类是规则匹配，针对股票课程调优；处理其他主题时改
classify_module的关键词与MODULES列表 - 笔记的 SYSTEM_PROMPT 内置了 Z哥股票黑话词典，换领域时改写该 prompt
- 阶段 2/3 需要联网调 LLM；阶段 4 纯本地；阶段 5 截图也纯本地（仅需 ffmpeg，不耗 GPU）
- 截图阶段会改写
学生笔记.md（插入图片引用），建议在笔记生成（阶段2）完成后、且不再重跑 gen_notes 覆盖前执行；gen_notes 对已存在笔记默认跳过，不会丢失截图引用 - 详细环境搭建与排错见
references/env_setup.md
