Communitygithub.com

Aseel1600/Edit01 - 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`)。

Edit01 - HyperFrames CLI 开发循环 是什么?

该技能为开发者提供了完整的 HyperFrames CLI 工具链,用于创建、编辑、预览和渲染视频合成项目。它支持从项目脚手架搭建到最终渲染的完整工作流,包括代码检查(lint)、运行时验证(validate)、视觉检查(inspect)和快照测试(snapshot)。 对于云渲染需求,该技能集成了 AWS Lambda 部署能力,支持通过 `hyperframes lambda` 子命令进行分布式渲染,适用于长视频、4K 内容或大规模并行批次。所有命令都支持 `--json` 输出(除 render、preview 和 play 外),方便 CI/CD 集成和自动化脚本调用。 核心特性包括:自动检测非 TTY 模式以适配 CI/代理环境;渲染前的用户确认机制以确保仅在用户批准后执行渲染;渲染后的输出文件验证;以及跨技能集成支持(如 Tailwind、Registry 组件、媒体预处理等)。此外,针对使用子合成的项目,`hyperframes snapshot` 命令提供了更全面的可视化烟雾测试,能捕获静态检查遗漏的跨文件挂载问题。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Aseel1600/Edit01/tree/HEAD/.agents/skills/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

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

工作流

  1. 脚手架 — npx hyperframes init my-video(或从 URL 执行 capture)。init 还会检查已安装的技能是否与 GitHub 上的最新版本一致,如果有过期的,则更新全局技能集。--skip-skills 标志当前已被禁用(暂时的,等待 skills.sh 注册中心追赶上来),因此每次 init 都会执行此检查并拉取最新的技能。
  2. 编写 — 编写 HTML 合成(参见 hyperframes-core 技能)
  3. 检查 — 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 在无头 Chrome 中加载合成,并报告运行时控制台错误以及 WCAG 对比度问题。inspect 在时间线中搜索,并报告文本溢出气泡/容器或画布的问题——并且,当存在 *.motion.json 侧车文件时,它会根据同一搜索的时间线验证运动意图(在搜索下触发进入、交错顺序、在帧内、活跃度)。

对于运动密集型工作,首选基于快照的迭代和 *.motion.json 侧车文件——请参见 references/lint-validate-inspect.md 了解相关规范及运动验证规范。

代理约定

适用于每个命令的横向规则:

  • --json 可用于除 render、preview 和 play 之外的所有命令。 在支持的命令的任何代理/CI 调用中使用它;输出包含一个 _meta 信封(cli 版本、最新可用版本、更新建议)。render 仅通过 stdout + 退出码报告状态——通过下面的渲染后检查验证成功;preview / play 是服务器,不输出 JSON。
  • doctor --json 始终以退出码 0 退出,即使环境有问题。通过 payload 的 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) → 在编辑类或主题令牌之前使用 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。

有关先决条件、所有 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 挂载子合成,因此它们无法捕获跨文件挂载失败(参见 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)—— 时间线从未运行,在初始状态捕获帧
快照命令日志显示 在 45000ms 后子合成时间线未注册陷阱 2 —— 直接确认

snapshots/ 可以在肉眼检查后删除;面向用户的最终渲染是使用 npx hyperframes render 进行的单独步骤。

Individual skills in this repo

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

Aseel1600/Edit01

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, Kling official direct API, and the Gemini API (Gemini Omni Flash).

Aseel1600/Edit01

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Aseel1600/Edit01

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Aseel1600/Edit01

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Aseel1600/Edit01

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Aseel1600/Edit01

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Aseel1600/Edit01

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Aseel1600/Edit01

Generate expressive, multilingual narration with fish.audio (S1 / S2-generation models) and reuse cloned voices via reference_id. Use when the user prefers fish.audio/Fish Audio TTS, wants a specific playground voice model, or needs high-emotion voice-clone narration.

Aseel1600/Edit01

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Aseel1600/Edit01

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.

Aseel1600/Edit01

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.

Aseel1600/Edit01

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

Aseel1600/Edit01

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

Aseel1600/Edit01

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).

Aseel1600/Edit01

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

Aseel1600/Edit01

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

Aseel1600/Edit01

Best practices for Remotion - Video creation in React

Aseel1600/Edit01

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Aseel1600/Edit01

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

Aseel1600/Edit01

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

相关技能