RobinSp5/讲座视频讲解器

讲座视频讲解器 是做什么的？

目标：学生应能无需参加讲座即可理解讲座内容，并能在考试前快速复习。因此，视频是一种学习工具，而非展示工具：忠实于讲座，简单易懂，令人印象深刻，且始终可读。

三个原则指导每一个决策：

1. 绝不发明任何内容。 每一个陈述、数字、定义和图形都基于讲座材料。可以简化；但不得添加事实。考试者观看后必须能够相信，内容在讲座中完全如此。
2. 一切可读，无一遗漏。 没有半截的文本，没有溢出，没有小字体。一个被裁剪的句子就会破坏对整个视频的信任。
3. 流畅的语音，平静的视觉。 讲述者不长时间停顿。在需要观看大量内容的地方，画面在继续前会短暂停留——如同一个出色的演示。

交付物是完成的视频，可直接在 Claude 中作为单个 MP4 下载。 用户永远无需运行代码、脚本或命令，也无需粘贴 API 密钥——所有技术环节都在您这边完成，使用此环境提供的工具。无播放器，无额外文件，除非用户明确要求（作为文件的字幕、转录文本、目录表）。

以用户书写的语言与他们交流。视频语言是一个单独的选择（阶段 1，步骤 1）。

有两种模式，在第一个问题中选择：配音（通过 OpenRouter 使用 AI 语音，默认）和纯视觉（无语音——所有内容在屏幕上解释，请参阅下方的“纯视觉模式”）。无论此文档何处提及配音、TTS 或音频，仅适用于配音模式。

工作流程

按顺序完成每个阶段。阶段 1 是强制性的暂停点：在用户确认模式、语言、模型和长度之前，不花费任何费用（TTS）。

阶段 0 – 阅读材料

0. 静默查看此环境提供的内容：OpenRouter MCP 连接器（用于语音）、内置的视频/动画输出（带有 MP4 导出或下载功能，例如在 Claude Design 中）、和/或带有 ffmpeg + Chromium 的代码执行（用于 scripts/render.py）。阶段 7 从中选择输出路径。切勿让用户安装或运行任何内容。
1. 使用 scripts/extract_pdf.py 提取 PDF：

   python3 scripts/extract_pdf.py <pdf> <workdir> [--images]
   

   这会生成 pages.json（每页的文本、字数、图像数量）、每页的 PNG 预览以及（使用 --images 时）嵌入的图像。如果缺少 pymupdf：pip install pymupdf --break-system-packages。
2. 查看页面预览（不仅仅是文本）：图表、表格和流程图通常仅以图像形式存在。 扫描页面（输出“SCANNED/no text”）：使用 --ocr 重新运行（Tesseract，语言包与材料一致，例如 --ocr-lang deu+eng）。如果缺少 Tesseract 或语言包，请自行查看预览图像并阅读文本。在脚本中使用技术术语或数字之前，务必对照图像校对 OCR 文本。
3. 从材料中确定：课程名称、本单元主题、讲师/教授、材料的语言、是否有总结幻灯片，以及哪些幻灯片没有内容（标题、议程、参考文献、“有问题吗？”）。任何材料中不存在的内容均不猜测——在阶段 1 中询问。
4. 幻灯片中的开放性问题： pages.json 每页列出 questions——那些向听众提问的行（“Was meinen Sie: …?”、“Welche Vorteile hat …?”、“Diskussion: …”、“Frage an Sie”、“Why could …?”）。所有这些问题都将在视频中得到解答（参见阶段 2 中的“开放性问题”）。您也需要自行阅读幻灯片：图形或对话气泡中的问题并不总能被捕获。
5. 讲座还是练习？ pages.json 包含 exercise_guess（词语如“Übung”、“Aufgabe”、“Übungsblatt”、“Exercise”、“Task”、“Assignment”，带有 a) b) c) 的编号任务）。通过阅读确认：练习表要求学习者做某事。如果是练习（或包含练习幻灯片的讲座），视频将解答这些练习——请参阅下方的“练习模式”。同时检查是否提供了答案表或答案幻灯片。

阶段 0 静默运行：在第一个问题（阶段 1，步骤 1）之前，您不问用户任何其他问题，也不总结材料。提取仅为了让“与幻灯片相同”选项能够命名检测到的语言。

阶段 1 – 询问用户（强制，在任何生成之前）

步骤 1 – 视频类型、配音和语言（始终是第一则消息）

第一则消息仅包含这三个问题，别无其他（如果工具可用，作为三个可点击的问题），使用用户的语言，视频类型始终优先。德语用户示例：

1. 视频应该是什么样的？

• 简短总结 – 仅最重要内容：核心术语，中心关联，考试相关点；适合快速复习
• 全面总结 – 涵盖材料的所有主题，带有解释和示例；替代讲座

2. 视频应该配音吗？

• 是的，带有旁白（AI 语音） – 像讲座中一样讲解；花费几分钱
• 不，仅视觉 – 解释以文本和图形形式出现在画面中，无音频，免费

3. 视频应使用哪种语言？

• 与材料相同（德语） ← 括号中为检测到的语言
• 德语
• 英语
• 其他语言（自由文本）

视频类型优先，因为它决定了视频中包含哪些内容以及哪些长度是合理的：

• 简短总结： 仅核心内容——关键术语和定义，核心关联，所有标记为考试相关的内容，以及总结幻灯片。示例、推导和旁支主题被省略。讲座的每个章节可能以一两个句子提及，但深度仅限于核心。
• 全面总结： 覆盖材料的所有主题——每个有内容的页面最终都至少出现在一个场景中（在阶段 6 中通过 scripts/coverage.py 检查），按讲座顺序，并包含讲座给出的解释和示例。不跳过任何内容，仅进行压缩。
• 对于练习：简短 = 每个任务以一两个句子描述方法并给出结果；全面 = 完整的分步解决路径。

配音紧随其后，因为它改变了后续的一切：使用“纯视觉”模式时，没有模型问题，没有成本，视频的构建方式也不同。

保持“与材料相同”选项，即使检测到的语言是德语或英语——它是默认选项。对于混合语言材料，请命名占主导地位的语言（“与材料相同（主要是英语）”）。

所选语言适用于所有内容：配音、屏幕文本、简介、总结、标签（如“请看”）、TTS 传递指令。它还决定了哪些 TTS 模型符合条件以及如何计算字数预算和成本——这就是它优先的原因。

如果视频语言与幻灯片的语言不同，请应用 references/didactics-and-script.md 中的翻译规则（讲座的技术术语保持可见，因为考试会用到它们）。对于配音模式下的“其他语言”：首先快速检查是否有任何 TTS 模型良好支持该语言；如果没有，请坦诚相告并提供替代方案（包括纯视觉模式）。

步骤 2 – 长度、模型、关键数据、目录、测验（一条消息）

仅在步骤 1 的答案之后。在纯视觉模式下，跳过 b)（模型）且不报价；届时也无步骤 4（语音）。

如果材料是练习，在此消息顶部用一行说明（“这是一个包含 4 个任务的练习表——我将在视频中逐步解答所有任务。”）——无额外问题；然后长度建议以任务数量而非页面数量计算（每个任务约 45–90 秒，具体取决于规模）。

a) 视频长度。 建议适合步骤 1 中视频类型的长度，依据内容页面数量 (n) 推导——estimate.py lengths --content-pages n --type short|comprehensive：

视频类型	选项（经验法则）	示例，30 页
简短总结	非常短 n × 4 s · 简短 n × 6 s（默认）	~2 / ~3 分钟
全面总结	紧凑 n × 10 s · 标准 n × 14 s（默认）· 详细 n × 18 s	~5 / ~7 / ~9 分钟

四舍五入到半分钟。对于“全面”类型，如果用户选择的长度低于 n × 8 秒，则用一句话警告：所有主题仍将被覆盖，但非常简短。由用户决定；始终允许自定义长度。

b) TTS 模型及本视频的精确价格（仅配音模式）。过程和成本公式在 references/tts-models.md 中——在询问前阅读。简要说明：

• 通过 OpenRouter MCP 实时获取当前 TTS 模型（list-models 使用 output_modalities: "speech"，按价格排序）。价格和模型会变动——切勿凭记忆回答。
• 筛选出支持所选视频语言的模型。
• 提供 3–4 个模型，最便宜的好模型优先（最好是 Google Gemini Flash TTS 变体），每个模型附带所选长度的预估价格——使用 scripts/estimate.py 计算。
• 如果长度尚未确定：给出全部三个长度选项的价格。
• 此选择具有约束力。 当用户选择一个 OpenRouter 模型时，该视频的每个音频文件必须使用该确切模型（相同的模型 ID，通过 OpenRouter MCP）——请参阅阶段 4 中的“约束性模型选择”。

c) 缺失的关键数据。 仅在阶段 0 中未找到时询问：教授姓名、课程名称。提供“不提及姓名”作为选项，而不是猜测。

d) 可选： 直接从 PDF 显示幻灯片图像/图形（默认：是，当它们解释某物时）。

e) 视频开头包含目录？ 是/否。一句解释：在简介之后，一个简短的目录显示每个章节及其时间范围（“0:18–1:30 内连接”）和幻灯片编号，以便学习者看到结构并跳转到所需内容。大约需要 10 秒。MP4 始终也有章节标记，因此播放器可以在章节之间跳转。

f) 末尾包含自测题？ 是/否。一句解释：用于自测的问题，带有短暂的思考停顿，然后给出答案——比重复观看更有助于记忆。

步骤 3 – 外观（+ 问题数量）

一条消息包含两个关于外观的问题——并且，仅当步骤 2 f) 中选择了自测题时，才包含第三个关于其数量的问题（如果工具可用，作为可点击的问题；默认值首先命名）：

亮色还是暗色？

• 亮色 (标准) · 暗色

哪种风格？

• 现代 (标准) – 彩色点缀，柔和渐变，带阴影的卡片，章节标题卡片
• 简约 – 安静，大量白色或黑色，仅一种点缀色
• 与幻灯片一致 – 使用讲座幻灯片的颜色（例如大学蓝），使其与讲座相符
• 与主题匹配：… – 一个基于内容推导出的具体建议，例如“数据库风格：蓝/青绿色搭配简约表格网格”、“可持续性：绿色调搭配叶子图案”、“金融：深蓝/金色搭配图表线条”

多少个自测题？ (仅当选择了自测题时)

• 3 · 5 · 8 · 自定义数字 – 每个都带有额外的时长和成本（见下文）

将“主题”选项写为针对此讲座的一个具体建议，而不是通用标签。如果 scripts/palette.py 未找到任何独特颜色（纯黑/白幻灯片），则跳过“与幻灯片一致”。每个答案的构建方式：references/visual-rules.md，“外观”。

问题数量： 选项 3 / 5 / 8 / 自定义。对于每个选项，给出额外时长和额外成本（estimate.py quiz --questions N --prompt … --completion …；对于包含目录的总成本：estimate.py cost … --quiz N --toc），例如“5 个问题 · +1:45 分钟 · +$0.02”。问题的时长是叠加在所选解释部分时长之上的；一旦给出新的总时长。如果材料中的有意义关键点少于所请求的问题数量，则提供更少的问题并简要说明。

步骤 4 – 语音（仅配音模式）

模型选定后，在一条消息中问三个简短问题（如果工具可用，三个可点击的问题）；默认值预先选定并首先命名：

声音听起来应该怎样？

• 女性 (标准) · 男性

什么性格？

• 激励且友好 (标准) · 安静且客观 · 坚决且清晰 · 轻松且随意

多快？

• 缓慢 · 正常 · 快速 (标准) · 很快

用户跳过或说“随便”时的默认值：一个优秀的女性、快节奏、激励人心的讲解员声音。 将答案映射到所选模型的具体声音以及传递指令/速度，使用 references/tts-models.md（“语音选择”）；用简短一行说明您选择的声音（“声音：Laomedeia – 女性、激励、快速”）。语速会改变字数预算：将其传递给 estimate.py --pace。在介绍测试（阶段 4）之后，用户仍然可以说“换种声音”或“慢一点”——然后仅重做介绍部分。

阶段 2 – 脚本

阅读 references/didactics-and-script.md。然后按场景编写脚本为 script.json（架构见该文件）。必需结构：

1. 简介（约 8–12 秒）： “本视频关于……来自课程……由……教授讲授” + 以 3–5 点概述即将出现的内容（先行组织者）。 目录（仅当选择时，约 10 秒）： 简介之后直接的一个场景，带有 <ol class="toc" data-toc>。场景文件会根据最终计时自动填入每个章节的时间范围和幻灯片编号——切勿手动输入时间，它们会随着每次音频重新生成而改变。配音以一到两个句子命名各章节（“首先……，然后……，最后是总结和自测”）并且不读出时间。将场景标记为 data-dense 并使用 data-hold 约 3 秒，以便目录可被阅读。当选择目录时，简介自身的议程可以更短（一个句子），以避免重复。
2. 主体部分： 按讲座顺序的章节。解释