hyperframes-registry

插件安装： 在运行设置或检查更新命令前，如果此技能位于 HyperFrames 插件中，请遵循插件执行规则。独立安装请遵循下方的更新说明。

HyperFrames 注册表

注册表提供可通过 hyperframes add <name> 安装的可复用区块和组件。

• 区块 — 独立的子合成（具有自己的尺寸、时长和时间轴）。通过 data-composition-src 引入宿主合成。
• 组件 — 效果片段（没有自己的尺寸）。直接粘贴到宿主合成的 HTML 中。

快速参考

hyperframes add data-chart              # install a block
hyperframes add grain-overlay           # install a component
hyperframes add captions                # install every block tagged captions
hyperframes add shimmer-sweep --dir .   # target a specific project
hyperframes add data-chart --json       # machine-readable output
hyperframes add data-chart --no-clipboard  # skip clipboard (CI/headless)

安装后，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。

连接区块

区块是独立的合成——通过 data-composition-src 将其引入宿主 index.html：

<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 — Studio 时间轴行；仅用于显示。请使用 CSS z-index 进行图层叠放

完整详情请参阅 wiring-blocks.md。

连接组件

组件是代码片段——将其 HTML 粘贴到合成的标记中，将 CSS 粘贴到样式块中，并将 JS 粘贴到脚本中（如果有）：

1. 阅读已安装的文件（例如，compositions/components/grain-overlay.html）
2. 将 HTML 元素复制到合成的 <div data-composition-id="..."> 中
3. 将 <style> 块复制到合成的样式中
4. 将任何 <script> 内容复制到合成的脚本中（位于时间轴代码之前）
5. 如果组件提供 GSAP 时间轴集成（参见代码片段中的注释块），请将相应调用添加到时间轴中

完整详情请参阅 wiring-components.md。

发现

将 CLI 用作主要的发现入口。**先按意图搜索，再浏览：**注册表中的条目远多于你能逐一查看的数量，因此列出条目再按名称或标签匹配是较慢的做法，而且作者用词与你不同时时，这种方法就会失效。

# Rank the whole catalog against what the beat should do
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe

搜索在本地进行，不会发送任何内容。默认情况下，搜索会根据条目名称、标题和描述中与你的查询词汇相同的词进行排序，因此只能找到重复使用了你所用词语的条目；--on-device 则会在一次性下载模型后，改为根据含义排序。使用 --json 时，结果封装会标明由哪个层级提供答案，因此请检查该信息，而不要假定搜索执行了排序。

**无论视频使用哪种语言，始终用英文查询。**目录以英文编写，两个层级也都以英文为索引（设备端模型也仅支持英文）。使用其他文字系统查询不会产生可搜索的词，因此不会返回任何结果。在日语或中文项目中很容易弄错这点，因为项目简介、字幕和旁白都使用该语言，查询也自然会跟着使用该语言：用英文描述_动作_，然后用视频需要的语言编写屏幕文案。如果查询返回 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 或 Agent 工作流中，建议使用 --json，然后明确执行 add。

报告目录中缺少的内容

搜索完成后，如果没有任何结果能满足需求，请先报告，再手动编写相应内容：

npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>

catalog --query 会为你打印这行内容并预先填好，--json 则会将其作为 report_gap 携带，因此当你确定没有合适结果时，这行内容已经准备就绪。

如果结果中没有任何内容能满足需求，无论在哪个层级，都要报告。 不要等设备端层级返回结果：它需要用户同意下载 33 MB，因此除非 Agent 明确选择加入，否则 Agent 运行时使用的是 words；如果以 on-device 为条件，几乎所有报告都会被抑制。--tier 的值会一并传递，因此阅读报告时，可以区分词汇缺失和含义缺失。请描述你想要的效果，而不是你想象中的项目名称：返回的内容是一份值得开发的操作列表，而报告一个不存在的项目名称毫无帮助。这是唯一会将查询发送到任何地方的途径，正因如此，它才是一个独立、刻意执行的命令，而不是搜索自动执行的操作。它不携带评分，也不会计入评分指标。

这是目录唯一的需求信号。如果跳过这一步，你遇到的缺口就只能根据安装次数来推测，而安装次数无法反映用户无法安装的操作。

如果 CLI 无法连接到配置的注册表，请检查原始清单作为备用方案：

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

CLI 无法连接的注册表不会导致目录无法用于发现：重新验证失败时，之前获取的清单会在 24h 刷新期限之后继续提供服务，因此 catalog 和 catalog --query 仍会根据磁盘上的最后一份副本列出并排序。

add 仍然需要网络，即使你昨天刚安装过某个项目也是如此。 只有清单会缓存；每次安装都会重新获取项目的实际文件。因此，离线时你可以搜索，也可以查看项目内容，但安装会在获取文件时失败。不要向用户承诺可以离线安装。

每个项目的 registry-item.json 都包含：名称、类型、标题、描述、标签、维度（仅限区块）、时长（仅限区块）以及文件列表。

有关按类型和标签筛选的详情，请参阅 discovery.md。

贡献新的区块或组件

若要编写新的注册表项目（字幕样式、VFX 区块、转场、下三分之一字幕条或可复用组件）并通过上游 PR 发布，而不是安装现有项目，请按照 contributing.md 中完整的构思 → 脚手架 → 构建 → 验证 → 预览 → 发布工作流操作。可直接复制粘贴的入门模板（字幕 / VFX / 组件 / registry-item.json）见 templates.md。