hyperframes-cli

插件安装： 如果此技能位于 HyperFrames 插件中，在运行设置或检查更新的命令前，请遵循插件执行规则。独立安装请遵循下方的更新说明。

HyperFrames CLI

除非项目说明提供了包装命令，否则请使用 npx hyperframes ... 运行命令。有包装命令时，请遵循该命令。CLI 需要 Node.js 22 或更高版本，以及 FFmpeg。

开发流程

1. 搭建项目： npx hyperframes init <project>（居中留白）。或者采集网站。只有在要从指定示例开始时，才传入 --example=<name>。
2. 找到合适的动效： 如果请求中提到了素材、声音、图像、语音或快速视觉编辑，请先通过 /media-use 找到对应内容，再提出方案。否则，手动编写动效前，请先搜索是否已有可实现该效果的基础组件：npx hyperframes catalog --query "reveal a headline one line at a time"。描述你想要的效果，而不是你想到的实现机制。使用 npx hyperframes add <name> 安装（参见 /hyperframes-registry）。只有找不到合适选项时，才手动编写。
3. 编写内容： 使用 /hyperframes-core 编写合成内容。若要了解项目时间线上的内容（轨道、片段、起止时间和播放内容），请运行 npx hyperframes timeline --json，不要读取 index.html 和每个子合成文件：嵌套行包含主时间线中的绝对 absStart/absEnd 及其所属 file，而不只是各子合成内的局部时间。优先使用 --json 而非文本格式；在正确性相同或更好的情况下，它消耗的令牌更少。常见问题的一行命令见 references/upgrade-info-misc.md，无需读取完整输出。
4. 编辑时快速获取反馈： 首轮 HTML 编写完成后以及结构性更改后，运行 npx hyperframes lint。
5. 运行最终检查： 运行 npx hyperframes check；它会在打开浏览器前重新运行 lint。不要额外重复单独运行 lint。添加 --snapshots 可获取带注释的概览帧和问题区域裁剪图。
6. 检查子合成： 当 index.html 挂载 data-composition-src 时，截取中点快照并检查每个已挂载场景。以全分辨率检查开头 30 秒和报告的问题时间点；请放大查看精细的几何细节、文字和 WebGL 边缘，不要只凭联系表判断。
7. 打开最终 Studio 预览： 运行 npx hyperframes preview --background，确认 URL 返回 HTTP 200，将时间线项目 URL 提供给用户，并询问是否要修改或渲染。审核结束前，请保持预览运行。
8. 仅在获批后渲染： 迭代时使用 --quality draft，首次正式编码时使用 --quality looks（CLI 默认值），最终交付时使用 --quality delivery。
9. 提供桌面应用项目选项： 当渲染的 Framey 行以 hyperframes open … 结尾时，提供运行 npx hyperframes open [dir] 的选项。它会在 HyperFrames 桌面应用中打开项目并将其添加到 Home；在 Claude Code、Codex 或 Grok 中，应用内聊天会接续此对话。若未安装该应用，命令会以 1 退出并打印下载链接。供 Agent 使用时添加 --json。当 open 提示用户返回后运行 catch-up，或任何命令的输出末尾提到该命令时，请在进行下一次更改前运行 npx hyperframes catch-up [dir]：它会列出交接后在应用中提出的请求和所做的更改。较旧的 CLI 不支持 catch-up。
10. 验证输出： 确认文件存在且非空。阅读渲染摘要的第二行（beginframe 与 screenshot、GPU、各阶段耗时）。在 Linux 上，screenshot 加 software gpu 是较慢的路径。运行 ffprobe -v error -show_format -show_streams，并将时长（若需求指定了 fps，也包括 fps）与根级 data-duration 进行比较。按照与预览相同的时间点，目视检查解码后的视频帧，包括特写画面；检查或编码成功并不能保证画布中的像素正确。

本轮项目历史记录

对项目的每次写入都会保存为一条可撤销的记录。只在两个时点使用它，切勿每一步都使用：

• 开始一轮时： 运行 npx hyperframes history begin --who <your-name> --label "<what you are about to do>"，然后运行 npx hyperframes history --since mine --who <your-name>，查看自上次轮次以来其他人所做的更改。基于他们的编辑继续；切勿覆盖。
• 检查失败，或对方说效果变差时： 运行 npx hyperframes history undo --who <your-name>，撤销你最新一轮的更改，同时保留对方的编辑。不要手动改回。发生冲突时，该命令会以状态码 2 退出，并显示两种选择。

每轮结束时运行 npx hyperframes history end，这样你的写入会标记为你所做，而不是“在应用之外更改”。轮次开启期间，所有项目写入都会计入你的名下；若 10 分钟内没有写入，轮次就会自动结束。

强制要求的创作者编辑交叉参考

• 在创作或诊断缩放、推近／拉远、重新构图、镜头移动或任何关键帧动画之前，先阅读 /hyperframes-keyframes。
• 使用 hyperframes keyframes 之前，先阅读 /hyperframes-keyframes；该命令会展示动画轨迹，不会诊断片段剪切。
• 对于剪切、修剪、拼接、重排或源素材时序编辑，请阅读 /hyperframes-core 并遵循其中的片段／时间线约定。
• 对于淡入／淡出、交叉淡化、音轨增益、音量自动化、闪避、旁白腾挪或已放置音频上的效果，请阅读 /hyperframes-audio。如果还会更改片段放置位置或画面时序，也要一并加载 core。
• 请求中提及素材、声音、图像、语音或快速视觉编辑时，必须先通过 /media-use 确定处理方式，才能提出计划。 从 /hyperframes-core → references/creator-editing-recipes.md 复制创作者编辑标记。

# Fast iteration check; repeat while authoring as needed.
npx hyperframes lint

# Required final gate; includes 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>）来检查已组装的时间线。聊天中的计划和分镜板（boards/storyboard.html，格式见 hyperframes-creative/references/storyboard-recipe.md）都不能视为对最终视频的批准。渲染始终需要获得 hyperframes/references/review-loop.md 中定义的最终批准。

子合成冒烟测试

静态审计无法发现所有挂载失败。当项目使用子合成时，请为每个宿主插槽至少截取一张可见的中点画面：

npx hyperframes snapshot --at <t1>,<t2>,<t3>
# For multiple samples within one scene or interval:
npx hyperframes snapshot --composition <data-composition-id> --frames 8
npx hyperframes snapshot --range 3:5 --frames 8

微小且未设置样式的内容、与画布同尺寸的图标、缺失的主体元素或时间线注册超时，都应视为会阻止渲染的挂载缺陷。相应修复方法见 hyperframes-core/references/sub-compositions.md。

Agent 约定

• 手动编写动画前，先搜索目录。 npx hyperframes catalog --query "<the beat, in plain English>"。搜索完全在本地进行：没有托管层级、不需要账户，查询文本也绝不会发送到任何地方。默认情况下，搜索会根据与项目名称、标题、描述和标签共用的词汇进行排名，因此无法命中未使用目录自身措辞的表达。添加 --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 层级出现同样的结果则是个 bug。top_score 仅适用于设备端，且没有对应的阈值：无论查询是什么，排名器都会按某种顺序返回整个目录，因此应将它视为参考依据，而不是通过或未通过的判定。

• dropped 和 unindexed 表示注册表与设备端索引之间相反的偏差，改写查询无法解决其中任何一种。 dropped 统计了此注册表无法安装的排名靠前项目，因此丢失的是最匹配的项目。unindexed 统计了索引完全看不到的注册表动画，这些动画无论如何查询都无法返回。刷新注册表并不能解决这两种情况：其清单带有 24 小时 TTL，并会自动修复；而向量是单独发布的构件，会下载到 ~/.hyperframes/catalog/。如果 unindexed 大于零，使用 --on-device 重新运行会重新获取该索引，因此应建议用户这样处理。若只有覆盖范围偏差（dropped 大于零，而 unindexed 为零），则不会触发重新获取；清除 ~/.hyperframes/catalog/ 是唯一的解决办法。这两个计数统计的是项目名称，而不是结果，因此任一计数都可能超过 total。

• 如果搜索没有找到值得安装的内容，就如实说明。 npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>。你不必自行拼出这条命令：catalog --query 会预先填好并打印出来；每个 --json 搜索数据封装也会附带 report_gap，其中的查询和层级均已填妥——只需填写 --wanted 并发送。这是唯一会将查询发送到任何地方的方式；它是单独且需要明确执行的命令，正是为了让普通的 catalog --query 兑现不发送任何内容的承诺。无论是哪个层级，只要结果无法实现所需效果，就应报告；不要等待设备端层级。它需要用户同意后下载 33 MB，因此在大多数 Agent 运行中都处于关闭状态——等它启用意味着永远不会报告。 报告中会附带层级，因此无需判断自己遇到的是哪种情况，就能区分词汇未命中和含义未命中。返回的内容是目录尚未收录的动画列表，应直接阅读，而不是根据安装次数猜测；因此，重要的是你想要的效果，而不是你设想中的项目名称。报告不包含评分，也绝不会计入评分指标。

• 可以提供离线层级，但绝不要默默启用。 一次性下载约 33 MB（量化版 bge-small-en-v1.5 ONNX 构建及其分词器，固定到指定修订版），以及从注册表获取的目录向量，两者都会缓存在 ~/.hyperframes/ 下，不会添加到项目或任何软件包中。缓存完成后，它会在不发送任何内容的情况下按含义排名。明确告知用户下载大小并让其决定；获得同意后，再传入 --on-device（使用 -y 可跳过提示）。交互式选项只会在 TTY 中出现。使用 --json 时不会弹出提示，但如果搜索没有结果，warnings 中会包含相同的提示；请查看该数组，并自行询问用户的决定。如果用户询问下载内容、为何使用此模型，或有什么内容会离开设备，请引导他们访问 https://hyperframes.heygen.com/developers/catalog-search。

• Agent 和 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。在 TTY 上使用 --non-interactive 可强制启用仅标志参数模式。

• 同一验证循环中的所有命令都使用同一个 HYPERFRAMES_RUN_ID。

• 磁盘空间紧张时，运行 npx hyperframes clean（先用 --dry-run 列出内容）；它会清理失败渲染遗留的内容和可自动重建的闲置缓存，但不会删除输出、源文件或运行中渲染正在使用的任何内容。将一次性 QC 帧写入临时目录，然后只删除该目录。受管理的快照运行会保留最新的 10 个项目以及当前、最新和已渲染的证据；正在进行的捕获，以及未满 24 小时的运行都会受到保护。在证据过期前，将有意保留的前后对比证据复制到受管理存储之外。切勿整体删除 .hyperframes：其中还包含项目历史记录。

• 只有在相应的警告、变量或 CI 条件必须阻止渲染时，才使用 --strict、--strict-all 和 --strict-variables。

• 对于 shader_unbounded_cosine_pow，在执行 pow(1 - cosine, exponent) 之前，将余弦值限制在 [0, 1] 范围内；仅使用下限 max 不足以解决问题。请遵循 /hyperframes-animation → adapters/three.md 修复源代码，并验证受影响 GPU 上的预览和导出。Lint 只能识别静态着色器表达式，而软件渲染可能无法检测到硬件特定的无效像素。

• 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
渲染会在启动它的进程停止时停止，因此按下 Ctrl-C 或关闭终端都不会让 Chrome 继续运行。如果你的工具会在命令超时或结束时终止整个进程组，长时间渲染也会随之终止。使用 HYPERFRAMES_RENDER_DETACHED=1 在独立进程组中启动此类渲染，例如 bash -c 'set -m; HYPERFRAMES_RENDER_DETACHED=1 npx hyperframes render --output out.mp4 < /dev/null > render.log 2>&1 &'（适用于 macOS 和 Linux），然后检查日志和输出文件，而不是等待命令完成。

技能归属会自动确定——上面的示例无需使用 --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 "<specific result or friction>"

对于运行正常的反馈，内容应简洁。遇到任何错误或使用阻碍时，请在提交前记录一份复现材料包；不要只发送症状摘要。请包括可重新运行的命令（相对于项目目录——反馈会提交到公开渠道，因此不要粘贴绝对路径、主目录前缀或用户／机器标识符）、预期行为与实际行为、确切错误（堆栈跟踪中的绝对路径也要删去——保留基本文件名和行号，去掉开头的目录）、输出是否完成／回退／失败、解决方法，以及复现项目的状态。对于描述视觉缺陷（黑帧、闪烁、输出损坏、帧错误、输出空白或其他视觉异常）的评分 ≤ 7，还要附上 COMPOSITION_STRUCTURE: 块——其中包含保护隐私的结构概要（元素清单 + 属性是否存在 + 时间线形态），以便维护人员在没有合成 ZIP 的情况下将问题与已知错误类型对应起来。Agent 会通过合成清单辅助工具自动填写此内容；用户无需手动填写。如果问题未能再次复现，请说明这一点，但仍须附上上次失败的命令和日志。只有获得同意时才使用 --file-issue：它会将最小复现内容发布到公开 URL。所需材料包格式和隐私警告见 references/preview-render.md。

还有两种报告使用不带 --rating 的 --comment，因此不会计入评分指标。除非遥测已禁用或用户选择退出，否则请按照相同的隐私规则发送：

• 缺失功能。 每当有人要求 HyperFrames 或宿主应用无法实现，或只能通过变通方法实现的功能时，每项请求发送一份报告：npx hyperframes feedback --comment "MISSING FEATURE: <用对方自己的话描述所需功能，省略名称、客户端、数字和路径> | WORKAROUND: <你采取的替代办法，或 none>"。报告应描述他们需要的功能，绝不可包含其内容或任何私人信息。目录搜索无结果时，应使用 --search-miss。
• 宿主应用。 设置了 HYPERFRAMES_CLIENT 时，表示 CLI 正在宿主应用中运行。当该应用本身造成阻碍（面板、按钮、预览或导出行为异常）时，请附上复现材料包并发送 npx hyperframes feedback --comment "HOST APP: <发生了什么>"。

运行命令前，请先阅读对应的参考文档

以下参考文档及其所属技能是必须遵循的命令约定，并非可选的背景阅读。运行表格中的命令前，请先阅读对应行。

需求	参考文档
init、capture、skills	references/init-and-scaffold.md
lint、check、motion sidecars、snapshot	references/lint-validate-inspect.md
compare、grade-compare、由变量驱动的 render --batch	references/compare-and-batch.md
现有项目的 Studio 节拍网格中的 beats	references/beats.md
preview、play、render、publish、Studio 上下文、反馈	references/preview-render.md
doctor、浏览器管理	references/doctor-browser.md
auth、由 HeyGen 托管的云渲染及模板变量	references/cloud.md
AWS Lambda 部署与渲染	references/lambda.md
Google Cloud Run 部署与渲染	references/cloudrun.md
info、upgrade、compositions、timeline、docs、benchmark、遥测、媒体预处理	references/upgrade-info-misc.md

对于合成变量，还要阅读 /hyperframes-core → references/variables-and-media.md。对于 hyperframes add 和 hyperframes catalog，请使用 /hyperframes-registry。运行 hyperframes present 前，请阅读 /slideshow；运行 hyperframes keyframes 前，请阅读 /hyperframes-keyframes。对于 TTS、转录、字幕或背景移除选项，请使用 /media-use。

专用命令由其所属工作流有意单独说明：

npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
npx hyperframes media-treatment --capabilities
npx hyperframes figma asset KEY:10-20

present 会提供可导航的演示文稿，并同步演讲者视图与观众视图。beats 是独立的 Studio 节拍网格工具，定义见 references/beats.md。keyframes 会显示可安全跳转的动画与运动路径诊断信息。media-treatment 用于发现、应用和清除本地素材上的确定性效果——使用 --capabilities 查看概览，使用 --capability <name> 查看某个系列；关于需求所要求的效果类型，请参阅 /media-use。figma 通过 REST API 使用 asset、tokens 和 component 子命令导入内容，并且需要 FIGMA_TOKEN；运动和着色器导入没有 REST 端点，只能由 Agent 执行，因此相关说明由 /figma 负责。

不应运行的命令

hyperframes --help 中有两个条目不属于创作流程，尝试使用它们只会浪费一次调用：

• events 是技能用于报告其自身调用情况的遥测端点，最好通过捆绑脚本调用。它会发出匿名事件，无论传入什么参数都会以状态码 0 退出。它无法读取遥测数据，Agent 没有理由手动调用它。
• validate、inspect 和 layout 是为旧脚本保留的弃用别名。当前维护的命令是 check，而且本技能中的所有参考文档都以它为准。

剩余额度用量

在视频工作流开始时运行 npx hyperframes usage --json，并在起草完成后、渲染前等里程碑再次运行。交接时读取最新用量也可作为开始时的读取。使用 --harness claude-code、--harness codex 或 --harness grok 显式选择。

已知结果包含 status: "known"、harness、planTier、session、weekly 和 spend。每个可用时间窗口都包含 usedPercent、remainingPercent 和 resetsAt；不可用的窗口为 null。如果有订阅层级，则 planTier 为易读的订阅层级；否则为 null。Claude Code 会报告共享的五小时和每周窗口；按用量计费的计划（例如 Enterprise）没有这两个窗口，并会报告 spend，即计费周期支出限额中已使用的比例，其 resetsAt 为 null。如果可用，Codex 会报告共享的会话和每周窗口。Grok 会报告包含在计划中的每周额度，且 session 为 null。只有 Claude Code 会报告 spend；其他情况下该字段为 null。如果没有可用窗口，结果为 status: "unknown"，且 reason: "no_usage_windows"。

未知结果包含 status: "unknown" 和不含令牌的 reason。登录信息缺失、过期、不受支持、含糊不清或无法读取，以及提供方响应不可用时，都会返回未知状态。应如实报告未知状态，不要猜测额度。该命令会读取现有凭据，不会刷新或重写凭据，也不会输出令牌或遥测数据。用量是一个快照；它不会预留额度，也不会估算下一个视频的成本。由用户决定范围和工作流选项。