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 --background，确认 URL 返回 HTTP 200，将时间线项目 URL 交给用户，并询问是修改还是渲染。保持预览活动直到审核结束。 - 仅在批准后渲染： 迭代使用草稿质量，最终交付使用高质量。
- 验证输出： 确认文件存在、非空，并且具有合理的时长。
强制性的创作者-编辑交叉引用
- 在创作或诊断缩放、推入/推出、重构图、摄像机运动或任何关键帧运动之前，请先阅读
/hyperframes-keyframes。 - 在
hyperframes keyframes之前，请阅读/hyperframes-keyframes；该命令显示动画轨迹，不诊断片段剪切。 - 对于剪切、修剪、拼接、重新排序或源时间编辑，请阅读
/hyperframes-core并使用其片段/时间线合约。 - 对于淡入/淡出、交叉淡入淡出、轨道增益、音量自动化、闪避、画外音雕刻或对放置的音频应用效果，请阅读
/hyperframes-audio。当片段放置或画面时间也发生变化时，同时加载内核。 - 仅使用
/media-use来获取/生成媒体或预处理衍生资源。从/hyperframes-core→references/creator-editing-recipes.md复制创作者编辑标记。
# 快速迭代检查；作者创作时可按需重复。
npx hyperframes lint
# 必需的最终检查；包括 lint。
npx hyperframes check
npx hyperframes preview --background
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 约定
-
在徒手编写运动之前搜索目录。
npx hyperframes catalog --query "<用简单英文描述的动作>"。搜索完全是本地的：没有托管层，没有帐户，查询文本永远不会被发送到任何地方。默认情况下，它根据与项目名称、标题和描述共享的词汇进行排名，这会遗漏任何不重复使用目录自身措辞的短语。添加--on-device以根据含义进行排名（参见下面的离线层）。 -
即使视频不是英文，也使用英文查询。 两个层都为英文目录建立索引，因此使用其他脚本的查询不会产生可搜索的术语并返回空结果。用英文描述动作；屏幕上的文字保持视频所需的任何语言。
查询中没有可搜索的单词就是这个意思，并非缺少组件，因此不要将其报告为目录缺口。 -
阅读哪个层回答了问题；永远不要从结果出现来推断。 使用
--json时，信封携带query、tier（on-device或words）、tier_detail、dropped、unindexed、shown、total和results，以及当回答层产生时附带top_score，当请求一个层但无法运行时附带warnings。words上的弱结果是预期的；on-device上的相同结果是一个错误。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 <回答的层>。你不需要手动组装那行命令：catalog --query会打印预填充的版本，并且每个--json搜索信封都将其作为report_gap携带，查询和层已经正确——填写--wanted并发送。这是唯一会将查询发送到任何地方的路径，并且它是一个单独的、经过深思熟虑的命令，正是为了确保普通的catalog --query保持其不发送任何内容的承诺。在任何一个层上报告，只要结果没有完成所需操作；不要等待 on-device 层，它需要同意下载 33 MB，因此在大多数 agent 运行中是关闭的——等待它意味着永远不报告。该层会连带在报告中，因此词汇未命中与含义未命中仍然可以区分，无需你判断是哪个。返回的是目录中尚不存在的动作列表，直接读取而不是通过安装计数猜测，因此重要的措辞是你想要的效果，而不是你想象的项目名称。它不携带评级，也永远不会进入评级指标。 -
提供离线层；永远不要静默启用它。 一次性 ~33 MB 下载（
bge-small-en-v1.5的量化 ONNX 构建及其分词器，固定为固定修订版）和来自注册表的目录向量，都缓存在~/.hyperframes/下，不会添加到项目或任何包中。缓存后，它根据含义进行排名，不发送任何内容。说出大小让对方决定，然后在他们同意后传递--on-device（使用-y跳过提示）。交互式提供仅在 TTY 上触发，并且在--json下不会打印任何关于它的信息，因此在 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；不要尝试反转替换。 -
当托管的云项目接近或超过 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 "<具体结果或问题>"
保持简洁的干净运行反馈。对于任何错误或问题，在提交之前捕获一个复现包；不要只发送问题摘要。包括可重试的命令（相对于项目目录——反馈会提交到公共频道，因此不要粘贴绝对路径、主目录前缀或用户/机器标识符）、预期与实际行为、确切错误（同样从堆栈跟踪中去除绝对路径——保留基本名称 + 行号，去掉前导目录）、输出是否完成/回退/失败、解决方法以及复现项目状态。对于描述视觉缺陷（黑帧、闪烁、损坏输出、错误帧、空白输出或其他视觉异常）且评分 ≤ 7 的评级，还需包含一个 COMPOSITION_STRUCTURE: 块——一个保护隐私的结构性解剖（元素清单 + 属性存在 + 时间线形状），以便维护者无需合成 ZIP 即可模式匹配已知的错误系列。Agent 通过合成普查助手自动填充此内容；人类用户无需手动填写。如果问题没有再次重现，请说明并仍包含最后一次失败的命令和日志。仅在获得同意后使用 --file-issue：它会将最简复现发布到公共 URL。必需的包格式和隐私警告位于 references/preview-render.md。
在运行命令前阅读相应的参考文档
以下参考文档在命令运行前必须阅读...
[后续内容被截断用于翻译]