HyperFrames 注册表
该注册表提供可通过 hyperframes add <name> 安装的可复用块和组件。
- 块 (Blocks) — 独立的子合成(拥有自己的尺寸、时长、时间线)。通过宿主合成中的
data-composition-src引入。 - 组件 (Components) — 效果片段(没有自己的尺寸)。直接粘贴到宿主合成的 HTML 中。
快速参考
hyperframes add data-chart # 安装一个块
hyperframes add grain-overlay # 安装一个组件
hyperframes add captions # 安装所有标签为 captions 的块
hyperframes add shimmer-sweep --dir . # 指定目标项目
hyperframes add data-chart --json # 机器可读输出
hyperframes add data-chart --no-clipboard # 跳过剪贴板(CI/无头模式)
安装后,CLI 会打印写入的文件以及要粘贴到宿主合成中的代码片段。该片段是起点:在连接块时,您需要添加 data-composition-id(必须与块的内部合成 ID 匹配)、data-start 和 data-track-index 属性。
位置参数首先被解析为精确项名称。如果没有匹配的项且该值是标签,则命令会安装所有具有该标签的块。注册表依赖项会在请求的项之前安装。hyperframes add 仅适用于块和组件;对于示例,请改用 hyperframes init <dir> --example <name>。
安装位置
块默认安装到 compositions/<name>.html。组件默认安装到 compositions/components/<name>.html。
这些路径可在 hyperframes.json 中配置:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
详细信息请参见 install-locations.md。
连接块
块是独立的合成——通过宿主 index.html 中的 data-composition-src 引入:
<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-src— 块 HTML 文件的路径data-composition-id— 必须与块的内部 ID 匹配data-start— 块在宿主时间线中出现的时间(秒)data-duration— 块播放的时长data-width/data-height— 块画布尺寸data-track-index— 图层顺序(数值越大越靠前)
详细信息请参见 wiring-blocks.md。
连接组件
组件是片段——将它们的 HTML 粘贴到合成的标记中,CSS 粘贴到样式块中,JS(如果有)粘贴到脚本中:
- 读取已安装的文件(例如
compositions/components/grain-overlay.html) - 将 HTML 元素复制到您的合成的
<div data-composition-id="...">中 - 将
<style>块复制到您合成的样式中 - 将任何
<script>内容复制到您合成的脚本中(在时间线代码之前) - 如果组件暴露了 GSAP 时间线集成(参见片段中的注释块),将这些调用添加到您的时间线中
详细信息请参见 wiring-components.md。
发现
使用 CLI 作为主要的发现界面。在使用分类浏览前先通过意图搜索: 注册表中的项目比您手动扫描的要多,列出它们并按名称或标签匹配是慢速路径,而且当作者的措辞与您不同时可能会失败。
# 根据节拍应该做的事情对整个目录进行排序
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜索是本地进行的,不会发送任何信息。默认情况下,它根据与项目名称、标题和描述共享的词汇进行排序,因此只能找到使用您词汇的项目;--on-device 则根据含义进行排序(在一次模型下载后)。使用 --json 时,信封会指明哪个层级回答了问题,因此请检查这一点,而不是假设排序已经发生。
无论视频使用什么语言,始终用英文查询。 目录是用英文编写的,两个层级都按此方式索引(on-device 模型也只支持英文)。用其他脚本编写的查询不会产生可搜索的术语,也不会返回任何结果。这在日语或中文项目中很容易出错,因为项目简报、字幕和旁白都是那种语言,查询自然会跟随:用英文描述_动作_,然后用视频所需的任何语言编写屏幕上的文案。如果查询确实返回 No searchable words in query,这是规则问题,而不是缺少组件,也不值得提交漏洞报告。
可安装性是在排序之后应用的,而不是之前:向量携带但此注册表无法提供的名称会从结果中删除,并计入 dropped,因此非零的 dropped 意味着两者属于不同代。有关离线层级、同意门控以及如何刷新过时索引的信息,请参见 /hyperframes-cli。
要浏览或筛选而不是搜索:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
普通表格和 --json 模式仅列出匹配项;使用 hyperframes add <name> 安装所选项目。--human-friendly 会打开一个交互式选择器并立即安装所选项目。在 CI 或智能体工作流中,优先使用 --json 后跟明确的 add。
报告目录中缺失的内容
当搜索返回结果但没有一个能完成任务时,在手动编写动作之前请报告:
npx hyperframes feedback --search-miss "<您运行的查询>" --wanted "<您需要的动作>" --tier on-device
catalog --query 会为您打印这行代码(已预填),而 --json 会将其作为 report_gap 携带——因此当您决定没有合适的项时,它已经在手边了。
只要结果中没有能完成任务的项,就请报告,无论哪个层级。 不要等到 on-device 层级回答:它需要经过同意的 33 MB 下载,因此智能体运行默认使用 words 层级,除非明确选择加入;而依赖 on-device 会使几乎所有的报告被沉默。--tier 值会附带,以便在阅读时区分词汇缺失和含义缺失。描述您想要的效果,而不是您想象的项目名称:返回的是值得构建的动作列表,而报告一个不存在的项目没有任何意义。这是唯一会将查询发送到任何地方的路径,这正是为什么它是一个独立的、有意的命令,而不是搜索自行完成的事情。它不携带任何评分,也永远不会进入评分指标。
这是目录的整个需求信号。跳过它意味着您遇到的缺口只能从安装计数中猜测,而安装计数无法看到没有人能安装的动作。
如果 CLI 无法连接到配置的注册表,请检查原始清单作为后备:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
CLI 无法访问的注册表不会使目录在发现方面为空:当重新验证失败时,之前获取的清单会在其 24 小时刷新窗口之后继续提供服务,因此 catalog 和 catalog --query 仍然会根据磁盘上的最后一个副本进行列出和排序。
add 仍然需要网络,即使对于昨天安装的项目也是如此。 只有清单被缓存;项目的实际文件在每次安装时都会获取。因此离线时您可以搜索,也可以查看项目内容,但安装会在文件获取时失败。不要向用户承诺离线安装。
每个项目的 registry-item.json 包含:名称、类型、标题、描述、标签、尺寸(仅块)、时长(仅块)和文件列表。
有关按类型和标签筛选的详细信息,请参见 discovery.md。
贡献新的块或组件
要创作一个全新的注册表项目(字幕样式、VFX 块、过渡、下三分之一或可复用组件)并将其作为上游 PR 提交——而不是安装现有项目——请遵循 contributing.md 中的完整创意→脚手架→构建→验证→预览→发布工作流。可复制粘贴的入门模板(字幕/VFX/组件/registry-item.json)位于 templates.md。