HyperFrames CLI
所有命令均通过 npx hyperframes 运行,除非项目说明指定了本地包装器。必须完全遵循本地包装器。需要 Node.js >= 22 和 FFmpeg。
工作流
- 脚手架搭建 —
npx hyperframes init my-video(或通过capture从 URL 捕获) - 编写 — 创作 HTML 合成(参见
../core) - Lint 检查 —
npx hyperframes lint - 验证 —
npx hyperframes validate(运行时错误 + 对比度) - 可视化检查 —
npx hyperframes inspect - 预览 —
npx hyperframes preview打开 Studio,一个时间线编辑器,用户可以手动编辑任何内容(不仅仅是观看)。在此处审查,然后询问用户后再渲染。 - 渲染 — 选择变体:
- 迭代:
npx hyperframes render --quality draft - 交付:
npx hyperframes render --quality high --output out.mp4 - CI / 跨主机复现:
npx hyperframes render --docker --strict --output out.mp4 - 云端(长 / 大):
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(见下方 Lambda)
- 迭代:
在预览前运行 lint、validate 和 inspect。lint 捕获缺失的 data-composition-id、重叠轨道和未注册的时间线。validate 在 headless Chrome 中加载合成并报告运行时控制台错误以及 WCAG 对比度问题。inspect 遍历时间线并报告文本溢出气泡/容器或画布的问题——当存在 *.motion.json 侧车文件时,还会根据同一个遍历过的时间线验证运动意图(入场触发时机、交错顺序、在帧内、活性)。
对于动效密集的工作,优先使用基于快照的迭代和 *.motion.json 侧车文件——关于该规范和运动验证规范的详细说明,请参见 references/lint-validate-inspect.md。
代理约定
适用于所有命令的跨切面规则:
- 除
render、preview和play外,每个命令都支持--json。 在支持的命令的任何代理/CI 调用中使用它;输出包含一个_meta信封(CLI 版本、最新可用版本、更新建议)。render仅通过 stdout + 退出码报告状态——通过以下后期渲染检查验证成功;preview/play是服务器,不支持 JSON。 doctor --json始终以退出码 0 退出,即使环境已损坏。通过检查负载中的ok字段来判断:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这可以防止管道因 CLI 版本发布变动而中断。- 非 TTY 模式自动检测。 当
stdout不是 TTY(CI、代理、管道输出)时,CLI 会自动切换到非交互模式;此时init需要--example。传入--non-interactive可强制在 TTY 上也使用此模式。 - CI 对渲染的门控:
--strict在 lint 错误时失败,--strict-all在警告时也失败,--strict-variables在未声明的--variables键时失败。 --json中的路径被脱敏——$HOME变为字面量$HOME,这样输出可以安全地粘贴到错误报告和代理上下文中。- 渲染需要用户确认。 一旦检查通过,绝不要自动渲染。在
preview处暂停,告知用户视频可在 Studio 中编辑,并且仅在用户批准后才渲染。 - 后期渲染验证。 在
render返回退出码 0 后,确认输出文件存在且大小合理,然后再报告成功:[ -s "$OUTPUT" ] || echo "渲染未产生输出"。CLI 在成功时打印◇ <path>;对于长时间渲染,还要使用ffprobe -i "$OUTPUT" -show_format -v error检查时长是否合理。
路由
| 想要… | 阅读 |
|---|---|
脚手架项目(init、capture、skills) | references/init-and-scaffold.md |
检查正确性(lint、validate、inspect、snapshot) | references/lint-validate-inspect.md |
预览或渲染(preview、play、render、publish) | references/preview-render.md |
诊断环境(doctor、browser) | references/doctor-browser.md |
在 AWS Lambda 云端渲染(lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
其他所有(info、upgrade、compositions、docs、benchmark、telemetry、资产预处理) | references/upgrade-info-misc.md |
章节转交
- Tailwind 项目(
init --tailwind)→ 在编辑类或主题令牌之前,请参阅../core/references/tailwind.md。 - Registry 区块/组件(
hyperframes add、hyperframes catalog)→ 参阅../registry了解安装路径、子合成接线和代码片段合并。 - 参数化渲染(
--variables)→ 通过<html>上的data-composition-variables声明;完整模式请参阅../core/references/variables-and-media.md。
Lambda(云端渲染)
hyperframes lambda 将分布式渲染部署到 AWS Lambda,并从您的笔记本电脑或 CI 驱动渲染。端到端共三个命令:
npx hyperframes lambda deploy # 配置 SAM 堆栈(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # 拆除(S3 存储桶会被保留)
当渲染时间过长/过大(多分钟视频、4K、大批量并行)且已配置 AWS 凭证时,使用 Lambda。对于开发循环迭代,请继续使用本地 render。
前提条件、所有 6 个子命令(deploy、sites create、render、progress、destroy、policies)、IAM 策略验证、状态文件以及成本/清理规则,请参阅 references/lambda.md。
最低完成门控
静态门控
npx hyperframes lint
npx hyperframes validate
对于布局敏感的工作,添加 inspect;在 CI 中使用 render --strict 以在 lint 错误时失败。
视觉冒烟测试——当项目使用子合成时必须执行
lint / validate / inspect 独立地评估每个合成。它们从不加载 index.html 并通过 data-composition-src 挂载子合成,因此无法捕获跨文件挂载失败(请参见 ../core/references/sub-compositions.md,“常见陷阱”)。唯一能捕获这些问题的门控是实际加载 index.html 并遍历时间线的那个。
使用 hyperframes snapshot——它以与 render 相同的方式加载项目(因此它执行相同的挂载路径),但只捕获您请求的时间戳,因此只需几秒而不是完整渲染:
# 在每个子合成的中点捕获一帧。
# 中点 = index.html 中每个宿主插槽的 data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# 或者,如果您不需要针对每个场景,可以使用均匀间隔的样本:
npx hyperframes snapshot --frames 9
输出位于 snapshots/frame-NN-at-Xs.png。目视检查每帧与场景计划是否一致。
每帧的红旗标志(每个都对应一个静态门控遗漏的特定失败模式):
| 您看到的 | 根本原因 |
|---|---|
| 文本在左上角以小号+无样式显示 | <style> 块留在了 <head> 中且位于 <template> 外部(陷阱 1)——无 CSS 到达实时 DOM |
| SVG/图标元素放大到画布大小 | 同上——未应用宽度/高度约束 |
| 场景的主角元素完全缺失;仅可见背景和水印 | Host-id ≠ template id(陷阱 2)——时间线从未运行,在初始状态下捕获帧 |
快照命令日志 Sub-composition timelines not registered after 45000ms | 陷阱 2——直接确认 |
snapshots/ 在目视检查后可删除;用户面向的最终渲染是通过 npx hyperframes render 单独完成的。