如何给 HyperFrames Catalog 贡献一个可安装的 Block 或 Component 并提交 PR【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 的 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.mdfork 后 clone 自己的 fork运行bun install会自动安装 lefthook git 钩子在每次提交前对暂存文件执行 lint 和 format 检查然后建分支git checkout -b feat/registry-name条目类型决定目录结构和 manifest 内容选定后不再更改类型用途必需文件Block独立 composition有固定尺寸和时长registry-item.json composition HTMLComponent安装进其他 composition 的片段registry-item.json 片段 HTML 独立的demo.html目录约定catalog.mdxregistry/blocks/my-block/ my-block.html registry-item.json registry/components/my-effect/ my-effect.html demo.html registry-item.jsonmy-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-idname-demo避免 ID 冲突。Block 本身已是独立 composition不需要demo.html。编写 registry-item.json manifestregistry-item.json遵循 registry item schema。Block 必须声明dimensions和durationComponent 则不能声明这两项——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.mdxregistryDependencies声明必须先安装的条目名。安装器会传递解析依赖并拒绝缺失项或循环minCliVersion支持该条目的最早 CLI 版本。所有解析出的条目含依赖都必须先通过兼容性检查任何文件才会被安装deprecated条目有替代品时写一句迁移说明安装器会给出警告并保留条目供已有项目使用。构建条目时的硬性要求每个 registry 条目必须满足catalog.mdx使用注册在window.__timelines上的 paused GSAP timelinedata-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。仓库提供了专门的脚本把条目挂载到一个一次性宿主项目里再 lintscripts/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 checknpx 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.tsdocs/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 强制CIbuild、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），仅供参考 如何给 HyperFrames Catalog 贡献一个可安装的 Block 或 Component 并提交 PR
如何给 HyperFrames Catalog 贡献一个可安装的 Block 或 Component 并提交 PR【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 的 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.mdfork 后 clone 自己的 fork运行bun install会自动安装 lefthook git 钩子在每次提交前对暂存文件执行 lint 和 format 检查然后建分支git checkout -b feat/registry-name条目类型决定目录结构和 manifest 内容选定后不再更改类型用途必需文件Block独立 composition有固定尺寸和时长registry-item.json composition HTMLComponent安装进其他 composition 的片段registry-item.json 片段 HTML 独立的demo.html目录约定catalog.mdxregistry/blocks/my-block/ my-block.html registry-item.json registry/components/my-effect/ my-effect.html demo.html registry-item.jsonmy-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-idname-demo避免 ID 冲突。Block 本身已是独立 composition不需要demo.html。编写 registry-item.json manifestregistry-item.json遵循 registry item schema。Block 必须声明dimensions和durationComponent 则不能声明这两项——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.mdxregistryDependencies声明必须先安装的条目名。安装器会传递解析依赖并拒绝缺失项或循环minCliVersion支持该条目的最早 CLI 版本。所有解析出的条目含依赖都必须先通过兼容性检查任何文件才会被安装deprecated条目有替代品时写一句迁移说明安装器会给出警告并保留条目供已有项目使用。构建条目时的硬性要求每个 registry 条目必须满足catalog.mdx使用注册在window.__timelines上的 paused GSAP timelinedata-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。仓库提供了专门的脚本把条目挂载到一个一次性宿主项目里再 lintscripts/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 checknpx 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.tsdocs/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 强制CIbuild、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），仅供参考