玩转 HyperFrames：从 AI Coder 到 AI Layout Driver

玩转 HyperFrames 的关键，是把 AI 从每次重写 HTML、CSS 和动画的 Coder，转变为选择 Block、填充 Scene JSON、绑定主题和编排时间的 Layout Driver，再由固定编译器和检查流水线生成视频。

真正的升级不是让 AI 写得更快

刚开始使用 HyperFrames 时，最直接的方式通常是：

用户提出需求
  ↓
AI 阅读 Skills 和项目规范
  ↓
现场编写 HTML、CSS、GSAP
  ↓
执行 check
  ↓
根据错误反复修改
  ↓
渲染视频

这条路线适合第一条视频，也适合探索新的视觉形式。但如果每条视频都这样生产，成本很快会暴露出来：

• 相同的标题场景被重复编写
• 相同的终端窗口被重复实现
• 每次重新决定字体、颜色和圆角
• 每次重新设计时间轴
• Composition ID、根尺寸和媒体路径问题反复出现
• Agent 输出大量重复代码
• 修改一个数据也可能触发整页重构
• 视频之间的品牌风格难以保持一致

真正玩转 HyperFrames，不是继续要求 AI “把代码写得更快”，而是改变 AI 在系统中的角色：

从 AI Coder 转向 AI Layout Driver。

AI 不再为每条视频重新发明组件和动效，而是在已经验证过的 Block、主题、动画 Recipe 和数据协议中做选择、填充和编排。

AI Coder 和 AI Layout Driver 有什么区别

AI Coder 模式

AI 负责：

• 设计 DOM 结构
• 决定 CSS
• 创建 Timeline
• 选择动画
• 计算场景时间
• 绑定媒体
• 处理所有异常

输入可能只有一句：

做一个科技感的终端安装场景。

输出是几百行一次性代码。

AI Layout Driver 模式

AI 负责：

• 从 Registry 中选择 terminal-command Block
• 输出符合 Schema 的 Scene JSON
• 选择已有主题和 Motion Recipe
• 把旁白 Cue 映射给 Block
• 决定场景顺序和时间
• 根据检查结果调整数据

输出可以变成：

{
  "scene_id": "03-install",
  "block": "terminal-command",
  "start": 6,
  "duration": 5.5,
  "track": 1,
  "theme": "code-editorial",
  "motion": "type-and-confirm",
  "props": {
    "command": "npm install hyperframes",
    "output": "Installed successfully"
  }
}

两种模式并不是互相排斥。

AI 仍然可以写代码，但应该集中在高价值工作上：

• Registry 中没有合适 Block
• 已有 Block 缺少必要能力
• 一个新场景未来会被多次使用
• 需要升级主题、编译器或验证规则
• 需要修复组件本身的技术问题

对于已经成熟的场景，AI 更适合驱动数据，而不是重复实现。

一张图看懂数据驱动的视频工厂

一个更成熟的 HyperFrames 系统可以拆成五层：

┌──────────────────────────────────────────┐
│ 1. Intent：Brief / Script / Storyboard   │
├──────────────────────────────────────────┤
│ 2. Scene Data：内容、时间、素材、Block   │
├──────────────────────────────────────────┤
│ 3. Registry：Block / Component / Recipe  │
├──────────────────────────────────────────┤
│ 4. Design：Theme / Token / Motion Rules  │
├──────────────────────────────────────────┤
│ 5. Compiler + QA：HTML / Check / Render  │
└──────────────────────────────────────────┘

完整数据流是：

Prompt / Brief
  ↓
AI 生成 Scene JSON
  ↓
JSON Schema 验证
  ↓
语义检查
  ↓
选择 Registry Block
  ↓
绑定 Theme、Motion 和 Audio Cue
  ↓
编译为 HyperFrames Composition
  ↓
lint / check / snapshot / preview
  ↓
render

这里最关键的变化是：

Agent 的输出不再直接等于最终视频源码，而是先成为一份受约束的视频描述数据。

第一层：先建立 Block Registry

什么是 HyperFrames Block

在当前 HyperFrames Registry 模型中，Block 是一个可以独立渲染的 Sub-composition，拥有：

• 自己的 Composition ID
• 自己的宽度和高度
• 自己的时长
• 自己的 HTML 和 CSS
• 自己的可 Seek Timeline
• 自己支持的变量和媒体

主 Composition 通过 data-composition-src 加载它：

<div
  data-composition-id="terminal-command"
  data-composition-src="compositions/terminal-command.html"
  data-start="6"
  data-duration="5.5"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

Block 的内部 Timeline 独立运行。HyperFrames 会按照 Host 的 data-start 计算相对时间，不需要主 Timeline 再手动调用 Block 的动画函数。

Block 和 Component 不一样

HyperFrames Registry 中有两种主要复用单元：

Block 更像剪辑软件里的预合成；Component 更像一段可以复制进现有场景的效果代码。

可以通过 CLI 发现和安装 Registry 内容：

npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --json

npx hyperframes add data-chart

对于 Agent 或 CI，推荐使用 catalog --json 获取结构化结果，再显式选择和安装一个 Block，而不是让脚本在交互界面中随意挑选。

不要混淆 Registry 和 Web Components

浏览器原生 Web Components 也可以提高复用率：

class TerminalView extends HTMLElement {
  connectedCallback() {
    const command = this.getAttribute("data-command") || "";

    this.innerHTML = `
      <div class="terminal">
        <span class="prompt">$</span>
        <span class="command"></span>
      </div>
    `;

    this.querySelector(".command").textContent = command;
  }
}

customElements.define("hf-terminal-view", TerminalView);

但它属于浏览器组件机制，不自动等于一个 HyperFrames Registry Block。

推荐的边界是：

HyperFrames Block
├── 负责 Composition ID、尺寸、时长、变量和 Timeline
└── 内部可以选择使用 Web Component 组织 DOM

而不是：

自定义 HTML 标签
= HyperFrames Registry Block

Web Component 可以是 Block 的内部实现方式，但仍要遵守 HyperFrames Composition 合约。

第二层：让 AI 只输出 Scene JSON

建立 Registry 后，下一步是把视频内容变成标准数据。

一个更完整的 Scene JSON

{
  "schema_version": "1.0",
  "scene_id": "03-install",
  "block": "terminal-command",
  "block_version": "1.2.0",
  "start": 6,
  "duration": 5.5,
  "track": 1,
  "theme": "code-editorial",
  "motion": {
    "preset": "type-and-confirm",
    "intensity": "medium"
  },
  "props": {
    "command": "npm install hyperframes",
    "output": "Installed successfully"
  },
  "audio": {
    "cue": "scene-03",
    "sync": "word"
  }
}

这份数据描述了：

• 使用哪个 Block
• 从什么时候开始
• 持续多久
• 位于哪条 Track
• 使用哪个主题
• 使用哪个动画预设
• 传入什么内容
• 与哪段音频对齐

Agent 不需要输出任意 CSS 和 JavaScript。

为什么必须有 schema_version

没有版本号时，今天生成的 Scene JSON 可能在几个月后无法被新 Builder 正确理解。

例如：

{
  "schema_version": "1.0"
}

未来如果字段结构发生变化，可以升级为：

{
  "schema_version": "2.0"
}

编译器可以拒绝未知版本，或者先执行迁移脚本，而不是静默生成错误视频。

JSON Schema 能解决什么

JSON Schema 可以检查：

• 必填字段是否存在
• start 和 duration 是否为数字
• duration 是否大于零
• scene_id 是否符合命名格式
• theme 是否属于允许值
• motion.preset 是否属于预设
• props.command 是否过长
• 是否出现了未知字段

简化示例：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "schema_version",
    "scene_id",
    "block",
    "start",
    "duration",
    "track",
    "props"
  ],
  "properties": {
    "schema_version": {
      "const": "1.0"
    },
    "scene_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$"
    },
    "start": {
      "type": "number",
      "minimum": 0
    },
    "duration": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "track": {
      "type": "integer",
      "minimum": 0
    },
    "theme": {
      "enum": ["code-editorial", "terminal-green"]
    }
  },
  "additionalProperties": false
}

Schema 能减少格式和类型错误，但不能保证视频一定正确。

还需要第二层语义检查

以下问题无法只靠单个 Scene 的 JSON Schema 发现：

• 两个 Scene 使用了相同 ID
• 同一 Track 上出现意外重叠
• start + duration 超出视频总时长
• Registry 中不存在指定 Block
• Block 不支持当前画幅
• Block 不支持某个 Motion Preset
• 音频 Cue 不存在
• 本地媒体文件缺失
• 标题长度超过 Block 容量
• 两个 Block 组装后产生重复 DOM ID

因此完整验证应该是：

JSON Schema
  ↓
Registry 能力检查
  ↓
全局时间轴检查
  ↓
媒体文件检查
  ↓
编译 HTML
  ↓
HyperFrames check

可以把它概括为：

Schema 验证“数据长得对不对”
Semantic Validator 验证“数据组合得对不对”
HyperFrames check 验证“浏览器最终渲染得对不对”

第三层：使用编译器，而不是渲染时动态请求

一个常见想法是在浏览器加载后执行：

const data = await fetch("./video.json");
buildScenes(data);

对于普通网页，这很自然；对于确定性视频渲染，不建议把关键工程结构依赖在运行时异步请求上。

更可靠的方式是构建时编译：

node scripts/validate-scenes.mjs
node scripts/build-composition.mjs
npx hyperframes check

Builder 在渲染前完成：

1. 读取 JSON
2. 验证 Schema
3. 执行语义检查
4. 查找 Registry Block
5. 生成 Host 元素
6. 绑定变量
7. 计算总时长
8. 输出稳定的 index.html

然后 HyperFrames 读取的是已经确定的 Composition，而不是等待运行时临时生成。

为什么这对确定性更友好

渲染阶段不再依赖：

• 网络请求
• 异步 JSON 加载
• 临时 DOM 构建顺序
• 运行时接口返回值
• Timeline 延迟注册

同一份 Scene JSON 和同一版本 Builder，应该生成相同 Composition 源码。

第四层：让音频驱动视觉

视频节奏最可靠的来源通常不是 Agent 估算的秒数，而是真实音频。

推荐顺序：

锁定 Script
  ↓
生成或导入 Voiceover
  ↓
获得词级或句级时间
  ↓
生成 Audio Map
  ↓
Scene 引用 Cue
  ↓
Block 把 Cue 映射到 Timeline

Audio Map 示例

{
  "version": "1.0",
  "duration": 15.42,
  "cues": {
    "scene-03": {
      "start": 6.18,
      "duration": 4.96,
      "words": [
        {
          "text": "安装",
          "start": 6.42,
          "duration": 0.38
        },
        {
          "text": "HyperFrames",
          "start": 6.86,
          "duration": 0.72
        }
      ]
    }
  }
}

Scene 只需要引用：

{
  "audio": {
    "cue": "scene-03",
    "sync": "word"
  }
}

Block 可以消费标准 Cue：

scene.start
command.start
result.start
scene.duration

它不需要知道语音来自哪个 TTS 服务。

不要把“毫秒级数据”写成“毫秒级画面”

TTS 时间可以用毫秒表示，但最终画面会映射到视频帧。

30 FPS 的一帧约为 33.3 毫秒，60 FPS 的一帧约为 16.7 毫秒。因此更准确的目标是：

使用统一 Audio Map，让相同事件稳定落在相同的视频帧附近。

实际效果还取决于 TTS 时间数据、媒体 Seek 和解码准确性。

第五层：建立真正的设计真值系统

单独写一个 theme.css 是好开始，但还不够。

真正的设计系统至少包括：

frame.md          视觉原则与禁止事项
theme.css         颜色、字体、圆角、阴影和间距
Theme Schema      允许 Agent 选择的主题名称
Block Contract    每个 Block 支持的主题和密度
Motion Tokens     速度、缓动、位移和能量等级
Visual QA         check、snapshot 和人工审阅

Theme Token 示例

:root {
  --hf-bg: #12131c;
  --hf-surface: #1a1c29;
  --hf-foreground: #f6f7fb;
  --hf-muted: #9296a8;
  --hf-accent: #ff6b4a;

  --hf-font-main: "Inter", sans-serif;
  --hf-font-code: "Fira Code", monospace;

  --hf-radius-sm: 12px;
  --hf-radius-lg: 28px;
  --hf-safe-margin: 96px;

  --hf-motion-fast: 0.35s;
  --hf-motion-normal: 0.65s;
  --hf-motion-slow: 1.1s;
}

Agent 不直接选择颜色值

不推荐：

{
  "background": "#100B28",
  "accent": "#FF00C8"
}

推荐：

{
  "theme": "code-editorial",
  "accent_role": "primary",
  "density": "spacious",
  "motion_energy": "medium"
}

由系统把这些语义值转换为真实 token。

否则，即使存在 CSS Variables，Agent 仍然可以通过内联样式绕过设计系统。

第六层：把动画变成 Motion Recipe

在 AI Coder 模式中，Agent 可能为每个元素写不同动画。

在 Layout Driver 模式中，Agent 只选择预置动作：

{
  "motion": {
    "preset": "type-and-confirm",
    "intensity": "medium"
  }
}

一个 Motion Recipe 应该声明：

{
  "name": "type-and-confirm",
  "version": "1.0.0",
  "supported_blocks": ["terminal-command"],
  "min_duration": 3.5,
  "seek_safe": true,
  "randomness": "none",
  "checkpoints": [0.1, 0.35, 0.7, 0.95]
}

第一批值得沉淀的 Recipe

• title-rise-reveal
• terminal-type-and-confirm
• diagram-build
• number-count-up
• mask-wipe
• card-focus
• logo-resolve
• caption-highlight

不要一开始建立几十种效果。先围绕真正高频场景做 5～8 个稳定 Recipe。

高级插件不是自动的“高级感开关”

ScrambleTextPlugin

适合文字解码和科技感 Hook，但要检查字符扰动是否可以稳定 Seek。如果效果依赖未固定随机状态，应改为：

• 固定字符池
• 预先生成字符序列
• 使用固定种子
• 对同一时间点多次 Snapshot 比较

FlipPlugin

FLIP 可以实现元素在两个布局间平滑过渡，但它会涉及布局状态测量。

更安全的做法是：

• 在初始化时同步捕获布局状态
• 不在 Tween 执行期间重复测量 DOM
• 不依赖当前播放顺序才能得到目标状态
• 用 transform 完成运动
• 直接 Seek 到中间时间进行测试

Lottie

Lottie 适合勾选、Spinner 和品牌矢量动画，但必须让 HyperFrames 能够控制播放进度。

不要只让 Lottie 自然播放，而要使用对应运行时适配，让任意时间点都能定位到确定帧。

先注册能力，再允许 Agent 使用

可以维护一个能力表：

{
  "scramble-reveal": {
    "status": "experimental",
    "seek_safe": false
  },
  "flip-card-to-detail": {
    "status": "verified",
    "seek_safe": true
  },
  "lottie-success": {
    "status": "verified",
    "seek_safe": true
  }
}

Agent 只能选择 verified Recipe。实验效果先经过多时间点、多次渲染检查，再进入生产 Registry。

怎样判断 Registry 是否真的提高了效率

“生成时间缩短 90%”“5 分钟出片”可以作为目标，但不应该在没有测试数据时直接写成普遍结论。

更可靠的做法是记录项目 Benchmark：

最终应该能回答：

• 哪些 Block 使用最频繁
• 哪些 Block 经常需要返工
• 哪些字段最容易被 Agent 填错
• 哪些主题组合质量最高
• 哪些动画 Recipe 最稳定
• Registry 模式实际减少了多少代码和时间

工业化不是一句口号，而是一个可以度量、优化和回归测试的系统。

从现有项目迁移的四个阶段

阶段一：统计重复场景

先分析过去的视频：

• 哪些标题场景重复出现
• 哪些终端和代码演示重复出现
• 哪些 CTA 基本相同
• 哪些数据图表只是替换数字
• 哪些错误反复发生

阶段二：抽取第一批 Block

推荐先做：

1. Title Card
2. Terminal Command
3. Process Flow
4. Big Number
5. CTA

这五类通常已经能覆盖大量技术解释视频。

阶段三：定义 Scene Schema 和 Theme

先让一个画幅、一种主题、一套语言跑通。

不要同时解决：

• 16:9、9:16、1:1
• 中文、英文、日文
• 五种主题
• 十种转场
• 三种动画运行时

边界越小，第一版越容易稳定。

阶段四：加入 Builder、Validator 和 QA

最后把人工组装步骤自动化：

Scene JSON
→ validate
→ compile
→ lint
→ check
→ snapshot
→ preview
→ render

一份适合 Layout Driver 的 Agent 指令

你现在是 HyperFrames Layout Driver，不要默认从空白 HTML 开始。

执行顺序：
1. 读取 BRIEF.md、STORYBOARD.md、frame.md 和 Registry Catalog。
2. 为每个 Scene 选择已验证的 Block。
3. 只输出符合当前 Scene Schema 的 JSON。
4. Theme、Motion 和 Density 只能使用 Registry 中声明的枚举值。
5. 不输出自定义 CSS、JavaScript 或远程媒体 URL。
6. 如果现有 Block 无法表达内容，先报告能力缺口，不要偷偷重写整个场景。
7. 使用 Audio Map 中的 Cue 校准场景与动作时间。
8. 运行 Validator 和 Builder，生成 Composition。
9. 执行 lint、check 和关键帧 snapshot。
10. 等待最终 preview 确认后再 render。

验收：
- Scene JSON 通过 Schema 和语义检查
- 所有 Block 和 Recipe 都来自已验证 Registry
- 主题没有越过设计 token
- 没有运行时网络、未固定随机数和异步 Timeline
- 生成结果可以由相同数据重复构建

总结

从 AI Coder 转向 AI Layout Driver，真正改变的是视频生产的责任边界：

AI 负责：
理解内容、选择 Block、填充数据、编排时间、响应检查结果

系统负责：
画面结构、主题样式、动画实现、Schema、编译和质量门槛

最终目标不是完全禁止 AI 写代码，而是让代码生产发生在正确层级：

• 高频场景通过 Block 复用
• 内容通过 Scene JSON 输入
• 品牌通过 Theme Token 固定
• 动画通过 Motion Recipe 复用
• 音频通过 Cue Map 对齐
• Composition 通过 Builder 生成
• 视频通过固定 QA 流水线验证

当这些层稳定后，HyperFrames 才真正从“AI 能生成的视频网页”，升级为“AI 可以持续驱动的视频生产系统”。

下一篇将实际搭建一个 Terminal Block、Scene JSON Schema、语义验证器和 Composition Builder，完成从数据到 HyperFrames 视频工程的闭环。

系列导航

1. HyperFrames 原理详解：AI Agent 如何把 HTML 渲染成视频
2. HyperFrames Skills 实战：从 Brief 到 MP4 生成第一条视频
3. HyperFrames 进阶：如何提高画面质量与生产效率
4. 玩转 HyperFrames：从 AI Coder 到 AI Layout Driver
5. HyperFrames 官方 Registry 指南：让 Agent 自动查、拉、挂、验
6. HyperFrames Registry 实战：Block + JSON Schema 视频流水线

配套资源：

• HyperFrames AI 视频 Prompt、Brief 与检查清单
• HyperFrames Block Registry Starter Kit

参考资料

• HyperFrames 官方 GitHub 仓库
• GSAP ScrambleTextPlugin 文档
• GSAP FlipPlugin 文档