插件安装： 在执行设置或刷新命令之前，如果此技能位于HyperFrames插件内部，请遵循插件执行规则。独立安装则保留下面的更新说明。
HyperFrames 注册表
注册表提供可通过 hyperframes add <名称> 安装的可复用块和组件。
- 块 — 独立的子合成（拥有自己的尺寸、时长、时间线）。通过主机合成中的
data-composition-src属性包含。 - 组件 — 效果片段（无自身尺寸）。直接粘贴到主机合成的 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 <目录> --example <名称>。
安装位置
默认情况下，块安装到 compositions/<名称>.html。组件默认安装到 compositions/components/<名称>.html。
这些路径可在 hyperframes.json 中配置：
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
连接块
块是独立的合成——通过主机 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 时间线集成（参见代码片段中的注释块），将这些调用添加到你的时间线中
发现
将 CLI 作为主要发现工具。在浏览之前按意图搜索： 注册表中的项目数量超过了你用眼睛扫描的范围，因此列出它们并按名称或标签匹配是慢路径，并且当作者的措辞与你的不同时就会失败。
# 根据节拍应该做什么对整个目录进行排序
npx hyperframes catalog --query "逐行显示标题"
npx hyperframes add caption-clip-wipe
搜索是本地进行的，不会发送任何信息。默认情况下，它根据与项目名称、标题和描述共享的词汇进行排序，因此只会找到重用你词汇的项目；--on-device 则根据含义进行排序，需要一次性模型下载。使用 --json 时，信封会标明哪个层级进行了回答，请检查该信息，而不是假设进行了排序。
始终用英语进行查询，无论视频使用什么语言。 目录是用英语编写的，两个层级都以此方式进行索引（本地设备模型也只是英语的）。使用其他语言编写脚本的查询不会产生可搜索的术语，并且什么也不会返回。在日语或中文项目中很容易出错，因为简报、字幕和旁白都是那种语言，查询自然也会跟随：用英语描述 动作，然后用视频需要的任何语言编写屏幕上的文字。如果查询返回了“查询中没有可搜索的单词”，那正是这条规则的问题，而不是缺少组件，也不值得提交差距报告。
可安装性是在排序之后应用的，而不是之前：向量带来但此注册表无法提供的名称会从结果中丢弃，并计入 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 <名称> 安装选定的名称。--human-friendly 会打开一个交互式选择器并立即安装选定的项目。在 CI 或代理工作流中，建议使用 --json 后跟显式的 add。
报告目录中没有的内容
当搜索返回的结果中没有任何内容符合要求时，请在手动编写动作之前说明：
npx hyperframes feedback --search-miss "<你运行的查询>" --wanted "<你需要的动作>" --tier on-device
catalog --query 会为你打印此行（已预填充），并且 --json 会将其携带为 report_gap——因此当你决定什么都不合适时，它已经在你手中了。
当结果中没有任何内容符合要求时，请报告，无论哪个层级。 不要等待本地设备层级回答：它需要经过同意的 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。