HyperFrames CLI
一切操作都通过 npx hyperframes 运行,除非项目说明指定了本地包装器。请严格遵守本地包装器。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 脚手架 —
npx hyperframes init my-video(或从 URL 使用capture)。init还会检查已安装的技能与 GitHub 上的最新版本,如果任何技能过时,则更新全局技能集。--skip-skills标志目前已被禁用(暂时的,等待 skills.sh 注册表更新),因此每次init都会运行此检查并获取我们最新的技能。 - 编写 — 编写 HTML 合成(参见
hyperframes-core技能) - 代码检查 —
npx hyperframes lint(静态检查,快速 — 在迭代早期运行它) - 检查 —
npx hyperframes check(浏览器门控;添加--snapshots可获取带注释的帧和每个发现的裁剪图) - 预览 / 编辑 —
npx hyperframes preview打开 Studio,这是一个时间线编辑器,用户可以在其中手动编辑任何内容(不仅仅是观看)。在那里查看,然后询问后再渲染。 - 渲染 — 选择变体:
- 迭代:
npx hyperframes render --quality draft - 交付:
npx hyperframes render --quality high --output out.mp4 - CI / 跨主机重现:
npx hyperframes render --docker --strict --output out.mp4 - 云渲染,零基础设施:
npx hyperframes cloud render(HeyGen 托管渲染;无需本地 Chrome/FFmpeg/AWS,参见下文云渲染部分) - 云渲染,自带 AWS:
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(参见下文 Lambda 部分)
- 迭代:
- 报告反馈 — 验证输出后,每个任务运行一次
npx hyperframes feedback --rating <1-5> --comment "..."(参见代理约定)。
在预览之前运行 check。它首先运行 linter(并在 lint 错误时完全跳过浏览器),然后在 一次 浏览器会话和一次查找遍历中完成旧的 validate → inspect → snapshot 序列所做的所有事情:运行时控制台错误和失败的请求、布局缺陷(文本溢出气泡/容器或画布、保持重叠、遮挡)、运动副驾验证(*.motion.json — 查找入场、交错顺序、帧内状态、活力)以及 WCAG 对比度。对比度失败是错误,并携带采样的前景/背景颜色、测量值与所需比率以及建议的合规颜色,因此大多数对比度修复不需要截图。每个发现都携带选择器、data-* 标识、合成源文件、边界框和采样时间 — 直接跳转到 HTML。单样本瞬态降级为信息;跨样本保持的发现会门控退出代码(--strict 也会门控警告)。validate、inspect 和 layout 仍然有效,但它们是 check 某些部分的弃用别名。
对于运动密集型工作,首选快照驱动的迭代和 *.motion.json 副驾 — 参见 references/lint-validate-inspect.md 了解规范和运动验证规范。要比较代理编写的候选变体,请使用 npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json] 通过其自己的运行时渲染每个合成,组装一个带标签的表格,并排检查,然后选择。要选择颜色分级,请使用颜色特定的同级命令 npx hyperframes grade-compare --for <frame> --grades grades.json(或 --luts a.cube,b.cube),通过真实的 WebGL 分级运行时将每个分级候选渲染到一个带标签的 PNG 中,然后选择获胜者。
代理约定
适用于每个命令的交叉规则:
--json可用于除render、preview和play服务模式之外的每个命令。 将其用于任何支持的命令的代理/CI 调用;输出包括一个_meta信封(cli 版本、最新可用版本、更新建议)。render仅通过 stdout + 退出代码报告状态 — 使用下面的渲染后检查验证成功。preview --selection --json和preview --context --json是预览例外:它们不启动服务器,而是查询用户正在运行的 Studio 会话并退出。doctor --json始终以 0 退出,即使环境损坏。根据有效负载的ok字段门控:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这保护管道免受 CLI 发布变更的影响。- 非 TTY 模式会自动检测。 当
stdout不是 TTY(CI、代理、管道输出)时,CLI 会自动切换到非交互模式;init此时需要--example。传递--non-interactive以强制在 TTY 上进入此模式。 - 关于渲染的 CI 门控:
--strict在 lint 错误时失败,--strict-all在警告时也失败,--strict-variables在未声明的--variables键上失败。 - 使用
HYPERFRAMES_RUN_ID关联验证循环。 驱动 CLI 针对每个任务/设计元素的管理器应为每个工作单元设置一次此环境变量;每次命令调用都会将其附加到遥测中,并且check会输出每个门控的细分,使每次任务的往返次数可衡量。 --json中的路径会被编辑 —$HOME成为字面字符串$HOME,因此输出可以安全地粘贴到错误报告和代理上下文中。- 渲染是用户门控的。 检查通过后切勿自动渲染。在
preview时暂停,告诉用户视频在 Studio 中可编辑,并且只有在他们批准后才渲染。 - 将 Studio 上下文用于用户指导的编辑。 当用户说“这个选中的元素”、“我点击的东西”、“当前选择”或类似内容时,请他们先在 Studio 中选择它,然后运行
npx hyperframes preview --context --json --context-fields selection。使用返回的selection.target.hfId/selector、selection.sourceFile、selection.currentTime和selection.thumbnailUrl来定位编辑。如果selection是null并且errors.selection.code是no-selection,请用户点击该元素并重新运行;不要从截图中猜测。 - 保持 Studio 上下文紧凑。
preview --context --json默认返回紧凑的选择。添加--context-fields selection、--context-fields selection,lint或--context-fields lint以避免使代理上下文膨胀。仅当您需要计算样式、内联样式或文本字段元数据等重字段时,才使用--context-detail full。 - 渲染后验证。 在
render返回退出代码 0 后,在报告成功之前确认输出文件存在且大小合理:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 在成功时打印◇ <path>;对于长时间渲染,还可使用ffprobe -i "$OUTPUT" -show_format -v error进行完整性检查时长。 - 在成功渲染后报告反馈。 验证输出后,每个任务运行一次
npx hyperframes feedback --rating <1-5> --comment "..."以报告运行情况 —5表示顺利,较低表示遇到摩擦。将您遇到的任何错误、解决方法、缺失功能或令人困惑的行为放入--comment。这是项目的主要信号通道;静默的渲染会使维护者失明。仅在禁用遥测或用户选择退出时跳过。- 对于可重现的错误,添加
--file-issue— 它将项目中最小可重现示例发布到公共 URL,并打开一个预先填写的 GitHub Issue,其中包含您的评论 + 环境。仅靠评论几乎无法让维护者重现;发布的合成才是使报告可操作的关键。如果失败的合成不在当前目录,请使用--dir <project>指向它。 - 编写维护者可以重现的错误评论 — 无法操作的转述会浪费报告。 CLI 已经附加 os/arch/mem/ffmpeg/CLI-version,所以不要重复这些;将评论用于您看到的独特信息。对于错误,请包含所有适用的以下各项:
- 确切的错误字符串,逐字引用(复制,不要总结)—— 以及渲染是否仍然生成了输出文件、是否静默回退(查找
[Render] … re-rendering via screenshot/falling back日志行)或进程是否硬退出且无错误(Killed: 9、FATAL … heap、Target closed)。“哪个超时 / 哪个失败模式” 是唯一最有用的信息。 - 最小可重现示例:仍然显示该问题的最小合成(或仅违规元素及其 CSS)—— 在评论中内联它或注明文件。命名您隔离的触发器(例如“仅当文本节点使用
font-family: 苹方时”、“仅在 4K 时”、“仅当存在<video>时”)。 - 您运行的确切命令 + 标志,以及设置的任何环境变量(
HF_*/PRODUCER_*)。 - 问题所在和具体表现:帧号或时间戳,以及视觉缺陷(空白文本、底部的黑色带、错误的字形、冻结的画布)与您期望的对比。如果您保存了截图,请提供截图路径。
- 如果它只是有时重现,请说明并给出命中率。
- 确切的错误字符串,逐字引用(复制,不要总结)—— 以及渲染是否仍然生成了输出文件、是否静默回退(查找
- 对于可重现的错误,添加
路由
| 想要… | 阅读 |
|---|---|
搭建项目(init、capture、skills) | references/init-and-scaffold.md |
检查正确性(lint、check、snapshot、已弃用的 validate/inspect) | references/lint-validate-inspect.md |
预览或渲染(preview、play、render、publish) | references/preview-render.md |
诊断环境(doctor、browser) | references/doctor-browser.md |
云渲染,零基础设施 HeyGen 托管(cloud render / list / get / delete、auth) | references/cloud.md |
在您自己的 AWS Lambda 上进行云渲染(lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
参数化 / 模板渲染(--variables、--variables-file、--strict-variables、--batch) | references/cloud.md + hyperframes-core(variables-and-media.md) |
其他所有内容(info、upgrade、compositions、docs、benchmark、telemetry、资产预处理) | references/upgrade-info-misc.md |
跨技能交接
- Tailwind 项目(
init --tailwind)→ 在编辑类或主题令牌之前使用hyperframes-core(Tailwind 参考)。 - Registry 块/组件(
hyperframes add、hyperframes catalog)→ 使用hyperframes-registry了解安装路径、子合成接线和代码片段合并。 - 资产预处理(
tts、transcribe、remove-background)→ 使用media-use了解语音选择、Whisper 模型规则、字幕和 TTS 到字幕链。 - 参数化渲染(
--variables)→ 通过<html>上的data-composition-variables声明;参见hyperframes-core了解完整模式。
云渲染(HeyGen 托管)
hyperframes cloud render 是零基础设施渲染路径:CLI 压缩您的项目,上传,在 HeyGen 的云上渲染,并下载 mp4。无需 Chrome、无需 FFmpeg、无需 AWS,您按积分付费。这是“在云端渲染这个”的默认答案;仅当您已经拥有 AWS 并需要分布式/分块渲染时,才使用 Lambda。
npx hyperframes auth login # 一次性登录(与 `heygen` CLI 共享)
npx hyperframes cloud render # 压缩,上传,渲染,下载到 renders/<id>.mp4
常用标志:--composition <html>、--output <path>、--quality draft|standard|high、--fps、--resolution 1080p|4k、--format mp4|webm|mov、--aspect-ratio(从 data-width/data-height 自动检测)。使用 --no-wait + --callback-url 进行即发即弃;使用 --idempotency-key "$(uuidgen)" 使重试安全。使用 cloud list / cloud get <id> / cloud delete <id> 管理作业。
惯用的模板工作流是一次上传,多次重新渲染:渲染本地项目一次以获得其 asset_id,然后使用不同的 --variables 针对该资产重新提交(跳过压缩 + 上传)。有关完整的标志集、认证模型、webhook 和模板循环,请参见 references/cloud.md。
变量(参数化 / 模板渲染)
任何渲染(本地、云或 Lambda)都可以在渲染时填充已声明的模板插槽。声明位于合成上(data-composition-variables);CLI 表面是:
npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
--strict-variables 在任何未声明的键或类型不匹配时使渲染失败(在 CI 中使用)。--batch <rows.json> 为每个数据行渲染一个输出,使用 {key}/{index} 路径占位符,并写入 manifest.json。有关完整模式(声明类型、data-var-src/data-var-text 声明性绑定、子合成的每个实例 data-variable-values 和优先级),请使用 hyperframes-core 技能(references/variables-and-media.md)。云模板循环位于 references/cloud.md 中。
Lambda(云渲染)
hyperframes lambda 将分布式渲染部署到 AWS Lambda,并从您的笔记本电脑或 CI 驱动渲染。端到端需要三个命令:
npx hyperframes lambda deploy # 配置 SAM 栈(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # 拆除(S3 桶……