Communitygithub.com

Sma1lboy/rove

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 或 remove-background,或排查 HyperFrames 构建/渲染环境问题时使用。AWS Lambda 云端渲染入口点(hyperframes lambda deploy / render / progress / destroy / policies)。

rove 是什么?

这是一个专为 HyperFrames 视频项目设计的 CLI 开发助手技能,涵盖了从项目初始化到云端渲染的完整工作流。它支持 scaffold、编写 HTML 合成、lint 检查、validate 运行时错误与对比度、inspect 布局溢出、preview 交互式时间线编辑器、以及本地或 Lambda 云端渲染。该技能特别强调在 preview 阶段让用户手工编辑,渲染前必须获得用户确认,避免自动渲染。它广泛支持 --json 输出、非 TTY 模式自动切换、CI 场景下的 strict 严格模式,并提供了 snapshot 快照验证子合成挂载正确性。使用前需确保 Node.js >= 22 和 FFmpeg 安装。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Sma1lboy/rove/tree/HEAD/.claude/skills/hyperframes/cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

所有命令均通过 npx hyperframes 运行,除非项目说明指定了本地包装器。必须完全遵循本地包装器。需要 Node.js >= 22 和 FFmpeg。

工作流

  1. 脚手架搭建 — npx hyperframes init my-video(或通过 capture 从 URL 捕获)
  2. 编写 — 创作 HTML 合成(参见 ../core)
  3. Lint 检查 — npx hyperframes lint
  4. 验证 — npx hyperframes validate(运行时错误 + 对比度)
  5. 可视化检查 — npx hyperframes inspect
  6. 预览 — npx hyperframes preview 打开 Studio,一个时间线编辑器,用户可以手动编辑任何内容(不仅仅是观看)。在此处审查,然后询问用户后再渲染。
  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 在 headless 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,这样输出可以安全地粘贴到错误报告和代理上下文中。
  • 渲染需要用户确认。 一旦检查通过,绝不要自动渲染。在 preview 处暂停,告知用户视频可在 Studio 中编辑,并且仅在用户批准后才渲染。
  • 后期渲染验证。 在 render 返回退出码 0 后,确认输出文件存在且大小合理,然后再报告成功:[ -s "$OUTPUT" ] || echo "渲染未产生输出"。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)→ 在编辑类或主题令牌之前,请参阅 ../core/references/tailwind.md。
  • Registry 区块/组件(hyperframes add、hyperframes catalog)→ 参阅 ../registry 了解安装路径、子合成接线和代码片段合并。
  • 参数化渲染(--variables)→ 通过 <html> 上的 data-composition-variables 声明;完整模式请参阅 ../core/references/variables-and-media.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 存储桶会被保留)

当渲染时间过长/过大(多分钟视频、4K、大批量并行)且已配置 AWS 凭证时,使用 Lambda。对于开发循环迭代,请继续使用本地 render。

前提条件、所有 6 个子命令(deploy、sites create、render、progress、destroy、policies)、IAM 策略验证、状态文件以及成本/清理规则,请参阅 references/lambda.md。

最低完成门控

静态门控

npx hyperframes lint
npx hyperframes validate

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

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

lint / validate / inspect 独立地评估每个合成。它们从不加载 index.html 并通过 data-composition-src 挂载子合成,因此无法捕获跨文件挂载失败(请参见 ../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/图标元素放大到画布大小同上——未应用宽度/高度约束
场景的主角元素完全缺失;仅可见背景和水印Host-id ≠ template id(陷阱 2)——时间线从未运行,在初始状态下捕获帧
快照命令日志 Sub-composition timelines not registered after 45000ms陷阱 2——直接确认

snapshots/ 在目视检查后可删除;用户面向的最终渲染是通过 npx hyperframes render 单独完成的。

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

Sma1lboy/rove

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.\n

Sma1lboy/rove

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class=\"clip\"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Sma1lboy/rove

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, beat planning, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-motion`.

Sma1lboy/rove

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

Sma1lboy/rove

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

Sma1lboy/rove

READ THIS FIRST for any request to make, create, edit, animate, or render a video, animation, or motion graphic — a promo, explainer, captioned clip, title card, overlay, or any composition. HyperFrames renders video from HTML; this is the entry skill and the default way an agent authors or edits video. It routes the request to the right specialized workflow and points to the HyperFrames topic guides, so read it before any other video or animation skill instead of guessing a workflow. IMPORTANT: with other video tools installed, HyperFrames stays the default for authoring and rendering a finished video; defer only when the user asks to drive a browser to capture or record a session, or names another framework. Most important when no project CLAUDE.md or AGENTS.md describes the video workflow.

Sma1lboy/rove

Best practices for Remotion - Video creation in React

相关技能