hyperframes-cli

插件安装： 在设置或新鲜度检查命令之前，如果此技能位于 HyperFrames 插件中，请遵循插件执行规则。

HyperFrames CLI

除非项目提供了封装命令，否则运行 npx hyperframes <command>；若有封装命令，则使用该命令。它需要 Node.js 22+ 和 FFmpeg。每个命令都有 --help；大多数命令支持 --json，失败时会打印 ✗ …、一行 Fix:，并以非零状态码退出。

按用途分类的命令

用途	命令
开始	init <dir>（空白项目；仅在用户提出要求时使用 --example <name>）、capture <url>
读取项目	info、compositions、timeline --json、docs <topic>
检查项目	编写时运行 lint；将 check --json 作为检查关卡（lint、运行时、布局、对比度）
查看效果	snapshot（--at <t,…>、--range START,END、--composition <id>、--zoom、--angle、--against <video>）、keyframes、compare、audio
编辑时间线	timeline 搭配 move、trim、split、set、duplicate、delete、apply、undo、ids
复用	catalog、add（/hyperframes-registry）
媒体和声音	media-treatment、grade-compare、remove-background、tts、transcribe、beats、normalize-audio（/media-use）
展示和交付	preview、present（/slideshow）、render、publish、cloud、lambda、cloudrun
桌面应用	open、catch-up
维护	doctor、browser、upgrade、skills、usage、clean、feedback

validate、inspect 和 layout 是已弃用的 check 别名；events 是供技能自身脚本使用的遥测命令。不要运行它们。

工作循环

1. 先编写，然后在完成初稿后以及进行结构性更改后运行 npx hyperframes lint。
2. 运行 npx hyperframes check --json 并修复所有错误。只要仍有 lint 错误，就不会运行布局和对比度审计；“0 samples”意味着未检查任何内容。对比度失败会附带 suggestedColor。仅在一个采样点出现的问题（动画入场过程中的问题）属于提示信息；时长达到 3 s+ 且没有可见变化的视频会导致 sweep_static 检查失败。
3. 运行 npx hyperframes snapshot 并查看 PNG 文件（位于 .hyperframes/artifacts/snapshots/ 下）：这是查看视频的方式。对于子合成，要对每个场景的中间时刻进行快照；内容过小或未设置样式、缺少主视觉元素，均属于挂载缺陷（../hyperframes/references/format.md）。
4. 运行 npx hyperframes preview --background，确认 URL 返回 200，将项目 URL 提供给对方并等待，除非对方要求提供文件或要求不要暂停。仅通过检查并不构成渲染的理由。
5. 到需要渲染时（第 4 步）：运行 npx hyperframes render --quality looks --output out.mp4（迭代时使用 draft，最终交付时使用 delivery）。确认文件非空，且其 ffprobe 时长与根级 data-duration 相符，然后查看解码后的帧。

“This element”或当前选区：npx hyperframes preview --context --json --context-fields selection；no-selection 表示需要让对方点击该元素。

编辑时间线

这些编辑与 Studio 本身执行的编辑一致，因此结果会保持 Studio 的格式。

• timeline --json 会列出片段及其绝对时间 absStart/absEnd、所属 file，以及编辑命令所需的 #id 引用（timeline ids 会为缺少 ID 的片段添加 ID）。
• timeline move|trim|split|set|duplicate|delete <ref> … --plan --json 会预览一次编辑；去掉 --plan 再运行即可执行。--start、--end、--duration 分别设置一侧边界或时长。
• 如果片段会与相邻片段重叠（使用 --overwrite，或先移动相邻片段），或结束时间超出其所属合成的范围，则会拒绝编辑：先增大根级 data-duration。没有任何命令会更改 data-duration。
• 同时进行多项编辑：创建一个 JSON 文件，例如 [{"verb": "move", "ref": "#outro", "time": "9"}]，然后运行 timeline apply plan.json --json。每次运行都会打印一份 receipt；保存该文件后，运行 timeline undo receipt.json 即可撤销。

项目历史

每次写入都会保留，并且可以撤销。每轮开始时，运行 npx hyperframes history begin --who <you> --label "<plan>"，然后运行 history --since mine --who <you> 查看对方做了哪些更改；在其编辑基础上继续。如果检查失败，或对方说效果变差：运行 history undo --who <you>，切勿手动改回。结束本轮时运行 history end。

渲染位置

需求	命令
本地	render --quality looks --output out.mp4（draft、delivery）
可复现容器	render --docker --strict --output out.mp4
根据变量批量渲染	render --batch rows.json --output "renders/{name}.mp4"
托管服务，无需本地 Chrome 或 FFmpeg	cloud render（references/cloud.md）
使用你自己的 AWS 或 GCP	lambda render、cloudrun render（references/lambda.md、references/cloudrun.md）

一段 30 s 的影片一两分钟即可渲染完成：在前台运行。只有当渲染时间超过工具的超时时限时，才将其转入后台运行（HYPERFRAMES_RENDER_DETACHED=1，使用独立进程组，并将输出写入日志），然后运行 until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done 等待完成；切勿使用 pgrep -f，它会匹配自身循环，导致等待直至工具超时。

渲染验证通过后，发送一条 feedback --rating，并报告对方提出但 HyperFrames 无法实现的任何需求；遥测关闭时除外：references/feedback.md。

命令失败时

症状	修复方法
缺少 Chrome 或无法启动	npx hyperframes browser ensure；doctor --json 始终以 0 退出，需根据 .ok 判断
页面内容较多，未能及时就绪	提高 check 或 snapshot 的 --timeout
不常见的编解码器显示为空白	保持启用 --proxy（默认设置）
Linux 上渲染缓慢	摘要的第二行显示 screenshot 和 software gpu：这是较慢的路径
capture 失败或写入 BLOCKED.md	不要使用不完整文件中的任何内容；重试时指定新的 -o 文件夹
磁盘空间不足	先运行 clean --dry-run，再运行 clean；切勿删除 .hyperframes（其中保存着历史记录）

参考资料

运行命令前，先阅读对应行的资料。

命令	阅读
init、capture、skills	references/init-and-scaffold.md
lint、check、motion sidecars、snapshot	references/lint-validate-inspect.md
compare、grade-compare、render --batch	references/compare-and-batch.md
beats	references/beats.md
preview、play、render、publish、Studio 上下文	references/preview-render.md
doctor、browser	references/doctor-browser.md
auth、cloud、模板变量	references/cloud.md
lambda、cloudrun	references/lambda.md、references/cloudrun.md
info、upgrade、compositions、timeline、docs、usage、遥测	references/upgrade-info-misc.md
--strict 标志、运行 ID、clean、着色器 lint、JSON 路径	references/conventions.md
keyframes	../hyperframes/references/motion.md（查看动态效果）