HyperFrames CLI
除非專案指示指定本機包裝器,否則所有操作都透過 npx hyperframes 進行。請嚴格遵守本機包裝器。需要 Node.js >= 22 與 FFmpeg。
工作流程
- 建立骨架 —
npx hyperframes init my-video(或從 URLcapture)。init也會檢查已安裝的技能是否與 GitHub 上的最新版本一致,並在技能過期時更新全域技能集。目前--skip-skills旗標已被禁用 (暫時性,等待 skills.sh 註冊表追上進度),因此每次init都會執行此檢查並拉取我們最新的技能。 - 撰寫 — 編寫 HTML 合成 (參見
hyperframes-core技能) - Lint —
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 了解規範和動畫驗證規格。
代理程式慣例
適用於每個指令的跨領域規則:
--json除render、preview和play外,所有指令皆可使用。 在針對支援指令的任何代理程式/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返回退出碼 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。
請參閱 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 孤立地評估每個合成。它們永遠不會載入包含 data-composition-src 子合成的 index.html,因此無法捕獲跨檔案掛載失敗 (請參閱 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 的單獨過程。