/lecture-to-md

name: lecture-to-md
description: 把课堂视频（本地或 B 站/YouTube）、文字稿、课件三者（任意组合）整理成一份详细的中文 Markdown 课堂笔记，输出按课程标题命名的 `{title_name}.md`（首行为 `# 文档标题`）+ 相对路径图片。Markdown 工作流，与上游 `lecture-to-notes` 的 LaTeX/PDF 输出并行存在；上游 skill 完全不动。触发词：markdown 笔记、md 笔记、视频转 markdown、Markdown 讲义、不要 LaTeX、不要 PDF、纯文本笔记。

Lecture to Notes (Markdown)

把课堂视频（本地或 B 站/YouTube）、文字稿、课件三者（任意组合）整理成一份详细的中文 Markdown 课堂笔记，输出按课程标题命名的 `{title_name}.md`（首行为 `# 文档标题`）+ 相对路径图片。**作为上游 `lecture-to-notes` LaTeX/PDF 流的 Markdown 平行方案；本 skill 与上游 skill 完全独立，不修改也不依赖上游 skill 的脚本。**

> **子代理分工**：素材获取（下载/ASR/抽帧/课件转 PNG）委派 **S0** 子代理并行做；主代理通读文字稿定死一级标题结构后，切素材（文字稿切片 / 帧按时段分目录 / 课件标页码）委派 **S1** 子代理做；然后每个撰写子代理领 1–3 个 H1 并行撰写 → 主代理汇总 → **对照文字稿重排目录结构**（只改标题、不动正文）→ 交付。 > 切分与素材委派见 [`references/splitting.md`](references/splitting.md)，派发与汇总见 [`references/subagent-workflow.md`](references/subagent-workflow.md)，结构重排见 [`references/structure-reorder.md`](references/structure-reorder.md)。

与 LaTeX 版的区别

| | lecture-to-notes (LaTeX) | 本 skill (Markdown) | | ----- | ------------------------ | --------------------- | | 输出 | `.tex` + PDF | `{title_name}.md` + 图片 | | 抽帧 | 每 15s（按章节） | 严格每 5s | | 配图 | 全帧 + contact sheet 人工选 | LLM 多模态按 `###` 标题自动选图 | | 配图优先级 | 视频帧 | 课件截图 > 视频帧 | | 编译 | xelatex | 无需编译 |

子技能（asr 与云端转写）

本 skill 包内自带两个 ASR 子 skill，**默认走本地 ASR（见下「ASR 选型」一节）**：

| 子 skill 路径 | 何时用 | | ---------------------------------------- | -------------------------------------------------------------------- | | [`local-asr/`](../local-asr/SKILL.md) | **默认**。无字幕时全文转写 / 短片段核验。已在 **macOS Apple Silicon**、**Linux ARM64**（CPU）与 **Windows**（PowerShell 5.1，CPU）端到端跑通。 | | [`volcengine-asr/`](../volcengine-asr/SKILL.md) | 备用。火山引擎豆包 BigASR / 豆包 2.0，需要 APP ID + Token；长音频首选异步模式 |

调用约定见各子 skill 的 SKILL.md，本 SKILL.md 不重复列参数。

ASR 选型

• **首选 `local-asr/`**（sherpa-onnx X-ASR，跨平台路径齐备，int8 量化 + Apple Silicon AMX 矩阵加速 ~100× 实时）；调用时默认带 `--timestamps`，以保留字幕时间轴。
• 若用户已自带文字稿（火山引擎豆包、飞书妙记等），**跳过 ASR**，直接走 Phase 1 的文字稿核验。
• 火山引擎走 `volcengine-asr/`，把产出的 `transcript.txt` 当作 S0-a 的产物继续。

Dependencies

跨平台检查命令是否就位，缺则按平台提示用户安装（具体安装命令见各子 skill 的 setup 脚本）：

| 平台 | 检查命令 | 备注 | | ------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- | | macOS / Linux shell | `which <cmd>` 或 `command -v <cmd>` | 沙箱 PATH 可能不含 `/opt/homebrew/bin`（macOS）/ `/usr/local/bin`（Linux），见「已知坑」#1 | | Windows PowerShell 5.1 / cmd | `where.exe <cmd>` | **`which` 不是 Windows 内建命令**，PowerShell 5.1 也没有该 alias；只有装了 Git for Windows / msys2 时才会有 `which.exe`（实测）。Windows 沙箱 PATH 可能不含 winget links / scoop shims / Chocolatey bin，见「已知坑」#1 |

最简做法：跑 `local-asr/scripts/common.py::require("<cmd>")`，它内部已经做了 `shutil.which` 兜底 + 按平台补齐常见 bin 目录（macOS `/opt/homebrew/bin`、Windows `winget links` / `%ProgramFiles%\ffmpeg\bin` / `~\scoop\shims` / `%ProgramData%\chocolatey\bin` 等），并返回**绝对路径**，避免子进程再吃 PATH 的亏。

| 工具 | 必需 | 用途 | | ----------------------- | -- | ------------------------------------------------------------- | | `yt-dlp` | ✓ | 视频/字幕/元数据下载（YouTube + Bilibili） | | `ffmpeg` | ✓ | 5s 抽帧、音频提取（`ffprobe` 随 ffmpeg 一起装，Phase 4 判时长要用） | | `python3` | ✓ | `clean_subs.py` | | `pdftoppm` | △ | 课件 PDF → PNG | | `soffice` (LibreOffice) | △ | 课件 PPT/PPTX → PDF | | `local-asr/` | △ | 无字幕时全文转写 / 前 1min 核验；默认加 `--timestamps` 出 srt/vtt 时间戳 | | `volcengine-asr/` | △ | 调用火山引擎豆包 ASR（需要凭据） | | `sherpa-onnx` (pip 包) | △ | `local-asr/` 后端依赖，首次跑 `bash ../local-asr/scripts/setup.sh` 自动装 |

已知坑（务必遵守）

1. **PATH 兜底**：沙箱 PATH 可能丢以下常用 bin 目录——macOS `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`；Linux `/usr/local/bin`、`~/.local/bin`、`/snap/bin`；Windows `%LOCALAPPDATA%\Microsoft\WinGet\Links`、`%ProgramFiles%\ffmpeg\bin`、`~\scoop\shims`、`~\scoop\apps\<app>\current\bin`、`%ProgramData%\chocolatey\bin`。`yt-dlp`/`ffmpeg`/`pdftoppm`/`soffice` 一律用绝对路径，或先 `require()` 兜底（参考 `../local-asr/scripts/common.py::require`，Python 脚本首选；它内部已按平台列好候选目录）。 2. **帧序号 → 时间戳**：`verify_figures.py`（LaTeX 版脚本）硬编码 `×15`，本 skill 不复用该脚本。**不要硬编码 `帧时间 = (帧序号-1)×5`**——`fps=1/5` 的首帧可能不落在 0s、末尾帧可能被被丢、起始 PTS/掉帧都会让算术失真（实测 12s 片段只出 2 帧而非 3 帧）。帧时间一律由 ffmpeg 的 `showinfo` 记录真实 `pts_time`（见 Phase 1 的 S0-b）。 3. **ASR 时间戳选型**：`local-asr/` 默认 sherpa-onnx X-ASR 模型直接产出 token 级时间戳（transducer 模型自带）。S0-a 调用默认带 `--timestamps`（`transcribe.py --timestamps`，会写 srt/vtt）；只有用户明确只要纯文本时才省略。若是已有稿子想补时间戳，跑一次 `transcribe.py 音频 --timestamps`，把生成的 srt 时间轴对齐到原文即可（sherpa-onnx 不需要独立的 ForcedAligner 模型）。

平台识别

| 匹配 | 平台 | | --------------------------------- | -------- | | `youtube.com`, `youtu.be` | YouTube | | `bilibili.com/video/BV`, `b23.tv` | Bilibili |

B 站分 P（多 part）视频：先用 `yt-dlp --flat-playlist --dump-json "<URL>"` 列出所有 part，**先问用户处理哪几 P** 再下载。

输入矩阵（视频 × 文字稿 × 课件）

| 视频 | 文字稿 | 课件 | 处理动作 | | :-: | :-: | :-: | -------------------------------------------- | | ✓ | ✗ | ✗ | 取视频 → 先试官方字幕（CC→自动字幕），兜底 `local-asr/` → 5s 抽帧配图 | | ✓ | ✓ | ✗ | 核验文字稿 → 5s 抽帧配图 | | ✓ | ✗ | ✓ | 取视频 → 先试官方字幕，兜底 `local-asr/` → 课件截图优先 + 5s 抽帧（都要做） | | ✓ | ✓