hyperframes-cli

HyperFrames CLI

除非项目说明指定使用本地包装器，否则所有操作都通过 npx hyperframes 执行。请严格遵循本地包装器的要求。需要 Node.js >= 22 和 FFmpeg。

工作流

1. 搭建 — npx hyperframes init my-video（或从 URL 执行 capture）。init 还会检查已安装的技能是否为 GitHub 上的最新版本，并在有过期技能时更新全局技能集。--skip-skills 标志目前已失效（临时状态，等待 skills.sh 注册表更新），因此每次执行 init 都会运行此检查并拉取我们最新的技能。
2. 编写 — 编写 HTML 合成（参见 hyperframes-core 技能）
3. Lint 检查 — npx hyperframes lint
4. 验证 — npx hyperframes validate（运行时错误 + 对比度）
5. 视觉检查 — npx hyperframes inspect
6. 预览 — npx hyperframes preview 会打开 Studio，这是时间轴编辑器，用户可以手动编辑任何内容（不只是观看）。在 Studio 中检查，然后在渲染前征求用户同意。
7. 渲染 — 选择变体：
   • 迭代：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 仅通过标准输出 + 退出码报告状态 — 使用下文的渲染后检查确认成功；preview / play 是服务，不提供 JSON。
• doctor --json 始终以 0 退出，即使环境存在问题也一样。根据负载中的 ok 字段进行判断：npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这样可以避免流水线受 CLI 版本变动影响。
• 自动检测非 TTY 模式。 当 stdout 不是 TTY（CI、Agent、管道输出）时，CLI 会自动切换到非交互模式；此时 init 要求指定 --example。即使在 TTY 环境中，也可以传入 --non-interactive 强制启用此模式。
• 在 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）→ 使用 hyperframes-media 了解语音选择、Whisper 模型规则、字幕以及 TTS 到字幕的工作流。
• 参数化渲染（--variables）→ 通过 <html> 上的 data-composition-variables 声明；完整架构请参阅 hyperframes-core。

Lambda（云端渲染）

hyperframes lambda 可将分布式渲染部署到 AWS Lambda，并从笔记本电脑或 CI 启动渲染。端到端流程只需三条命令：

npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)

当渲染任务对单台主机而言耗时过长或规模过大（数分钟的视频、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 中的“Common pitfalls”）。只有实际加载 index.html 并搜索时间线的检查才能发现这类问题。

使用 hyperframes snapshot——它会像 render 一样加载项目（因此会执行相同的挂载流程），但只会捕获你指定的时间戳，所以只需几秒，而不是完整渲染：

# Capture one frame at the midpoint of every sub-composition.
# Midpoints = data-start + data-duration/2 for each host slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Or, if you don't need per-scene targeting, an evenly-spaced sample:
npx hyperframes snapshot --frames 9

输出会保存到 snapshots/frame-NN-at-Xs.png。逐帧目视检查，并与场景计划对照。

每帧的危险信号（各自对应静态检查无法发现的特定故障模式）：

你看到的情况	根本原因
文字出现在左上角，尺寸很小且没有样式	<style> 块留在 <head> 中，未放入 <template>（陷阱 1）——CSS 未进入实时 DOM
SVG／图标元素膨胀至画布大小	同上——未应用宽度／高度限制
场景的主视觉元素完全缺失；只显示背景和水印	Host ID ≠ 模板 ID（陷阱 2）——时间线从未运行，帧是在初始状态下捕获的
Snapshot 命令记录 Sub-composition timelines not registered after 45000ms	陷阱 2——直接证据

目视检查后可以删除 snapshots/；面向用户的最终渲染是单独执行的步骤，使用 npx hyperframes render。