HyperFrames Schema 合规审查实战：用 15 项检查清单守住 HTML 组合的确定性渲染
【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes
HyperFrames 的核心思路是"Write HTML, render video"。当多个 Composition 相互嵌套、时间线由 GSAP 驱动、字幕由逐词时间轴驱动时，如何保证每个文件最终能通过编译、预览与渲染的一致性考验？仓库在 packages/producer/tests/style-16-prod/src/code_review.md 中保存了一份针对真实生产风格回归样例的 Schema 合规审查报告，把"能否被可靠渲染"拆成了 15 条可勾选、可执行的检查项。读完本文，你将理解这套检查清单背后的设计动机、每条规则对应的 HTML/Schema 写法，以及如何在仓库源码与文档中找到依据，把同样的审查流程复用到自己的项目中。
这份审查报告审查的是什么
code_review.md是一份"HyperFrame Schema Compliance Review"，审查对象是与它同目录的三份源文件：
- packages/producer/tests/style-16-prod/src/index.html：竖屏 1080×1920 主文档（根 Composition）；
- packages/producer/tests/style-16-prod/src/compositions/motion-graphics.html：可复用的动效 Composition；
- packages/producer/tests/style-16-prod/src/compositions/captions.html：可复用的逐词字幕 Composition。
审查结论是三项文件全部COMPLIANT，Critical issues: 0，整体PASS。值得注意的是，这份报告并非孤立存在——它的目录结构本身就是仓库的"风格回归夹具（style regression fixture）"的一部分。同级的 meta.json 声明了它的身份：tags: ["style-regression", "prod-style", "slow", "portrait"]，并带有minPsnr: 30、maxFrameFailures: 0等渲染质量门槛与renderConfig.fps: 30。也就是说，一份合格的 Schema 合规审查报告会被放在被测源文件旁边，作为 Agent 交付物的一部分持续维护，而不是渲染完成后再补写的形式文档。
从"内容骨架"上看，这份报告包含三段固定结构，也是你可以复用到任意项目中的审查模板：
- Executive Summary：统计文件数、致命问题数与总体结论；
- Critical Issues：致命问题列表（此处为空）；
- Compliance Checklist + 逐文件明细：全局清单逐条勾选，再对每个被审文件给出
COMPLIANT与问题列表。
15 条检查项逐条拆解：每一项对应什么约束
报告正文的合规清单值得完整保留，因为每一条都能在 HyperFrames 的文档与实现里找到对应物。以下按四组拆解。
组合（Composition）的元数据与时长边界
| 检查项 | 含义与依据 |
|---|---|
所有组合都有data-width/data-height | 组合必须声明固定画布尺寸，这是确定性渲染"fixed output size"前提的一部分（见 docs/concepts/determinism.mdx）；示例中三层文件统一声明1080×1920 |
所有时间线有限长且duration > 0 | 组合必须有已知终点（finite length），渲染引擎才能逐帧推进而不陷入死循环 |
| 无无限时长或零时长时间线 | 防止repeat: Infinity、duration 为 0 或未声明 end 的时间线破坏帧推进 |
在源文件中可以一一核对：主文档根元素#main-comp声明了data-composition-id="main"、data-width="1080"、data-height="1920"、data-start="0"、data-duration="13.88"（见 index.html），两个子组合文件内部也都各自声明了相同的画布与时长（motion-graphics 见 motion-graphics.html）。报告清单中duration > 0、非无限长等条目在 13.88 秒的有限窗口内自然成立。
确定性：时间线注册与非随机性
| 检查项 | 含义与依据 |
|---|---|
所有组合注册到window.__timelines | 这是渲染/预览管线定位时间线的契约入口——从核心运行时到 producer 的 htmlCompiler 服务，都围绕该注册表工作；合规写法是window.__timelines["main"] = tl |
不使用Math.random()、Date.now()或任何非确定性代码 | 这是确定性渲染的红线。同样的第 90 帧，两次渲染必须像素级一致；一旦读取了墙钟或未播种随机数，每次运行都会得到不同结果 |
三份文件的script都先创建gsap.timeline({ paused: true })，再在结尾注册。例如主文档在 index.html 中创建tl，逐步加入fromTo/to关键帧，最后window.__timelines["main"] = tl；motion-graphics 与 captions 也以同样模式分别注册"motion-graphics"、"captions"键。paused: true不是可有可无的细节：按 确定性渲染文档 的约定，GSAP 时间线应当"暂停并被 seek"，而非播放——引擎为每一帧把时间线 seek 到精确时刻t = floor(frame) / fps（整数数学，绝不读取真实时钟）。整个样例中也确实不存在Math.random/Date.now/requestAnimationFrame。
仓库在编译器层把同样的限制做成了静态检查：在 packages/core/src/compiler 的htmlBundler.ts、timingResolver.ts等模块中都有针对非确定性代码的静态守卫与时间引用解析逻辑，staticGuard的名称与作用与此吻合。审查报告中的勾选项本质上是把编译器的静态规则翻译成人可读的清单。
原始剪辑（Primitive Clip）的数据属性
| 检查项 | 含义与依据 |
|---|---|
原始剪辑具备id、data-start、data-track等必需属性 | 在 时间元素与数据属性 中，一个被计时的元素需要data-start（进入时间轴的时刻）与data-duration（时间槽长度）；轨道索引决定 Studio 中显示在哪条泳道 |
所有<img>剪辑都声明data-duration | 图片没有媒体运行时去推断时长，必须显式声明；本样例无图片，故标 N/A |
| 同一轨道上的剪辑在时间上不重叠 | 轨道是 Studio 的行，不是层级；刻意交叠（如叠化）应放在不同轨道上保持可读 |
这里有一个值得注意的口径细节：报告清单写作data-track，而当前 contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
的Matlab实现与性能优化)
