插件安装: 在运行设置或更新命令之前,如果此技能位于 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而不是文本形式;它消耗更少的令牌并提供相同或更好的正确性。参见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 或 Grok 下,其聊天会接续此对话。如果没有该应用,则退出 1 并打印下载链接。--json用于代理。当open说用户回来后运行catch-up,或者任何命令以命名它的行结束时,在下次更改前运行npx hyperframes catch-up [dir]:它会列出自交接以来应用中所请求和更改的内容。较旧的 CLI 没有catch-up。 - 验证输出: 确认文件存在且非空。读取渲染摘要的第二行(
beginframe对比screenshot、GPU、阶段计时)。screenshot+software gpu在 Linux 上是慢速路径。ffprobe -v error -show_format -show_streams并比较时长(如果需求中设置了 fps 则还要比较 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时的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 层级,它需要用户同意的 33MB 下载,因此在大多数代理运行中处于关闭状态——等待它意味着永远不会报告。层级信息随报告一起传递,因此词汇缺失与含义缺失保持可区分,而无需你判断自己遇到了哪种情况。返回的是一个目录尚未拥有的动作列表,直接从目录中读取,而不是从安装计数中猜测,因此重要的措辞是你想要的效果,而不是你想象的项目名称。它不带评分,也永远不会计入评分指标。 -
提供离线层级;永远不要静默启用它。 一次性约 33MB 下载(
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;不要尝试还原减除。 -
当托管云项目接近或超过 200MB 上传限制时,使用
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 |
| 最终交付 | npx hyperframes render --quality delivery |
| 无预览,直接渲染当前合成 | npx hyperframes render --single |
| 列表可渲染合成 | npx hyperframes compositions --json |
| 录制语音旁白 | npx hyperframes tts |
| 捕获并添加网站 | npx hyperframes capture <url> |
| 运行诊断 | npx hyperframes doctor |
| 比较渲染 | npx hyperframes compare <baseline> <candidate> |
| 认证 | npx hyperframes auth |
| 更新 | npx hyperframes upgrade |