插件安装: 在设置或 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。 - 将项目交给桌面应用(如有提供): 当渲染器的 Framey 行以
hyperframes open …结尾时,提供npx hyperframes open [dir]。它会在 HyperFrames 桌面应用中打开项目并将其添加到主页;在 Claude Code 或 Codex 下,其聊天将继承此对话。如果没有桌面应用,则退出并返回 1,并打印下载链接。--json用于智能体。 - 验证输出: 确认文件存在且非空。读取渲染摘要的第二行(
beginframe与screenshot、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,然后使用一个浏览器会话和一个 seek 过程来审计运行时错误、失败的请求、布局、*.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时,以及当要求某个层但无法运行,或搜索未返回任何结果且更好的层仍在等待某人同意时的warnings。words上结果较弱是预期的;on-device上的相同结果是错误。top_score仅限 on-device,其背后没有阈值:排名器对每个查询都会以某种顺序返回整个目录,因此将其视为证据,而不是通过或失败。 -
dropped和unindexed是注册表和 on-device 索引之间的相反偏差,并且重新措辞查询都无法解决。dropped计算此注册表无法安装的排名名称,因此丢失的是最强匹配。unindexed计算索引完全无法看到的注册表动作,任何查询都无法返回。刷新注册表不是解决这两者中任何一个的答案:其清单具有 24 小时 TTL 并会自我修复,而向量是单独发布并获取到~/.hyperfaces/catalog/中的工件。当unindexed大于零时,使用--on-device重新运行会重新获取该索引,因此这是给用户的解决方案。纯粹的超覆盖偏差(dropped大于零而unindexed为零)不会触发重新获取;清除~/.hyperfaces/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 构建及其分词器,固定修订版本)以及注册表的目录向量,两者都缓存在~/.hyperfaces/下,不添加到项目或任何包中。缓存后,它按含义排名,不发送任何内容。说清楚大小,让用户决定,然后一旦他们同意,就传递--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 -- |