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，將時間軸專案網址交給使用者，並詢問是要修改還是渲染。 - 僅在批准後才渲染： 疊代時使用草稿品質，交付時使用高品質。
- 驗證輸出： 確認檔案存在、非空且具有合理的時長。
# 快速疊代檢查；編寫時視需要重複執行。
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>
將微小的無樣式內容、畫布大小的圖示、缺少的 Hero 元素或時間軸註冊超時視為阻擋渲染的掛載缺陷。有關相應的修正，請參見 hyperframes-core/references/sub-compositions.md。
代理約定
-
在代理與 CI 呼叫中偏好使用
--json。伺服器模式的render、preview和play不提供一般的 JSON 輸出；preview --selection --json和preview --context --json是查詢模式的例外。 -
doctor --json總是返回退出碼 0。根據其負載內容來判斷：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 "<具體結果或障礙>"
對於順利執行的反饋，請保持簡潔。對於任何錯誤或障礙，請在提交前捕獲一個再現封包；不要僅發送症狀摘要。包括可重複執行的命令及其工作目錄、預期行為 vs 實際行為、確切錯誤訊息、輸出是否完成/降級/失敗、任何已知的因應措施，以及再現專案的狀態。對於評分 ≤ 7 且描述視覺缺陷（黑幀、閃爍、輸出損毀、錯誤影格、空白輸出或其他視覺異常）的情況，請同時包含一個 COMPOSITION_STRUCTURE: 區塊——這是一個保護隱私的結構解剖（元素數量普查 + 屬性存在性 + 時間軸形狀），使維護者能夠在不需要組合 ZIP 檔案的情況下，根據已知的錯誤家族進行模式匹配。代理會透過組合普查輔助工具自動填寫此區塊；人類使用者無需手動填寫。如果問題未能再次重現，請說明並仍附上最後失敗的命令和日誌。僅在獲得同意後才使用 --file-issue：它會將最小化再現案例發佈到公開網址。必要的封包格式和隱私警告定義於 references/preview-render.md。
在執行命令前請先閱讀對應的參考文件
以下參考文件及其所屬技能是強制性的命令合約，而非選擇性的背景閱讀。在執行表格中的命令前，請先閱讀其對應行。
| 需求 | 參考文件 |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, 動作側車檔, 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 則提供關於尋道安全的動畫與運動路徑診斷資訊。