HyperFrames CLI
以 npx hyperframes ... 运行命令，除非项目说明提供了包装器。如果存在包装器，则遵循它。CLI 需要 Node.js 22 或更高版本以及 FFmpeg。
开发循环
- 脚手架：
npx hyperframes init <project>或捕获站点。在非 TTY 模式下，传递--non-interactive --example=<name>。 - 寻找动作： 在手动编写动画之前，搜索是否已有原语实现：
npx hyperframes catalog --query "逐行显示标题"。询问你想要的效果，而不是你想到的机制。使用npx hyperframes add <name>安装（见/hyperframes-registry）。只有没有合适的原语时，才手动编写。 - 创作： 使用
/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，然后使用一个浏览器会话和一次 seek 传递来审计运行时错误、请求失败、布局、*.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 了解相应的修复方法。
代理约定
-
在手动编写动画之前搜索目录。
npx hyperframes catalog --query "<目标动作的通俗语言描述>"。搜索完全在本地进行：没有托管层，没有账户，查询文本永远不会被发送到任何地方。默认情况下，它根据与项目名称、标题和描述共享的词汇进行排名，这会遗漏任何未使用目录自身措辞的表述。添加--on-device以根据含义进行排名（参见下面的离线层）。 -
读取哪个层回答了问题；不要仅仅根据结果出现来推断。 使用
--json时，信封携带query、tier（on-device或words）、tier_detail、dropped、unindexed、shown、total和results，以及当回答层产生top_score时的top_score和当要求一个层但无法运行时产生的warnings。在words层上出现弱结果属预期行为；在on-device层上出现相同结果则是一个 bug。top_score仅适用于 on-device 层，并且背后没有阈值：排名器对每个查询都以某种顺序返回整个目录，因此应将其视为证据，而不是通过或失败的标志。 -
dropped和unindexed是注册表和 on-device 索引之间的相反偏差，重新措辞查询无法解决任何一个问题。dropped统计此注册表无法安装的已排名名称，因此丢失的是最强的匹配项。unindexed统计索引完全看不到的注册表移动，任何查询都无法返回这些移动。刷新注册表不是这两者的解决方案：其清单携带 24 小时的 TTL 并且会自愈，而向量是单独发布的工件，被获取到~/.hyperframes/catalog/。当unindexed大于零时，使用--on-device重新运行会重新获取该索引，因此这是要交给用户的补救措施。纯过度覆盖偏差（dropped大于零而unindexed为零）不会触发重新获取；清除~/.hyperframes/catalog/是摆脱该问题的唯一方法。这两个计数都是针对名称的，而不是针对结果的，因此任何一个都可能超过total。 -
当语义搜索返回的结果没有值得安装的内容时，请说出来。
npx hyperframes feedback --search-miss "<你运行的查询>" --wanted "<你需要的动作>" --tier on-device。这是唯一会把查询发送到任何地方的途径，并且它是一个单独的有意命令，正是为了确保普通的catalog --query承诺不发送任何东西。当 on-device 层回答了问题但最佳结果仍然不能达到目的时报告丢失；在words层出现弱结果是预期行为，不值得报告。返回的是一个目录中尚未拥有的动作列表，直接读取而非通过安装次数猜测，因此重要的措辞是你想要的效果，而不是你想象的项目名称。它不携带评分，也不会进入评分指标。 -
提供离线层；但不要静默启用它。 一次性大约 33 MB 的下载（
bge-small-en-v1.5的量化 ONNX 构建及其分词器，固定到特定修订版）和来自注册表的目录向量，两者都缓存在~/.hyperframes/下，不会添加到项目或任何包中。一旦缓存，它将根据含义进行排名，不会发送任何内容。说出大小让用户决定，然后在用户同意后传递--on-device（加上-y跳过提示）。交互式提供仅在 TTY 上触发，而在--json下根本不会打印任何相关内容，因此在代理运行中，您必须自己向用户提出。 -
对于代理和 CI 调用，优先使用
--json。服务器模式的render、preview和play不提供普通的 JSON 输出；preview --selection --json和preview --context --json是查询模式的例外。 -
doctor --json总是以退出码 0 退出。根据其负载进行判断：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；不要尝试逆转此编辑。 -
当托管云项目接近或超过 200 MB 的上传限制时，使用
cloud render --dry-run --json并遵循references/cloud.md中的.hyperframesignore调查。永远不要仅仅因为资产大而忽略它。 -
永远不要仅仅因为检查通过就渲染。在最终预览处暂停并等待批准。
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 |
技能归属是自动的——上面的示例不需要 --skill。由工作流构建的项目（hyperframes init --skill=<workflow>）会将其所属技能记录在 hyperframes.json 中，并且后续的每次渲染都会通过匿名遥测继承该技能：重新渲染、npm run render 和 --batch 都一样。仅当需要标记一个不是通过工作流创建的项目时，才显式传递 --skill=<slug>（其首次渲染会持久化它）。
当用户希望使用托管渲染而无需本地 Chrome、FFmpeg 或 AWS 时，使用云渲染。仅当需要拥有 AWS 的所有权时，才使用 Lambda。仅当需要拥有 GCP 的所有权时，才使用 Cloud Run。在运行任何云路径之前，请阅读相应的参考资料。
验证渲染成功之后，除非遥测被禁用或用户选择退出，否则发送一份反馈报告：
npx hyperframes feedback --rating <0-10> --comment "<具体结果或问题>"
保持顺利运行的反馈简洁。对于任何错误或问题，在进行反馈之前先捕获一个重现包；不要只发送症状摘要。包括可重用的命令（相对于项目目录——反馈提交到公共频道，所以不要粘贴绝对路径、主目录前缀或用户/机器标识符）、预期行为与实际行为、确切的错误（同样从堆栈跟踪中剥离绝对路径——保留 basename + 行号，去掉前导目录）、输出是否完成/降级/失败、变通方法以及重现项目的状态。对于评分 ≤ 7 且描述视觉缺陷（黑帧、闪烁、损坏输出、错误帧、空白输出或其他视觉异常）的反馈，还要包括一个 COMPOSITION_STRUCTURE: 块——一个保护隐私的结构性解剖（元素普查 + 属性存在性 + 时间线形状），以便维护者可以在没有合成 ZIP 的情况下根据已知 bug 家族进行模式匹配。代理通过合成普查辅助工具自动填充此块；人类用户不会手动填写。如果问题不再重现，请说明，但仍包括最后失败的命令和日志。仅在获得同意的情况下使用 --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 |
对于合成变量，以及...