第一章：技术概述

HyperFrames 是由 HeyGen 开源的一款 HTML-to-Video 渲染框架，核心理念是 "Write HTML. Render video. Built for agents"。它让 AI Agent（如 Claude Code、Cursor、Codex）用纯 HTML + GSAP 动画来"编写"视频，再通过无头浏览器确定性渲染为 MP4/WebM。

HyperFrames 不是视频编辑器，而是一个声明式视频合成框架。你写的是 HTML，输出的是视频。中间的渲染过程对 Agent 完全透明。

HyperFrames = HTML Composition（声明式数据模型） + Frame Adapter（可插拔动画运行时） + Deterministic Engine（确定性逐帧渲染引擎）

关键数据

维度	数据
开发者	HeyGen（AI 视频生成平台）
开源协议	Apache 2.0
核心语言	TypeScript
最新版本	v0.4.3（2026-04-17）
Commits	329+
核心包	7 个（cli / core / engine / producer / studio / player / shader-transitions）
Skills	4 个（hyperframes / hyperframes-cli / hyperframes-registry / gsap）
Catalog	50+ 预制 Block（社交叠加层、Shader 转场、数据可视化、电影级特效）
技术栈	Node.js ≥ 22 + Puppeteer + FFmpeg + GSAP

技术体系归属

HyperFrames 属于声明式视频渲染领域，横跨三个技术体系：

• 前端工程：HTML/CSS/JS 原生技术栈，无框架依赖
• 视频工程：逐帧捕获 + FFmpeg 编码的管线式渲染
• AI Agent 基础设施：非交互式 CLI + Vercel Skills 规范，让 LLM 原生驱动视频生产

核心技术栈

维度	技术选型
合成语言	纯 HTML + CSS + GSAP
渲染引擎	基于 Puppeteer 的无头 Chromium
CLI 工具	Node.js，npx hyperframes
Agent 集成	Skills 系统（Vercel Skills 规范）
TTS 引擎	Kokoro（本地运行，无需 API Key）
输出格式	MP4、WebM（支持透明通道）
默认分辨率	1920×1080 @ 30fps

---

第二章：问题背景与痛点

2.1 AI Agent 无法操作传统视频工具

传统视频编辑器（Premiere、DaVinci、CapCut）的核心交互模型是拖拽 + 时间线 + GUI。AI Agent 只能通过 CLI 和文件系统与外部世界交互——它不能"点击按钮"、"拖动关键帧"、"预览画布"。

这产生了根本性矛盾：视频是最主流的内容形态之一，但 AI Agent 无法参与视频的生产流程。

2.2 现有代码视频方案的五大痛点

#	痛点	说明
1	专有 DSL 学习成本高	Remotion（React-based）要求用 React 组件定义视频，Agent 每多学一个概念层，生成正确代码的概率就降低一次
2	渲染不确定性	Canvas-based 方案依赖实时播放捕获，帧率不稳定，同输入不同输出
3	动画运行时锁定	大多数框架绑定特定动画库。你想用 GSAP？不行。想用 Lottie？换框架
4	Agent 不可驱动	很多工具的 CLI 是交互式的（需要选菜单、确认操作），Agent 没法"看到"提示符
5	提示词与实现脱节	用户说"做 10 秒产品视频"，AI 生成的代码质量完全取决于对框架的理解，没有领域知识注入只能"猜"

2.3 行业驱动力

• 短视频内容爆炸：TikTok、Reels、Shorts 日产量以亿计
• AI Agent 编程能力成熟：Claude Code、Codex、Cursor 已能生成复杂前端代码
• LLM 最擅长生成 HTML：HTML 是 LLM 训练数据中占比最高的格式之一
• HeyGen 自身需求：作为 AI 视频公司，需要让 Agent 驱动的视频模板系统

2.4 HyperFrames 优化的链路

用户意图 → LLM 生成 HTML → CLI 渲染 MP4 → 发布

HyperFrames 不是优化"渲染速度"或"视频质量"，而是优化从意图到视频的整条链路——用 HTML 作为"LLM 到视频"的中间格式。

---

第三章：核心思想

3.1 一句话本质

把视频当作网页来写，把渲染当作截图来做。

3.2 六大设计原则

#	原则	含义
1	HTML-Native	视频定义 = HTML 文件 + data 属性，不发明新 DSL
2	Agent-First	CLI 默认非交互式（flag-driven），所有输出为纯文本，fail-fast
3	Deterministic by Design	逐帧 seek + 确定性捕获，同输入必定同输出
4	Frame Adapter	动画运行时可插拔（GSAP / Lottie / CSS / Three.js），只要求能"seek 到第 N 帧"
5	Skills over Docs	通过 Vercel Skills 规范教 Agent 框架模式，而不是让 Agent 读文档猜
6	Two-Layer Architecture	HTML 层管"播什么、什么时候播"，Script 层管"怎么动"

3.3 通俗类比

想象一个 PowerPoint 幻灯片：每张幻灯片上有文字、图片、视频，它们按你设定的时间出现和消失。HyperFrames 就是"代码版 PowerPoint"——你的"幻灯片"是 HTML 文件，"动画"是 GSAP 脚本，最终"导出"的是 MP4 视频。

3.4 核心公式

Composition = HTML Primitives（声明式） + GSAP Scripts（命令式） + Frame Adapter（运行时接口）
Video = 逐帧 Seek → Chrome Capture → FFmpeg Encode

---

第四章：核心原理

4.1 Composition 数据模型

Composition 是 HyperFrames 的核心数据结构——一个带 data-composition-id 的 HTML 文档。

<div id="root" data-composition-id="root"
     data-start="0" data-width="1920" data-height="1080">
  <video class="clip" src="bg.mp4"
         data-start="0" data-duration="10" data-track-index="0"></video>
  <img class="clip" src="logo.png"
       data-start="0" data-duration="5" data-track-index="1">
  <audio class="clip" src="music.mp3"
         data-start="0" data-duration="10" data-track-index="2">
  <div data-composition-id="intro-anim"
       data-composition-src="compositions/intro-anim.html"
       data-start="0" data-track-index="3"></div>
</div>

HTML 层（Primitives）

属性	作用	示例
data-composition-id	标识一个 Composition	"root"
data-start	开始时间（秒）	"0" 或 "clip-1"
data-duration	持续时间（秒）	"5"
data-track-index	轨道编号（控制 z-order）	"0"
data-width / data-height	画布尺寸	"1920" / "1080"
data-media-start	媒体裁剪起点	"2"
data-volume	音量 0-1	"0.5"
data-has-audio	标记含音轨视频	"true"

Script 层（Animations）

用 GSAP 定义动画效果。关键规则：Script 不控制媒体播放或 Clip 可见性——这些由 HTML 属性自动管理。

const tl = gsap.timeline({ paused: true });
tl.from(".title", { opacity: 0, y: -50, duration: 1 });
window.__timelines["intro-anim"] = tl;

4.2 剪辑类型（Clip Types）

类型	HTML 元素	用途
视频	<video\>	主画面、B-roll、A-roll
图片	<img\>	静态覆盖、Logo、装饰
音频	<audio\>	背景音乐、音效（视频必须 muted）
子合成	<div data-composition-id\>	动画序列、分组片段

4.3 Frame Adapter 模式

Frame Adapter 是 HyperFrames 最核心的抽象。它回答一个问题："第 N 帧画面应该长什么样？"

type FrameAdapter = {
  id: string;
  init?: (ctx: FrameAdapterContext) => Promise<void> | void;
  getDurationFrames: () => number;
  seekFrame: (frame: number) => Promise<void> | void;
  destroy?: () => Promise<void> | void;
};

核心语义要求：

• seekFrame 必须支持任意顺序 seek（前进、后退、随机跳转）
• seekFrame 对同一帧必须是幂等的
• Adapter 不能有自己的时钟——它只响应 seek 命令

已支持 / 规划中的运行时

运行时	Seek 方式	状态
GSAP	timeline.seek\(frame / fps\)	已可用
CSS/WAAPI	animation.currentTime	规划中
Lottie	Set animation frame/progress	规划中
Three.js/WebGL	Compute deterministic scene state	规划中

4.4 确定性渲染引擎

渲染管线是 frame-by-frame + seek-driven 的，完全脱离实时播放：

确定性保证的五大规则：

1. 无墙钟依赖——不用 Date.now()、requestAnimationFrame 或系统计时器
2. 无未种子随机——Math.random() 不带 seed 会破坏确定性（使用 seeded PRNG 如 mulberry32）
3. 无渲染时网络请求——所有资源必须渲染前加载完毕
4. 固定输出参数——fps、width、height 在首帧前锁定
5. 有限时长——每个 Composition 都有已知的、有限的持续时间

7 条铁律清单

编写或修改 Composition 时必须遵守：

1. 注册所有 Timeline 到 window.\_\_timelines
2. 视频元素必须 muted，音频用 <audio\>
3. 禁止 Math.random\(\)，用 seeded PRNG
4. 同步构建 Timeline，不用 async/await
5. 定时元素加 class="clip" + data-start + data-duration + data-track-index
6. 每个场景加入场动画（无动画的元素在视频中会"闪现"）
7. 场景间加转场（跳切几乎总是无意的） 前 5 条是技术要求（违反会产生错误渲染），后 2 条是最佳实践。

4.5 Skills 系统

HyperFrames 采用 Vercel Labs 的 skills 规范，把框架模式教给 AI Agent：

Skill	教什么
/hyperframes	HTML Composition 编写、字幕、TTS、音频反应动画、转场
/hyperframes-cli	CLI 命令：init / lint / preview / render / transcribe / tts / doctor
/hyperframes-registry	Block 安装（hyperframes add \<block-name\>）
/gsap	GSAP 动画 API、时间线、缓动、ScrollTrigger、插件

安装方式：npx skills add heygen-com/hyperframes

类比：Skills 就像给 AI 发了一份"岗位说明书"，告诉它"你是视频制作专家，这些是你的工具和规范"。

4.6 提示词词汇表（Vocabulary Table）

提示词工程的核心是将自然语言形容词映射到框架设置：

Motion & Easing

用户说	Agent 使用	效果
smooth	power2.out	自然减速
snappy	power4.out	快速果断
bouncy	back.out	过冲后回弹
springy	elastic.out	弹性振荡
dramatic	expo.out	快启动长滑行
dreamy	sine.inOut	慢速对称

Timing Shorthand

用户说	时长	感觉
fast	0.2s	充满活力
medium	0.4s	专业标准
slow	0.6s	奢华质感
very slow	1-2s	电影感

Caption Tone

风格	字体	动画	字号
Hype	粗体字	Scale-pop	72-96px
Corporate	无衬线	Fade + slide	56-72px
Tutorial	等宽字体	打字机	48-64px
Storytelling	衬线	慢速淡入	44-56px
Social	圆角活泼	弹跳	56-80px

Transition

能量	CSS 方案	Shader 方案
Calm	模糊交叉淡入	交叉扭曲变形
Medium	推入滑动	快速平移
High	缩放穿越	故障/燃烧

Audio-Reactive

音频频段	映射属性	视觉效果
Bass（低频）	scale	跟着节拍脉冲
Treble（高频）	glow	闪烁强度
Amplitude（振幅）	opacity	呼吸感
Mids（中频）	shape	形态变形

Marker Highlights

模式	效果	适用
highlight	荧光笔划过	关键词强调
circle	手绘椭圆	单词圈注
burst	放射线	hype 时刻
scribble	涂划线	划掉内容
sketchout	矩形框	标注区

TTS 语音选择

内容类型	推荐语音
产品 Demo	af\_heart, af\_nova
教程讲解	am\_adam, bf\_emma
营销推广	af\_sky, am\_michael

---

第五章：系统架构

5.1 整体架构

🖼 飞书画板（暂不支持内嵌预览，请在原文查看）

5.2 Monorepo 包结构

packages/
├── cli/                    # CLI 工具：create, preview, lint, render
├── core/                   # 基础：类型、解析器、生成器、运行时、Linter
├── engine/                 # 可 seek 的页面→视频捕获引擎
├── producer/               # 完整渲染管线（capture + encode + audio mix）
├── studio/                 # 浏览器内可视化编辑器
├── player/                 # 可嵌入的 <hyperframes-player> Web Component
└── shader-transitions/     # WebGL Shader 转场效果

5.3 Catalog（Block 生态）

50+ 预制 Block，涵盖四大类：

类别	示例	安装方式
社交叠加层	Instagram Follow、YouTube Subscribe	npx hyperframes add instagram-follow
Shader 转场	Flash Through White、Dissolve	npx hyperframes add flash-through-white
数据可视化	Animated Chart	npx hyperframes add data-chart
电影级特效	Cinematic Bars、Light Leaks	浏览 Catalog 选择

5.4 两种 Prompt 形态

类型	描述
冷启动	从零描述视频。指定时长、画幅比例、风格、核心元素。例：Using /hyperframes, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
暖启动	给 Agent 素材（URL/文档/CSV/PDF），让它综合后生成视频。优势：研究/总结 + 制作一步到位。例：Take a look at this GitHub repo and explain its architecture using /hyperframes.

---

第六章：关键流程

6.1 AI Agent Cold Start（从零生成）

🖼 飞书画板（暂不支持内嵌预览，请在原文查看）

6.2 Warm Start（内容转化）

用户可以给 Agent 任意上下文，Agent 自动提取内容并生成视频：

"把这个 CSV 数据转成一个动态柱状图竞赛视频，用 /hyperframes"
"Summarize this changelog into a 30-second release announcement video using /hyperframes"

Agent 处理步骤：解析数据 → 生成 Composition → 配置时间轴 → 预览 → 迭代 → 渲染

6.3 提示词迭代模式

HyperFrames 是对话式创作系统。第一次生成后，用小步迭代：

好的方式（精准修改）：

• "Make the title 2x bigger"

• "Swap to dark mode"

• "Add a fade-out at the end"

• "Replace the background music with assets/track.mp3" 不好的方式（重新描述）：

• 重新发完整 Prompt——Agent 已经有上下文 核心原则：Agent 已打开 Composition 并加载了 Skills，小而精准的修改比长篇重述效果好得多。

6.4 Prompt 模板

冷启动模板

Using /hyperframes, create a [时长] [视频类型] with [风格描述].
- Aspect ratio: [16:9 / 9:16 / 1:1]
- Mood: [minimal / warm / high-energy / cinematic]
- Elements: [title + subtitles + background video + music]
- Caption style: [Hype / Corporate / Tutorial / Storytelling]
- Transitions: [Calm / Medium / High energy]

暖启动模板

Take a look at [URL / 文件 / CSV] and [动作] using /hyperframes.
- Duration: [时长]
- Focus on: [重点内容]
- Style: [风格]
- Include TTS: [yes/no, voice type]

6.5 反模式（Anti-patterns）

• 不要要求 React/Vue 组件——HyperFrames 是纯 HTML
• 不要要求 4K/60fps 除非真的需要——默认 1920×1080@30fps 已很好
• 不要跳过 /hyperframes Slash Command——没有它 Agent 会"猜"
• 不要直接粘贴错误日志——先跑 npx hyperframes lint 和 npx hyperframes validate
• 不要假设 Agent 知道你的素材路径——明确告诉文件路径

6.6 Block 安装与使用

npx hyperframes add flash-through-white
npx hyperframes add instagram-follow
# Block 会被安装到项目目录，在 Composition 中通过 data-composition-src 引用

---

第七章：和相似技术的关系与区别

竞品对比矩阵

维度	HyperFrames	Remotion	Motion Canvas	MoviePy
定义格式	纯 HTML + data 属性	React 组件	TypeScript API	Python
Agent 友好度	最高（HTML 是 LLM 最擅长）	中（需 React）	低（专有 API）	低（Python）
确定性	逐帧 seek	WebGL capture	逐帧	逐帧
动画运行时	可插拔（GSAP/Lottie/CSS/Three.js）	仅 React + Remotion	仅 Motion Canvas	Python
CLI 非交互	是	部分	否	否
Skills 系统	是（Vercel Skills）	否	否	否
Block 生态	50+ 预制	社区模板	少量	无
TTS 集成	内置 Kokoro	无	无	无
提示词工程	核心能力	不支持	不支持	不支持

关系分析

vs Remotion（最直接竞品）：Remotion 拥抱 React 生态，HyperFrames 回归原生 Web。HyperFrames 核心赌注是：HTML 比 JSX 更适合 Agent 生成。替代关系。

vs Motion Canvas：Motion Canvas 更像"代码版 After Effects"适合手工动画，HyperFrames 更像"代码版 PowerPoint"面向 Agent 快速生成。互补关系。

vs FFCreator / MoviePy：面向"程序员写脚本生成视频"，HyperFrames 面向"Agent 写 HTML 生成视频"。不同赛道。

适用场景决策树

需要 Agent 自动生成视频？
├── 是 → HyperFrames
└── 否 → 手动编写？
    ├── 已有 React 项目？→ Remotion
    ├── 需要精细动画控制？→ Motion Canvas / After Effects
    ├── Python 生态？→ MoviePy
    └── 快速原型？→ HyperFrames

第八章：真实应用场景

场景 1：AI Agent 批量生成短视频

背景：电商团队每天需要在抖音、TikTok、Reels 上发布几十条产品介绍视频。

为什么适合：产品数据是结构化的，Agent 可直接读取；视频模板标准化，适合 Composition 模板化；npx hyperframes render 可脚本化批量渲染。

落地方式：设计 Composition 模板 → 用脚本循环填充产品数据 → CLI 批量渲染 → 自动上传各平台

价值：从"一条视频 2 小时"降到"一条视频 5 分钟"。

场景 2：数据新闻动态可视化视频

背景：新闻媒体想把数据图表做成动态视频发布。

为什么适合：数据驱动的内容天然适合代码生成；GSAP 动画可制作流畅的图表动画；确定性渲染保证同数据同输出。

落地方式：用 data-chart Block 创建基础图表 → 注入数据 → 渲染发布

价值：数据驱动叙事，从表格到视频一步到位。

场景 3：开发者工具 Demo 视频自动生成

背景：开源项目需要为每个 Release 自动生成功能 Demo 视频。

为什么适合：代码 diff / changelog 是结构化文本，Agent 可直接解析；可把终端截图、代码片段组合成视频。

落地方式：从 git log 提取变更 → Agent 生成 Composition → CI/CD 自动渲染并上传

价值：每次发版自动生成宣传视频，零人工。

场景 4：社交模板批量定制

背景：MCN 机构需为 KOL 批量定制视频模板（Instagram Story、TikTok Hook）。

为什么适合：预制 Block（Instagram Follow、YouTube Subscribe）可直接使用；不同 KOL 只是数据不同，模板一样。

落地方式：设计竖屏模板（1080×1920）→ 用 Variables 注入不同素材 → 批量渲染

价值：一套模板覆盖全平台，A/B 测试不同尺寸和文案。

场景 5：教育和知识分享视频

背景：教育平台需要把课程内容自动转化为视频。

为什么适合：课程内容通常是 Markdown/HTML 格式；TTS 集成可把文字转语音；字幕 Block 可自动生成时间轴对齐的字幕。

落地方式：将课程转为 HTML Composition → TTS 生成旁白 → 自动对齐字幕 → 渲染发布

价值：从笔记到视频，全程自动化。

---

第九章：工程落地

9.1 环境要求

依赖	版本	用途
Node.js	≥ 22	运行 CLI 和所有包
FFmpeg	任意最新版	视频编码 + 音频混流
Chrome/Chromium	最新版	Puppeteer 逐帧捕获

9.2 快速开始

# 方式一：Agent 驱动（推荐）
npx skills add heygen-com/hyperframes
# 然后在 Agent 中使用 /hyperframes 命令

# 方式二：手动创建
npx hyperframes init my-video
cd my-video
npx hyperframes preview                  # 浏览器预览（live reload）
npx hyperframes render --output demo.mp4 # 渲染 MP4

9.3 CLI 命令速查

命令	作用
npx hyperframes init \\<name\\\>	创建新项目
npx hyperframes preview	浏览器预览（live reload）
npx hyperframes render	渲染到 MP4
npx hyperframes render --docker	Docker 模式渲染（最大确定性）
npx hyperframes render --quality draft	快速草稿渲染
npx hyperframes render --quality high	高质量渲染
npx hyperframes lint	校验 Composition 结构
npx hyperframes validate	运行时错误检查
npx hyperframes add \\<block\\\>	安装 Catalog Block
npx hyperframes compositions	列出所有 Composition
npx hyperframes transcribe	语音转文字
npx hyperframes tts	文字转语音（Kokoro）
npx hyperframes doctor	环境诊断

9.4 项目结构

my-video/
├── index.html                    # 主 Composition
├── compositions/                 # 嵌套 Composition
│   ├── intro-anim.html
│   ├── caption-overlay.html
│   └── outro-title.html
├── assets/                       # 媒体资源
│   ├── intro.mp4
│   ├── logo.png
│   └── music.wav
└── package.json

9.5 环境变量

变量	作用	默认值
HF\_FPS	渲染帧率	30
HF\_WIDTH	画布宽度	1920
HF\_HEIGHT	画布高度	1080
HF\_OUTPUT	输出文件名	output.mp4

9.6 Docker 部署

# 获得跨平台完全一致的渲染结果
npx hyperframes render --docker --output demo.mp4

Docker 模式保证：同一 Chromium 版本、同一系统字体集、同一 FFmpeg 编码器。

9.7 CI/CD 集成

# GitHub Actions 示例
- name: Render video
  run: npx hyperframes render --docker --output ${{ github.sha }}.mp4
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: video
    path: "*.mp4"

9.8 自定义 Frame Adapter 开发

const myAdapter: FrameAdapter = {
  id: "my-adapter",
  init(ctx) { /* 初始化 */ },
  getDurationFrames() { return 300; },  // 10秒 × 30fps
  async seekFrame(frame) {
    const t = frame / ctx.fps;
    // 把所有动画状态设置到时间 t
  },
  destroy() { /* 清理 */ }
};

9.9 渲染质量控制

质量	用途	特点
draft	快速迭代	速度优先，画质较低
standard	审核反馈	平衡速度与画质
high	最终交付	画质优先，渲染较慢

---

第十章：优缺点与局限

优点

优点	说明
Agent 原生	HTML 是 LLM 最擅长的格式，Skills 系统实现知识注入
确定性渲染	同输入必定同输出，适合 CI/CD 和批量生产
动画运行时可插拔	不绑定特定动画库，GSAP/Lottie/CSS/Three.js 随意切换
零框架依赖	不需要 React/Vue，原生 HTML 即可
CLI 非交互	Agent 可以完全驱动
提示词驱动	词汇表让非技术人员也能精确控制输出
内置 TTS	Kokoro 本地运行，无需 API Key
Block 生态	50+ 预制组件
Docker 模式	跨平台渲染结果完全一致

缺点

缺点	说明
生态早期	v0.4.x，API 可能变化
仅 GSAP Adapter 可用	CSS/Lottie/Three.js Adapter 还在规划中
渲染速度	逐帧捕获比实时编码慢，长视频耗时较长
复杂动画需 GSAP 知识	人类理解和调试仍需学习
GUI 编辑器有限	Studio 仍在开发中
不适合实时视频	离线渲染框架，不适合直播/RTC

不建议使用的场景

• 需要实时交互的视频应用（直播、视频通话）
• 需要 After Effects 级别复杂特效
• 对渲染速度有极致要求
• 纯音频制作（没有视觉内容）
• 非 Agent 驱动且已有成熟视频流程

---

第十一章：常见误区

不是。它是声明式视频合成框架，没有时间线 UI、拖拽、可视化编辑。定位更接近"视频的 Markdown"——用代码定义内容，用命令渲染输出。

完全不需要。HyperFrames 刻意避免了 React 依赖。Composition 是纯 HTML + data 属性 + 原生 JS（GSAP）。

不能。这是最易犯的错误。媒体播放和 Clip 可见性由 data 属性驱动。GSAP 只负责动画效果（位移、透明度、缩放等）。在 GSAP 里写 video.play() 会和框架冲突。

不能。没有它 Agent 会"猜"HTML 视频约定（class="clip"、Timeline 注册等），导致大量结构性错误。

1920×1080@30fps 已经很好了。4K 和 60fps 会显著增加渲染时间，但大多数场景下画质提升不明显。

不需要。Agent 已有上下文。用小步迭代——"标题大一点"、"加个淡入"——比重新描述整个视频效果好得多。

只有 Docker 模式才能保证。本地渲染可能因 Chrome 版本、系统字体差异产生微小差异。

---

第十二章：学习路径

阶段一：入门（1-2 小时）

目标：能创建一个简单 Composition 并渲染成 MP4

• npx hyperframes init demo && cd demo
• 编写 10 秒 Composition（标题 + 背景图 + 背景音乐）
• npx hyperframes preview 预览
• npx hyperframes render --output demo.mp4 渲染
• 检查点：成功渲染含 3 个元素的简单视频

阶段二：进阶（3-5 小时）

目标：掌握 data 属性、嵌套 Composition、GSAP 动画

• 学习 Data Attributes 全部属性
• 学习嵌套 Composition 机制
• 学习 GSAP Animation Guide
• 用 npx hyperframes add 安装 2-3 个 Block
• 检查点：能创建含 5+ 元素、嵌套 Composition、GSAP 动画的视频

阶段三：Agent 集成（2-3 小时）

目标：能让 AI Agent 独立完成视频生成

• 安装 Skills：npx skills add heygen-com/hyperframes
• 阅读 Prompt Guide，掌握词汇表
• 练习 Cold Start、Warm Start、迭代修改三种 Prompt 模式
• 检查点：Agent 能根据自然语言独立生成并渲染视频

阶段四：工程化（3-5 小时）

目标：集成到生产管线

• 配置 Docker 渲染模式
• 集成 CI/CD（GitHub Actions）
• 学习 Deterministic Rendering 原理
• 尝试开发自定义 Frame Adapter
• 检查点：有可复用的渲染管线 + 至少一个自定义 Adapter

阶段五：精通（持续）

• 学习 Common Mistakes 和 Troubleshooting
• 研究源码，参与开源贡献
• 建立 Composition 模板库
• 团队协作规范建立

---

第十三章：必须记住的重点

1. 核心定位：HTML-to-Video 渲染框架，AI Agent 原生设计，不是视频编辑器
2. Composition = HTML + data 属性：不需要 React、不需要专有 DSL、不需要 GUI
3. 两层架构：HTML 层管"播什么"，Script 层管"怎么动"。永远不要在 GSAP 里控制媒体播放
4. Frame Adapter 核心契约：seekFrame 必须幂等、支持任意顺序 seek、无墙钟依赖
5. 确定性 = 逐帧 seek + Chrome capture + FFmpeg encode：不是实时录制
6. Skills 系统 > 文档阅读：通过 Vercel Skills 注入上下文，比让 Agent 读文档猜靠谱得多
7. 词汇表驱动："smooth"→power2.out、"bouncy"→back.out——自然语言直接映射 GSAP 缓动
8. 两种 Prompt：冷启动（从零描述）vs 暖启动（喂素材转化）——暖启动产出更丰富
9. 迭代原则：小步精准修改 > 大段重新描述——Agent 已有上下文
10. Docker 模式 = 跨平台完全一致：对一致性有要求时必须用 --docker

---

第十四章：两版总结

学习笔记版

是什么：HeyGen 开源 HTML-to-Video 框架，Apache 2.0，v0.4.3，7 核心包。

核心公式：HTML Composition（data 属性声明时间轴）+ GSAP Script（命令式动画）+ Frame Adapter（可插拔运行时）→ 逐帧 Seek → Chrome Capture → FFmpeg Encode → MP4

关键概念：

• Composition：带 data-composition-id 的 HTML 文档，视频的"源代码"
• Frame Adapter：回答"第 N 帧画面长什么样"的接口，可插拔
• Deterministic Rendering：无墙钟依赖，逐帧 seek，同输入同输出
• Skills：3 个 Slash Command + 完整词汇表，将框架知识注入 Agent 上下文 关键约束：Script 不控制媒体播放；CLI 非交互式；Docker 保证跨平台一致；Frame Adapter 必须确定性

核心命令：

npx hyperframes init my-video    # 创建项目
npx hyperframes preview          # 浏览器预览
npx hyperframes render           # 渲染 MP4
npx hyperframes add <block>      # 安装 Block
npx skills add heygen-com/hyperframes  # 安装 Skills

讲给别人听版

你知道怎么用代码生成视频吗？传统做法是用 After Effects 之类的 GUI 工具，手动拖时间线、调关键帧。这事儿人做还行，但 AI Agent 做不了——它不会"拖东西"。

HyperFrames 的思路特别直接：视频不就是一帧一帧的画面吗？那我就把每一帧当作网页截图来做。你写一个 HTML 文件，像做网页一样定义标题、图片、视频、音频，给每个元素标注"第几秒出现、持续几秒、在第几层"。然后告诉引擎"从第 0 帧到第 300 帧，每一帧都截图，最后用 FFmpeg 拼成视频"。

因为每一帧都是独立 seek 出来的（不是实时录制），所以同样输入永远得到同样输出——这对批量生产和 CI/CD 至关重要。

它最大的创新点是 Frame Adapter 模式：动画不绑定特定库。不管你用 GSAP、Lottie、CSS 还是 Three.js，只要你能回答"第 N 帧画面长什么样"，就能接入渲染管线。

另一个创新是 Skills 系统 + 词汇表：它不指望 AI 自己读文档学会用法，而是通过 Slash Command 注入框架知识。你只需要说"smooth"（平滑）、"bouncy"（弹跳）这样的日常词汇，AI 就会自动翻译成专业的动画代码。

简单说，HyperFrames 就是把视频生产从 GUI 拉回到了代码层，让 AI Agent 能像生成网页一样生成视频。

---

信息来源：

• GitHub 仓库：https://github.com/heygen-com/hyperframes
• 官方文档：https://hyperframes.heygen.com/introduction
• Prompt Guide：https://hyperframes.heygen.com/guides/prompting
• Compositions 概念：https://hyperframes.heygen.com/concepts/compositions
• Frame Adapters：https://hyperframes.heygen.com/concepts/frame-adapters
• 确定性渲染：https://hyperframes.heygen.com/concepts/determinism
• GSAP 动画指南：https://hyperframes.heygen.com/guides/gsap-animation