HyperFrames CLI
除非项目说明提供了包装器，否则以 npx hyperframes ... 运行命令。当存在包装器时，遵循它。CLI 需要 Node.js 22 或更高版本以及 FFmpeg。
开发循环
- 脚手架：
npx hyperframes init <project>或捕获一个站点。在非 TTY 模式下，传递--non-interactive --example=<name>。 - 创作： 使用
/hyperframes-core编写合成。 - 编辑时快速获取反馈： 在第一次 HTML 传递之后以及结构更改之后，运行
npx hyperframes lint。 - 运行最终关卡： 运行
npx hyperframes check；它会在打开浏览器之前重新运行 lint。不要预先附加一个多余的独立 lint 调用。添加--snapshots以获取带注释的概览帧和查找裁剪。 - 检查子合成： 当
index.html挂载了data-composition-src时，捕获中间点快照并检查每个挂载的场景。 - 打开最终的 Studio 预览： 运行
npx hyperframes preview，将时间线项目 URL 交给用户，并询问是修改还是渲染。 - 仅在批准后渲染： 迭代使用草稿质量，交付使用高质量。
- 验证输出： 确认文件存在、非空且具有合理的时长。
# 快速迭代检查；创作时根据需要重复。
npx hyperframes lint
# 必需的最终关卡；包含 lint。
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check 首先运行 lint，然后使用一个浏览器会话和一次定位扫描来审计运行时错误、失败的请求、布局、*.motion.json 断言和 WCAG 对比度。持久性问题会阻滞退出码；瞬态进入或退出问题仅作为参考。使用 --strict 来阻滞警告。validate、inspect 和 layout 作为别名保留以实现兼容性，但不得出现在新的指令或脚本中。
两种不同的预览界面
不要混淆这些状态：
| 界面 | 何时可能打开 | 目的 |
|---|---|---|
| 故事板 | 在合成检查之前，仅当 storyboard: yes 时 | 审查计划卡片和线框图草图。打开 ?view=storyboard#project/<name>。 |
| 最终合成预览 | 在 check 通过后 | 在渲染前审查已组装的时间线。打开 #project/<name>。 |
早期面板不是最终视频的批准。渲染始终需要 hyperframes-core/references/review-loop.md 定义的最终批准。
子合成冒烟测试
静态审计无法捕获所有挂载失败。当项目使用子合成时，为每个宿主槽位捕获至少一个可见的中间点：
npx hyperframes snapshot --at <t1>,<t2>,<t3>
将微小的无样式内容、画布大小的图标、缺少的英雄元素或时间线注册超时视为阻塞渲染的挂载缺陷。有关相应修复，请参阅 hyperframes-core/references/sub-compositions.md。
Agent 约定
-
对于 agent 和 CI 调用，优先使用
--json。服务器模式的render、preview和play不提供普通的 JSON 输出；preview --selection --json和preview --context --json是查询模式的例外。 -
doctor --json总是以零退出。基于其有效载荷进行门控：npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非 TTY 模式是自动的。
init在此模式下需要--example；使用--non-interactive在 TTY 上强制确定性行为。 -
在同一个验证循环中，对所有命令使用一个
HYPERFRAMES_RUN_ID。 -
当相应的警告、变量或 CI 条件必须阻滞渲染时，使用
--strict、--strict-all和--strict-variables。 -
JSON 路径将主目录编辑为
$HOME；不要尝试还原该编辑。 -
永远不要仅仅因为检查通过就进行渲染。在最终预览处暂停并等待批准。
Studio 定向编辑
当用户提到“这个元素”或当前选择时，查询 Studio 而不是猜测：
npx hyperframes preview --context --json --context-fields selection
尽可能使用 selection.target.hfId，否则使用其选择器和源文件。如果结果报告 no-selection，请用户点击元素并重新运行。只请求你需要的上下文切片；仅在需要计算样式或可编辑文本元数据时使用 --context-detail full。完整的行为和失败代码位于 references/preview-render.md。
渲染选择
| 需求 | 命令 |
|---|---|
| 快速本地迭代 | npx hyperframes render --quality draft |
| 最终本地交付 | npx hyperframes render --quality high --output out.mp4 |
| 可复现的容器渲染 | npx hyperframes render --docker --strict --output out.mp4 |
| 本地变量驱动的批量渲染 | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen 托管的零基础设施渲染 | npx hyperframes cloud render |
| 自管理的分布式 AWS 渲染 | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| 自管理的分布式 GCP 渲染 | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
当用户希望使用托管渲染而无需本地 Chrome、FFmpeg 或 AWS 时，使用云端渲染。仅当需要 AWS 所有权时使用 Lambda。仅当需要 GCP 所有权时使用 Cloud Run。在运行任何云端路径之前，阅读匹配的参考文档。
在验证渲染成功后，发送一份反馈报告，除非遥测已禁用或用户选择退出：
npx hyperframes feedback --rating <0-10> --comment "<具体结果或问题>"
保持干净运行的反馈简洁。对于任何错误或问题，请在提交前捕获一个重现包；不要只发送症状摘要。包括可重新运行的命令和工作目录、预期行为与实际行为、确切错误、输出是否完成/降级/失败、解决方法以及重现项目的状态。对于描述视觉缺陷（黑帧、闪烁、损坏输出、错误帧、空白输出或其他视觉异常）且评分 ≤ 7 的情况，还需包含一个 COMPOSITION_STRUCTURE: 块——一个保护隐私的结构剖析（元素计数 + 属性存在 + 时间线形状），以便维护者无需合成 ZIP 文件即可与已知错误族进行模式匹配。Agent 通过合成普查助手自动填写此内容；人类用户无需手动填写。如果问题没有再次重现，请说明情况，但仍包含最后失败的命令和日志。仅在获得同意后使用 --file-issue：它会将一个最小重现发布到公共 URL。所需的包格式和隐私警告位于 references/preview-render.md。
在运行命令之前阅读匹配的参考文档
以下参考文档和所属技能是强制性的命令契约，而非可选的背景阅读。在运行表中的命令之前，请阅读其匹配行。
| 需求 | 参考文档 |
|---|---|
init、capture、skills | references/init-and-scaffold.md |
lint、check、运动侧车文件、snapshot | references/lint-validate-inspect.md |
compare、grade-compare、变量驱动的 render --batch | references/compare-and-batch.md |
现有项目的 Studio 节拍网格 beats | references/beats.md |
preview、play、render、publish、Studio 上下文、反馈 | references/preview-render.md |
doctor、浏览器管理 | references/doctor-browser.md |
auth、HeyGen 托管云端渲染以及模板变量 | references/cloud.md |
| AWS Lambda 部署和渲染 | references/lambda.md |
| Google Cloud Run 部署和渲染 | references/cloudrun.md |
info、upgrade、compositions、docs、benchmark、遥测、媒体预处理 | references/upgrade-info-misc.md |
对于合成变量，还需阅读 /hyperframes-core → references/variables-and-media.md。对于 hyperframes add 和 hyperframes catalog，使用 /hyperframes-registry。在 hyperframes present 之前，阅读 /slideshow；在 hyperframes keyframes 之前，阅读 /hyperframes-keyframes。对于 TTS、转录、字幕或背景移除选择，使用 /media-use。
专门的命令由其所属的工作流文档记录：
npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
present 提供一个可导航的演示文稿，具有演示者和观众同步功能。beats 是 references/beats.md 中定义的独立 Studio 节拍网格工具。keyframes 展示 seek 安全的动画和运动路径诊断。