Communitygithub.com

kitfunso/claude-config

安装、发现并连接 HyperFrames 注册表中的块和组件。用于 hyperframes add、catalog、index.html 接线、hyperframes.json 配置。

claude-config 是什么?

此技能提供了与 HyperFrames 注册表交互的完整工具链,支持安装、发现和连接可复用的块(独立子合成)和组件(效果片段)。核心命令包括 `hyperframes add`(按名称或标签安装)、`hyperframes catalog`(通过关键词搜索或按类型/标签筛选),以及 `--json` 标志用于机器可读输出,适合 CI 或智能体工作流。搜索功能支持本地词汇匹配和可选的 on-device 语义搜索(需下载 33MB 模型),并且始终以英文查询,无论视频使用何种语言。安装后的接线说明详细指导了如何将块通过 `data-composition-src`、`data-composition-id`、`data-start` 等属性集成到宿主 `index.html` 中,组件则通过复制 HTML、CSS 和 JS 片段进行集成。当注册表没有所需功能时,技能鼓励使用 `hyperframes feedback` 提交“搜索缺失”报告,这是完善目录的唯一反馈途径。此技能主要在 HyperFrames CLI 环境下使用,由 Heygen 的 HyperFrames 项目提供支持。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kitfunso/claude-config/tree/HEAD/skills/hyperframes-registry

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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(如果有)粘贴到脚本中:

  1. 读取已安装的文件(例如 compositions/components/grain-overlay.html)
  2. 将 HTML 元素复制到您的合成的 <div data-composition-id="..."> 中
  3. 将 <style> 块复制到您合成的样式中
  4. 将任何 <script> 内容复制到您合成的脚本中(在时间线代码之前)
  5. 如果组件暴露了 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。

相关技能