sourceframe 是做什么的？
一种制作视频的方法，就像构建系统一样：先有需求，然后有一份真实情况的账本，一份布局合同，逐步验证的小步骤，以及在发表意见之前先进行测量。最终产品是一个简短的、无声优先的视频（15 到 90 秒），通过追踪一个核心元素来解释一个机制。其名称就是规则：每一帧都追溯到一个来源。
此技能源自一个真实的构建案例（一个 77 秒的解释性视频，讲解 coreboot 如何在 DRAM 存在之前运行 C 代码，包含一个 4096 单元格的缓存网格、一个 3D 闪存芯片和 DRAM 训练），并在第二个无关的主题（examples/merkle-proof，一个 Merkle 包含证明，其每个哈希值都由构建过程计算）上得到了验证。以下路径均相对于此技能的文件夹。
何时使用，何时不使用
适用于以下场景：工作原理类视频、协议或算法讲解、系统架构导览、“当…时会发生什么”序列、事后复盘。当主题涉及具有变化状态的机制（如比特翻转、指针移动、哈希传播）时，其优势尤为突出。
不适用于以下场景：人物讲解或素材剪辑、产品广告、纯动态品牌宣传、任何内容是基于观点而非机制的视频。对于这些场景，请使用普通的动态图形技能。如果用户只想要静态轮播，请使用轮播技能。
七大原则
- 账本先于像素。 在第一个场景之前，先编写
FACTS.md（声明、证据、状态）。状态V表示本会话中从来源读取的内容，C表示由构建过程计算得到，S表示示意图并已在屏幕上标注，H表示记忆内容（需重新检查），N表示需要来源（阻碍交付）。永远不要凭空捏造数字、符号、路径或版本。首选C：让构建过程计算视频所展示的内容。 - 一个核心元素。 每帧只有一个东西是视觉的锚点：它使用唯一的“焦点”颜色，始终是当前步骤，绝不与另一个元素竞争。其他所有元素都保持低调。
- 颜色即意义。 调色板角色（
data、focus、ok、bad、ink）是语义化的，并针对整个视频固定。永远不要因为好看而选择某种色调。 - 确定性。 一帧是其帧号的纯函数。不使用挂钟时间、
Math.random、CSS 过渡或useFrame。任何伪随机内容都使用种子化的hash(n)。这使并行渲染、静态帧和后续的音频同步成为可能。 - 画面即工具。 动画的存在是为了展示状态变化。每一个运动都要回答“这展示了什么？”。禁止：在每个块上使用相同的淡入效果、弹跳或弹性缓动、循环装饰、为了发光而发光。
- 先测量，后观察。 数字廉价而精确；观点昂贵且主观。进行类型检查、账本检查、探测容器、尽可能测量像素，然后再每轮查看一张联系表。
- 停止规则。 每组场景最多三轮审查，每轮最多三次修复。说明留下了什么以及为何停止。诚实胜过完美：标注未经验证的内容。
十个阶段
每个阶段都有可交付成果和关口。不要为了节省时间而跳过关口：昂贵的错误都出在上游。
| # | 阶段 | 可交付成果 | 关口 |
|---|---|---|---|
| 0 | 需求摄入 | 一行适配性检查、平台、时长、是否无声优先 | 只询问会阻碍工作的内容（一个问题），否则做出决定并说明 |
| 1 | 简报 | BRIEF.md 第 1 到 3 节 | 核心信息能用一句话概括；核心元素能用一句话命名 |
| 2 | 证据 | FACTS.md 填满所有计划中的声明；C 行的计算脚本 | tools/ledger_lint.py 通过；没有 N 行 |
| 3 | 方向 | 排除列表、核心理念句、标志性时刻、theme.ts 令牌 | 通过竞争对手测试（参见 references/02-direction.md） |
| 4 | 故事板 | 表格：场景、秒数、运动内容、字幕、账本行；timeline.json | 字幕预算达标；总时长合理 |
| 5 | 基础建设 | 脚手架项目、字体、主题、外壳、相机、预览打开 | 能渲染出一张静态帧；WebGL 正常工作（参见陷阱：路径长度） |
| 6 | 构建 | 场景，从最难和最核心的开始 | 每个场景：静态帧、一张联系表、最多 3 次修复 |
| 7 | 资源 | 3D 和图标资源，除非需要许可来源，否则使用程序化生成 | 每个使用的徽标或商标，未经修改并注明出处 |
| 8 | 验证 | 完整渲染、编码、探测、帧表、账本检查 | 所有自动检查通过；帧表已审查；列出缺陷 |
| 9 | 交付 | mp4、封面帧、字幕文本、替代文本、致谢、“未验证”列表 | 用户无需追问真实性即可发布 |
阶段 0：需求摄入
用一句话说明你要制作的内容：解读为：<媒介> 面向 <读者>，<核心元素>，<时长>。只有当问题的答案会改变你的构建内容（平台和宽高比；是否后续有音频；哪些来源是权威的）时才提问。社交源默认画布为 1080 x 1350 (4:5)，30 fps；参见 references/08-adapting.md 了解 16:9、1:1、9:16。
阶段 1：简报
复制 templates/starter/BRIEF.md。填写意图（媒介、读者、核心信息、核心元素、情绪）。核心信息必须是一个观众能重复说出的句子。如果你无法用一个短语命名核心元素，你还没有一个视频：做出决定并说明，或者问一个问题。
阶段 2：证据（大多数视频忽略的部分）
- 确定主要来源（规范、RFC、源代码树、数据表、手册页、测量输出）。阅读你将引用的确切行。记录
文件:行号或 URL 加章节。 - 对于每个数字，问：构建过程能计算它吗？如果能，编写一个脚本来计算它，用第二种方法交叉检查，发现不一致时中止，并写入一个场景可以导入的生成模块（
examples/merkle-proof/scripts/compute.mjs是范例：RFC 递归与迭代构建必须一致，否则什么都不写入）。 - 任何无法找到来源的内容要么变成带标签的示意图（
S，并且屏幕上会显示“示意图”字样），要么被删除。草稿中允许出现可见的[需要来源]，但渲染版中不允许。 - 示例数据在诚实的条件下是合法的：虚构的示例项以纯文本示例形式显示，并记录为
S。 - 运行
python tools/ledger_lint.py作为触发器：场景字符串中的每个数字都必须在账本中出现。
完整格式和示例：references/01-brief-and-ledger.md。
阶段 3：方向
写下核心理念句：“在这个视频中，[属于主题的某个东西] 变成了 [那个装置]。”运行竞争对手测试：如果一个关于该主题的通用视频也可以使用相同句子，那它就是一个类别创意，而不是一个真正的创意。选择一个标志性时刻（唯一一个高调的动作）和排除列表（三种最明显的可视化方式，现在被禁止：通常是带箭头的矩形堆栈、屏幕截图、渐变背景上的居中对象）。设定基调：变化程度、运动强度、密度，每个维度从 1 到 10，根据主题而定（面向工程师的安全解释器应平静而密集；发布预告片则两者皆非）。详细信息和编排规则见 references/02-direction.md。
阶段 4：故事板和时序
一个表格：场景、秒数、运动内容、字幕、账本行。实践中验证有效的预算：
- 字幕最多 2 行、14 个单词，在 1080 画布上最小字号 48 px（手机显示画布约为 0.36 倍，因此 48 px 约为 17 pt）；标签至少 26 px；
- 字幕至少停留
单词数 / 2.6 + 0.8秒，绝不在句子中间替换； - 一个场景一个想法；超过 12 秒的场景需要内部节拍（步骤）并配有相应字幕；
- 整部作品只讲述一个想法：删除任何不会导致丢失账本行的场景。
仅在 timeline.json 中编写场景顺序和时长。Remotion、验证脚本和 cuelab 音频管道都读取这一个文件。
阶段 5：基础建设
node scripts/scaffold.mjs <目标目录> --install
然后：编辑 src/theme.ts（调色板，画布），将字体放入 public/fonts，在 src/ui/Chrome.tsx 中设置 BRAND，编辑 timeline.json。保持项目路径简短（参见陷阱：ANGLE 在 Windows 上需要短路径）。在编写更多内容之前，先渲染一个 3D 场景的静态帧：如果现在 WebGL 失败，它以后也会失败。
阶段 6：逐步构建场景
顺序：标志性场景优先（困难的 3D 或网格），然后是其依赖的场景，最后是连接性场景。每个场景：
- 使用外壳、令牌和动画辅助工具，按照布局合同（
references/03-layout-contract.md）编写场景； bash tools/shots.sh <场景名> out/<场景名> <帧号...>：选取每个节拍的开始、运动中和结束的帧，生成一张联系表；- 查看一次联系表，回答：第一眼/第二眼/第三眼看到什么？核心元素是否在预期位置？是否有任何通用元素？要删减什么？最多修复三件事；仅重新渲染更改过的帧；
- 当场景稳定后，继续前进。不要在场景 6 未构建的情况下打磨场景 2。
承担主要工作的动画模式（遮罩线条揭示、交错行、哈希打乱、比特翻转、3D 投影标签、实例化网格）见 references/04-remotion-patterns.md；3D 配方见 references/05-three-assets.md。
阶段 7：资源
优先使用程序化生成资源：它们是确定性的、体积小、可定制主题且无许可风险。箔片盒子、挤压徽标、实例化单元格网格和点场涵盖了大多数解释性视频的需求。仅当有机或品牌对象是必需的，并且服务的许可和成本可被用户接受时，才使用 AI 生成的网格；永远不要隐瞒某个资源是生成的。真实的徽标和商标：使用项目自己的原始文件（重新着色单色标志通常可以；但重新绘制则不行），检查许可，在屏幕或字幕中注明出处。
阶段 8：验证
自动化，按此顺序执行（从便宜到昂贵）：
npx tsc --noEmit # 类型检查
python tools/ledger_lint.py # 数字与账本比对
bash tools/shots.sh Main out/m <帧号> # 生成联系表，查看一次
npm run render && npm run encode # 原始渲染，然后限定范围的 yuv420p h264
# encode.sh 最后运行 tools/probe.py
tools/probe.py 检查编码格式、yuv420p（而非 yuvj420p）、尺寸、fps、相对于 timeline.json 的时长、限定范围、无黑帧、快速启动原子。然后查看最终 mp4 的静态帧表（每 4 秒一帧，使用 ffmpeg 提取），并以全尺寸查看一帧以检查文字清晰度。如果可以使用设计评审（例如 creator-critic 技能），则在一组静态帧上运行它：将阻塞性问题视为必须修复的问题，将主要问题视为待讨论的问题。完整检查清单：references/06-verification.md。
阶段 9：交付
交付内容：out/video.mp4、封面帧（标题和核心元素均清晰可读的静止帧）、字幕草稿（平实描述，无夸张，注明来源）、替代文本（一句话描述视频内容）、致谢（资源、徽标、许可）、以及一个**“未验证”列表**（账本状态为 H 或 S 的任何内容，构建过程无法证明的任何内容，以及你无法肉眼审查的任何内容）。不要自行发布任何内容。
选项选择决策表
| 问题 | 选择 | 原因 |
|---|---|---|
| 元素使用 2D 还是 3D | 仅在深度或物理形态是关键时（如芯片、堆栈、包含数百万项的字段）使用 3D；否则使用 2D | 3D 耗费渲染时间并降低可读性；在它能解释问题的地方使用它 |
| 相机 | 正交相机，manual = true，每个场景固定 | 正交视角使标签可投影，测量真实 |
| 3D 上的标签 | 使用 project() 投影的 HTML 或 SVG | 文字保持清晰且样式化 |
| 大量重复单元格 | 使用 InstancedMesh（数千个）或 Points（数百万个） | 减少 draw calls |
| 字体 | 最多两种字族，OFL 或授权字体，打包在 public/fonts 中 | 确定性，渲染时无网络请求 |
| 文字在色块或填充上 | 深色文字在亮色填充上，绝不在亮色上使用白色文字 | 确保对比度 |
| 音频 | 在画面锁定后，根据 timeline.json 设计音频 | 参见 cuelab 技能 |
此方法旨在预防的失败模式
内容美观但错误（没有账本）；内容正确但难以阅读（没有布局合同）；内容通用无特色（没有核心理念句，没有排除列表）；在工作室中看起来不错但在渲染时出错（非确定性）；在 100% 缩放时看起来不错但在手机上模糊不清（字号下限，缩略图测试）；无法评分的视频（没有单一的 timeilne）；声称的内容无人能验证（交付不诚实）。在前两部视频构建过程中遇到的具体错误，包括症状、原因和修复，记录在 references/07-pitfalls.md 中；在调试任何看起来像魔法的问题之前，请先阅读它。
此技能包含的文件
| 路径 | 内容 |
|---|---|
references/01-brief-and-ledger.md | 简报模板、账本格式、如何计算和交叉验证事实 |
references/02-direction.md | 核心理念句、排除列表、基调、编排规则、运动令牌 |
references/03-layout-contract.md | 画布、安全区域、字号下限和手机缩放计算 |
references/04-remotion-patterns.md | 经过测试的动画模式及代码 |
references/05-three-assets.md | Remotion 中的 three.js：相机、箔片着色器、边缘、实例化、点云、挤压、标签投影 |
references/06-verification.md | 完整的验证阶梯、联系表协议、编码和探测 |
references/07-pitfalls.md | 遇到的所有真实错误及修复方法 |
references/08-adapting.md | 其他宽高比、主题、语言、无 3D 变体、音频移交 |
templates/starter/ | 一个可运行的 Remotion 项目：主题、辅助工具、UI 外壳、three.js 工具包、工具、BRIEF 和 FACTS 模板 |
scripts/scaffold.mjs | 将 starter 复制到新项目并安装 |
../../examples/merkle-proof/ | 一个完整的 36 秒示例，包含计算的事实、账本、渲染和探测 |
你必须传达的许可证说明
Remotion 不是 MIT 许可证。它对个人和最多三人的团队免费；超过该规模的公司需要付费许可证（Remotion CLI 会打印此通知，请参见 remotion.pro/license）。在项目可能用于商业用途时，尽早告知用户一次。three.js、React 和打包的字体（SIL OFL）是宽松许可证。