插件安装： 在设置或 freshness 命令之前，如果此技能位于 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。 - 验证输出： 确认文件存在且非空。读取渲染摘要的第二行（
beginframe比screenshot、GPU、阶段计时）。screenshot+software gpu在 Linux 上是慢路径。运行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以根据含义进行排名（参见下面的离线层）。 -
即使视频不是英文，也用英文查询。 两层都索引了一个英文目录，因此使用其他脚本的查询不会产生可搜索的术语，并且会返回空结果。用英文描述动作；屏幕上的文字保持视频所需的任何语言。
No searchable words in query正是这个意思，而不是缺少组件，因此不要将其报告为目录缺口。 -
读取哪个层回答了；永远不要根据出现的结果推断。 使用
--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 下载，因此在大多数代理运行中处于关闭状态——等待它意味着永远不报告。层会随报告一起传递，因此词汇失误和含义失误仍然可以区分，而无需你判断自己命中哪一个。返回的是目录中尚不存在的动作列表，直接从安装计数以外的方式读取，因此重要的措辞是你想要的效果，而不是你想象的条目名称。它不携带评级，也永远不会进入评级指标。 -
提供离线层；不要静默启用它。 一次性的 ~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 |