AI Skills
hyperframes-cli

hyperframes-cli

热门

HyperFrames CLI 开发循环。用于运行 npx hyperframes init、add、catalog、capture、lint、validate、inspect、layout、snapshot、preview、play、render、publish、lambda、doctor、browser、info、upgrade、skills、compositions、docs、benchmark、telemetry、transcribe、tts 或 remove-background 时，或排查 HyperFrames 构建/渲染环境问题时。AWS Lambda 云端渲染的入口点（`hyperframes lambda deploy / render / progress / destroy / policies`）。

2.9万Star
3036Fork
更新于 2026/6/20
获取 Skill源代码

相关 Skills

cloud-design-patterns3.7万claude-automation-recommender3.3万deployment-pipeline-design3.8万
SKILL.md
readonly只读
name
hyperframes-cli
description

HyperFrames CLI 开发循环。用于运行 npx hyperframes init、add、catalog、capture、lint、validate、inspect、layout、snapshot、preview、play、render、publish、lambda、doctor、browser、info、upgrade、skills、compositions、docs、benchmark、telemetry、transcribe、tts 或 remove-background 时，或排查 HyperFrames 构建/渲染环境问题时。AWS Lambda 云端渲染的入口点（`hyperframes lambda deploy / render / progress / destroy / policies`）。

HyperFrames CLI

所有操作都通过 npx hyperframes 运行，除非项目说明指定了本地包装器。请严格遵循本地包装器。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 脚手架 — npx hyperframes init my-video（或从 URL capture）
  2. 编写 — 创作 HTML 合成（参见 hyperframes-core 技能）
  3. Lint — npx hyperframes lint
  4. 验证 — npx hyperframes validate（运行时错误 + 对比度）
  5. 可视化检查 — npx hyperframes inspect
  6. 预览 — npx hyperframes preview
  7. 渲染 — 选择变体：
    • 迭代：npx hyperframes render --quality draft
    • 交付：npx hyperframes render --quality high --output out.mp4
    • CI / 跨主机复现：npx hyperframes render --docker --strict --output out.mp4
    • 云端（长时间/大型）：npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait（参见下面的 Lambda）

在预览前运行 lint、validate 和 inspect。lint 捕获缺失的 data-composition-id、重叠轨道和未注册的时间线。validate 在无头 Chrome 中加载合成并报告运行时控制台错误以及 WCAG 对比度问题。inspect 在时间线中搜索并报告文本溢出气泡/容器或画布的情况——并且，当存在 *.motion.json 侧车文件时，验证运动意图（在搜索下触发的入场、交错顺序、在帧内、活跃性）与同一搜索的时间线是否一致。

对于运动密集型工作，优先使用快照驱动的迭代和 *.motion.json 侧车文件——参见 references/lint-validate-inspect.md 了解规范和运动验证规范。

代理约定

适用于所有命令的通用规则：

  • 除 render、preview 和 play 外，所有命令都支持 --json。 在代理/CI 调用支持的命令时使用；输出包含 _meta 信封（CLI 版本、最新可用版本、更新建议）。render 仅通过 stdout + 退出码报告状态——使用下面的渲染后检查验证成功；preview/play 是服务器，无 JSON。
  • 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 键时失败。
  • --json 中的路径会被脱敏——$HOME 变为字面量 $HOME，因此输出可以安全地粘贴到错误报告和代理上下文中。
  • 渲染后验证。 在 render 返回退出码 0 后，确认输出文件存在且大小合理，然后再报告成功：[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 在成功时打印 ◇ <path>；对于长时间渲染，还可以使用 ffprobe -i "$OUTPUT" -show_format -v error 检查时长是否合理。

路由

想要… 阅读
脚手架项目（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
在 AWS Lambda 上云端渲染（lambda deploy / sites / render / progress / destroy / policies） references/lambda.md
其他所有内容（info、upgrade、compositions、docs、benchmark、telemetry、资产预处理） references/upgrade-info-misc.md

跨技能交接

  • Tailwind 项目（init --tailwind）→ 在编辑类或主题令牌之前使用 hyperframes-core（Tailwind 参考）。
  • 注册表块/组件（hyperframes add、hyperframes catalog）→ 使用 hyperframes-registry 了解安装路径、子合成接线和片段合并。
  • 资产预处理（tts、transcribe、remove-background）→ 使用 hyperframes-media 了解语音选择、Whisper 模型规则、字幕和 TTS 到字幕链。
  • 参数化渲染（--variables）→ 通过在 <html> 上声明 data-composition-variables；参见 hyperframes-core 了解完整模式。

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 存储桶保留）

当渲染时间过长/文件过大（多分钟视频、4K、大型并行批次）且您已配置 AWS 凭证时，使用 Lambda。对于开发循环迭代，请坚持使用本地 render。

参见 references/lambda.md 了解先决条件、所有 6 个子命令（deploy、sites create、render、progress、destroy、policies）、IAM 策略验证、状态文件以及成本/清理规则。

最低完成门控

静态门控

npx hyperframes lint
npx hyperframes validate

对于布局敏感的工作，添加 inspect；在 CI 中添加 render --strict 以在 lint 错误时失败。

视觉冒烟测试——当项目使用子合成时必需

lint/validate/inspect 单独评估每个合成。它们从不加载 index.html 并通过 data-composition-src 挂载子合成，因此无法捕获跨文件挂载失败（参见 hyperframes-core → references/sub-compositions.md，“常见陷阱”）。唯一能捕获它们的是实际加载 index.html 并搜索时间线的门控。

使用 hyperframes snapshot——它像 render 一样加载项目（因此执行相同的挂载路径），但只捕获您请求的时间戳，因此只需几秒钟而不是完整渲染：

# 在每个子合成的中点捕获一帧。
# 中点 = index.html 中每个宿主槽位的 data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# 或者，如果您不需要逐场景定位，可以使用均匀间隔的样本：
npx hyperframes snapshot --frames 9

输出位于 snapshots/frame-NN-at-Xs.png。目视检查每一帧与场景计划。

每帧的红旗（每个都对应静态门控无法捕获的特定失败模式）：

您看到的内容 根本原因
文本在左上角显示为微小且无样式 <style> 块留在 <head> 中且位于 <template> 之外（陷阱 1）——没有 CSS 到达实时 DOM
SVG/图标元素放大到画布大小 同上——未应用宽度/高度约束
场景的主角元素完全缺失；仅可见背景和水印 宿主 ID ≠ 模板 ID（陷阱 2）——时间线从未运行，帧在初始状态捕获
快照命令记录 Sub-composition timelines not registered after 45000ms 陷阱 2——直接确认

snapshots/ 可以在目视检查后删除；面向用户的最终渲染是使用 npx hyperframes render 的单独步骤。