HyperFrames 组件安装完全指南：一条 hyperframes add 命令装好现成视频组件
【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes
HyperFrames 是一个"写 HTML，渲染出 MP4"的开源视频框架。它的内置命令hyperframes add能从官方组件目录（Registry）里把一个现成的视频组件装进你的项目：转场、字幕、图表场景、地图动画，都能装完就用。这篇文章按"选什么 → 怎么装 → 怎么接 → 出坑怎么办"的顺序，带你把这条链路走一遍。
先分清两类素材：Block 和 Component
目录里的素材分两种，接入方式不一样，动手前先把类型定下来：
| 类型 | 人话解释 | 默认安装位置 |
|---|---|---|
| Block（区块） | 独立场景文件：自带尺寸、时长和动画时间线 | compositions/<name>.html |
| Component（组件） | 特效片段：没有独立尺寸，要贴进现有场景里 | compositions/components/<name>.html |
所有素材都来自仓库的 registry/ 目录。判断标准很简单：你要的是"一整段场景"（比如一个图表、一张地图动画），选 Block；你要的是"一层效果"（比如颗粒噪点、光泽扫过），选 Component。
不知道装什么？先用 catalog 按意图搜索
目录里有数百个条目，靠肉眼一个个翻既慢又容易漏。官方建议的路径是：先按"你想让画面做什么"搜，再装。
# 用英文描述你要的效果，本地语义排序 npx hyperframes catalog --query "reveal a headline one line at a time" # 或按类型 / 标签浏览 npx hyperframes catalog --type block --tag social两个注意点。查询一律用英文——目录是用英文编写的，换成中文会检索不到任何词条；但视频里的屏显文案想写什么语言都可以，别把这两件事搞混。选定名字后，用hyperframes add <name>安装即可。
一条命令装进项目：单个与批量
先建项目（要求 Node.js 22+ 和 FFmpeg），再装：
npx hyperframes init my-video cd my-video npx hyperframes add>npx hyperframes add captionsCLI 会逐个安装，最后汇报成功和跳过的数量。带依赖的条目会先装依赖、再装本体。
常用参数：
| 参数 | 作用 |
|---|---|
--dir <路径> | 指向另一个项目目录，如--dir ./my-video |
--json | 输出机器可读结果，供脚本或 AI 代理解析 |
--no-clipboard | 跳过剪贴板复制，CI / 无头环境用 |
--vars <JSON> | 把目录页上的变量值写进引入片段 |
--force | 覆盖你安装后修改过的文件（默认保留你的改动） |
参数和标签回退逻辑的实现，可以看源码 packages/cli/src/commands/add.ts。
装完怎么接入主合成
安装完成后，CLI 会列出写了哪些文件，并把一段"引入片段（snippet）"复制到剪贴板。两类素材的接法不同：
Block：把片段粘进index.html，补上时间轴属性：
<div contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.![]()
项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
