🧩 两种资产，两条路线

HyperFrames 的核心思路是“写 HTML，渲染视频”——你把画面、动画、时间轴都用 HTML 和 CSS 写出来，框架负责把它们渲染成确定性的 MP4。hyperframes-registry 是这个体系里管“素材”的那一环。

它把注册表里的可复用资产分成两类，理解这个分类是使用一切命令的前提：

Blocks（区块）——独立的子合成，自带尺寸、时长和 GSAP 时间轴。装进项目之后，通过宿主合成里的 data-composition-src 属性被引用进来。典型代表有数据图表、代码动画、shader 转场、VFX 特效块、社交卡片等。可以把它想象成“插进时间线里的一段独立影片”。

Components（组件）——效果片段，不拥有自己的尺寸或时间轴。安装后需要手动把它的 HTML、CSS、JS 合并进宿主合成的对应位置，由宿主合成的时间线来驱动。典型代表有 grain-overlay（胶片颗粒）、shimmer-sweep（光泽扫过）、morph-text（文字变形）等。

目前官方注册表收录了 97 个区块，按 shader 转场、转场画廊、字幕样式、VFX 等类别组织，数量还在增长。

📦 第一次怎么装

hyperframes-registry 是一个 Agent Skill，通过 skills CLI 安装到你的 AI 编码工具中：

npx skills add https://github.com/heygen-com/hyperframes --skill hyperframes-registry

如果你想把 HyperFrames 全套核心技能一次装好，也可以直接跑 npx skills add heygen-com/hyperframes，然后在选择器中勾选你需要的技能。

装好之后，你需要确保本机可以运行 hyperframes CLI 命令。hyperframes-registry 本身只负责“指挥”，实际的安装操作由 npx hyperframes add 执行，不需要额外安装全局依赖。

有一个小细节值得注意：skills add 解析的是 skills.sh 上的注册表快照，可能比 GitHub main 分支慢几个小时。如果你需要最新的 skill 版本，用 npx hyperframes skills update 直接从 main 拉取。

🛠️ 装好之后怎么用

先搜，再装

注册表里的内容比你能用肉眼扫一遍的多得多，所以不要翻列表，用 catalog 命令按意图搜索：

npx hyperframes catalog --query "reveal a headline one line at a time"

搜索是本地执行的，不会向外部发送任何数据。默认按词汇匹配排序，加 --on-device 可以切换为语义匹配（需要一次性下载模型）。如果你想自己浏览，也可以用 --type block 或 --tag social 做筛选。

安装命令

确定要装什么之后，核心命令就一条：

hyperframes add data-chart

这个命令有几种用法值得记住：如果参数是一个精确的项目名，就装那一个；如果参数是一个标签（比如 captions），会把所有带这个标签的区块都装上。加 --dir . 可以指定目标项目目录，加 --json 输出机器可读的结果，加 --no-clipboard 在 CI 环境中跳过剪贴板操作。

默认安装位置是：区块进 compositions/<name>.html，组件进 compositions/components/<name>.html。如果你想把它们放到别的目录，在项目的 hyperframes.json 里改 paths 配置就行。

把装好的东西“接”进画面

这一步是 hyperframes-registry 区别于普通“素材下载”的地方——它不只是装文件，还管接线。

接线区块：在 index.html 里加一个 div，带上这几个属性：

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

data-composition-id 必须和区块内部的合成 ID 一致，data-start 是它在时间轴上出现的时间，data-track-index 控制图层顺序（值越大越靠前）。

接线组件：组件是代码片段，需要手动合并——把它的 HTML 元素复制到你的合成容器里，CSS 复制到样式块里，JS 复制到脚本区（放在时间轴代码之前）。如果组件暴露了 GSAP 时间轴集成点，还要把对应的调用加到你的 timeline 里。

💡 几个让它更好用的技巧

  • 用语义搜索替代翻列表。注册表已经有 97 个区块，靠名字猜很难找到合适的。试试 npx hyperframes catalog --query "用打字机效果逐字显示一段提示词"，让它按意思去匹配。
  • 安装后先看 CLI 打印的片段。每次 add 完成后，CLI 会告诉你写了哪些文件，并给出一段可粘贴到宿主合成里的起始代码。那段代码里的 data-start 和 data-track-index 通常需要你根据实际时间轴调整，不要原样粘贴就完事。
  • 区块的依赖会自动安装。如果你装的那个区块依赖另一个注册表项，hyperframes add 会先把依赖装好再装你指定的那个，不需要手动处理。
  • 区块和示例是两回事。hyperframes add 只管区块和组件。如果你想要一个完整的示例项目作为起点，应该用 hyperframes init <dir> --example <name>，它会在新目录里生成一个可预览的完整项目。
  • 配合 hyperframes 主技能使用。hyperframes-registry 负责“装和接”，但视频的时间轴设计、GSAP 动画编排、渲染预览这些创作工作，交给 /hyperframes 这个路由技能处理。两个技能搭配使用，覆盖从素材到成片的完整链路。

🤖 适合哪些 AI 工具

hyperframes-registry 是一个标准的 Agent Skill，不绑定特定平台。HyperFrames 官方把它设计成“first-class support for AI agents”，所以对 AI 编码工具的兼容性做得比较到位。

目前经过验证的兼容工具包括：Claude Code、Cursor、Gemini CLI、Codex CLI、Windsurf，以及其他支持 Agent Skill 工作流的工具。在 Claude Code 中，这些技能会注册为斜杠命令，直接输入 /hyperframes-registry 即可触发。

需要留意的是，hyperframes-registry 只负责“安装和接线”这一环。它不生成视频内容，也不替代 HyperFrames 主技能进行创作编排。如果你的需求是“帮我做一个 10 秒的产品介绍”，应该从 /hyperframes 入口进入，让路由技能来决定何时调用 registry 来装素材。