HyperFrames CLI
除非專案指示提供了包裝器，否則以 npx hyperframes ... 執行命令。若有包裝器，請遵從它。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。
開發循環
- 搭建骨架：
npx hyperframes init <project>或捕捉一個網站。在非 TTY 模式下，請傳入--non-interactive --example=<name>。 - 尋找動作： 在手工編寫動畫之前，先搜尋是否已有可用的基本動作：
npx hyperframes catalog --query "reveal a headline one line at a time"。詢問你想要的效果，而不是你心中想好的機制。使用npx hyperframes add <name>安裝（參閱/hyperframes-registry）。只有當沒有任何東西符合時，才手工編寫。 - 編寫： 使用
/hyperframes-core編寫合成（composition）。 - 在編輯時獲得快速反饋： 在第一次 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 board） | 在合成檢查之前，僅當 storyboard: yes 時 | 檢閱計畫卡片和線框草圖。開啟 ?view=storyboard#project/<name>。 |
| 最終合成預覽 | 在 check 通過之後 | 在渲染前檢閱組裝好的時間軸。開啟 #project/<name>。 |
早期的板子並非對最終影片的批准。渲染始終需要 hyperframes-core/references/review-loop.md 所定義的最終批准。
子合成冒煙測試
靜態稽核無法捕捉到所有的掛載失敗。當專案使用子合成時，為每個主機插槽（host slot）捕捉至少一個可見的中點：
npx hyperframes snapshot --at <t1>,<t2>,<t3>
將微小無樣式的內容、畫布大小的圖示、缺少的英雄元素或時間軸註冊超時視為阻塞渲染的掛載缺陷。相關的修復方法請參閱 hyperframes-core/references/sub-compositions.md。
代理慣例
-
在手工編寫動畫之前搜尋目錄。
npx hyperframes catalog --query "<the beat, in plain language>"。搜尋完全是本機的：沒有代管服務、沒有帳號，且查詢文字絕不會被發送到任何地方。預設情況下，它根據與項目名稱、標題和描述共享的詞彙進行排名，這會錯過任何未重用目錄自身用詞的措辭。加上--on-device可根據語義進行排名（參閱下方的本機離線層級）。 -
讀取是哪個層級回應的；切勿從結果的出現來推斷。 使用
--json時，信封（envelope）會攜帶query、tier（on-device或words）、tier_detail、dropped、unindexed、shown、total和results，此外當回答的層級產生top_score時會包含它，當要求某個層級但無法執行時則包含warnings。words層級出現弱結果是預期中的；on-device層級出現同樣的結果則是錯誤。top_score僅供 on-device 使用，且背後沒有門檻：排名器對於每個查詢都會以某種順序回傳整個目錄，所以請將其視為證據，而不是通過或失敗的標準。 -
dropped和unindexed是註冊表和 on-device 索引之間的相反偏移，重新措辭查詢無法解決任何一個。dropped計算此註冊表無法安裝的已排名名稱，因此遺失的是最強匹配的項目。unindexed計算索引完全無法看到的註冊表變動，沒有任何查詢能回傳這些項目。重新整理註冊表對這兩者都不是答案：其資訊清單帶有 24 小時的 TTL 並會自行修復，而向量則是單獨發佈的工件，會擷取到~/.hyperframes/catalog/。當unindexed大於零時，使用--on-device重新執行會重新擷取該索引，因此這是提供給使用者的補救措施。純粹的過度覆蓋偏移（dropped大於零而unindexed為零）不會觸發重新擷取；清除~/.hyperframes/catalog/是跳出該情況的唯一方法。這兩個計數都是按照名稱計算，而不是按照結果計算，因此任一者都可能超過total。 -
當語義搜尋沒有回傳任何值得安裝的內容時，請明確告知。
npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier on-device。這是唯一會將查詢發送到某處的路徑，而且它是一個分開的、特意執行的命令，正是為了確保純粹的catalog --query能信守「不發送任何資料」的承諾。當 on-device 層級回應了，但最相關的結果仍然不適用時，請回報此次未命中；words層級的弱結果是預期中的，不值得回報。回傳的是一個目錄中尚不存在的動作列表，這些是直接讀取而非從安裝計數猜測的，因此重要的措辭是你想要的效果，而不是你想像中的項目名稱。它不附帶評分，也永遠不會進入評分指標。 -
提供本機離線層級；切勿在未告知的情況下啟用它。 一次性約 33 MB 的下載（
bge-small-en-v1.5的量化 ONNX 建置版及其分詞器，固定在某個修訂版）以及來自註冊表的目錄向量，兩者都快取在~/.hyperframes/下，不會添加到專案或任何套件中。快取後，它會根據語義進行排名，並且不會發送任何資料。大聲說出大小，讓使用者決定，然後在他們同意後傳入--on-device（加上-y可跳過提示）。互動式提供僅在 TTY 上觸發，而在--json模式下，不會印出任何相關資訊，因此在代理程式的執行中，你必須自行向使用者提出。 -
對於代理和 CI 呼叫，偏好使用
--json。伺服器模式的render、preview和play不提供一般的 JSON 輸出；preview --selection --json和preview --context --json是查詢模式的例外。 -
doctor --json始終以退出碼 0 結束。根據其 payload 進行閘控：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；不要嘗試還原此替換。 -
當代管雲端專案接近或超過 200 MB 上傳限制時，請使用
cloud render --dry-run --json，並遵循references/cloud.md中的.hyperframesignore調查步驟。切勿僅因為資產很大就忽略它。 -
切勿僅因為檢查通過就進行渲染。在最終預覽處暫停，等待批准。
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 |
技能歸屬是自動的 — 上述範例不需要 --skill。由工作流程搭建骨架的專案（hyperframes init --skill=<workflow>）會將其擁有技能記錄在 hyperframes.json 中，後續的每次渲染都會在匿名遙測中繼承它：重新渲染、npm run render 和 --batch 皆然。僅在需要為非透過工作流程建立的專案蓋上技能戳記時，才明確傳入 --skill=<slug>（其首次渲染會將其持久化）。
當使用者希望在沒有本機 Chrome、FFmpeg 或 AWS 的情況下進行代管渲染時，請使用雲端渲染。僅在 AWS 所有權是必要條件時使用 Lambda。僅在 GCP 所有權是必要條件時使用 Cloud Run。在執行任何雲端路徑之前，請先閱讀對應的參考文件。
在驗證渲染成功後，發送一份反饋報告，除非遙測被停用或使用者選擇退出：
npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
對於順利執行的反饋，請保持簡潔。對於任何錯誤或摩擦，在提交之前先捕捉一個再現封包；不要只發送症狀摘要。包含可重新執行的命令（相對於專案目錄 — 反饋會提交到公開頻道，所以不要貼上絕對路徑、家目錄前綴或用戶/機器識別碼）、預期行為與實際行為、確切的錯誤（也從堆疊追蹤中移除絕對路徑 — 保留 basename + 行號，刪除前導目錄）、輸出是否完成/降級/失敗、解決方法以及再現專案的狀態。對於評分 ≤ 7 且描述視覺缺陷（黑畫面、閃爍、損壞的輸出、錯誤的影格、空白輸出、其他視覺異常）的情況，也需包含一個 COMPOSITION_STRUCTURE: 區塊 — 一個保護隱私的結構性解剖（元素普查 + 屬性存在 + 時間軸形狀），以便維護者可以在沒有合成 ZIP 的情況下針對已知的錯誤家族進行模式比對。代理程式會透過組合普查輔助功能自動填寫此區塊；人類使用者不需要手動填寫。如果問題沒有再次重現，請說明並仍包含最後失敗的命令和日誌。僅在獲得同意後使用 --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 |
對於合成變數，請仔細閱讀個別參考文件。