Communitygithub.com

HyperFrames CLI

使用 HyperFrames CLI 開發循環:初始化、新增、目錄、捕捉、檢查、快照、比較、評級比較、預覽、播放、簡報、節拍、關鍵影格、單一批次渲染、發佈、雲端、雲端執行、回饋、Lambda、診斷、瀏覽器、資訊、升級、技能、組合、文件、基準測試、遙測、轉錄、驗證、文字轉語音、移除背景。也可用於診斷建置或渲染失敗。

HyperFrames CLI 是什麼?

HyperFrames CLI 是一個用於影音動畫工作流程的命令列工具,支援本地、HeyGen 雲端、AWS Lambda 和 Google Cloud Run 等多種渲染平台。此技能定義了從專案初始化(`init`)、撰寫合成、語法檢查(`lint`)、最終驗證(`check`)、預覽(`preview`)到渲染(`render`)的完整開發循環。它強調在渲染前必須獲得使用者對最終預覽的批准,並提供批次渲染、子合成煙霧測試、Studio 導向編輯、雲端渲染部署以及診斷(`doctor`)等功能。使用者應先閱讀對應的參考文件再執行特定命令,以確保正確使用。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dbillion/hermes-skills-public/tree/HEAD/skills-external/hyperframes-cli

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames CLI 是做什麼的?

除非專案說明提供了包裝器,否則以 npx hyperframes ... 執行命令。若有包裝器則遵循該包裝器。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。

開發循環

  1. 建立專案: npx hyperframes init <project> 或捕捉網站。在非 TTY 模式下,傳遞 --non-interactive --example=<name>。
  2. 編寫: 使用 /hyperframes-core 編寫合成。
  3. 編輯時快速取得回饋: 在第一次 HTML 傳遞之後及結構變更之後,執行 npx hyperframes lint。
  4. 執行最終關卡: 執行 npx hyperframes check;它在開啟瀏覽器之前會重新執行 lint。不要在前面加上多餘的獨立 lint 調用。加上 --snapshots 以取得帶註解的概覽影格和尋找裁切。
  5. 檢查子合成: 當 index.html 掛載了 data-composition-src,捕捉中點快照並檢查每個掛載的場景。
  6. 開啟最終 Studio 預覽: 執行 npx hyperframes preview,將時間軸專案 URL 交給使用者,並詢問是要修改還是要渲染。
  7. 僅在獲得批准後才渲染: 草稿品質用於疊代,高品質用於交付。
  8. 驗證輸出: 確認檔案存在、非空且具有合理的持續時間。
# 快速疊代檢查;在編寫時視需要重複執行。
npx hyperframes lint

# 必要的最終關卡;包含 lint。
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4

check 先執行 lint,然後使用一個瀏覽器工作階段和一次搜尋遍歷來審計執行時期錯誤、失敗的請求、版面配置、*.motion.json 斷言以及 WCAG 對比度。持續性發現會導致退出碼為非零;短暫的進入或退出發現僅供參考。使用 --strict 來將警告也導向非零退出碼。validate、inspect 和 layout 為相容性而保留為別名,但不得出現在新的指令或腳本中。

兩個不同的預覽表面

不要混淆這些狀態:

表面何時可能開啟目的
故事板在合成檢查之前,僅當 storyboard: yes 時審查計劃卡和線框草稿。開啟 ?view=storyboard#project/<name>。
最終合成預覽在 check 通過之後在渲染前審查已組裝的時間軸。開啟 #project/<name>。

早期故事板並非最終影片的批准。渲染始終需要 hyperframes-core/references/review-loop.md 定義的最終批准。

子合成煙霧測試

靜態審計無法捕捉到所有的掛載失敗。當專案使用子合成時,為每個主機插槽捕捉至少一個可見的中點:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

將微小的未設定樣式的內容、畫布大小的圖示、缺少的主題元素或時間軸註冊超時視為會阻擋渲染的掛載缺陷。相關修復方法請參閱 hyperframes-core/references/sub-compositions.md。

代理程式慣例

  • 對於代理程式和 CI 呼叫,優先使用 --json。伺服器模式的 render、preview 和 play 不提供一般的 JSON 輸出;preview --selection --json 和 preview --context --json 是查詢模式的例外。

  • doctor --json 始終以零退出碼退出。根據其負載來判斷:

    npx hyperframes doctor --json | jq -e '.ok' >/dev/null
    
  • 非 TTY 模式是自動的。在該模式下 init 需要 --example;使用 --non-interactive 來強制在 TTY 上具有確定性行為。

  • 在同一個驗證循環中的所有命令使用同一個 HYPERFRAMES_RUN_ID。

  • 當對應的警告、變數或 CI 條件必須決定渲染是否繼續時,使用 --strict、--strict-all 和 --strict-variables。

  • JSON 路徑會將主目錄替換為 $HOME;不要試圖反轉此替換。

  • 切勿僅因為檢查通過就進行渲染。在最終預覽處暫停,並等待批准。

Studio 導向編輯

當使用者提到「這個元素」或當前選取項目時,請查詢 Studio 而非猜測:

npx hyperframes preview --context --json --context-fields selection

盡可能使用 selection.target.hfId,否則使用其選擇器和來源檔案。如果結果回報 no-selection,請要求使用者點擊該元素並重新執行。只請求你需要的上下文切片。僅在需要計算樣式或可編輯文字元資料時使用 --context-detail full。完整行為和失敗碼請參閱 references/preview-render.md。

渲染選擇

需求命令
快速的本地疊代npx hyperframes render --quality draft
最終的本地交付npx hyperframes render --quality high --output out.mp4
可重現的容器渲染npx hyperframes render --docker --strict --output out.mp4
本地變數驅動的批次渲染npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
HeyGen 託管的無基礎設施渲染npx hyperframes cloud render
自我管理的分散式 AWS 渲染npx hyperframes lambda render <project> --width 1920 --height 1080 --wait
自我管理的分散式 GCP 渲染npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait

當使用者想要託管渲染而不需要本地 Chrome、FFmpeg 或 AWS 時,使用雲端渲染。只有在 AWS 所有權是必要條件時才使用 Lambda。只有在 GCP 所有權是必要條件時才使用 Cloud Run。在執行任何雲端路徑之前,請閱讀對應的參考文件。

在驗證渲染成功後,除非遙測被停用或使用者選擇退出,否則發送一份回饋報告:

npx hyperframes feedback --rating <0-10> --comment "<具體結果或困擾>"

對於順利運行的回饋,保持簡潔。對於任何錯誤或困擾,請在提交前擷取重現封包;不要只發送症狀摘要。包含可重新執行的命令和工作目錄、預期行為與實際行為、確切錯誤、輸出是否完成/降級/失敗、解決方法以及重現專案狀態。如果問題無法再次重現,請說明但仍包含最後一次失敗的命令和日誌。僅在使用者同意後才使用 --file-issue:它會將最小重現案例發佈到公開 URL。所需的封包格式和隱私警告位於 references/preview-render.md。

執行命令前請先閱讀對應的參考文件

以下參考文件和擁有技能是強制性的命令合約,非選讀的背景資料。在執行表格中的命令之前,請閱讀其對應的行。

需求參考文件
init、capture、skillsreferences/init-and-scaffold.md
lint、check、motion sidecars、snapshotreferences/lint-validate-inspect.md
compare、grade-compare、變數驅動的 render --batchreferences/compare-and-batch.md
現有專案的 Studio 節拍網格 beatsreferences/beats.md
preview、play、render、publish、Studio 上下文、回饋references/preview-render.md
doctor、瀏覽器管理references/doctor-browser.md
auth、HeyGen 託管的雲端渲染、以及模板變數references/cloud.md
AWS Lambda 部署和渲染references/lambda.md
Google Cloud Run 部署和渲染references/cloudrun.md
info、upgrade、compositions、docs、benchmark、遙測、媒體預處理references/upgrade-info-misc.md

對於合成變數,也請閱讀 /hyperframes-core → references/variables-and-media.md。對於 hyperframes add 和 hyperframes catalog,請使用 /hyperframes-registry。在 hyperframes present 之前,請閱讀 /slideshow;在 hyperframes keyframes 之前,請閱讀 /hyperframes-keyframes。對於 TTS、轉錄、字幕或背景移除選擇,請使用 /media-use。

專門的命令由其擁有工作流程的文件明確記錄:

npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json

present 提供一個可導覽的簡報,並具有簡報者與觀眾同步功能。beats 是獨立的 Studio 節拍網格工具,定義於 references/beats.md。keyframes 呈現安全搜尋的動畫和運動路徑診斷資訊。

Individual skills in this repo

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

dbillion/hermes-skills-public

Edit an existing image based on a text prompt.

dbillion/hermes-skills-public

Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.

dbillion/hermes-skills-public

Expert in video composition, editing, and format conversion. Use when the user wants to generate high-quality video, overlay images on video, concatenate clips, create GIFs, or sync audio to video using mcp-avtool-go and mcp-veo-go.

dbillion/hermes-skills-public

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). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

dbillion/hermes-skills-public

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. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

dbillion/hermes-skills-public

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

相關技能