HyperFrames Registry 完全指南区块与组件的发现、安装、接线与贡献【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本指南系统讲解 HyperFrames 内置的可复用内容库 Registry如何用hyperframes add与hyperframes catalog发现、安装区块Blocks与组件Components如何将安装产物接线进宿主合成composition的时间轴以及如何从零贡献一个新的区块或组件回上游。读完你将掌握一套完整的搜索 → 安装 → 接线 → 校验 → 贡献工作流并理解 CLI 底层的安装位置映射、语义检索分级与清单缓存机制。一、Registry 是什么可复用的区块与组件HyperFrames 的核心理念是写 HTML、渲染视频Registry 就是围绕这一理念建立的可复用内容仓库开发者把常见镜头效果打包成标准条目任何人一条命令即可装进自己的项目。Registry 里只有两类条目二者定位完全不同维度Blocks区块Components组件本质独立的子合成sub-composition效果片段effect snippet自有尺寸/时长有自带 dimensions、duration、时间轴无继承宿主合成的尺寸与时长接入方式通过宿主合成中的data-composition-src引入直接把 HTML/CSS/JS 粘贴进宿主合成典型用途字幕样式、VFX 特效、标题卡、下三分之一、转场CSS 效果、文字处理、覆盖层从仓库结构可以直观印证这一划分registry/blocks 目录下每个条目都是一个独立目录如data-chart、whip-pan包含条目 HTML 与registry-item.json清单registry/components 目录则存放纯片段式组件。二者的清单字段也因此不同区块的registry-item.json声明dimensions与duration组件则没有详见下文条目清单字段。二、快速上手hyperframes add 命令hyperframes add name是安装入口支持多种形态hyperframes add>{ $schema: https://hyperframes.heygen.com/schema/hyperframes.json, registry: https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry, paths: { blocks: compositions, components: compositions/components, assets: assets } }自定义目录布局例如希望把区块装进scenes/目录而非compositions/{ paths: { blocks: scenes } }之后hyperframes add>div idstage>div >!-- 把覆盖层 div 粘贴进你的合成 -- div idgrain-overlay styleposition: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100; div classgrain-texture/div /div再把 CSS 的keyframes与.grain-texture规则粘贴进样式块即可——颗粒纹理通过 CSS 动画驱动不需要任何 GSAP 时间轴调用。示例二shimmer-sweep需要时间轴集成先安装并读取片段注释头然后四步接线HTML——包裹目标元素div classshimmer-sweep-target style--shimmer-color: rgba(255, 255, 255, 0.5) h1 classtitleAI-Powered Video/h1 /divCSS——从片段中复制.shimmer-sweep-target与.shimmer-mask规则。JS——在时间轴代码之前粘贴自动注入脚本document.querySelectorAll(.shimmer-sweep-target).forEach((el) { if (!el.querySelector(.shimmer-mask)) { const mask document.createElement(div); mask.className shimmer-mask; el.appendChild(mask); } });Timeline——在宿主时间轴上加入扫光动画tl.fromTo( .shimmer-sweep-target, { --shimmer-pos: -20%, }, { --shimmer-pos: 120%, duration: 1.2, ease: power2.inOut, stagger: 0.15, }, 1.5, );关键原则与可调参数组件继承宿主合成的尺寸与时长组件 HTML 的 z-index 要相对内容合理设置每个片段注释头都标注了可定制值以 shimmer-sweep 为例--shimmer-color高光颜色、--shimmer-width光带宽度默认 20%、--shimmer-angle扫光方向默认 120deg时间轴侧的duration、ease、stagger控制速度与手感接线完成后务必运行hyperframes lint检查结构问题完整演练见 add-component.md 与 wiring-components.md。六、发现与检索catalog 命令体系先按意图搜索再浏览列表CLI 是主要的发现入口。Registry 条目数量庞大仓库 registry/blocks 下区块已达上百个逐条浏览匹配名字或标签是慢路径且当作者用词与你不同时必然失败。正确姿势是先描述这个镜头应该做什么让检索替你排序# 对整个目录按节拍应该实现的效果排序 npx hyperframes catalog --query reveal a headline one line at a time npx hyperframes add caption-clip-wipe两级检索words 与 on-device搜索在本地进行不发送任何数据。默认按与条目 name/title/description 共享的词汇排序因此只能命中与你用词相同的条目--on-device则按语义含义排序但需要一次性下载约 33 MB 的本地模型。在 catalog.ts 的实现中可以看到这条分级路径searchByWords负责词汇级检索localSemantic/localEmbedder/localModel系列模块构成 on-device 语义层的模型下载、向量索引与排序管线且 on-device 层有一整套同意门consent gate未征得同意、曾拒绝下载、运行环境缺少 ONNX 原生运行时等情况都会被逐条记录并输出警告避免在 CI/Agent 无提示环境下擅自下载。使用--json时返回信封会标明是哪一级tier给出的答案——应检查该字段而不是想当然地认为排序一定发生了。必须用英文查询无论视频使用什么语言查询一律用英文。目录本身是英文书写的两级索引都以英文建索引on-device 模型也是纯英文。用其他语言查询不会产生可搜索词条直接返回空结果——这在日文、中文项目里极易踩坑简报、字幕、旁白都是目标语言查询自然跟着走了。正确做法是用英文描述镜头运动再用视频所需语言书写画面文案。如果查询返回No searchable words in query这是规则所致而非缺组件不值得上报 gap。排序后再过滤可安装性可安装性installability是在排序之后应用的而非之前向量命中了但当前 Registry 无法提供的名字会被从结果中剔除并计入dropped计数——dropped非零意味着本地索引与远端 Registry 是两个不同代次。关于离线级offline tier、同意门以及如何刷新过期索引参见 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默认输出为可读表格不安装任何东西--type接受block或component--tag可进一步收窄结果--json是确定性的 Agent/CI 接口选定名字后运行npx hyperframes add name--human-friendly打开交互式选择器并立即安装所选条目在 CI 或 Agent 工作流中优先--json后接显式add上报目录缺失项feedback --search-miss当搜索后没有任何结果能胜任时应在上手手写动画之前先上报npx hyperframes feedback --search-miss 你运行的查询 --wanted 你需要的效果 --tier on-devicecatalog --query会直接打印这行预填好的命令--json模式下则作为report_gap字段携带——也就是说在你判定没有合适条目的那一刻上报命令已经在手。要点任一检索级发现无合适结果都应上报不必等 on-device 级给出答案——on-device 需要 33 MB 的同意下载Agent 默认跑在words级若以on-device为门槛会沉默掉几乎所有报告--tier值随上报携带便于区分词汇没对上与语义没对上上报时描述你想要的效果而不是你想象出的条目名返回的是值得去构建的动作清单上报一个不存在的条目名毫无信息量这是唯一会把查询发送出去的路径正因如此它被设计为独立、刻意的命令而非搜索的隐含行为它不携带评分也绝不会落入评分指标它是目录的全部需求信号跳过上报意味着你遇到的缺口只能靠安装量来猜——而安装量看不见没人能安装的动作清单不可达时的兜底与离线语义如果 CLI 无法连上配置的 Registry可以退回直接查看原始清单curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json需要特别澄清两个离线行为CLI 连不上 Registry 不会清空 catalog 的发现能力只要之前抓取过清单即使超过 24 小时刷新窗口且校验失败上一次的本地副本仍会继续服务于catalog与catalog --query的列表和排序add即使对昨天刚装过的条目也仍然需要网络只有清单被缓存条目实际文件每次安装都会重新抓取。所以离线时你可以搜索、可以看到条目内容但安装会在文件抓取环节失败——不要向用户承诺离线安装条目清单字段registry-item.json每个条目附带一个registry-item.json包含name、type、title、description、tags、dimensions仅区块、duration仅区块、files文件列表、registryDependencies依赖的其他条目。以仓库内真实条目>hyperframes lint # 要求 0 错误 hyperframes check --no-contrast # 要求 0 控制台错误Step 5Preview 预览# 渲染预览视频 hyperframes render -o preview.mp4 # 截图做视觉 QA hyperframes snapshot --at 1.0,3.0,5.0,7.0 # 发布到 hyperframes.dev 供评审 npx hyperframes publish目录预览图默认 PNG 预览需把截图存到仓库 checkout 的docs/images/catalog/{kind}/{name}.png{kind}为blocks或components若registry-item.json声明了preview卡片使用其posterURL仅有preview而无poster则无图片兜底。HeyGen 内部贡献者从仓库根运行scripts/upload-docs-images.sh需 AWS profileengineering-767398024897外部贡献者把预览 MP4 附在 PR 描述里由维护者合并前生成并上传目录图片。Step 6Ship 发布所有步骤缺一不可缺任何一步都会产出损坏的目录条目。{kind}为blocks或components# 1. 创建分支 git checkout -b feat/registry-{name} # 2. 格式化 HTML npx oxfmt registry/{kind}/{name}/*.html # 3. 从条目目录重新生成 registry/registry.json。 # 不要手工编辑它手工加的条目会在下次重新生成时消失 # 而目录已不存在却残留的条目更糟——hyperframes add name # 解析到名字后在文件抓取环节失败。 npx tsx scripts/generate-registry-items.ts # 4. 生成目录文档页 npx tsx scripts/generate-catalog-pages.ts # 5. 发布到 hyperframes.dev 供评审预览 npx hyperframes publish # 6. 暂存全部内容 git add registry/{kind}/{name}/ registry/registry.json docs/catalog/ # 7. 提交 git commit -m feat(registry): add {name} — {one sentence} # 8. 推送并开 PR附 hyperframes.dev 链接 git push origin feat/registry-{name} gh pr create --title feat(registry): {name} --body preview: {hyperframes.dev-url}没有 GitHub 账号需要先注册并执行gh auth login。质量门Quality Gatehyperframes lint→ 0 错误hyperframes check→ 0 控制台错误npx oxfmt --check通过registry/registry.json已更新新条目已运行scripts/generate-catalog-pages.ts生成文档页已运行npx hyperframes publish认领你的项目 URL预览 MP4 已附到 PR外部或目录 PNG 已上传内部所有 ID 唯一且带前缀结语HyperFrames Registry 把找效果、装效果、用效果、造效果收敛成了一套命令驱动的工作流catalog负责意图式发现词汇级与 on-device 语义级双轨add负责按清单安装并自动重映射路径data-composition-src/ 片段合并负责接线feedback --search-miss负责把缺口反馈回上游而贡献流程则用模板、质量门与确定性规则保证了新条目与既有生态无缝兼容。对于 Agent 与自动化流水线而言--json、--no-clipboard与仅清单被缓存、条目文件每次实抓的语义让整个安装过程可以确定性地嵌入 CI 而无需人工介入——这也正是本项目Built for agents定位在内容复用层上的具体体现。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考