Motion Diorama — 教育视频制作技能

Motion Diorama — 教育视频制作技能 (v3.0 · 公开版)

核心原则：先检查，再渲染，而不是事后检查。 所有能够廉价检查的内容（时间线、静止帧、文本宽度）必须先通过检查。 全分辨率渲染只做一次，在最后阶段，所有门控都为绿灯后。

此文件是核心。每个模式的视觉细节在 references/ 目录下。 — mode-a.md 用于 A 模式，mode-b.md 用于 B 模式，mode-c.md 用于 C 模式（必须根据本视频对应的模式阅读相应的文件，然后才开始构建场景）。测试脚本在 evals/evals.md 中。scripts/ 目录下的脚本必须照原样执行——不要重写其功能。

锁定决策（由技能创建者制定——不可擅自更改；如果你使用此技能并进行更改，请有意识地更改）

• 三种活动模式：A 模式（景观/历史 + 活地图变体）、B 模式（拆解物体——物体/机器工作原理）和 C 模式（解剖学——人体系列）。用户在开始提示时为每个视频选择模式；会话在进入第 2 阶段之前会读取该模式的参考文件。
• 目标：建立观众群。 默认结尾 = 结论（A 模式）/ 回调（C 模式）+ 渐隐至黑屏。视频内没有系列卡片/标签，屏幕上没有阶段印记/位置指示器（用户于 2026 年 11 月 13 日决定，v2.8）——系列身份仅存在于字幕中。价值呼吁仅偶尔使用，当主题合适且用户为该视频特别要求时——并非必需元素。禁止销售性行为召唤（CTA）。
• 数字/数据 = 混合模式：屏幕读出（DOM 覆盖层）是所有数字的主要系统。例外：每个视频在场景内最多允许一个金色3D英雄数字，仅用于该视频的峰值数字——并且该数字必须同时作为读出/字幕显示，因为 3D 版本是视觉强调，而非信息载体。
• 最终时长 30-60 秒，跟随音频。
• 音频：此技能对音频不可知——使用用户提供的任何 MP3 叙述，放在 public/narasi.mp3。
• 音乐：用户提供的文件放在 public/musik.*——不要为用户选择音乐。
• 事实：用户的来源是主要参考，当有冲突时以用户来源为准。会话可以通过网络研究补充信息，条件是：最终报告中必须注明来源，优先使用权威来源（期刊、机构、官方），未经验证的声明必须标记为不确定——禁止将猜测当作事实呈现。
• 单一操作员：一个人。所有结果必须作为文件显示在会话中（静止帧、预览、最终输出），以便下载。
• 目标节奏：每天 1-2 个视频。效率是设计的要求——重用脚手架、基元和组件；不要重复构建已有的东西。
• 门控——直通模式是公开版的默认模式： 会话不会停下来等待用户批准。门控 1（时间线摘要）和门控 2（静止帧联系表）内部执行：会话根据此技能的书面标准（验证器通过 + QC 检查清单）自行评估其阶段结果，自行修复发现的问题（每个场景最多 2 次修复尝试），然后继续。决策遵循提示中的决策块（默认：过长的叙述使用 atempo 加速，最多 1.25 倍；未验证的事实标记在报告中）。该块未回答的问题将在构建开始前一次性在一个消息中提出——禁止中途提问。会话仅可因硬性障碍而暂停：(a) 素材缺失或损坏，(b) 无法生成转录，(c) 在最大 atempo 后叙述仍超出 30-60 秒范围。如果提示声明“直通模式：不”，则应用经典门控——两次用户批准（在第 1 阶段后和第 3 阶段后），并配有基于证据的门控 2 宽松阶梯：连续 3 次干净通过 → 每个场景 1 个静止帧；再 3 次 → 对已验证的场景类型可选；门控 1 从不放松；一次重大视觉修改会恢复完整格式；每次宽松都会记录在最终报告中。

硬性禁止

• 禁止使用 AI 图像/照片/2D/精灵/外部纹理/下载模型作为场景。所有视觉效果 = Three.js 程序化 3D 几何体。
• 禁止使用信箱模式（Letterbox）；原生 9:16 摄像机。
• 运动仅来自 3D 空间中的摄像机（真实视差）。禁止通过 2D 图像的缩放/平移模拟运动。
• 人类仅以深色小剪影呈现，无面部。A 模式中主要主体不是特写（景观英雄动物/物体的摄像机最小距离为 8 米）——在 C 模式中此距离规则不适用：英雄器官确实填满画面；在 B 模式中此规则仅约束上下文帧的构图——实验室阶段的英雄物体确实填满画面（参见 references/mode-b.md 和 references/mode-c.md）。
• 所有场景使用一个渲染器、一组材质、一个灯光结构。
• 禁止根据单词数/故事板猜测时长。时间仅来自原始音频（参见时间部分）。
• 禁止使用 useFrame()、Math.random()、Date.now() 或帧累积进行动画——所有运动均来自 useCurrentFrame() 和固定种子的随机常数。

时间线——timeline.json 是唯一的真实来源

1. 确保 public/narasi.mp3 存在。如果不存在：停止，通知用户。在音频可用之前，不要确定任何时间。
2. 使用以下层级获取每个单词的时间戳： a. 内置的 TTS 时间戳（例如 ElevenLabs 带时间戳的输出），如果用户提供的话——最准确。 b. 回退到 Whisper：仅使用大模型，强制 language="id"（不要自动检测），并且 Whisper 仅提供时间——句子文本必须来自用户的官方脚本，而不是转录结果（印尼语 ASR 在数字和名称上容易出错）。
3. 按照以下确切模式组织 docs/timeline.json：

{
  "fps": 30,
  "audio_duration_s": 40.20,
  "total_duration_s": 41.00,
  "sentences": [
    {"id": 1, "text": "…", "start_s": 0.00, "end_s": 3.68, "scene": 1}
  ],
  "scenes": [
    {"id": 1, "sentence_ids": [1, 2], "start_s": 0.00, "end_s": 6.44}
  ]
}

4. 映射规则：场景边界 = 下一个场景第一个句子的开始秒数；映射基于句子内容——禁止为了填充时长而分组句子；实际片段与时间线的差异 ≤ 0.3 秒。
5. 运行 python3 scripts/validate_timeline.py docs/timeline.json。如果失败：修复时间线，重复。失败时禁止继续。
6. 整理时间线摘要（句子数、场景映射、总时长）并根据这些标准自我评估——这是门控 1。直通模式：不要停止；保存摘要用于最终报告。经典门控模式：显示给用户并等待批准。
7. total_duration_s 必须在 30-60 秒之间。超出此范围：直通模式——应用提示策略（过长的使用 atempo 最多 1.25 倍；过短的拉伸结束停顿）并记录在报告中；如果仍超出范围，则为硬性障碍：停止并报告。经典模式：报告给用户——不要悄然剪切或修补。 禁止无故静默；结尾允许 0.3-1 秒的回报停顿，并计入总时长。

样式锁定（摘要——每个模式的细节请参考 references/ 目录）

A 模式（详情见 references/mode-a.md）

• 风格化的半写实 3D 立体模型：温暖电影调色板，一个固定的黄昏灯光结构，干净光滑的表面，简化的背景。调色板可根据主题/季节调整；灯光结构和材质不可调整。
• 主题标题：在移动的定场镜头上方使用大写衬线字体。钩子 = 叙述的第一句话（问题/辟谣/悖论），在头 ±1.5 秒内以文本 + 声音 + 视觉形式出现。
• 字幕：每页 2-4 个单词的逐词卡拉OK（非单个单词），活动单词清晰，关键词用强调颜色，位于底部安全区域。
• 数据读出：动画计数器，在叙述说出数字时精确计数 + 小标签 + 指示线；后续读出样式相同。允许显示的唯一 3D 文本：一个用于峰值数字的金色英雄数字（参见锁定决策）。
• 摄像机：段内连续移动；作为论据结构的缩放层级；仅事实段之间硬切换，形式为 ±0.1 秒的黑色渐隐。
• 叙述结构：对于系统/流程主题使用“单流跟随”；一个视频可包含同一主题的两个事实，带演示段落。
• 结尾：美感镜头 + 重复的衬线标题/时代 + 结论句。渐隐至黑屏；视频内无系列标签/卡片（v2.8）。（仅当为该视频要求时才使用价值呼吁。）

B 模式——拆解物体（详情见 references/mode-b.md）

• 两个世界阶段：A 模式风格的温暖上下文立体模型（物体完整出现在其环境中）→ 深色技术网格背景的实验室阶段，物体在此被拆解；通过连续缩放过渡（背景淡出/虹膜状），无硬切换。
• 一个程序化的英雄物体模型构建一次；分解图和剖面图从同一模型派生。
• 没有标题卡片（钩子 = 上下文镜头中叙述的第一句话），没有永久 HUD——面包屑、缩放计数器和参考小地图已取消（研究决策 + v2.8 方向）。导航通过连续摄像机、引线标签和短暂阶段标题进行。
• 标准阶段：上下文 → 缩放 + 物体标签 → 拆解（双语 ID + EN 术语的部分标签，按叙述顺序出现）→ 剖面（动画过程 + 过程读出）→ 运作时（剖面运行，单流跟随，过程标签，语义颜色编码的流微粒）→ 决定性机制宏观 → 摄像机拉出时的一行原则标签回报。
• B 模式结尾：结论/原则句 + 渐隐至黑屏；无系列卡片/标签（v2.8）。

C 模式——解剖学（详情见 references/mode-c.md）

• 不是立体模型：一个光泽的 3D 英雄器官悬浮在深紫色虚化虚空中；一个器官模型构建一次，用于所有场景。默认系列名称示例：“人体系列”（替换为你的系列名称）。
• 流颜色代码绝对： 蓝色 = 缺氧，亮红色 = 富氧——在视频内或系列视频间从不颠倒。细胞微粒在交换点改变颜色，恰好在其句子处。
• 必须使用单流跟随结构：摄像机引导一个包通过整个回路；缩放层级为器官 → 系统 → 微观 → 器官 → 完整身体（剪影）。
• 钩子 = 观众实时参考 + 从第一秒开始与器官视觉节拍同步的实时计数器。衬线标题延迟到 ±5-8 秒（钩子之后），然后跟随事实注释。
• 没有阶段印记，没有 HUD（v2.8）：流动位置从摄像机移动读取；解剖标签芯片附着在器官上，在其部分激活时亮起。
• C 模式结尾：动画 finale 计数器 + 反映钩子的回调句；渐隐至黑屏；无系列卡片/标签（v2.8）。禁止使用血腥/图形医学写实。

文本规则（防裁剪——导致修订的第一原因）

• 所有必须阅读的文本都是 DOM 覆盖层（Remotion 组件），不是 WebGL 画布内的文本。唯一例外：锁定决策中的混合 3D 英雄数字——其他 3D 文本禁止。
• 在字体加载后，使用 @remotion/layout-utils 的 measureText/fitText 测量每个文本；fontSize = min(模式限制, 适配结果)；最大宽度为帧宽的 90%；所有边留 5% 安全边距；尊重平台安全区域（重要文本避开顶部 ±250px 和底部 ±310px）。
• 如果文本在可读性底线上无法容纳：拆分成两页/行——禁止缩小到无法阅读，禁止让其被裁剪。
• 对比度：亮背景上的亮文本必须使用深色轮廓/阴影。
• 引线标签遵循相同规则。

音频

• 叙述是主时钟：所有场景边界、字幕、计数器、摄像机都读取 docs/timeline.json——没有第二个定时源。
• 用户提供的音乐文件作为背景放置在叙述下方（简单闪避；不要掩盖词语）。如果没有用户提供的音乐文件：不要编造音乐——通知用户。
• 最终音频标准化至 -14 LUFS，峰值 ≤ -1 dB。

制作流程（顺序不可跳过）

• 第 0 阶段——脚手架： 使用现有项目脚手架；渲染器、摄像机结构、样式锁定和基元不重写。如果仓库尚未包含 Remotion 项目（第一次生产）：从技能包仓库的 starter/ 文件夹构建脚手架（依赖版本精确到已验证可运行的版本），然后将其视为现有脚手架。
• 第 1 阶段——时间线： 遵循时间线部分 → 验证器通过 → 门控 1（直通模式内部；经典模式需用户批准）。
• 第 2 阶段——构建场景 读取 timeline.json 和本视频模式的参考文件（references/mode-a.md、references/mode-b.md 或 references/mode-c.md）。
• 第 3 阶段——静止帧门控： 为每个场景渲染 3 个静止帧（场景开始/中间/结束）+ 联系表。直通模式：对照本模式的 QC 检查清单评估联系表，在静止帧阶段修复发现的问题（每个场景最多 2 次尝试），然后继续——不要等待用户；保存联系表和评估清单用于最终报告。经典模式：显示并等待用户批准。在静止帧阶段修复——比在视频中修复便宜得多。
• 第 4 阶段——预览 + 自主 QC： 渲染 0.5 倍缩放预览，对自己的输出进行 QC，修复所有发现的问题（仅重新渲染更改的场景），然后再报告。
• 第 5 阶段——最终输出： 全分辨率渲染一次；运行 bash scripts/check_output.sh out/<slug>-final.mp4；在会话中显示文件 + QC 报告。

快速渲染（锁定流水线）

• 逐场景渲染： out/scenes/scene-N.mp4；使用 FFmpeg concat -c copy 合并（场景间的编解码器/分辨率/帧率参数必须相同，否则组合会损坏）。
• --concurrency = 会话的 CPU 核心数（检查 nproc），不要使用默认值。
• 预览始终使用 --scale=0.5；全分辨率 1080×1920 仅在第 5 阶段使用。
• 保持每帧成本低：使用基本几何体，实例化用于重复元素。