HyperFrames CLI
一切都透過 npx hyperframes 執行,除非專案說明指定使用本機包裝器。請嚴格遵守本機包裝器的指示。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 建立專案 —
npx hyperframes init my-video(或從 URLcapture)。init也會檢查已安裝的技能與 GitHub 上的最新版本是否一致,並在技能過期時更新全域技能組。--skip-skills旗標目前為停用狀態(暫時性的,因為 skills.sh 註冊表尚未跟上),因此每個init都會執行此檢查並下載最新的技能。 - 編寫 — 編寫 HTML 合成(請參閱
hyperframes-core技能) - 語法檢查 —
npx hyperframes lint - 驗證 —
npx hyperframes validate(執行時期錯誤 + 對比度) - 視覺檢查 —
npx hyperframes inspect - 預覽 —
npx hyperframes preview會開啟 Studio,這是一個時間軸編輯器,使用者可以在其中手動編輯任何內容(不只是觀看)。在那裡審查,然後再要求渲染。 - 渲染 — 選擇變體:
- 迭代:
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 過程。