HyperFrames CLI Skill 帮助 Agent 把 HTML 视频项目从建立、检查和预览推进到导出。它特别适合已有 HTML/CSS 基础、希望用代码控制标题卡和产品说明动画的人。Skill 是操作说明；真正运行的是 HyperFrames CLI、浏览器和 FFmpeg。
先完成一张五秒标题卡，证明环境、时间线和导出路径都能工作，再做复杂视频。下面是基于 CLI 0.8.159 文档设计的练习，不是本站运行记录。需要 Node.js 22+、npm/npx、FFmpeg（包含 ffprobe），以及可执行本地命令的 Agent。
先选择安装方式
如果已经安装官方 HyperFrames 插件，用插件自带的 Skill 和 CLI launcher。插件模式下不要再执行独立的 skills update 或 npx skills add；Agent 应在你的项目目录调用插件中的 skills/hyperframes/scripts/plugin-cli.mjs。插件包决定 CLI 版本，不能用下面的 npm 固定版本命令替换它。
下面所有命令都针对独立安装。 在普通项目终端安装官方 CLI Skill：
npx skills add heygen-com/hyperframes --skill hyperframes-cli
在选择器中选择实际使用的 Claude Code、Codex 等客户端，安装后开启新会话。CLI Skill 处理建立、检查、预览和导出；创作新的完整视频还需要 hyperframes router 和相应创作流程。不要把只装 CLI 当成整套创作能力。
首次标题卡还需要 core 的 composition 说明。在独立模式下先在终端安装官方 core 集合，再开启新的 Agent 会话：
npx hyperframes@0.8.159 skills update
不要在插件模式使用这条命令。它从当前 main 取得 core 集合，包含 router 和领域 Skill；只安装 hyperframes-cli 后，不能假设 core 已经齐全。
1. 检查机器，再建立项目
在终端检查基础程序：
node --version
ffmpeg -version
ffprobe -version
npx hyperframes@0.8.159 doctor --json
doctor 返回的 JSON 要看 ok 和具体检查项，不能只看退出码：命令运行成功会退出 0，但环境问题仍可能存在。先处理 Node、FFmpeg 和 Chrome 的问题；本练习用本地导出，不使用 Docker 或云渲染。若找不到浏览器，可按官方入口查找或下载渲染浏览器：
npx hyperframes@0.8.159 browser ensure
不要把文档里的示范诊断输出当成自己的检查结果。机器内存和磁盘也会影响渲染；小项目先用一个 worker，避免同时启动许多浏览器。
在一个新练习目录的父目录执行：
npx hyperframes@0.8.159 init title-card --non-interactive
cd title-card
默认建立居中的空白模板。确认当前目录里有 index.html 和项目配置，再进入 Agent 会话。独立模式的 init 会从当前 GitHub 来源维护 core Skills，所以固定 CLI 版本不等于固定所有 Skill 文件和外部资源。不要把 ClawHub 的 Skill 版本号当成 npm CLI 版本。
2. 给 Agent 一份可验收的修改任务
这是对已经建立的项目做小范围修改，不是让 router 从零规划一部电影。在加载 Skill 的会话中可以这样输入：
使用 hyperframes-cli，并参考 hyperframes-core 修改当前 title-card 项目。
把现有空白模板做成一张五秒、1920×1080 的标题卡。
标题是「Release Atlas」，副标题是「A small update, clearly explained」。
只用文字、纯色背景和简单淡入，不添加音乐、外部图片或云服务。
保持标题在安全区域内，用可 seek 的时间线，不用随机数或实时时钟。
运行 check 并检查问题，再开启预览。先不要导出，我看过预览后再决定。
Agent 应保留 HyperFrames 的项目结构。顶层 index.html 的 composition root 直接在 body 里，不要套进 <template>；模板包装用于 sub-composition。根元素的 data-width、data-height 是画布尺寸，根 data-duration 是视频长度。动画早于五秒结束可以保持最后画面；动画超过根时长会被截掉。
使用 GSAP 时，时间线需要 paused 并注册到对应 composition ID。普通网页里自动播放的 CSS/JS 效果，不一定能在逐帧 seek 的渲染中工作。先让 Agent 修正项目合约，再加装饰。
3. 检查与预览
在 title-card 目录运行：
npx hyperframes@0.8.159 check --json
npx hyperframes@0.8.159 check --snapshots
npx hyperframes@0.8.159 preview --background
第一条用于读结构化检查，第二条在需要看检测帧时运行，不要求每次把两条都重复一遍。check 已包含 lint，无须在最终检查前再机械重复 lint。旧的 validate、inspect、layout 是兼容别名，本指南使用当前的 check。
看 ok、错误与警告，并检查 browserSkipped。如果浏览器根本没启动，空的 layout/motion/contrast 列表不是“全都通过”。快照写到 .hyperframes/artifacts/snapshots/；自动检查是抽样，不保证没有遗漏。
打开 preview 输出的实际地址，不假定它一定用默认端口。检查开始、约 2.5 秒和接近 5 秒的画面：标题是否完整、副标题是否可读、淡入后是否稳定、是否出现空白或裁切。修订后重新检查，并确认预览变化。
4. 预览批准后导出
确认画面再在同一个项目目录运行：
npx hyperframes@0.8.159 render --output title-card.mp4 --fps 30 --quality draft --workers 1
ffprobe -v error -show_format -show_streams title-card.mp4
先检查草稿文件非空、能播放、有视频流、尺寸为 1920×1080，时长接近五秒。用播放器检查开头、中间和结尾；ffprobe 能报告媒体结构，不能判断文字是否好看。30 fps、五秒意味着约 150 帧，可作为排查意外时长的参考，不是保证返回固定帧数的运行日志。
草稿确认后再决定正式质量，换输出名保留可比较的版本：
npx hyperframes@0.8.159 render --output title-card-final.mp4 --fps 30 --quality delivery --workers 1
npx hyperframes@0.8.159 preview --stop
draft 适合迭代，looks 是默认质量，delivery 是最终导出选项。本练习没有音频，因此没有声音不是失败。结束后停当前项目的后台 preview；不要用会终止其他项目预览的 --kill-all。
常见卡点
| 问题 | 先看什么 |
|---|---|
doctor 退出 0，但 render 失败 | JSON 的 ok 和具体检查项；浏览器、FFmpeg、磁盘与内存分别确认。 |
| 黑屏或模板内容完全不见 | 顶层 root 是否误放 template，composition ID 和 timeline 注册是否对应。 |
| 动画被切断 | 根 data-duration 是否短于动画；不要只看 GSAP timeline 的长度。 |
| preview 能看，导出缺字或缺图片 | 字体/媒体是否依赖网络，check 是否有请求失败，是否在需要的时间点完成加载。 |
| 没有检查发现却仍不能证明通过 | browserSkipped 是否为 true，检查是否只抽样了部分时间。 |
| 导出占内存高 | 先保持 --workers 1、短时长和较小素材；更多 worker 会启动更多 Chrome。 |
| 插件命令与本文不同 | 遵循插件 launcher 和插件更新流程，不混入独立 CLI 命令。 |
从标题卡到真实工作
可把这套检查流程用在产品更新卡、功能介绍或多语言标题版本。先提供准确文案、画布和时长，再讨论镜头与素材。做全新完整视频时调用 hyperframes router，让它选择创作流程；本页的 CLI 操作练习并不能替代分镜与素材授权。
HTML 项目依赖的字体、CDN 和媒体可能需要网络；Agent 使用的模型服务也可能接收到文案或项目上下文。本地渲染不等于所有资料离线。官方 CLI 提供关闭匿名 telemetry 的设置：
npx hyperframes@0.8.159 telemetry disable
这不会关闭你所用 Agent/模型服务自己的数据处理。云渲染和第三方媒体服务是另一条流程，可能要求账号、权限和费用，本练习不需要它们。若你的团队已用 React 视频项目，可参考 Remotion Skill 指南；不要直接把两套 composition 与 CLI 命令混用。