HyperFrames CLI 是做什麼的?
除非專案說明提供了包裝器,否則以 npx hyperframes ... 執行命令。若有包裝器則遵循該包裝器。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。
開發循環
- 建立專案:
npx hyperframes init <project>或捕捉網站。在非 TTY 模式下,傳遞--non-interactive --example=<name>。 - 編寫: 使用
/hyperframes-core編寫合成。 - 編輯時快速取得回饋: 在第一次 HTML 傳遞之後及結構變更之後,執行
npx hyperframes lint。 - 執行最終關卡: 執行
npx hyperframes check;它在開啟瀏覽器之前會重新執行 lint。不要在前面加上多餘的獨立 lint 調用。加上--snapshots以取得帶註解的概覽影格和尋找裁切。 - 檢查子合成: 當
index.html掛載了data-composition-src,捕捉中點快照並檢查每個掛載的場景。 - 開啟最終 Studio 預覽: 執行
npx hyperframes preview,將時間軸專案 URL 交給使用者,並詢問是要修改還是要渲染。 - 僅在獲得批准後才渲染: 草稿品質用於疊代,高品質用於交付。
- 驗證輸出: 確認檔案存在、非空且具有合理的持續時間。
# 快速疊代檢查;在編寫時視需要重複執行。
npx hyperframes lint
# 必要的最終關卡;包含 lint。
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check 先執行 lint,然後使用一個瀏覽器工作階段和一次搜尋遍歷來審計執行時期錯誤、失敗的請求、版面配置、*.motion.json 斷言以及 WCAG 對比度。持續性發現會導致退出碼為非零;短暫的進入或退出發現僅供參考。使用 --strict 來將警告也導向非零退出碼。validate、inspect 和 layout 為相容性而保留為別名,但不得出現在新的指令或腳本中。
兩個不同的預覽表面
不要混淆這些狀態:
| 表面 | 何時可能開啟 | 目的 |
|---|---|---|
| 故事板 | 在合成檢查之前,僅當 storyboard: yes 時 | 審查計劃卡和線框草稿。開啟 ?view=storyboard#project/<name>。 |
| 最終合成預覽 | 在 check 通過之後 | 在渲染前審查已組裝的時間軸。開啟 #project/<name>。 |
早期故事板並非最終影片的批准。渲染始終需要 hyperframes-core/references/review-loop.md 定義的最終批准。
子合成煙霧測試
靜態審計無法捕捉到所有的掛載失敗。當專案使用子合成時,為每個主機插槽捕捉至少一個可見的中點:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
將微小的未設定樣式的內容、畫布大小的圖示、缺少的主題元素或時間軸註冊超時視為會阻擋渲染的掛載缺陷。相關修復方法請參閱 hyperframes-core/references/sub-compositions.md。
代理程式慣例
-
對於代理程式和 CI 呼叫,優先使用
--json。伺服器模式的render、preview和play不提供一般的 JSON 輸出;preview --selection --json和preview --context --json是查詢模式的例外。 -
doctor --json始終以零退出碼退出。根據其負載來判斷:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非 TTY 模式是自動的。在該模式下
init需要--example;使用--non-interactive來強制在 TTY 上具有確定性行為。 -
在同一個驗證循環中的所有命令使用同一個
HYPERFRAMES_RUN_ID。 -
當對應的警告、變數或 CI 條件必須決定渲染是否繼續時,使用
--strict、--strict-all和--strict-variables。 -
JSON 路徑會將主目錄替換為
$HOME;不要試圖反轉此替換。 -
切勿僅因為檢查通過就進行渲染。在最終預覽處暫停,並等待批准。
Studio 導向編輯
當使用者提到「這個元素」或當前選取項目時,請查詢 Studio 而非猜測:
npx hyperframes preview --context --json --context-fields selection
盡可能使用 selection.target.hfId,否則使用其選擇器和來源檔案。如果結果回報 no-selection,請要求使用者點擊該元素並重新執行。只請求你需要的上下文切片。僅在需要計算樣式或可編輯文字元資料時使用 --context-detail full。完整行為和失敗碼請參閱 references/preview-render.md。
渲染選擇
| 需求 | 命令 |
|---|---|
| 快速的本地疊代 | npx hyperframes render --quality draft |
| 最終的本地交付 | npx hyperframes render --quality high --output out.mp4 |
| 可重現的容器渲染 | npx hyperframes render --docker --strict --output out.mp4 |
| 本地變數驅動的批次渲染 | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen 託管的無基礎設施渲染 | npx hyperframes cloud render |
| 自我管理的分散式 AWS 渲染 | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| 自我管理的分散式 GCP 渲染 | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
當使用者想要託管渲染而不需要本地 Chrome、FFmpeg 或 AWS 時,使用雲端渲染。只有在 AWS 所有權是必要條件時才使用 Lambda。只有在 GCP 所有權是必要條件時才使用 Cloud Run。在執行任何雲端路徑之前,請閱讀對應的參考文件。
在驗證渲染成功後,除非遙測被停用或使用者選擇退出,否則發送一份回饋報告:
npx hyperframes feedback --rating <0-10> --comment "<具體結果或困擾>"
對於順利運行的回饋,保持簡潔。對於任何錯誤或困擾,請在提交前擷取重現封包;不要只發送症狀摘要。包含可重新執行的命令和工作目錄、預期行為與實際行為、確切錯誤、輸出是否完成/降級/失敗、解決方法以及重現專案狀態。如果問題無法再次重現,請說明但仍包含最後一次失敗的命令和日誌。僅在使用者同意後才使用 --file-issue:它會將最小重現案例發佈到公開 URL。所需的封包格式和隱私警告位於 references/preview-render.md。
執行命令前請先閱讀對應的參考文件
以下參考文件和擁有技能是強制性的命令合約,非選讀的背景資料。在執行表格中的命令之前,請閱讀其對應的行。
| 需求 | 參考文件 |
|---|---|
init、capture、skills | references/init-and-scaffold.md |
lint、check、motion sidecars、snapshot | references/lint-validate-inspect.md |
compare、grade-compare、變數驅動的 render --batch | references/compare-and-batch.md |
現有專案的 Studio 節拍網格 beats | references/beats.md |
preview、play、render、publish、Studio 上下文、回饋 | references/preview-render.md |
doctor、瀏覽器管理 | references/doctor-browser.md |
auth、HeyGen 託管的雲端渲染、以及模板變數 | references/cloud.md |
| AWS Lambda 部署和渲染 | references/lambda.md |
| Google Cloud Run 部署和渲染 | references/cloudrun.md |
info、upgrade、compositions、docs、benchmark、遙測、媒體預處理 | references/upgrade-info-misc.md |
對於合成變數,也請閱讀 /hyperframes-core → references/variables-and-media.md。對於 hyperframes add 和 hyperframes catalog,請使用 /hyperframes-registry。在 hyperframes present 之前,請閱讀 /slideshow;在 hyperframes keyframes 之前,請閱讀 /hyperframes-keyframes。對於 TTS、轉錄、字幕或背景移除選擇,請使用 /media-use。
專門的命令由其擁有工作流程的文件明確記錄:
npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
present 提供一個可導覽的簡報,並具有簡報者與觀眾同步功能。beats 是獨立的 Studio 節拍網格工具,定義於 references/beats.md。keyframes 呈現安全搜尋的動畫和運動路徑診斷資訊。