HyperFrames CLI 是一个围绕视频合成项目开发的命令行工具，所有操作默认通过 npx hyperframes 执行，除非项目说明指定了本地包装器（此时应严格遵循本地包装器）。运行环境要求 Node.js >= 22 与 FFmpeg。
【用途与工作流】 工具覆盖从创建到交付的完整开发闭环：
- 脚手架：npx hyperframes init my-video（或从 URL 捕获）。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。
【检查与验证能力】 lint 捕获缺失的 data-composition-id、重叠轨道和未注册时间线。validate 在无头 Chrome 中加载合成，报告运行时控制台错误及 WCAG 对比度问题。inspect 在时间线中定位并报告文本溢出气泡/容器或画布，且当存在 *.motion.json 边车文件时，会针对同一时间线验证运动意图（入场在定位时触发、错峰顺序、帧内、活跃性）。对于运动密集型工作，建议采用快照驱动迭代与 *.motion.json 边车。
【智能体约定】 --json 在除 render、preview、play 外的所有命令可用，输出包含 _meta 信封（CLI 版本、最新可用版本、更新建议）。render 仅通过 stdout + 退出码报告状态。doctor --json 始终退出 0，即使环境损坏，应基于载荷的 ok 字段判断。非 TTY 模式自动检测；在非 TTY 下 init 需要 --example，可用 --non-interactive 强制。CI 门控：--strict 在 lint 错误时失败，--strict-all 在警告时也失败，--strict-variables 在未声明的 --variables 键时失败。--json 中的路径会被脱敏（$HOME 变为字面 $HOME）。渲染需用户授权，检查通过后不得自动渲染，应在预览处暂停并告知用户视频可在 Studio 中编辑，获得批准后再渲染。渲染后验证：确认输出文件存在且大小合理，成功时 CLI 打印 ◇ <path>，长渲染可用 ffprobe 检查时长。
【路由与跨技能交接】 脚手架相关读 references/init-and-scaffold.md；正确性检查读 references/lint-validate-inspect.md；预览或渲染读 references/preview-render.md；环境诊断读 references/doctor-browser.md；Lambda 云端渲染读 references/lambda.md；其余（info、upgrade、compositions、docs、benchmark、telemetry、资产预处理）读 references/upgrade-info-misc.md。Tailwind 项目（init --tailwind）在编辑类或主题令牌前使用 hyperframes-core；注册表块/组件（hyperframes add、hyperframes catalog）使用 hyperframes-registry；资产预处理（tts、transcribe、remove-background）使用 hyperframes-media；参数化渲染（--variables）通过 <html> 上的 data-composition-variables 声明。
【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；开发循环迭代仍用本地渲染。
【最低完成门禁】 静态门禁：npx hyperframes lint 与 npx hyperframes validate；布局敏感工作加 inspect，CI 中用 render --strict 在 lint 错误时失败。视觉冒烟测试：当项目使用子合成时必需，因为 lint/validate/inspect 孤立评估每个合成，从不加载 index.html 并通过 data-composition-src 挂载子合成，无法捕获跨文件挂载失败。使用 hyperframes snapshot 加载项目（与 render 相同路径）但仅捕获指定时间戳，秒级完成：npx hyperframes snapshot --at <t1>,<t2>,... 或 npx hyperframes snapshot --frames 9。输出位于 snapshots/frame-NN-at-Xs.png。每帧红旗包括：文本在左上角显示微小且无样式（<style> 块留在 <head> 中 <template> 外）；SVG/图标元素被放大到画布尺寸（同上）；场景主元素完全缺失仅背景+水印可见（宿主 id ≠ 模板 id，时间线未运行）；快照命令日志出现 Sub-composition timelines not registered after 45000ms（直接确认该陷阱）。snapshots/ 可在目视检查后删除，面向用户的最终渲染是单独一次 npx hyperframes render。