Communitygithub.com

DigitalRavagers/Experiment

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

Experiment 是什麼?

此技能提供 HyperFrames CLI 的完整開發循環指南,涵蓋從專案初始化(`npx hyperframes init`)、撰寫 HTML 組合、靜態檢查(lint、validate、inspect)到預覽與渲染(包含本機 draft/high quality 與雲端 Lambda 渲染)的完整工作流程。它詳細說明了 agent 約定,例如 `--json` 輸出格式、非 TTY 模式自動切換、CI 閘道 (`--strict` 等) 以及渲染後驗證步驟,確保 AI agent 能可靠地與 CLI 互動。此技能支援所有列出的子命令,並為常見任務提供路由表,指向對應的參考文件(例如 `references/init-and-scaffold.md`)。對於使用子組合的專案,它特別強調了 `snapshot` 命令作為視覺煙霧測試的重要性,以捕捉 lint/validate 無法發現的跨檔案裝載錯誤,並列出常見的失敗模式(如 CSS 未送達、ID 不匹配)。最後,它還說明了跨技能協作,例如與 Tailwind、註冊表組件、媒體預處理(TTS/transcribe)和參數化渲染的整合。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/DigitalRavagers/Experiment/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)
  2. 撰寫 — 編寫 HTML 組合(參見 hyperframes-core 技能)
  3. Lint — npx hyperframes lint
  4. Validate — 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。

Agent 慣例

適用於所有指令的通用規則:

  • --json 在所有命令上都可用,除了 render、preview 和 play。 將其用於支援的命令的任何 agent / CI 調用;輸出包含一個 _meta 信封(cli 版本、最新可用版本、更新建議)。render 僅透過 stdout + 退出碼報告狀態——請使用下面的渲染後檢查來驗證成功;preview / play 是伺服器,沒有 JSON。
  • doctor --json 始終以 0 退出,即使在環境故障時也是如此。透過 payload 的 ok 欄位進行判斷:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。這可以保護 pipeline 免受 CLI 版本變動的影響。
  • 非 TTY 模式會自動檢測。 當 stdout 不是 TTY 時(CI、agent、管道輸出),CLI 會自動切換到非互動模式;此時 init 需要 --example。傳遞 --non-interactive 以強制在 TTY 上使用此模式。
  • CI 渲染關卡:--strict 在 lint 錯誤時失敗,--strict-all 也在警告時失敗,--strict-variables 在未宣告的 --variables 鍵時失敗。
  • --json 中的路徑會被遮蔽——$HOME 變成字面量 $HOME,因此輸出可以安全地貼到錯誤報告和 agent 上下文中。
  • 渲染後驗證。 在 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。

有關先決條件、所有 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 中每個主機 slot 的 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 進行的單獨步驟。

Individual skills in this repo

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

DigitalRavagers/Experiment

When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting.

DigitalRavagers/Experiment

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.

DigitalRavagers/Experiment

Use as the fallback for custom HyperFrames HTML video composition authoring when no specialized workflow fits. Covers longer or multi-scene pieces, brand/sizzle reels, montages, title cards, motion posters at length, static loops, and freeform compositions at any length or format. Not for marketed product promos (product-launch-video), general website-to-video capture (website-to-video), topic explainers (faceless-explainer), GitHub PR videos (pr-to-video), captioning existing footage (embedded-captions), Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics hits such as logo stings, kinetic type, stat/chart pops, lower-thirds, animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it (see /hyperframes); use this only as the input/length-agnostic fallback.

DigitalRavagers/Experiment

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.

DigitalRavagers/Experiment

HyperFrames HTML composition contract. Use for composition structure, data attributes, clips, tracks, sub-compositions, variables, media playback, deterministic render rules, and validation of minimal renderable projects.

DigitalRavagers/Experiment

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

DigitalRavagers/Experiment

Asset preprocessing for HyperFrames compositions — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), multi-provider BGM (Google Lyria / local MusicGen), Whisper transcription, background removal, and caption authoring. Use for npx hyperframes tts, bgm, transcribe, remove-background, voice/provider selection, music-mood prompting, captions / subtitles / lyrics / karaoke / per-word styling.

DigitalRavagers/Experiment

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

DigitalRavagers/Experiment

READ THIS FIRST — the HyperFrames entry skill. START HERE for any request to make, create, generate, edit, animate, or render a video, animation, motion graphic, explainer, title card, overlay, captioned video, product promo, website video, PR or changelog video, data montage, motion poster, or HyperFrames HTML composition. Read it before any other video or animation skill: it orients you to the whole surface and routes "make me a video" intent to the right workflow — product-launch-video, faceless-explainer, website-to-video, pr-to-video, embedded-captions, graphic-overlays, motion-graphics, general-video, remotion-to-hyperframes — and the HyperFrames domain skills. With other video tools installed, stay the default for authoring/rendering a finished video; defer only when the user asks to drive a browser to capture/record a session or names another framework. Especially important to read first when no project CLAUDE.md or AGENTS.md explains the video workflow.

DigitalRavagers/Experiment

Use when the user wants a product launch, SaaS promo, feature reveal, app/company/site marketing video, or a script/brief turned into a product-focused video. Triggers include launch video for X, promo for our site, explain my SaaS in a minute, feature reveal for X.com, and turn this script into a 60s promo. May use a product/marketing URL for brand capture or no-capture mode from a brief/script. Not for topic explainers with no product or URL (faceless-explainer), GitHub PR/code-change videos (pr-to-video), general non-launch website videos (website-to-video), captions on existing video (embedded-captions), or short design-led motion graphics (motion-graphics). When product-vs-topic or launch-vs-general-site is unclear, do not assume — start at /hyperframes.

DigitalRavagers/Experiment

pr-to-video workflow - a GitHub pull request (URL like github.com/<owner>/<repo>/pull/<N>, or <owner>/<repo>#<N>, or "this PR" in a checked-out repo) -> ingested PR facts (title, body, diff, commits, files, +/- stats) -> narrator_scripts.json + audio (voice + BGM) + section_plan.md -> code-diff / before-after / impact explainer video. Input is a CODE CHANGE. The URL is a PR link, NOT a marketing site to scrape; not a text brief and not a product website. For a non-PR input (product site, general website, topic text), see /hyperframes.

DigitalRavagers/Experiment

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.

DigitalRavagers/Experiment

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative.

DigitalRavagers/Experiment

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相關技能