HyperFrames 组合 schema 合规性审查：从 style-9-prod 回归样例看确定性渲染的硬性规则-港品优选

HyperFrames 组合 schema 合规性审查：从 style-9-prod 回归样例看确定性渲染的硬性规则

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames 是一款"Write HTML. Render video"的渲染引擎，其核心前提是：任何一次渲染都必须产出完全一致的画面，也就是文档所称的Deterministic Rendering（确定性渲染）。本仓库的style-9-prod生产回归样例中附带了一份面向该视频全部 4 个 HTML 源文件的code_review.md合规性审查报告，它逐条列出了组合（composition）必须遵守的结构与确定性规则。读完本文，你将掌握 HyperFrames schema 的全部合规检查项及其代码佐证，能够对任何 HTML 视频源文件执行同样的静态审查，在进入渲染流水线之前就把"不可复现帧"的隐患排查干净。

审查对象与上下文

code_review.md位于生产风格回归夹具目录 packages/producer/tests/style-9-prod，审查的是该夹具下 4 个 HTML 源文件：

src/index.html：根组合（root composition）main-video
src/compositions/intro.html：开场标题组合
src/compositions/captions.html：字幕组合
src/compositions/stats.html：数据贴纸组合

该夹具的 meta.json 表明它被用作"style regression"（样式回归）测试输入，并设置了渲染验收门槛：minPsnr: 30、maxFrameFailures: 2、minAudioCorrelation: 0.9、maxAudioLagWindows: 120，渲染帧率为fps: 30。也就是说，这份合规审查不是孤立文档，而是整个回归测试链路中"渲染前静态把关"的一环：源文件先在 schema 与确定性层面通过人工/代理审查，再交给渲染器产出视频，最后用 PSNR 与音频相关性做像素级与波形级验证。

审查结论为 4 个文件全部COMPLIANT（合规），无关键问题，整体状态PASS。这在生产风格夹具中属于常态——它是渲染测试的"正样本"，必须能在严格的确定性规则下稳定产出合格帧。

HyperFrame schema 合规清单全解析

原报告给出了 15 项可执行（[x]）的合规检查项。每一项背后都是组合模型与确定性渲染契约的具体约束，逐条对应到渲染管线中的实现：

1. 尺寸属性：所有组合带`data-width`/`data-height`

文档>window.__timelines = window.__timelines || {}; const tl = gsap.timeline({ paused: true }); window.__timelines["main-video"] = tl;

intro、captions、stats三个组合分别用window.__timelines["intro"]、window.__timelines["captions"]、window.__timelines["stats"]完成注册。从核心运行时实现看，这正是渲染器"按名字找到并 seek 每条时间线"的接口约定：相关逻辑集中在 packages/core/src/runtime/timeline.ts 与 packages/core/src/runtime/compositionLoader.ts。所有 GSAP 时间线一律以{ paused: true }创建，渲染时只 seek、从不 play——对应确定性契约里"GSAP timelines are paused and seeked, never played"的要求。

4. 禁止非确定性代码：无`Math.random()`、`Date.now()`等

determinism.mdx 明确列出三类红线：无墙钟（Date.now()、requestAnimationFrame、系统定时器）、无未播种随机数（Math.random()）、渲染中途不发起网络请求。任何一条都会导致同一帧每次渲染出不同结果。审查逐一扫描 4 个文件的脚本，未发现此类调用。

5. 元素属性：媒体/音频 clip 带`id`、`data-start`、`data-track`

音视频等"素材 clip"必须用这些属性表达在时间线上的位置与轨道归属，渲染器据此做素材排布与混音。例如 src/index.html 中的 7 个<audio>特效元素，每个都带id、data-start（如0、1.839、4.659、8.88）、data-duration="1.044898"以及不同的data-track-index（5/6/7），对应 bounce、whoosh、pop 三类音效按轨道分层。

6. 图片 clip 必须显式声明`data-duration`（本例 N/A）

审查表标注该项 N/A——夹具中没有任何<img>元素，因此规则不适用。规则本意是：图片等静态资源若不声明持续时长，渲染器无法确定它何时结束，进而无法保证时间线的有限性。

7. 禁止手动媒体播放控制

脚本中不得出现video.play()、audio.pause()之类的手动控制。原因有二：一是播放调用依赖真实时钟，破坏按帧 seek 的确定性；二是渲染器自行管理媒体时序（见 meta.json 的音频相关性验收项），手动控制会与引擎调度冲突。4 个文件均无此类调用。

8. 禁止脚本手动挂载/卸载 clip

组合（复用组件）的挂载/卸载应由运行时通过data-composition-src与<template>机制完成，脚本不应在渲染期间直接对 DOM 中的组合节点做挂载/卸载操作，否则 DOM 状态会偏离帧号唯一决定的预期。

9. 相对时间引用合法性（本例 N/A——全为绝对时间）

审查表标注 N/A：夹具中所有动画均使用绝对时间定位（如4.659、8.88、14.619），不存在相对引用因此无需校验。合规的另一种写法是使用相对偏移或"-=0.5"这类 GSAP 相对定位，但其前提是引用对象在时间线上已被确定。

10. 同轨 clip 在时间上不重叠

同一data-track上，不同元素的播放区间不得交叠，否则合成优先级会变得歧义。夹具中的音频元素各自占用不同轨道索引，或虽共享轨道（whoosh 用轨道 6、pop 用轨道 7）但时间段互不交叠，符合约束。

11–13. 可复用组合的工程规范

三项合在一起构成组合化开发的标准姿势：

可复用组合放在独立 HTML 文件：intro、captions、stats分别独立成文件；
组合文件使用<template>标签包裹：三个文件的外层都是<template id="...-template">，供运行时克隆实例；
外部组合通过data-composition-src加载：根文件里三个占位节点各自声明data-composition-src="compositions/intro.html"等路径，见 src/index.html。

14. 所有脚本动画内容包裹在组合内

根文件里不允许散落"裸脚本"驱动的动画；凡是script中需要驱动 GSAP 时间线的区块（如 src/index.html 的背景层、#L167-L178 的 A-roll 层），都被包成带data-composition-id的独立组合节点，保证每个动画块都能被独立寻址、seek 与回收。

15. 无无限或零时长时间线

第 2 项的严格化：即便 duration > 0，若脚本用repeat: -1制造无限循环，仍然违规。这一点在 stats.html 的处理上尤其值得学习，见下文。

逐文件审查结果与源码佐证

index.html —— 根组合`main-video`

审查结论 COMPLIANT，要点如下：

根节点正确声明组合main-video（data-composition-id、data-duration="16.04"、1920×1080）；
用data-composition-src引用三个外部组合；
时间线注册进window.__timelines["main-video"]；
7 个音频 clip 均带id/data-start/data-track。

从结构上看，根页面还通过z-index显式约定图层顺序（背景 1 < A-roll 10 < intro 100 < stats 150 < captions 200），并把背景切换时刻与 A-roll 构图切换时刻做硬编码对齐（4.659s变蓝、8.88s变白），这些都进一步保证了跨帧的一致性。

compositions/intro.html —— 开场标题

<template>包裹；
根元素带data-composition-id="intro"、尺寸与data-duration="16.04"；
脚本确定性强：开场序列（0.5s 起back.out(1.7)弹入 +elastic.out归位 + 有限yoyo环境摆动 +1.4s退场），再叠加 14.619s 的结尾卡片序列，全部基于常量时间轴，并正确注册时间线。

值得注意rotation环境动画用的是repeat: 1, yoyo: true（有限往复）而非无限重复，这正与确定性约束吻合。

compositions/captions.html —— 逐词字幕

<template>包裹、根元素声明完整；
采用固定转写稿驱动字幕生成：TRANSCRIPT数组内置了从 0.119s 到 16.019s 的 45 个词条及各自的start/end，随后按"每行最多 5 词"分组成行、为每行创建.caption-box并按行首/行尾时间绝对定位弹入、隐藏。因为数据源与时间全为编译期常量，字幕生成过程是完全确定的。

compositions/stats.html —— 数据贴纸

<template>、根元素声明完整；
三块数据 moment（47% / 62% / 75%）的入场时间不是魔法数字，而是从同一份转写稿里用getWordTime("Forty-seven")、getWordTime("Sixty-two")、getWordTime("three")派生，与旁白词精确对齐（如 75% 一条在 "Editor Agent" 出现前 3 个词的 14.239s 退场）；
环境摆动的有限化是亮点：装饰.shape的来回浮动不是repeat: -1，而是基于totalDuration = 16.04计算步数并显式展开为有限个tl.to补间：

const stepDuration = 2 + i * 0.2; const steps = Math.ceil(totalDuration / stepDuration); for (let s = 0; s < steps; s++) { tl.to(shape, { y: s % 2 === 0 ? 15 : -15, rotation: s % 2 === 0 ? 5 : -5, duration: stepDuration, ease: "sine.inOut" }, s * stepDuration); }

这正是审查意见中"Ambient motion 用有限循环、避免无限重复，是渲染器友好做法"的代码对应物。从引擎角度看，无限补间会让帧时钟对应的目标状态计算量无限增长或无法收敛，而把循环"展开"成有限个绝对时间补间后，任何一帧都能精确命中一个确定状态。

底层机制：合规清单为何存在

上述每一项都不是书写风格偏好，而是对 determinism.mdx 所描述渲染模型的直接服从：

渲染器从不"播放"视频，而是逐帧询问"第 90 帧长什么样"；
该问题的答案只取决于唯一变量——帧号：t = floor(frame) / fps（整数运算，绝不读墙钟）；
帧适配器（frame adapter）把每一条动画、DOM 变化、canvas 绘制seek到精确时刻；
Chrome HeadlessbeginFrame原子化抓取像素，FFmpeg 混入音轨并编码成 MP4。

compositions.mdx 进一步解释了组合机制的意义：HTML 片段经过作用域隔离、作为可复用单元加载，而引擎运行时正是通过data-composition-id找到节点、读取data-width/data-height/data-duration构建时间预算，再经window.__timelines找到并 seek 对应时间线。因此本审查清单中"属性是否齐全、时间线是否注册、脚本是否确定、是否使用 template/外链组合"这几类问题，直接决定了运行时能否拿到正确的注册表与时间轴——任何遗漏都可能让某个组合"找不到时间线"或"无限漂移"，最终体现为回归测试中 PSNR 低于 30、帧失败数超标或音画错位。

schema 审查与设计审查的分工

在 style-9-prod 夹具中，与code_review.md并列的还有 design_review.md。二者的分工可以看作"机器正确性"与"审美质量"的双通道：

code_review.md只评判技术合规：尺寸、时长、确定性、轨道、注册、可复用性，结论是唯一的布尔值（PASS/FAIL）。它对视觉、配色、动效质感完全沉默——这部分不是它的职责。
design_review.md则给出主观设计评审：例如批评stats.html高饱和撞色"贴纸书乱象"、180px 加粗斜体标题与多层阴影的"YouTube 缩略图感"、过度使用elastic.out/back.out导致"像在弹跳城堡里看视频"，同时肯定 A-roll 容器在构图切换时缩放让位的功能性布局设计。

对 AI Agent 生成视频的生产流水线而言，这种"双报告"模式很有参考价值：代码审查保证可渲染、可复现；设计审查保证成品值得看。前者为硬门槛，后者为软标准。

面向编写者的自查清单

若你要为 HyperFrames 编写可被渲染的组合 HTML，可以直接用code_review.md的 15 条作为提交前的静态自检：

组合根元素具备data-width与data-height；
每个组合的data-duration > 0，时间线有限且无零时长；
每条 GSAP 时间线均以{ paused: true }创建并注册进window.__timelines；
脚本不含Math.random()、Date.now()、requestAnimationFrame与渲染中途的 fetch；
媒体/音频 clip 标注id、data-start、data-track；
图片 clip 显式给出data-duration；
不手动调用video.play()/audio.pause()；
不在脚本中手动挂载/卸载组合节点；
相对时间引用指向已确定的对象（或直接使用绝对时间）；
同轨道 clip 时间段互不重叠；
可复用组合独立成 HTML 文件；
组合文件用<template>包裹；
外部组合经data-composition-src加载；
所有脚本动画包裹在组合节点内；
无repeat: -1之类的无限时间线（用基于totalDuration的有限展开替代）。

其中第 3、4、15 条最容易踩坑，也最直接影响产出稳定性：时间线没注册或不可寻址、随机/时钟调用、无限循环，都是确定性渲染的头号破坏者。style-9-prod 中stats.html的"有限展开环境动画"与"从转写稿派生时间点"两种写法，可以作为编写确定性动画时的直接范本。

总结

code_review.md虽是一份短小的合规报告，但它浓缩了 HyperFrames 组合 schema 的全部硬性约束。逐条对照 src/index.html 与三个组合源文件可以看到：尺寸、时长、轨道、注册、确定性、template 化、外链加载——每一条都最终服务于"同一输入永远得到同一输出"这一引擎级保证，并由 packages/core/src/runtime/timeline.ts 这类运行时实现与 docs/concepts/determinism.mdx 中描述的逐帧 seek 渲染模型共同背书。把这份清单转化为编写规范，是让 Agent 生成的 HTML 视频"一次渲染、次次相同"的最可靠起点。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析