HyperFrames 官方 Registry 指南：让 Agent 自动查、拉、挂、验

使用 HyperFrames 官方 Registry 的可靠流程是：先用 catalog 查询真实名称和类型，再用 add 安装到项目，检查 Block 的 Composition ID、变量和接入片段，完成 Host 挂载后执行 lint、check、snapshot 和 preview，确认后再渲染。

为什么应该先查 Registry，再让 Agent 写代码

HyperFrames 最有价值的能力之一，是把已经验证过的画面、字幕、代码演示、转场和视觉效果整理成 Registry Item，让开发者和 AI Agent 可以像使用包管理器一样进行发现和安装。

这意味着，面对“制作一个终端场景”时，不应该默认进入：

AI 重新写 HTML
→ 重新写终端 CSS
→ 重新写打字动画
→ 重新处理时间轴
→ 重新排查渲染错误

更有效的顺序是：

Catalog 搜索
→ 找到合适 Block
→ 安装到项目
→ 查看变量与使用说明
→ 挂载到主 Composition
→ 替换数据
→ 检查和预览

这正是“从 AI Coder 到 AI Layout Driver”的第一步：优先使用已经存在的能力，只有 Registry 无法满足需求时，才创建新的 Block。

当前官方 Registry 有多少内容

截至 2026 年 7 月 25 日，HyperFrames 官方 Registry Manifest 中共有 146 个条目：

Registry 会持续更新，因此教程不应该长期写死“官方有 150+ 个组件”，也不应该假设某个通用名称一定存在。

最可靠的真值永远是当前项目配置的 Catalog：

npx hyperframes catalog --json

如果文章、Prompt 或旧项目里写了 terminal-block、code-editor、stat-counter、bento-grid 等名称，应该先查询。它们可能只是描述性叫法，不一定是当前 Registry 的精确 Item Name。

Block、Component 和 Example 的区别

Block：独立场景或预合成

Block 是一个独立 HyperFrames Composition，通常拥有：

• 固定画幅
• 固定或建议时长
• 完整 HTML 和 CSS
• 自己的 Timeline
• 自己的 Composition ID
• 可选变量和媒体

Block 通过 data-composition-src 进入主 Composition。

适合：

• 代码演示
• 终端场景
• 数据图表
• Lower Third
• 完整字幕样式
• Shader 或转场场景
• 标题页

Component：合并进现有场景的片段

Component 没有自己的独立画幅和时长，通常是一组：

• HTML
• CSS
• 可选 JavaScript
• 可选 Host Timeline 调用

安装后需要把对应部分合并到现有 Composition 中。

适合：

• Grain Overlay
• Shimmer
• Vignette
• 字幕文字效果
• 局部 Glitch
• Morph Text
• Parallax Effect

Example：项目示范

Example 用来初始化或参考完整项目，通常不通过普通 Block 的方式接入。

对于 Example，应该使用当前 CLI 支持的 init --example 流程，而不是把它当作 Block 执行 add。

当前 Catalog 中有哪些实用内容

以下名称来自 2026 年 7 月 25 日的官方 Registry 清单。Catalog 更新后，以实际查询结果为准。

代码和终端类 Block

当前没有一个精确名称叫 terminal-block，但有一组更具体的终端主题：

code-snippet-apple-terminal-basic
code-snippet-apple-terminal-clear-dark
code-snippet-apple-terminal-clear-light
code-snippet-apple-terminal-homebrew
code-snippet-apple-terminal-ocean
code-snippet-apple-terminal-pro
code-snippet-apple-terminal-solid-colors

还有：

code-typing
code-diff
code-highlight
code-scroll
code-morph
code-snippet-dark-modern
code-snippet-monokai
code-snippet-visual-studio-dark
code-shader-dissolve
code-particle-assemble

AI 教程可以先搜索：

npx hyperframes catalog --type block --json

然后在 JSON 结果中筛选 code 或 terminal。

数据和流程类 Block

当前可以确认的名称包括：

data-chart
flowchart
flowchart-vertical

不要直接假设 stat-counter 存在。需要数字大字报时，应先搜索 data、number、chart 等标签或名称；如果没有合适结果，再复用自己的 Big Number Block。

转场和视觉效果 Block

当前清单中包括：

flash-through-white
whip-pan
glitch
ripple-waves
chromatic-radial-split

还包括按类型组织的转场集合：

transitions-3d
transitions-blur
transitions-cover
transitions-destruction
transitions-dissolve
transitions-distortion
transitions-grid
transitions-light
transitions-mechanical
transitions-push
transitions-radial
transitions-scale

Lower Third

当前可确认：

yt-lower-third
lower-third-bild

lower-third 本身不是当前 Manifest 中的精确名称，因此安装前必须 Catalog 查询。

常用 Component

当前 Component 包括：

grain-overlay
shimmer-sweep
motion-blur
vignette
morph-text
parallax-zoom
parallax-unzoom
caption-highlight
caption-matrix-decode
caption-glitch-rgb
caption-kinetic-slam
caption-gradient-fill
caption-neon-glow
caption-pill-karaoke

Component 和 Block 的接入方式不同，不能只看名称就统一使用 data-composition-src。

正确的 Catalog 命令

当前推荐的查询入口是：

npx hyperframes catalog

而不是：

npx hyperframes registry list

常用查询：

# 查看全部条目
npx hyperframes catalog

# 只查看 Block
npx hyperframes catalog --type block

# 只查看 Component
npx hyperframes catalog --type component

# 按标签筛选 Block
npx hyperframes catalog --type block --tag social

# 输出 JSON，适合 Agent 和 CI
npx hyperframes catalog --json

# 打开交互式选择器并安装选中内容
npx hyperframes catalog --human-friendly

对于 AI Agent，优先使用：

npx hyperframes catalog --json

因为 Agent 可以解析结构化输出，再明确选择 Item Name，而不是从终端表格或模糊描述里猜名称。

正确的安装命令

安装 Block 或 Component：

npx hyperframes add <name>

例如：

npx hyperframes add code-snippet-apple-terminal-basic
npx hyperframes add data-chart
npx hyperframes add flash-through-white
npx hyperframes add caption-highlight

适合 Agent 和 CI 的参数：

# 机器可读输出
npx hyperframes add data-chart --json

# 不复制 Snippet 到剪贴板
npx hyperframes add data-chart --no-clipboard

# 明确目标项目目录
npx hyperframes add data-chart --dir .

如果传入的是精确 Item Name，CLI 安装这个 Item；如果没有精确名称但匹配到一个标签，CLI 可能安装该标签下的多个 Block。因此自动化流程中应优先使用 Catalog 返回的精确名称。

add 执行后到底发生了什么

hyperframes add <name> 主要完成：

1. 读取当前项目的 Registry 配置
2. 解析目标 Item
3. 先安装 Registry 依赖
4. 把文件写入配置的项目路径
5. 输出文件清单
6. 输出接入 Snippet
7. 在允许时把 Snippet 复制到剪贴板

但需要注意三个容易误解的地方。

1. 默认不是下载到 registry/blocks

官方默认路径通常是：

Block     → compositions/<name>.html
Component → compositions/components/<name>.html

由 hyperframes.json 控制：

{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

registry/blocks/ 更适合 Registry 源码仓库，而不是普通项目的默认安装目录。

2. add 不等于自动组装进 index.html

CLI 会给出 Snippet，但通常仍需要开发者或 Agent：

• 检查安装文件
• 补充 Host 时间属性
• 确认 Composition ID
• 设置 Track
• 传入变量
• 把 Snippet 放进主 Composition

不能理解成执行 add 后，Block 自动出现在最终视频时间线上。

3. hyperframes.json 不是已安装 Item 的锁文件

hyperframes.json 主要保存：

• Registry 地址
• Block 安装路径
• Component 安装路径
• Assets 路径
• 其他项目配置

为了保证团队和 CI 可以复现，应该把安装后的本地 Block 文件、配置和项目依赖一起提交到版本控制，而不是只依赖以后再次拉取 Registry 的最新版本。

Block 的正确挂载方式

假设安装：

npx hyperframes add data-chart

CLI 默认把文件写到：

compositions/data-chart.html

主 Composition 中挂载：

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

最关键的规则是：

Host 的 data-composition-id 必须与 Block 内部的 Composition ID 完全一致。

不能为了表示场景顺序，随意写成：

data-composition-id="scene-03"

除非 Block 内部的 ID 本身就是 scene-03。

Block 实例位于视频的第几幕，应该由 Host 的 ID、外层结构或 Scene JSON 记录，不应该破坏内部 Composition ID 合约。

Block 变量应该怎样传递

不要假设每个 Block 都支持同样的变量名。

安装后先检查：

<html data-composition-variables='[...]'>

或者使用 CLI、Studio 提供的变量信息。

如果 Block 声明了：

[
  {
    "id": "title",
    "type": "string",
    "label": "Title",
    "default": "Quarterly Growth"
  },
  {
    "id": "accent",
    "type": "color",
    "label": "Accent",
    "default": "#48F7B2"
  }
]

Host 使用：

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="4"
  data-duration="8"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
  data-variable-values='{
    "title": "AI 视频产量",
    "accent": "#48F7B2"
  }'
></div>

不要使用未经 Block 支持的内嵌格式：

<script type="application/json">
  {
    "COMMAND": "..."
  }
</script>

除非该 Block 的文档明确实现了这种自定义读取逻辑。HyperFrames 标准的 Sub-composition 实例变量入口是 data-variable-values。

在 CI 中建议使用：

npx hyperframes check --strict-variables

让未声明变量、类型错误和非法枚举值直接失败。

Component 的接入方式不同

Component 不是独立 Composition，通常不能直接这样写：

<div data-composition-src="compositions/components/grain-overlay.html"></div>

标准流程是：

1. 安装 Component
2. 打开安装后的 HTML
3. 阅读文件头部使用说明
4. 把 HTML 节点合并进 Host Composition
5. 把 CSS 合并进 Host 的 <style>
6. 把必要 JavaScript 放到 Host Timeline 之前
7. 如果 Component 暴露 Timeline 调用，把调用加入 Host Timeline

例如 Grain Overlay 可能只需要：

<div id="grain-overlay" aria-hidden="true">
  <div class="grain-texture"></div>
</div>

而 Shimmer 一类 Component 可能还需要 Host Timeline 调用。

所以 Agent 必须先读取安装文件，不能把所有 Registry Item 都按 Block 方式挂载。

不要假设每个 Item 都有 demo.html

Registry Item 通常至少包含：

<name>.html
registry-item.json

不同 Item、Registry 页面和开发阶段可能还有预览或 Demo 资源，但不能把“每个 Component 都附带可直接打开的 demo.html”当作固定合约。

更可靠的预览方式是：

Catalog 信息
→ 安装文件说明
→ 独立测试 Composition
→ snapshot
→ preview

如果是自己维护的 Registry，可以主动为每个 Item 建立 Demo 和 Snapshot，但这是团队规范，不应该冒充官方对所有 Item 的保证。

如何安装 HyperFrames Agent Skills

官方仓库提供了 Skills 安装方式：

npx skills add heygen-com/hyperframes --full-depth

安装后，Agent 可以获得 HyperFrames 的入口路由、Composition 合约、Registry、CLI、动画、媒体和创意工作流知识。

但“安装了 Skills”不等于 Agent 可以无条件自动操作所有项目。

它仍然需要：

• 当前工作目录权限
• 执行 CLI 的权限
• 网络访问或已经缓存的 Registry
• 正确的 Node.js 和 FFmpeg 环境
• 清晰的视频 Brief
• 最终预览审批

Skills 解决的是“Agent 知道应该怎样做”，不是自动消除环境、权限和内容质量问题。

Agent 自动查、拉、挂、验的推荐流程

不要把自动化流程写成：

查 → 拉 → 直接 render

更可靠的是：

1. 查：catalog --json
2. 选：根据 Brief 和 Catalog 选择精确 Item
3. 拉：add <exact-name> --json
4. 读：检查安装文件、ID、变量和使用说明
5. 挂：把 Block 或 Component 正确接入 Host
6. 填：传入声明过的变量
7. 验：lint / check / snapshot
8. 看：preview
9. 批：人工确认
10. 渲：render

为什么必须有“读”这一步

即使名称相似，不同 Block 也可能有不同：

• Composition ID
• 宽高
• 默认时长
• 变量名称
• 支持的 Theme
• 需要的媒体
• 依赖文件
• 接入方式

Agent 不应该安装后立即凭经验组装。

给 Agent 的黄金提示词

请使用当前项目已安装的 HyperFrames Skills 完成 Registry 复用，不要默认从零写 HTML 和 GSAP。

执行顺序：

1. 读取 BRIEF.md、STORYBOARD.md、frame.md、hyperframes.json 和现有 compositions。
2. 运行 `npx hyperframes catalog --json`，根据实际输出查找适合本任务的 Block 或 Component。
3. 不得假设 `terminal-block`、`code-editor`、`bento-grid` 等描述性名称真实存在，必须使用 Catalog 返回的精确 Item Name。
4. 优先复用已安装 Item；需要新增时，使用 `npx hyperframes add <exact-name> --json --no-clipboard`。
5. 安装后读取文件和 registry-item 信息，确认：
   - 类型是 Block 还是 Component
   - Block 内部 Composition ID
   - 宽度、高度和默认时长
   - 声明的变量及类型
   - 依赖和使用说明
6. Block 使用 `data-composition-src` 挂载，Host ID 必须与内部 Composition ID 一致。
7. 变量只通过 Block 声明的 `data-variable-values` 传入，不创建未经支持的数据插槽。
8. Component 按安装文件说明合并 HTML、CSS 和 JavaScript，不得当作独立 Block 挂载。
9. 除非确认 Registry Item 无法满足需求，否则不要重写其内部 GSAP Timeline。
10. 完成后运行：
    - `npx hyperframes lint`
    - `npx hyperframes check --strict-variables`
    - 为每个新 Block 抽取至少一个可见中点 Snapshot
11. 检查通过后打开 `npx hyperframes preview`。
12. 最终预览未经确认，不执行高质量 render。

输出汇报：
- Catalog 中选择了哪些 Item
- 每个 Item 的精确名称和类型
- 安装了哪些文件
- 在哪个时间和 Track 挂载
- 使用了哪些变量
- lint/check/snapshot 结果
- 仍需人工确认的视觉问题

一个 AI 教程视频的 Registry 选型示例

假设主题是“3 分钟介绍 AI 编程工具”。

Agent 不应该直接写：

使用 terminal-block、code-editor 和 bento-grid

而应该先执行 Catalog，然后根据当前可用内容输出选择计划：

安装候选：
- code-snippet-apple-terminal-basic：终端命令演示
- code-diff：代码修改前后对比
- data-chart：数据图表
- flash-through-white：章节切换
- caption-highlight：关键词字幕高亮

然后按类型分别处理：

这比要求 Agent 使用一组可能不存在的通用名称更稳定。

怎样管理自己的自定义 Block

仅仅把文件放入：

registry/blocks/my-tutorial-card/

不代表普通项目中的 hyperframes add my-tutorial-card 一定能找到它。

要让 CLI 正式发现自定义 Registry Item，需要：

Registry Manifest
+ Item 目录
+ registry-item.json
+ Item 源文件
+ hyperframes.json 中可访问的 Registry 地址

如果只在单个项目中使用，最简单的方法是：

直接把通过检查的 Block 放入 compositions/
→ 提交 Git
→ 在主 Composition 中引用

如果需要跨多个项目使用，再建立私有或共享 Registry：

my-registry/
  registry.json
  blocks/
    my-tutorial-card/
      registry-item.json
      my-tutorial-card.html

并让 hyperframes.json 指向可访问的 Manifest。

这也是为什么官方 Registry 使用指南和自定义 Registry 流水线应该分开：

• 官方 Registry 篇解决“怎样正确复用已有能力”
• 自定义 Registry 篇解决“怎样把自己的高质量场景产品化”

自动化时最容易翻车的六件事

1. 使用不存在的 Item Name

解决：始终先执行 catalog --json。

2. 把 Block 和 Component 混用

解决：读取 Item Type 和安装文件说明。

3. Host ID 随意写成 Scene ID

解决：data-composition-id 必须匹配 Block 内部 ID。

4. 使用 Block 没有声明的变量

解决：检查 data-composition-variables，并使用 --strict-variables。

5. 安装后直接修改内部 Timeline

解决：优先只修改变量和 Host 时间；确实缺能力时，把修改升级为新的 Block 版本。

6. 跳过 Preview 直接 Render

解决：Registry 降低的是重复编码成本，不取消检查和人工审批。

推荐的极速工作流

# 1. 查询
npx hyperframes catalog --json

# 2. 安装精确 Item
npx hyperframes add code-snippet-apple-terminal-basic \
  --json \
  --no-clipboard

# 3. 检查安装文件和变量
# 由 Agent 读取 compositions/ 下的新文件

# 4. 挂载并传入声明过的变量
# 编辑主 Composition

# 5. 检查
npx hyperframes lint
npx hyperframes check --strict-variables

# 6. 检查新 Block 的可见中点
npx hyperframes snapshot --at 5.5

# 7. 最终预览
npx hyperframes preview

# 8. 人工确认后渲染
npx hyperframes render --quality high --output output/video.mp4

“极速”不是跳过步骤，而是把重复开发替换为：

精确查询
+ 本地安装
+ 标准接入
+ 数据替换
+ 固定验证

总结

HyperFrames 官方 Registry 的核心价值，不是让你记住一百多个 Item Name，而是建立一条可发现、可安装、可检查的复用路径。

正确心智模型是：

Catalog 是能力目录
add 是安装器
Block 是独立 Sub-composition
Component 是 Host 代码片段
Skills 是 Agent 的工作规范
check / snapshot / preview 是质量门槛

给 AI Agent 安装 Skills 后，最有效的指令也不是“帮我直接渲染一个视频”，而是：

先查询真实 Catalog，选择精确 Item，安装并阅读它的合约，正确挂载或合并，替换声明过的数据，再完成检查与预览。

这样才能真正把 Registry 的复用优势转化为稳定生产力，而不是因为名字、路径和接入方式错误，制造新的排错成本。

系列导航

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 官方 Registry Manifest
• HyperFrames 官方 GitHub 仓库