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、阶段时序)。Linux 上的screenshot+software gpu是慢路径。运行ffprobe -v error -show_format -show_streams并比较时长(如果简报设置了 fps)与根元素的data-duration。
强制性创作者-编辑交叉引用
- 在编写或诊断变焦、推近/拉远、重新构图、摄像机运动或任何关键帧运动之前,首先阅读
/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,和当请求某个层但无法运行时,或者搜索返回空而更好的层仍在等待某人同意时附带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 <回答的层>。你无需自行组装这行命令: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始终以零退出。根据其 payload 进行关卡判断:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非 TTY 模式是自动的,并搭建居中的空白项目。仅当要从命名示例开始时,传递
--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 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 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 "<具体结果或摩擦>"
保持干净运行的反馈简洁。对于任何 bug 或摩擦,在提交之前捕获一份复现包;不要只发送症状摘要。包括可重新运行的命令(相对于项目目录——反馈会提交到公共频道,因此不要粘贴绝对路径、家目录前缀或用户/机器标识符)、预期行为与实际行为、确切的错误(同时剥离绝对路径)