返回技能市场
开发运维 安全

hyperframes-registry

@admin/hyperframes-registry

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

admin 热度 332v0.0.1

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](./references/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](./references/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](./references/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 时，信封会指出哪个层级作出了响应，因此请检查这一点，而不是假设已经发生排序。

无论视频使用什么语言，始终用英文查询。 目录以英文编写，两个层级都按这种方式索引（设备端模型也只支持英文）。使用其他文字系统的查询不会产生可搜索的词语，并且完全不会返回任何内容。在日文或中文项目中很容易出错，因为 brief、字幕和旁白都使用该语言，查询会自然跟随：先用英文描述该 _动作_，然后按视频需要以任何语言编写屏幕文案。如果查询返回 No searchable words in query，这是该规则所致，而不是缺少组件，不值得提交 gap report。

可安装性是在排序之后而非之前应用的：向量中携带但此注册表无法提供的项目名称会被从结果中丢弃，并计入 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 on-device

catalog --query 会为你打印这一行预填充命令，而 --json 会将其作为 report_gap 携带——因此在你决定没有合适项目的那一刻，它已经在手。

只要结果中没有任何项目能完成任务，就在任一层级报告。 不要等待设备端层级作出回答：它需要一次经同意的 33 MB 下载，因此 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 包含：name、type、title、description、tags、dimensions（仅区块）、duration（仅区块）以及 file list。

有关按类型和标签筛选的细节，请参见 [discovery.md](./references/discovery.md)。

贡献新的区块或组件

要创建新的注册表项目（字幕样式、VFX 区块、转场、lower third，或可复用组件）并作为上游 PR 提交——而不是安装现有项目——请遵循 [contributing.md](./references/contributing.md) 中完整的 idea → scaffold → build → validate → preview → ship 工作流。可复制粘贴的入门模板（caption / VFX / component / registry-item.json）位于 [templates.md](./references/templates.md)。

qianwen skills install @admin/hyperframes-registry