HyperFrames CLI
通过 npx hyperframes ... 运行命令,除非项目说明提供了包装器。当包装器存在时,请遵循它。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。
开发循环
- 脚手架:
npx hyperframes init <项目>或捕获网站。在非 TTY 模式下,传递--non-interactive --example=<名称>。 - 创作: 使用
/hyperframes-core编写合成。 - 编辑时获取快速反馈: 在第一次 HTML 传递后和结构更改后运行
npx hyperframes lint。 - 运行最终关卡: 运行
npx hyperframes check;它会在打开浏览器之前重新运行 lint。不要预先添加多余的独立 lint 调用。添加--snapshots以获取带注释的概览帧和查找裁剪。 - 检查子合成: 当
index.html挂载data-composition-src时,捕获中点快照并检查每个挂载的场景。 - 打开最终 Studio 预览: 运行
npx hyperframes preview,将时间线项目 URL 交给用户,并询问是修改还是渲染。 - 仅在批准后渲染: 迭代使用草稿质量,交付使用高质量。
- 验证输出: 确认文件存在、非空且具有合理的持续时间。
# 快速迭代检查;在创作过程中根据需要重复。
npx hyperframes lint
# 必需的最终关卡;包含 lint。
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check 首先运行 lint,然后使用一个浏览器会话和一次查找传递来审计运行时错误、失败的请求、布局、*.motion.json 断言和 WCAG 对比度。持久性发现会阻塞退出码;瞬态进入或退出发现仅供参考。使用 --strict 来阻塞警告。validate、inspect 和 layout 仍然是用于兼容性的别名,但不得出现在新指令或脚本中。
两种不同的预览界面
不要混淆这些状态:
| 界面 | 可能打开的时间 | 目的 |
|---|---|---|
| 故事板 | 在合成检查之前,仅当 storyboard: yes 时 | 审查计划卡和线框图。打开 ?view=storyboard#project/<名称>。 |
| 最终合成预览 | 在 check 通过后 | 在渲染前审查组装好的时间线。打开 #project/<名称>。 |
早期故事板不是最终视频的批准。渲染始终需要 hyperframes-core/references/review-loop.md 定义的最终批准。
子合成烟雾测试
静态审计无法捕获每次挂载失败。当项目使用子合成时,为每个宿主槽捕获至少一个可见的中点:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
将微小的无样式内容、画布大小的图标、缺失的英雄元素或时间线注册超时视为阻塞渲染的挂载缺陷。有关相应的修复,请参见 hyperframes-core/references/sub-compositions.md。
代理约定
-
对于代理和 CI 调用,首选
--json。服务器模式下的render、preview和play不提供普通的 JSON 输出;preview --selection --json和preview --context --json是查询模式例外。 -
doctor --json总是以零退出。根据其有效载荷进行判断:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非 TTY 模式是自动的。在那里
init需要--example;在 TTY 上使用--non-interactive来强制确定性行为。 -
在同一个验证循环中的所有命令使用一个
HYPERFRAMES_RUN_ID。 -
当相应的警告、变量或 CI 条件必须阻塞渲染时,使用
--strict、--strict-all和--strict-variables。 -
JSON 路径会将 home 目录编辑为
$HOME;不要试图反转编辑。 -
永远不要仅仅因为检查通过就渲染。在最终预览处暂停并等待批准。
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 high --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 <项目> --width 1920 --height 1080 --wait |
| 自管理的分布式 GCP 渲染 | npx hyperframes cloudrun render <项目> --width 1920 --height 1080 --wait |
当用户希望在没有本地 Chrome、FFmpeg 或 AWS 的情况下进行托管渲染时,使用云渲染。仅当需要对 AWS 的所有权时,才使用 Lambda。仅当需要对 GCP 的所有权时,才使用 Cloud Run。在运行任何云路径之前,请阅读匹配的参考。
验证渲染成功后,发送一份反馈报告,除非遥测已禁用或用户已选择退出:
npx hyperframes feedback --rating <0-10> --comment "<具体结果或摩擦>"
保持干净运行的反馈简洁。对于任何错误或摩擦,在提交之前捕获一个重现包;不要只发送症状摘要。包括可重新运行的命令和工作目录、预期行为与实际行为、确切错误、输出是否完成/回退/失败、解决方法以及重现项目状态。如果问题没有再次重现,说明情况并仍然包括上次失败的命令和日志。仅在有同意时使用 --file-issue:它会将最小重现发布到公共 URL。必需的包格式和隐私警告位于 references/preview-render.md。
在运行命令之前阅读匹配的参考
以下参考和所属技能是强制性的命令契约,不是可选的背景阅读。在运行表中的命令之前,请阅读其对应的行。
| 需求 | 参考 |
|---|---|
init、capture、skills | references/init-and-scaffold.md |
lint、check、动作 sidecar、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、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 <项目目录> --port 3004 --no-open
npx hyperframes beats <项目目录> --json
npx hyperframes keyframes <项目目录> --json
present 提供一个可导航的演示文稿,带有演示者和观众同步。beats 是独立的 Studio 节拍网格工具,定义在 references/beats.md 中。keyframes 展示搜索安全的动画和运动路径诊断。