Communitygithub.com

EvovexAI/EvoFlow

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

EvoFlow 是什麼?

EvoFlow 是 HyperFrames CLI 的開發循環工具,為基於 HTML/JS 的動態影像合成提供完整的「建立-檢查-預覽-渲染」工作流程。它支援在區域端快速疊代,也能透過 AWS Lambda 進行雲端渲染以處理長時間或大規模任務。該工具有強大的靜態檢查(lint、validate、inspect)和視覺快照功能,能及早捕捉子合成掛載失敗、樣式遺失或動作意圖錯誤等常見問題。使用者應先執行 lint、validate 和 inspect,再進行預覽,並須獲得使用者核准後才能觸發最終渲染。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/EvovexAI/EvoFlow/tree/HEAD/skills/public/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 了解規範和動作驗證規格。

代理程式慣例

對每個指令都適用的跨領域規則:

  • 每個指令(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 返回 exit 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) → 在編輯類別或主題 token 之前,使用 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)—— 時間軸從未執行,影格在初始狀態捕捉
Snapshot 指令記錄 Sub-composition timelines not registered after 45000ms陷阱 2 —— 直接確認

snapshots/ 可以在目視檢查後刪除;最終使用者交付的渲染是一個單獨的 npx hyperframes render 過程。

Individual skills in this repo

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

EvovexAI/EvoFlow

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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

EvovexAI/EvoFlow

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 domain skills, 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.

EvovexAI/EvoFlow

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 (general-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.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

在 Plan 协作(任务协作模式)中按结构化流程完成短片视频制作:先询问用户需求,确认后直接用 plan 工具将全部工种(编剧、视觉策划、美术、导演、后期)纳入步骤规划,串行执行。

EvovexAI/EvoFlow

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

EvovexAI/EvoFlow

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /general-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

本地文字转语音,使用sherpa-onnx(离线,无需云端)。当需要离线语音合成时使用。

相關技能