HyperFrames CLI
所有操作均通过 npx hyperframes 执行,除非项目说明指定了本地包装器。请严格遵守本地包装器。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 脚手架 —
npx hyperframes init my-video(或从 URL 执行capture)。init还会检查本地安装的技能是否与 GitHub 上的最新版本一致,如有过时则更新全局技能集。--skip-skills标志当前已被禁用(临时措施,等待 skills.sh 注册表跟上),因此每次init都会执行此检查并拉取我们最新的技能。 - 编写 — 编写 HTML 合成(参见
hyperframes-core技能) - 代码检查 —
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 在无头 Chrome 中加载合成,并报告运行时控制台错误以及 WCAG 对比度问题。inspect 会在时间线中搜索,报告文本溢出气泡/容器或画布的情况——并且,当存在 *.motion.json 侧边文件时,会根据相同的时间线搜索验证运动意图(进入帧的触发、交错顺序、在帧内、活跃度)。
对于运动密集型工作,优先使用快照驱动的迭代和 *.motion.json 侧边文件——相关规范请参见 references/lint-validate-inspect.md。
Agent 约定
适用于所有命令的跨领域规则:
- 除
render、preview和play外,所有命令均可使用--json。 任何 Agent / CI 调用支持的命令时都应使用它;输出包含一个_meta信封(CLI 版本、最新可用版本、更新建议)。render仅通过 stdout + 退出码报告状态——请通过下面的渲染后检查来验证成功;preview/play是服务器,没有 JSON。 doctor --json始终以退出码 0 退出,即使环境出现问题。通过检查 payload 的ok字段来判断:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这可以避免管道受 CLI 发布变更的影响。- 非 TTY 模式会被自动检测。 当 stdout 不是 TTY(CI、Agent、管道输出)时,CLI 会自动切换到非交互模式;此时
init需要--example。可通过--non-interactive强制启用此模式,即使在 TTY 上也是如此。 - CI 对渲染的约束:
--strict在遇到 lint 错误时失败,--strict-all在遇到警告时也失败,--strict-variables在遇到未声明的--variables键时失败。 --json中的路径会被脱敏——$HOME会变成字面字符串$HOME,以便输出可以安全地粘贴到错误报告和 Agent 上下文中。- 渲染需要用户确认。 检查通过后切勿自动渲染。在
preview处暂停,告知用户视频可在 Studio 中编辑,仅在用户批准后执行渲染。 - 渲染后验证。 在
render返回退出码 0 后,先确认输出文件存在且大小合理,再报告成功:[ -s "$OUTPUT" ] || echo "render produced no output"。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)→ 对于语音选择、Whisper 模型规则、字幕和 TTS 到字幕链,使用hyperframes-media。 - 参数化渲染(
--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 的独立步骤。