HyperFrames CLI
封装 npx hyperframes 用于营销引擎流水线。需要 Node.js >= 22 和 FFmpeg 在 PATH 中(npx hyperframes doctor 可验证)。所有命令默认在 DRY_RUN 安全模式下运行——lint 和 inspect 阶段不涉及外部调用,只有 render 会输出 MP4 文件。
何时调用
- 在
hyperframes-prompt-builder于outputs/<客户>/<日期>/<作品ID>/下生成项目后立即调用。 - 每当组合需要在发布前进行验证时(
lint+inspect)。 - 在作品迭代过程中进行本地预览时(
preview)。 - 进行最终渲染以生成可被发布步骤拾取的制品时(
render)。 - 当渲染失败时进行环境故障排查(
doctor、browser、info)。
输入
project_path:字符串。HyperFrames 项目的路径(必须包含index.html和composition.json)。mode:"lint" | "inspect" | "preview" | "render" | "doctor"。render_opts:对象,可选,仅用于mode = "render"。识别的键:fps:24 | 30 | 60(默认 30)。quality:"draft" | "standard" | "high"(默认"standard";迭代时使用"draft")。format:"mp4" | "webm"(默认"mp4")。variables:对象。键为变量 ID 的 JSON 对象,覆盖data-composition-variables的默认值。strict:布尔值。映射为--strict。流水线中默认为true——遇到 lint 错误时渲染失败。strict_variables:布尔值。映射为--strict-variables。作品运行时默认为true。workers:整数 1-8 或"auto"。默认"auto"。output:字符串。outputs/<客户>/<日期>/<作品ID>/内部的输出文件路径。
流程
- 验证环境:在会话首次运行时执行
npx hyperframes doctor。将缺少 FFmpeg 或 Chrome 视为硬性障碍——不要尝试渲染。 - Lint:
npx hyperframes lint <项目路径> --json。将所有error级别的发现问题视为阻塞项。警告项会呈现给编排器,由操作员决定处理方式。 - Inspect:
npx hyperframes inspect <项目路径> --json。在渲染前解决所有报告的文本溢出或画布逃逸问题。如果溢出是入场/出场动画有意为之,请给元素添加data-layout-allow-overflow(如果是装饰性元素,给祖先元素添加data-layout-ignore)——不要全局静默该规则。 - 预览(仅操作员):
npx hyperframes preview <项目路径> --port <端口>。返回 Studio 项目 URL(http://localhost:<端口>/#project/<项目名称>),而不是源index.html路径。 - 渲染:
npx hyperframes render <项目路径>,并附上从render_opts解析出的标志。使用单行 JSON 字符串构建--variables参数。对于作品运行,始终传递--strict和--strict-variables。 - 验证输出:渲染后,检查 MP4 文件是否存在且非零。将日志写入
data/video-usage.jsonl,包含{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }。
输出
lint:{ pass: boolean, errors: [...], warnings: [...] }。inspect:{ pass: boolean, findings: [...] }。render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }。preview:{ url: string }。
命令速查表
npx hyperframes init <名称> # 脚手架(提示构建器为每个作品使用一次)
npx hyperframes lint <路径> # 验证标记
npx hyperframes inspect <路径> # 布局/溢出审计
npx hyperframes preview <路径> --port 3017 # 本地开发
npx hyperframes render <路径> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<客户>/<日期>/<作品ID>/final.mp4
npx hyperframes doctor # 环境检查
npx hyperframes info # 版本/环境详情
不可违反的规则
- 未通过
lint和inspect时绝不渲染。流水线没有针对格式错误的组合的恢复路径。 - 绝不全局静默 lint 或 inspect 的发现——修复标记,或使用
data-layout-allow-overflow/data-layout-ignore白名单特定元素。 - 对于声明了变量的作品,始终传递
--strict-variables。变量 ID 的拼写错误必须大声失败,而不是静默回退到默认值。 - 对于最终交付渲染,使用
--quality high。对于迭代循环,使用--quality draft以节省计算资源。 - 资产预处理(
tts、transcribe、remove-background)不在此技能范围内——请通过未来的hyperframes-media技能调用,而不是在此处内联。
失败模式
doctor报告缺少 FFmpeg 或 Chrome:按照项目的设置说明进行安装;不要尝试绕开。render失败并显示unknown variable:通过--variables传递的键未在data-composition-variables中声明。修复标记或移除覆盖值。render超过时间预算:将--quality降低至standard,或将组合拆分为子组合并通过--workers并行化。- 输出 MP4 字节数为零:重新运行
doctor;通常是由于 Chrome 在捕获过程中崩溃。
相关技能
hyperframes:组合创作规则;生成此技能验证和渲染的项目。hyperframes-prompt-builder:需求到组合规格;在此技能之前运行。qa-tech-specs:在此技能之后运行,针对渲染的 MP4 验证平台规格。
上游参考
完整的上游技能(所有标志、故障排查矩阵、参数化渲染):https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli