mairp/video-to-deck

视频转幻灯片

从视频制作演示文稿。你（模型）是纯文本的——你无法听到音频或看到画面。因此本技能的脚本负责“看”和“听”，并为你提供一个文本证据包（evidence.md）。你的任务仅仅是综合：阅读证据并写出好的幻灯片。不要捏造证据未支持的任何内容。

输出是 Marp markdown（deck.md）：一个你现在就能阅读的普通 .md 文件，之后通过执行 render.sh 命令即可生成真正的幻灯片（PPTX/PDF/HTML）。

$SKILL 以下表示本技能的目录（即包含此文件的文件夹）。

流程

1. 一次性设置（幂等）

bash "$SKILL/scripts/setup.sh"

安装 faster-whisper（语音转文字）、tesseract（OCR），以及——如果存在 npm——marp-cli 和 mermaid-cli。可以安全地重复运行。ffmpeg 必须已经安装。

2. 查找视频

bash "$SKILL/scripts/find_videos.sh" "<文件夹>"        # 每行一个路径，递归查找

如果是单个指定文件，请跳过此步，直接使用路径。

3. 为每个视频构建证据包（逐个进行）

bash "$SKILL/scripts/process_video.sh" "<视频>" "<输出目录>/<视频文件名主干>"

此脚本：提取音频 → 转写为文字，采样关键帧 → 对屏幕文字进行 OCR，并写入 <输出目录>/<视频文件名主干>/evidence.md（以及 transcript.txt、segments.tsv、frames/、ocr.txt）。在 CPU 上处理长视频较慢；为获得质量，请设置 WHISPER_MODEL=small，或使用 CUDA GPU 加速（自动检测；参见 scripts/transcribe.py 中的 WHISPER_DEVICE）。请顺序处理视频，不要并行。

可选的视觉通行（Qwen-VL）。 OCR 只能读取文字。为了同时捕捉文字无法表达的内容——图表及其趋势、示意图、用户界面布局、演讲者的手势——可以启用一个视觉模型，为每个保留的关键帧添加描述。此功能默认关闭；通过在环境变量中设置 VISION_MODEL（以及（如果需要）VISION_ENDPOINT）来打开它，与同一命令一起执行：

VISION_MODEL=qwen2.5-vl \
VISION_ENDPOINT=http://127.0.0.1:8081/v1/chat/completions \
  bash "$SKILL/scripts/process_video.sh" "<视频>" "<输出目录>/<视频文件名主干>"

启用后，evidence.md 会在 OCR 的基础上增加一个 “## 视觉描述” 小节——用于图表/示意图幻灯片。任何兼容 OpenAI 的视觉端点均可使用（llama-swap 配合本地服务器如 llama.cpp/llama-swap 或 Ollama，或托管的 API；如果需要令牌，则设置 VISION_API_KEY）。如果端点不可达，运行会继续仅使用 OCR——不会出现错误。

4. 编写幻灯片

阅读整个 evidence.md。将 "$SKILL/templates/deck.marp.md" 复制到 <输出目录>/<视频文件名主干>/deck.md 并填写。规则：

• 保留 marp: true 的 frontmatter ——这是使其成为幻灯片的关键。
• 对于所说的内容使用转录；对于幻灯片上显示的精确标签、数字、标题和代码，使用 OCR/屏幕文字；如果存在 “视觉描述” 小节（启用了视觉通行），请为 OCR 无法传达的图表/示意图/用户界面使用它。
• 在有用时为声明打上时间戳：[00:04:12]。
• 将幻灯片的关键帧放在幻灯片上——这是默认操作，不是可选的装饰。 ocr.txt 中的每个 ### [时间范围] frames/kf_####.jpg 块都指定了该幻灯片的代表性帧；将其引入到幻灯片中：![](frames/kf_0007.jpg)。关键帧是该幻灯片的证据，它展示了项目符号只能描述的图表/示意图/用户界面，并使幻灯片镜像源演示文稿。仅在幻灯片是您用 Mermaid 重新绘制的纯图表幻灯片，或关键帧没有视觉信号（说话者头部、空白过渡）时才省略它。当一张源幻灯片对应两张输出幻灯片时，使用来自该次运行的两个不同帧，而不是重复同一个帧。
• 只包含证据支持的内容。如果转录和 OCR 都为空，则说明该视频没有可提取的内容，不要编造幻灯片。

密度——幻灯片必须合并证据，而不是概括掉它。 最常见的失败是浅薄的幻灯片：20 张幻灯片，每个只有四个字的项目符号，丢弃了视频实际包含的大部分内容。证据包的构建成本很高；幻灯片是供人阅读的。

• 每张源幻灯片对应一张输出幻灯片。 OCR 部分中的每个 ### [时间范围] frames/… 块都是视频中的一张真实幻灯片——该列表是您的清单，大致决定了您的幻灯片数量。不要将三张源幻灯片合并成一个项目符号。一次 40 分钟的演讲通常有 30-45 张幻灯片。
• 将具体信息带到幻灯片上。 证据中存在的每个数字、指标、阈值、百分比、产品名称、CRD、配置键和标签都应出现在幻灯片上。如果源幻灯片有六个项目符号和四个统计数据，那么您的幻灯片应该有六个项目符号和四个统计数据——而不是“提高了准确性”。
• 项目符号应该是一整行（约 15-20 个词），而不是四个词。 每张 5-8 个是正常的。只有当源幻灯片本身简洁时，才使用简洁的表达。
• 当源内容是表格形式时，请使用表格——路由矩阵、基准网格、级别定义、优先级规则。重现每一行和每一列，而不是抽样。
• 演讲者注释是补充性的，用于那些在演讲中说过但不在幻灯片上的内容：注意事项、经验故事、“为什么”、问答细节。它们不是用来隐藏本应放在幻灯片上的内容的。
• 完成前进行覆盖检查。 按顺序浏览 ocr.txt 中的 ### [..] 块，并确认每个块都已呈现。如果您跳过了某个块，要么它是前一张幻灯片的副本/动画，要么是一个演示帧——您必须能够说出是哪种情况。

5. 图表通行（“这可以画成图表吗？”检查）

对于每个主题，问：这是结构性的（组件+连接、参与者交互、流程、状态+转换、实体+关系）吗？如果是，则将其绘制为 Mermaid（默认）或 PlantUML 图表，放在其自己的幻灯片上而不是项目符号。请参考 "$SKILL/references/diagrams-cheatsheet.md" 查看内容→类型决策表和可复制粘贴的骨架。不要强行绘制图表如果内容只是叙述性的。

6.（可选）导出真正的幻灯片

bash "$SKILL/scripts/render.sh" "<输出目录>/<视频文件名主干>/deck.md" pptx   # 或 pdf | html | all

此脚本先将图表块预渲染为图片，然后生成 PPTX/PDF。如果没有安装 marp/mermaid，幻灯片将保持为 .md 格式（仍然有效且可查看）。

对于一次性处理整个树，请改为在批量驱动程序（下方）中添加 --pdf，而不是对每个幻灯片单独调用 render.sh。

批量处理/嵌套文件夹

对于整个文件夹——特别是嵌套课程树——推荐使用 scripts/drive_decks.sh <根目录>：它在 Bash 中循环，并为每个视频启动一个独立的智能体（永远不会超出模型的上下文窗口），并将源子文件夹结构镜像到输出中，从而保留父子层级。然后使用 scripts/rename_by_topic.sh <幻灯片目录> 根据每个叶子节点在其课程文件夹内的主题进行 slug 化。添加 --pdf 以便在编写完成后将每个幻灯片导出为 PDF——Mermaid 被预渲染为图像，并且叶子文件夹被折叠，因此每个 PDF 都位于其父文件夹中（<输出>/课程A/lesson/deck.md → <输出>/课程A/lesson.pdf），避免了每个 PDF 一个子文件夹。要从上次运行产生的扁平幻灯片重新构建层次结构，请使用 scripts/regroup_by_source.sh <幻灯片目录>——它读取每个 evidence.md 的 Source: 行，将每个幻灯片放置在其课程父文件夹下（重复项隔离到 _duplicates/ 中），然后运行重命名。有关完整的批量处理指南，请参见 README.md。

参考资料

• references/marp-cheatsheet.md — Marp 幻灯片语法（分隔符、图片、注释、分栏）。
• references/diagrams-cheatsheet.md — 何时绘制图表以及每种类型的语法。

备注

• OCR 能很好地捕捉录屏/幻灯片视频中的屏幕文字。对于实拍镜头，转录承载了大部分信息——依赖它，不要对视觉效果过度声称。
• 转录、OCR 和渲染始终在本地进行。编写步骤是否离开机器完全取决于您为 --agent-cmd 指定的智能体。
• 该设计是模型无关的：任何能够运行 Bash 和读取文件的文本智能体都可以使用本技能。