Communitygithub.com

HyperFrames CLI 开发循环

`npx hyperframes` 命令行工具,用于脚手架搭建(init)、验证(lint、validate、inspect)、预览、渲染和环境故障排查(doctor、browser、info、upgrade)。

HyperFrames CLI 开发循环 是什么?

HyperFrames CLI 技能(sq-cm/claude-template)封装了 HyperFrames 视频合成框架的完整开发循环。它通过 `npx hyperframes` 命令提供从项目初始化(`init`)、静态代码分析(`lint`)、运行时验证(`validate`)到可视化检查(`inspect`)、热重载预览(`preview`)和最终渲染(`render`)的全流程支持。该技能还包含环境诊断工具(`doctor`、`browser`、`info`、`upgrade`),帮助开发者快速定位缺失依赖(如 FFmpeg、Chrome)或内存不足等问题。此技能适用于任何使用 CLI 构建或调试 HyperFrames 项目的场景;对于资产预处理命令(如 `tts`、`transcribe`、`remove-background`),应调用专门的 `hyperframes-media` 技能。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sq-cm/claude-template/tree/HEAD/.claude/skills/hyperframes-cli

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames CLI

所有操作通过 npx hyperframes 运行。需要 Node.js >= 22 和 FFmpeg。

工作流

  1. 脚手架搭建 — npx hyperframes init my-video
  2. 编写 — 编写 HTML 合成文件(参见 hyperframes 技能)
  3. 静态检查 — npx hyperframes lint
  4. 运行时验证 — npx hyperframes validate
  5. 可视化检查 — npx hyperframes inspect
  6. 预览 — npx hyperframes preview
  7. 渲染 — npx hyperframes render

先执行 lint 和 inspect,再进行预览。lint 会捕获缺少 data-composition-id、重叠轨道以及未注册的时间线问题。inspect 会在无头 Chrome 中打开渲染后的合成,扫描时间线,并报告溢出气泡/容器或画布外的文本。

脚手架搭建

npx hyperframes init my-video                        # 交互式向导
npx hyperframes init my-video --example warm-grain   # 选择示例
npx hyperframes init my-video --video clip.mp4        # 带视频文件
npx hyperframes init my-video --audio track.mp3       # 带音频文件
npx hyperframes init my-video --example blank --tailwind # 使用 Tailwind v4 浏览器运行时
npx hyperframes init my-video --non-interactive       # 跳过提示(CI/agent)

模板:blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。

init 会创建正确的文件结构、复制媒体、使用 Whisper 转录音频,并安装 AI 编码技能。请使用它,而不是手动创建文件。

使用 --tailwind 时,请注意脚手架使用浏览器运行时中的 Tailwind v4.2,而非 Studio 的 Tailwind v3 设置——编辑前请对照 v4 文档检查类和主题标记语法。

静态检查

npx hyperframes lint                  # 当前目录
npx hyperframes lint ./my-project     # 指定项目
npx hyperframes lint --verbose        # 信息级别结果
npx hyperframes lint --json           # 机器可读格式

检查 index.html 和 compositions/ 目录下所有文件。报告错误(必须修复)、警告(建议修复)和信息(需使用 --verbose)。

运行时验证

npx hyperframes validate                  # 当前目录
npx hyperframes validate ./my-project     # 指定项目
npx hyperframes validate --json           # 机器可读格式
npx hyperframes validate --timeout 5000   # 慢脚本/媒体(默认 3000 ms)

在无头 Chrome 中加载合成,并报告 JS 控制台错误、缺失资源和 WCAG 对比度问题(使用 --no-contrast 跳过对比度检查)。在 lint 之后、inspect 之前运行。

validate 上游已弃用,建议改用 npx hyperframes check,它在一个浏览器会话中同时运行 lint、运行时、布局、动画和对比度验证——可满足“lint 和 validate”清单项的要求。

可视化检查

npx hyperframes inspect                 # 检查渲染布局在时间线上的情况
npx hyperframes inspect ./my-project    # 指定项目
npx hyperframes inspect --json          # agent 可读的结果
npx hyperframes inspect --samples 15    # 更密集的时间线扫描
npx hyperframes inspect --at 1.5,4,7.25 # 显式的关键帧时间戳

在 lint 和 validate 之后使用,尤其适用于包含对话气泡、卡片、字幕或紧凑排版的合成。它会报告:

  • 文本超出最近的视觉容器或气泡
  • 文本被自己的固定宽度/高度框裁剪
  • 文本超出合成画布
  • 子元素逃离裁剪容器

错误应在渲染前修复。警告供 agent 审查;添加 --strict 可将警告也视为失败。重复的静态问题默认合并,以便 JSON 输出保持紧凑,适合 LLM 上下文窗口。如果溢出是入场/退场动画有意为之,请为元素或其祖先添加 data-layout-allow-overflow 属性。如果某个装饰性元素不应被检查,请为其添加 data-layout-ignore 属性。

npx hyperframes layout 仍可作为兼容性别名使用,功能与可视化检查相同。

预览

npx hyperframes preview                   # 启动当前目录的预览服务
npx hyperframes preview --port 4567       # 自定义端口(默认 3002)

文件更改时热重载。自动在浏览器中打开 Studio。

将项目交还给用户时,请使用 Studio 项目 URL,而不是源代码 index.html 路径:

http://localhost:<port>/#project/<project-name>

使用预览输出中的实际端口和项目目录名。例如,在 codex-openai-video 目录中执行 npx hyperframes preview --port 3017 后,应报告 http://localhost:3017/#project/codex-openai-video。

请将 index.html 仅视为源代码上下文。可以将其链接为实现文件,但不要将其标记为项目或预览界面。

渲染

npx hyperframes render                                # 标准 MP4
npx hyperframes render --output final.mp4             # 指定输出文件名
npx hyperframes render --quality draft                # 快速迭代
npx hyperframes render --fps 60 --quality high        # 最终交付
npx hyperframes render --format webm                  # 透明 WebM
npx hyperframes render --docker                       # 字节级一致输出
标志选项默认值说明
--output路径renders/name_timestamp.mp4输出路径
--fps24, 30, 603060fps 会使渲染时间翻倍
--qualitydraft, standard, highstandarddraft 用于迭代
--formatmp4, webmmp4WebM 支持透明度
--workers1-8 或 autoauto每个 worker 启动一个 Chrome 实例
--docker标志off可重现输出
--gpu标志offGPU 加速编码
--strict标志offlint 错误时失败
--strict-all标志off错误和警告时都失败
--variablesJSON 对象—覆盖 data-composition-variables 中声明的变量值
--variables-file路径—包含变量值的 JSON 文件(--variables 的替代方案)
--strict-variables标志off在 --variables 中出现未声明的键或类型不匹配时渲染失败

质量指南: 迭代时使用 draft,审查时使用 standard,最终交付时使用 high。

参数化渲染: 合成文件在 <html> 根元素上通过 data-composition-variables 声明其变量——一个 声明数组(每个条目包含 {id, type, label, default}),定义了模式。内部的脚本通过 window.__hyperframes.getVariables() 读取解析后的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一个按 id 键名的 JSON 对象,用于覆盖一次渲染中声明的默认值;缺失的键沿用默认值,因此同一个合成可以在开发预览和生产环境中无变化地运行。(子合成宿主也可以通过 data-variable-values 按实例覆盖——对象结构相同,作用域限定于子合成的一次挂载。完整模式请参见 hyperframes 技能。)

资产预处理

npx hyperframes tts、transcribe 和 remove-background 生成资产(解说音频、逐字转录、透明视频),这些资产会被放入合成中。每个命令在首次运行时都会下载自己的模型。有关语音选择、whisper 模型规则(.en 会翻译非英语内容的注意事项)、输出格式选择(带 Alpha 通道的 VP9 WebM 与 ProRes)以及 TTS → 转录 → 字幕链,请调用 hyperframes-media 技能。

故障排查

npx hyperframes doctor       # 检查环境(Chrome、FFmpeg、Node、内存)
npx hyperframes browser      # 管理捆绑的 Chrome
npx hyperframes info         # 版本和环境详细信息
npx hyperframes upgrade      # 检查更新

如果渲染失败,请先运行 doctor。常见问题:缺少 FFmpeg、缺少 Chrome、内存不足。

其他

npx hyperframes compositions   # 列出项目中的合成
npx hyperframes docs           # 打开文档
npx hyperframes benchmark .    # 基准测试渲染性能

相关技能