HyperFrames CLI
所有操作都透過 npx hyperframes 執行,除非專案說明指定了本地包裝器。請嚴格遵守本地包裝器。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 建立專案 —
npx hyperframes init my-video(或從 URLcapture) - 撰寫 — 編寫 HTML 組合(參見
hyperframes-core技能) - Lint —
npx hyperframes lint - Validate —
npx hyperframes validate(執行時錯誤 + 對比度) - 視覺檢查 —
npx hyperframes inspect - 預覽 —
npx hyperframes preview - 渲染 — 選擇變體:
- 迭代:
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。
Agent 慣例
適用於所有指令的通用規則:
--json在所有命令上都可用,除了render、preview和play。 將其用於支援的命令的任何 agent / CI 調用;輸出包含一個_meta信封(cli 版本、最新可用版本、更新建議)。render僅透過 stdout + 退出碼報告狀態——請使用下面的渲染後檢查來驗證成功;preview/play是伺服器,沒有 JSON。doctor --json始終以 0 退出,即使在環境故障時也是如此。透過 payload 的ok欄位進行判斷:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。這可以保護 pipeline 免受 CLI 版本變動的影響。- 非 TTY 模式會自動檢測。 當
stdout不是 TTY 時(CI、agent、管道輸出),CLI 會自動切換到非互動模式;此時init需要--example。傳遞--non-interactive以強制在 TTY 上使用此模式。 - CI 渲染關卡:
--strict在 lint 錯誤時失敗,--strict-all也在警告時失敗,--strict-variables在未宣告的--variables鍵時失敗。 --json中的路徑會被遮蔽——$HOME變成字面量$HOME,因此輸出可以安全地貼到錯誤報告和 agent 上下文中。- 渲染後驗證。 在
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。
有關先決條件、所有 6 個子命令(deploy、sites create、render、progress、destroy、policies)、IAM 策略驗證、狀態檔案以及成本/清理規則,請參閱 references/lambda.md。
完成最低門檻
靜態關卡
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 中每個主機 slot 的 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 進行的單獨步驟。