插件安装： 在执行设置或刷新命令之前，如果此技能位于HyperFrames插件内，请遵循插件执行规则。独立安装则保留下面的更新说明。
HyperFrames CLI
除非项目说明提供了包装器，否则以 npx hyperframes ... 运行命令。如果存在包装器，请遵循它。CLI需要Node.js 22或更高版本以及FFmpeg。
开发循环
- 脚手架：
npx hyperframes init <project>（居中空白）。或者捕获一个网站。仅当要从命名示例开始时传递--example=<name>。 - 找到动作： 如果请求指定了资产、声音、图像、语音或快速视觉编辑，请在提出计划之前通过
/media-use解决。否则，在手动编写动画之前，先搜索已经实现该效果的图元：npx hyperframes catalog --query "逐行显示标题"。描述你想要的效果，而不是你脑海中的机制。使用npx hyperframes add <name>安装（参见/hyperframes-registry）。只有在找不到匹配的图元时才手动编写。 - 创作： 使用
/hyperframes-core编写合成。要了解项目时间线上的内容（轨道、剪辑、开始、结束、播放内容），运行npx hyperframes timeline --json，而不是读取index.html和每个子合成文件：嵌套行携带绝对主时间线absStart/absEnd及其所属的file，而不仅仅是它们本地每个子合成的时间。优先使用--json而不是文本形式；它花费更少的token，同时获得相同或更好的正确性。参见references/upgrade-info-misc.md，了解无需读取整个输出即可回答常见问题的单行代码。 - 编辑时获取快速反馈： 在第一次HTML遍历之后以及结构性更改之后，运行
npx hyperframes lint。 - 运行最终关卡： 运行
npx hyperframes check；它会在打开浏览器之前重新运行lint。不要添加多余的独立lint调用。添加--snapshots以获取带注释的概览帧和裁剪区域。 - 检查子合成： 当
index.html挂载data-composition-src时，捕获中点快照并检查每个挂载的场景。 - 打开最终Studio预览： 运行
npx hyperframes preview --background，验证URL返回HTTP 200，将时间线项目URL交给用户，并询问是要修改还是渲染。保持其运行直到审核结束。 - 仅在批准后渲染： 迭代时使用
--quality draft，首次实际编码时使用--quality looks（CLI默认），最终交付时使用--quality delivery。 - 验证输出： 确认文件存在且不为空。读取渲染摘要的第二行（
beginframevsscreenshot、GPU、阶段时序）。Linux上的screenshot+software gpu是慢速路径。ffprobe -v error -show_format -show_streams并比较持续时间（以及如果简报中设置了fps）与根data-duration。
你的回合中的项目历史
每次对项目的写入都作为可撤销的条目保留。仅在两个时刻使用它，而不是在每个步骤：
- 回合开始时：
npx hyperframes history begin --who <你的名字> --label "<你将要做什么>"，然后npx hyperframes history --since mine --who <你的名字>以查看自你上一回合以来此人更改了什么。基于他们的编辑进行构建；切勿覆盖它们。 - 检查失败，或此人表示情况变得更糟：
npx hyperframes history undo --who <你的名字>可撤销你最新的回合，并保留此人的编辑。不要手动恢复。如果发生冲突，它会以退出码2退出并打印两个选项。
每个回合以 npx hyperframes history end 结束，这样你的写入会被视为你的，而不是 "在应用外更改"。当回合打开时，每次对项目的写入都会计为你，直到10分钟没有写入；之后回合自动结束。
强制性的创作者-编辑交叉引用
- 在创作或诊断缩放、切入/切出、重构、摄像机移动或任何关键帧动画之前，首先阅读
/hyperframes-keyframes。 - 在
hyperframes keyframes之前，阅读/hyperframes-keyframes；该命令显示动画轨迹，不诊断剪辑剪切。 - 对于剪切、修剪、拼接、重新排序或源时间编辑，阅读
/hyperframes-core并使用其剪辑/时间线契约。 - 对于淡入/淡出、交叉淡入、轨道增益、音量自动化、闪避、旁白雕刻或已放置音频上的FX，阅读
/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 looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check 首先运行lint，然后使用一个浏览器会话和一个搜索传递来审计运行时错误、失败的请求、布局、*.motion.json 断言和WCAG对比度。持久性发现项会阻塞退出码；瞬态进入或退出发现项仅提供信息。使用 --strict 来阻塞警告。validate、inspect 和 layout 仍然是兼容性别名，但不得出现在新指令或脚本中。
渲染前预览
仅在 check 通过后打开最终合成预览（#project/<name>），以审核组装好的时间线。聊天中的计划和 storyboard.html 草图不是最终视频的批准。渲染始终需要由 hyperframes/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上的相同结果是错误。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下载，因此在大多数代理运行中都是关闭的——等待意味着永远不会报告。层会随报告一起传递，因此词汇错误与含义错误保持可区分，而无需你判断自己遇到了哪一个。返回的是目录尚未拥有的动作列表，直接读取而不是根据安装计数猜测，因此重要的措辞是你想要的效果，而不是你想象的项目名称。它不携带评分，也永远不会进入评分指标。 -
提供离线层；永远不要静默启用它。 一次性约33 MB下载（
bge-small-en-v1.5的量化ONNX构建及其分词器，固定到特定修订版）以及来自注册表的目录向量，两者都缓存在~/.hyperframes/下，不会添加到项目或任何包中。缓存后它根据含义排序，不发送任何内容。说出大小并让用户决定，然后在他们同意后传递--on-device（使用-y跳过提示）。交互式提供仅会在TTY上触发。在--json下没有提示，但未找到任何内容的搜索会在warnings中放置相同的询问，因此读取该数组并将决定权交给用户。当用户询问下载内容、使用此模型的原因或什么离开机器时，请将他们指向 https://hyperframes.heygen.com/developers/catalog-search。 -
优先对代理和CI调用使用
--json。服务器模式的render、preview和play不提供普通的JSON输出；preview --selection --json和preview --context --json是查询模式例外。 -
doctor --json始终以零退出。检查其有效负载：npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非TTY模式是自动的，并搭建居中空白脚手架。仅当从命名示例开始时传递
--example。使用--non-interactive在TTY上强制仅标志模式。 -
在同一验证循环中对所有命令使用一个
HYPERFRAMES_RUN_ID。 -
当磁盘空间紧张时，运行
npx hyperframes clean（使用--dry-run先列出）；它移除死渲染留下的内容以及可以自行重建的空闲缓存，从不移除输出、源文件或运行中渲染使用的任何内容。将QC帧写入临时目录，而不是项目。 -
当相应的警告、变量或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 looks --output out.mp4 |
| 最终本地交付 | npx hyperframes render --quality delivery --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 l |
…
[翻译时截断]