AI Skills
hyperframes-cli

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

2.9萬星標
3036分支
更新於 2026/6/20
獲取技能源代碼

相關技能

docker-expert4.1萬vercel-cli-with-tokens2.8萬baoyu-diagram2.3萬
SKILL.md
readonlyread-only
name
hyperframes-cli
description

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

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. 驗證 — 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 了解規範和動畫驗證規格。

代理慣例

適用於所有指令的跨領域規則：

  • --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，因此輸出可安全貼到錯誤報告和代理上下文中。
  • 渲染後驗證。 在 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）→ 在編輯類別或主題 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）——時間軸從未執行，影格在初始狀態下捕捉
快照指令記錄 Sub-composition timelines not registered after 45000ms 陷阱 2——直接確認

snapshots/ 可在目視檢查後刪除；使用者最終的渲染是透過 npx hyperframes render 單獨進行的。