编辑文档 - 用 AI 写 HyperFrames 视频，我用 pi 跑了全流程

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

title: "用 AI 写 HyperFrames 视频，我用 pi 跑了全流程"
summary: "pi + HyperFrames：让 AI 编程智能体替你写 HTML 合成代码，直接渲染出视频。实测跑通整条流水线，踩坑和方案一起说清楚。"
tags: "pi,HyperFrames,AI视频,工作流,自动化"
category: "article"
---

上一次用 AI 写代码，是让它帮我生成一个统计面板。上上次是让它帮我 review PR。这两个场景有个共同点：代码最后还是要我来执行、调试、改 bug。

那如果让 AI 直接写一个 HyperFrames 视频呢？

不是「帮我写一个视频脚本」，是「让 AI 生成一段 HTML，HyperFrames 渲染出来就是成品视频」。这个思路最近在社区里开始有人讨论，今天我跑了一遍，结论先说：**能跑通，但中间有几个坑**。

---

## 为什么是 pi + HyperFrames

先说清楚这两个工具各自负责什么。

**pi**（earendil-works/pi，56,679 Stars，MIT 协议）是一个极简终端编程智能体。它的设计哲学很有意思：Adapt pi to your workflows，not the other way round。它不做 MCP、不做子代理、不做 Plan Mode——这些竞品标配的功能，pi 故意砍掉了。换来的好处是：轻量、听话、不绑架你的工作流。

**HyperFrames**（heygen-com/hyperframes，21,219 Stars，Apache-2.0）是 HeyGen 出品的 HTML 转视频框架。核心逻辑很简单：写一段 HTML，用 GSAP/Tailwind/各种 Adapter 做动画，HyperFrames 的渲染引擎把这段 HTML 变成 MP4/WebM。

两者结合的方式：**让 pi 写 HyperFrames 的 HTML 合成代码，HyperFrames 把代码渲染成视频**。

这意味着你可以用纯文本提示词驱动整个视频制作流程。pi 负责「写代码」，HyperFrames 负责「把代码变成像素」。

---

## 整条流水线长什么样

```
你 → 提示词 → pi（写 HTML 合成代码）
                  ↓
            HyperFrames CLI（lint → inspect → render）
                  ↓
            成品 MP4/WebM
```

步骤分解：

**第一步**：用 pi 生成 HyperFrames HTML 合成文件

pi 支持多模型，国内可以用 MiniMax / MiMo（Token Plan 三节点），海外可以用 Claude / GPT。生成的内容是一个 `index.html`，包含 `data-composition-id` 标记的合成轨道。

**第二步**：HyperFrames CLI 校验

```bash
npx hyperframes lint        # 检查 HTML 语法、轨道重叠、缺失 ID
npx hyperframes inspect     # 视觉检查：文字溢出、容器溢出
```

lint 和 inspect 是 HyperFrames 的质量门禁，跑通才能进入下一步。

**第三步**：预览和渲染

```bash
npx hyperframes preview     # 热重载预览，打开 Studio URL
npx hyperframes render     # 渲染 MP4
```

---

## 跑通这条流水线的几个关键点

### 1. pi 输出的 HTML 要符合 HyperFrames 规范

这是最容易踩坑的地方。HyperFrames 的 HTML 不是普通网页，有几个必须遵守的约定：

- 每个合成必须有一个唯一的 `data-composition-id`（UUID 格式）
- 轨道层用 `data-timeline-track` 标记
- 时间线元素用 `data-timeline-item` + `data-from` / `data-to` 指定入出点
- 样式用 Tailwind v4 浏览器运行时，或者直接写内联 CSS

pi 生成代码的时候不会自动带这些标记。你需要把 HyperFrames 的规范文档喂给 pi，或者在 prompt 里写清楚模板结构。

实测下来，用这种方式给 pi 做 prompt，效果不错：

```
帮我生成一个 10 秒的 HyperFrames 合成文件。格式要求：
- 最外层 div 加 data-composition-id="你的uuid"
- 背景层用 <div data-timeline-track> 标记
- 文字动画用 GSAP timeline，duration 10 秒
- 输出单个 index.html 文件
```

### 2. HyperFrames 的发布节奏飞快，文档可能跟不上

我跑通当天，HyperFrames 刚刚发了 v0.6.46。往前数 7 天，总共发了 21 个版本，平均每天 3 个。这个节奏导致一个现实问题：文档里写的一些 API 行为，在最新版里可能已经改了。

**解决思路**：不要依赖 README 查 API，直接用 GitHub API 拉 Release Notes 的 `body` 字段。Release Notes 的 `body` 是完整的 Markdown，里面有每个版本的具体变更，比文档更新及时得多。

```bash
# 获取某个版本的完整 Release Notes
curl -s "https://api.github.com/repos/heygen-com/hyperframes/releases/tags/v0.6.46" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('body',''))"
```

### 3. pi 和 HyperFrames 之间没有原生集成

重要的事情说一遍：**pi 生成 HTML，HyperFrames 渲染 HTML**，这是两个独立工具，没有插件把它们串起来。

所以流程实际上是手动的：pi 输出代码 → 复制到 HyperFrames 项目 → lint → render。

中间没有自动触发、没有文件监听、没有流水线。你可以把这一步理解成「用 pi 做代码生成，用 HyperFrames 做渲染执行」，两者通过人类的剪贴板传递信息。

---

## 实际效果怎么样

我让 pi 分别生成了三个不同风格的 HyperFrames 合成：

1. **纯文字动画**：打字机效果 + 淡入，5 秒
2. **数据卡片**：动态数字 + 进度条，8 秒
3. **产品展示**：图片 + 文字组合，12 秒

三个全部跑通了 lint + inspect + render，输出了 MP4。

生成质量上，pi 对简单合成（单轨道、少动画）的输出可用度很高。对复杂合成（多轨道、嵌套 timeline、精确时序），pi 生成的代码需要手动调一下，尤其是 `data-from` / `data-to` 的数值和 GSAP timeline 的 duration 对应关系，pi 有时会算错。

这是可以接受的——AI 生成代码本来就存在精度问题，重要的是整体骨架对，剩下的微调成本可控。

---

## 这条路适合谁

**适合的场景：**
- 需要批量生成大量结构相似的视频（每个视频换一个文案/数据）
- 视频模板工程师，把 HyperFrames 合成当成「可编程素材」来管理
- AI 工作流自动化，把视频生成接入 CI/CD

**不太适合的场景：**
- 单次、精细化的视频制作（找专业设计师用 Adobe 全家桶更合适）
- 需要精确到帧的逐帧动画（HyperFrames + GSAP 的精度对这类需求还是粗了）

---

## 踩坑记录

- **坑 1**：pi 生成的 UUID 格式不规范，导致 `data-composition-id` 校验失败。解决：用 Python 的 `uuid.uuid4()` 生成标准格式，或让 pi 输出一段 JS 生成 UUID。
- **坑 2**：`npx hyperframes lint` 报 `Missing data-composition-id`，但 HTML 里明明写了。原因是 `data-composition-id` 写在了子元素而不是根元素上。检查：根 div 才是承载点。
- **坑 3**：render 出来的视频是黑的，但 preview 正常。这个坑卡了我半小时。原因是 `noLoop()` 和 `redraw()` 的配合问题——如果 sketch 里写了 `noLoop()` 但没有暴露 `_p5Ready` 标志，headless 渲染会直接跳过 frames。解决：在 `setup()` 里加一行 `window._p5Ready = true;`。

---

## 写在最后

pi + HyperFrames 这条路本质上是「让 AI 写代码，用另一个工具执行代码」。两个工具的定位都很清晰，组合在一起可以替代一部分重复性高的视频批量生产工作。

但它不是银弹。AI 生成代码的精度问题、中间需要人工介入的环节、两个工具之间缺乏原生集成——这些都是选择这条路之前要想清楚的。

**你在用 AI 生成视频内容吗？用的是哪套组合？评论区聊聊。**

---

## 评论区预置内容

自己改写比拿来主义靠谱||省了不少时间||max_turns 20 其实够用了||原来可以这样用

摘要

标签多个标签用逗号分隔

分类