SuperAPI AI 工具集

hyperframes-cli

编程与开发

查看项目

更新于 11-08 16:04

技能介绍

HyperFrames CLI 是一套围绕 HTML 视频合成项目(video composition)的命令行开发工作流。除非项目说明指定本地包装器,否则所有命令都通过 npx hyperframes 执行;运行环境要求 Node.js >= 22 和 FFmpeg。

一、用途与工作流 标准流程为:脚手架 → 编写 → 检查 → 预览 → 渲染。

  1. 脚手架:npx hyperframes init my-video 创建项目,也可从 URL 捕获(capture)。init 会检查已安装技能与 GitHub 最新版本,如有过期则更新全局技能集;--skip-skills 标志目前被临时禁用,因此每次 init 都会执行该检查。
  2. 编写:编写 HTML 合成内容,具体规范参见 hyperframes-core 技能。
  3. 检查:依次使用 lint、validate、inspect。lint 捕获缺少 data-composition-id、轨道重叠、未注册时间线等问题;validate 在无头 Chrome 中加载合成并报告运行时控制台错误和 WCAG 对比度问题;inspect 遍历时间线,报告文本溢出气泡/容器或画布,并在存在 *.motion.json 边车文件时校验运动意图(入场是否随 seek 触发、错峰顺序、在帧内、活跃性)。
  4. 预览:npx hyperframes preview 打开 Studio 时间线编辑器,用户可手动编辑任意内容;应先在此审阅,渲染前征求用户同意。
  5. 渲染:按需选择变体——迭代用 --quality draft;交付用 --quality high --output out.mp4;CI/跨主机复现用 --docker --strict;长时间/大尺寸任务使用 Lambda 云渲染。

二、Agent 与 CI 约定

  • 除 render、preview、play 外,所有命令支持 --json,输出包含 _meta 元信息(CLI 版本、最新可用版本、更新建议)。
  • doctor --json 即使环境异常也退出 0,应以返回载荷的 ok 字段判断:npx hyperframes doctor --json | jq -e '.ok'。
  • 非 TTY 模式自动检测:stdout 非 TTY 时自动切换非交互模式,此模式下 init 需 --example;也可用 --non-interactive 强制。
  • CI 门禁:--strict 在 lint 错误时失败,--strict-all 在警告时也失败,--strict-variables 在未声明的 --variables 键时失败。
  • --json 中的路径会脱敏($HOME 保留为字面量)。
  • 渲染需用户确认,不可在检查通过后自动渲染。
  • 渲染后校验:确认输出文件存在且大小合理,例如 [ -s "$OUTPUT" ];长时间渲染可用 ffprobe 检查时长。

三、参考文档路由 init/capture/skills 见 references/init-and-scaffold.md;lint/validate/inspect/snapshot 见 references/lint-validate-inspect.md;preview/play/render/publish 见 references/preview-render.md;doctor/browser 见 references/doctor-browser.md;Lambda 见 references/lambda.md;其余(info、upgrade、compositions、docs、benchmark、telemetry、资产预处理)见 references/upgrade-info-misc.md。

四、跨技能交接 Tailwind 项目(init --tailwind)在修改类或主题令牌前使用 hyperframes-core;注册表区块/组件(hyperframes add、hyperframes catalog)使用 hyperframes-registry 处理安装路径、子合成接线与片段合并;资产预处理(tts、transcribe、remove-background)使用 hyperframes-media;参数化渲染(--variables)通过 <html> 上的 data-composition-variables 声明。

五、Lambda 云渲染 hyperframes lambda 将分布式渲染部署到 AWS Lambda,三条命令完成:lambda deploy(创建 SAM 栈:Lambda + Step Functions + S3)、lambda render ./my-project --width 1920 --height 1080 --wait、lambda destroy(S3 桶保留)。适用于单机难以承担的多分钟视频、4K、大规模并行批次,需已配置 AWS 凭证;开发迭代仍建议本地渲染。

六、最低完成门禁 静态门禁:lint 与 validate;布局敏感工作加 inspect;CI 中用 render --strict 在 lint 错误时失败。 当项目使用子合成时,必须做视觉冒烟测试:lint/validate/inspect 单独评估各合成,不加载 index.html 挂载子合成,无法发现跨文件挂载失败。使用 hyperframes snapshot 以与 render 相同的加载路径快速截帧,例如 --at <t1>,<t2> 或 --frames 9,输出到 snapshots/。常见问题包括:<style> 块留在模板外导致文字无样式、SVG 尺寸失控、宿主 id 与模板 id 不一致导致时间线未运行等。snapshots/ 在检查后可删除,最终交付另用 render 生成。