如何给 HyperFrames Catalog 贡献一个可安装的 Block 或 Component 并提交 PR-酒店常州论坛

如何给 HyperFrames Catalog 贡献一个可安装的 Block 或 Component 并提交 PR

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames 的 Catalog 是由仓库里的 registry 生成的：每个可安装条目都放在registry/blocks/或registry/components/下的独立目录中，用户通过hyperframes add <name>安装。如果你想把自己的视觉效果（字幕样式、转场、VFX、下三分之一等）做成别人能直接安装的条目，本文给出一条完整的操作路径：选型、建目录、写 manifest、构建、本地验证、生成 Catalog 产物，最后提交 PR。主文档是 docs/contributing/catalog.mdx，根目录的 CONTRIBUTING.md 补充了仓库级的前置步骤与 PR 约定。

也可以让 Agent 代替你走这套流程：skills/hyperframes-registry/SKILL.md 声明了/hyperframes-registryskill 覆盖 "idea → scaffold → validate → PR" 的完整工作流，详细步骤在 skills/hyperframes-registry/references/contributing.md。

先确认仓库工作环境和两种条目类型

仓库侧准备（来自 CONTRIBUTING.md）：fork 后 clone 自己的 fork，运行bun install（会自动安装 lefthook git 钩子，在每次提交前对暂存文件执行 lint 和 format 检查），然后建分支：

git checkout -b feat/registry-<name>

条目类型决定目录结构和 manifest 内容，选定后不再更改：

类型	用途	必需文件
Block	独立 composition，有固定尺寸和时长	`registry-item.json`+ composition HTML
Component	安装进其他 composition 的片段	`registry-item.json`+ 片段 HTML + 独立的`demo.html`

目录约定（catalog.mdx）：

registry/blocks/my-block/ my-block.html registry-item.json registry/components/my-effect/ my-effect.html demo.html registry-item.json

my-block/my-effect是文档中的示例条目名，替换成你自己的 kebab-case 名称（schema 要求以小写字母或数字开头和结尾，见 docs/schema/registry-item.json）。两个硬性规则：

所有元素 ID 必须加条目名缩写前缀（skill 建议 2–3 个字母，如my-effect用me-），避免条目作为 sub-composition 安装时 ID 冲突；
Component 缺demo.html会被 Catalog preview 生成器直接跳过，不会出现在预览里。

Component 的demo.html有四项要求（CONTRIBUTING.md）：完整的独立 HTML 文档（含<!doctype html>、GSAP CDN 等）；展示组件效果应用于代表性内容的样子；把 GSAP timeline 注册到window.__timelines以便 Studio 预览和 CI 预览管线渲染；根节点使用data-composition-id="<name>-demo"避免 ID 冲突。Block 本身已是独立 composition，不需要demo.html。

编写 registry-item.json manifest

registry-item.json遵循 registry item schema。Block 必须声明dimensions和duration；Component 则不能声明这两项——schema 中有一条条件规则专门校验这一点。文档给出的 block manifest 示例如下（my-block为示例条目名）：

{ "$schema": "https://hyperframes.heygen.com/schema/registry-item.json", "name": "my-block", "type": "hyperframes:block", "title": "My Block", "description": "What this block does in one sentence", "tags": ["category", "subcategory"], "dimensions": { "width": 1920, "height": 1080 }, "duration": 5, "params": [ { "key": "--accent", "label": "Accent", "type": "color", "default": "#ff4d4d" } ], "files": [ { "path": "my-block.html", "target": "compositions/my-block.html", "type": "hyperframes:composition" } ] }

params用于让使用者在 Studio 中不改 HTML 就能调整的值，受支持的控件类型是color、text、number、select。注意文档明确说明：已发布的 JSON schema 校验的是共享 manifest 字段，尚未描述 block 专用的params字段，所以这部分请以 TypeScript registry 类型和仓库中现有 manifest 为准。

其他可选字段：author、authorUrl、relatedSkill、registryDependencies、license、sourcePrompt、minCliVersion、deprecated。三者用途（catalog.mdx）：

registryDependencies：声明必须先安装的条目名。安装器会传递解析依赖并拒绝缺失项或循环；
minCliVersion：支持该条目的最早 CLI 版本。所有解析出的条目（含依赖）都必须先通过兼容性检查，任何文件才会被安装；
deprecated：条目有替代品时写一句迁移说明，安装器会给出警告并保留条目供已有项目使用。

构建条目时的硬性要求

每个 registry 条目必须满足（catalog.mdx）：

使用注册在window.__timelines上的 paused GSAP timeline；
data-composition-id与注册的 timeline ID 一致；
元素 ID 带前缀；
避免Date.now()、未播种的Math.random()和实时动画循环；
任意帧 seek 都正确；
从源目录之外安装后仍能工作。

一句话的判断标准：一次性演示属于 Examples，不属于 Catalog。条目必须是可复用的。

本地验证：lint、check 与预览

直接对 registry 目录跑裸npx hyperframes lint是行不通的——CLI 找index.html，而条目交付的是<name>.html或demo.html。仓库提供了专门的脚本把条目挂载到一个一次性宿主项目里再 lint（scripts/lint-registry-items.mjs 会把条目复制到临时目录的compositions/下执行bun packages/cli/src/cli.ts lint，只报告条目自身文件的发现项，完成后删除临时目录）：

bun run lint:registry-items my-block

不带参数则检查所有条目；没有匹配条目时会报错并以非零码退出。

要跑完整的门禁，把条目装进一个干净的临时项目再验证（副作用：在当前目录下新建scratch/临时项目）：

npx hyperframes init scratch && cd scratch npx hyperframes add my-block npx hyperframes check

npx hyperframes add从hyperframes.json里的 registry URL 解析条目，不能按名字安装未发布的本地条目——所以按名字安装这条路径要在条目进入该 registry manifest 之后、从干净项目测试（可选分支，不是本地主路径）。

再生成 Catalog 页面和预览资产（scripts/generate-catalog-previews.ts 的--only参数可只生成单个条目）：

npx tsx scripts/generate-catalog-pages.ts npx tsx scripts/generate-catalog-previews.ts --only my-block

这些生成器直接从工作树读取条目，因此不要手改生成的条目页面——修 manifest 或生成器，然后重新生成。最后用全速看一遍预览：check通过只证明 composition 合法，不证明动效可读、有用。

提交 PR 前：重新生成 registry.json 与提交约定

registry/registry.json是从条目目录生成的，不能手改：手加条目能活到下次重新生成然后消失，为已删除目录留下的条目更糟——hyperframes add <name>会先解析到名字、再在缺失文件上失败。CONTRIBUTING.md 指定的重新生成命令是：

npx tsx scripts/generate-registry-items.ts

docs/contributing/catalog.mdx 的 "Open the pull request" 一节列出了 PR 必须包含的内容：

条目目录；
registry/registry.json中对应的条目；
重新生成的 Catalog 输出；
通过npx hyperframes publish得到的hyperframes.dev预览；
条目适用场景、有用的时长范围、已知坑。

外部贡献者在 PR 中附上预览 MP4 即可，最终 Catalog 媒体由维护者发布；HeyGen 内部贡献者可在预览评审后运行scripts/upload-docs-images.sh（需要 AWS profileengineering-767398024897，见 skills/hyperframes-registry/references/contributing.md）。

另外两件需要仓库资产、外部贡献者没有的东西，CONTRIBUTING.md 明确由维护者在合并前补上，不阻塞 review：搜索索引registry/catalog-artifact/（pre-commit hook 能重建时由 hook 处理，否则 CI 会指出缺口）和 Catalog 预览图（外部贡献者用 PR 里的 MP4 代替）。

PR 本身的仓库约定：所有 commit 使用 conventional commit 格式（例如feat(registry): add my-block），由 git hook 强制；CI（build、typecheck、tests、semantic PR title）必须通过；至少 1 个 approval。

无法走通时的替代方式

如果只是想提出一个视觉想法而不是自己构建，catalog.mdx 给出的路径是开一个 GitHub issue，附视觉参考（录屏、Figma 草图或其他工具的示例都够）并说明效果在什么场景有用。这不需要仓库权限，但也不经过本文的构建与验证流程。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析