HyperFrames CLI
所有操作通过 npx hyperframes 运行,除非项目说明指定了本地包装器。必须严格遵循本地包装器。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 构建脚手架 —
npx hyperframes init my-video(或从 URL 使用capture) - 编写 — 编写 HTML 组合(参见
hyperframes-core技能) - Lint —
npx hyperframes lint - Validate —
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 在无头 Chrome 中加载组合并报告运行时控制台错误以及 WCAG 对比度问题。inspect 遍历时间线并报告从气泡/容器或画布中溢出的文本——并且当存在 *.motion.json 侧车文件时,它会针对相同的遍历时间线验证运动意图(进入触发时间、交错顺序、在帧内、活跃度)。
对于运动密集型工作,首选基于快照的迭代和 *.motion.json 侧车文件——有关规则和运动验证规范,请参见 references/lint-validate-inspect.md。
代理约定
适用于每个命令的横切规则:
--json在每个命令上都可用,除了render、preview和play。 对于任何代理 / 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)→ 在编辑类或主题令牌之前使用hyperframes-core(Tailwind 参考)。 - 注册表块/组件(
hyperframes add、hyperframes catalog)→ 使用hyperframes-registry处理安装路径、子组合连接和代码片段合并。 - 资源预处理(
tts、transcribe、remove-background)→ 使用hyperframes-media处理语音选择、Whisper 模型规则、字幕以及 TTS 到字幕链。 - 参数化渲染(
--variables)→ 通过在<html>上声明的data-composition-variables;完整模式请参见hyperframes-core。
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 挂载子组合,因此它们无法捕获跨文件挂载失败(参见 hyperframes-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/图标元素放大到画布大小 | 同上——未应用宽度/高度约束 |
| 场景的主角元素完全丢失;仅可见背景和水印 | 宿主 id ≠ 模板 id(陷阱 2)——时间线从未运行,在初始状态捕获帧 |
快照命令记录 Sub-composition timelines not registered after 45000ms | 陷阱 2 —— 直接确认 |
snapshots/ 可以在目视检查后删除;面向用户的最终渲染是通过 npx hyperframes render 进行的单独过程。