HyperFrames CLI
所有操作都透過 npx hyperframes 進行,除非專案說明指定了本地包裝器。請嚴格遵守本地包裝器。需要 Node.js >= 22 和 FFmpeg。
工作流程
- Scaffold(支架建立) —
npx hyperframes init my-video(或從 URL 使用capture)。init同時會檢查已安裝的技能是否與 GitHub 上最新版本相符,若有過期則更新全局技能集。目前--skip-skills旗標暫時失效(因為 skills.sh 註冊表正在追趕進度),所以每次執行init都會進行此檢查並拉取我們最新的技能。 - Write(撰寫) — 編寫 HTML 合成內容(請參考
hyperframes-core技能) - Lint(程式碼檢查) —
npx hyperframes lint - Validate(驗證) —
npx hyperframes validate(執行時期錯誤 + 對比度檢查) - Visual inspect(視覺檢查) —
npx hyperframes inspect - Preview(預覽) —
npx hyperframes preview會開啟 Studio,這是一個時間軸編輯器,使用者不僅可以觀看,還能手動編輯任何內容。在 Studio 中進行審查,並在詢問後再進行渲染。 - Render(渲染) — 選擇變體:
- 疊代:
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僅透過標準輸出和退出碼報告狀態——使用下面的渲染後檢查來驗證成功;preview/play是伺服器,不支援 JSON。doctor --json總是退出碼 0,即使環境有問題也是如此。請依據 payload 的ok欄位進行判斷:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。這可以保護 pipeline 不受 CLI 版本變動的影響。- 非 TTY 模式是自動偵測的。 當標準輸出不是一個 TTY(例如 CI、代理程式、管道輸出)時,CLI 會自動切換到非互動模式;此時
init需要--example。傳入--non-interactive可以即使在 TTY 上也強制使用此模式。 - CI 渲染閘門:
--strict會在 lint 錯誤時失敗,--strict-all連警告也會導致失敗,--strict-variables會因未宣告的--variables鍵值而失敗。 --json中的路徑會被匿名化——$HOME會變成字面字串$HOME,這樣輸出就可以安全地貼到錯誤報告和代理程式的上下文中。- 渲染需要使用者許可。 檢查通過後切勿自動渲染。請在
preview處暫停,告訴使用者在 Studio 中編輯影片,並在使用者批准後才進行渲染。 - 渲染後驗證。 在
render回傳退出碼 0 後,請確認輸出檔案存在且大小合理:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 會在成功時印出◇ <路徑>;對於長時間渲染,也請使用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)→ 在編輯 class 或主題 token 前,請使用hyperframes-core(Tailwind 參考)。 - Registry 區塊/元件(
hyperframes add、hyperframes catalog)→ 使用hyperframes-registry處理安裝路徑、子合成接線和程式碼片段合併。 - 素材預處理(
tts、transcribe、remove-background)→ 使用hyperframes-media處理語音選擇、Whisper 模型規則、字幕和 TTS 轉字幕鏈。 - 參數化渲染(
--variables)→ 透過<html>上的data-composition-variables宣告;請參閱hyperframes-core了解完整 schema。
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。