用 AI 写 HyperFrames 视频，我用 pi 跑了全流程

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 校验

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

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

第三步：预览和渲染

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，里面有每个版本的具体变更，比文档更新及时得多。

# 获取某个版本的完整 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 合成：

纯文字动画：打字机效果 + 淡入，5 秒
数据卡片：动态数字 + 进度条，8 秒
产品展示：图片 + 文字组合，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 其实够用了||原来可以这样用

📄 文档管理系统