HyperFrames CLI
以 npx hyperframes ... 執行命令，除非專案說明提供包裝器。若有包裝器，請遵從它。此 CLI 需要 Node.js 22 以上和 FFmpeg。
開發循環
- 脚手架：
npx hyperframes init <project>或捕捉網站。在非 TTY 模式下，傳遞--non-interactive --example=<name>。 - 尋找動作： 在手動編寫動畫之前，先搜尋是否已有現成素材：
npx hyperframes catalog --query "逐行揭示標題"。請描述你想要的視覺效果，而非你腦中想用的機制。使用npx hyperframes add <name>安裝（請參閱/hyperframes-registry）。只有在無任何素材符合需求時才自行編寫。 - 編寫： 使用
/hyperframes-core撰寫作品。 - 即時回饋： 在第一次 HTML 編寫後以及結構性變更後，執行
npx hyperframes lint。 - 最終檢查關卡： 執行
npx hyperframes check；它會先執行 lint，再開啟瀏覽器。請勿重複單獨執行 lint。加上--snapshots可獲得附註解的總覽影格，並找出裁切區域。 - 檢查子作品： 當
index.html掛載data-composition-src時，捕捉中點快照並檢查每個掛載場景。 - 開啟最終 Studio 預覽： 執行
npx hyperframes preview --background，確認 URL 返回 HTTP 200，將時間軸專案網址交給使用者，並詢問是要修改還是渲染。保持預覽開啟直到審查結束。 - 僅在核准後渲染： 迭代時使用草稿品質，交付時使用高品質。
- 驗證輸出結果： 確認檔案存在、非空，且具有合理的時間長度。
強制性創作者編輯交叉參考
- 在編寫或診斷縮放、推近/拉遠、重新構圖、鏡頭移動或任何關鍵影格動畫之前，請先閱讀
/hyperframes-keyframes。 - 在
hyperframes keyframes之前，請先閱讀/hyperframes-keyframes；此命令顯示動畫軌跡，不診斷片段裁切。 - 對於裁切、修剪、拼接、重新排序或來源時間編輯，請閱讀
/hyperframes-core並使用其片段/時間軸協定。 - 對於淡入/淡出、交叉淡變、音軌增益、音量自動化、迴避、配音剪裁或音訊效果，請閱讀
/hyperframes-audio。當片段放置或畫面時間也變更時，一併載入核心模組。 - 僅在需要來源/生成媒體或預處理衍生資產時使用
/media-use。從/hyperframes-core→references/creator-editing-recipes.md複製創作者編輯標記。
# 快速迭代檢查；編寫時視需要重複執行。
npx hyperframes lint
# 必要的最終關卡；包含 lint。
npx hyperframes check
npx hyperframes preview --background
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 以取得對應的修復方法。
代理慣例
-
在自行編寫動畫之前，務必先搜尋素材庫。
npx hyperframes catalog --query "<以白話英文描述的效果>"。搜尋完全在本機進行：沒有託管服務、沒有帳號，且查詢文字絕不會被傳送到任何地方。預設情況下，它會根據與項目名稱、標題和描述共用的詞彙進行排名，這會遺漏任何未使用素材庫自身詞彙的措辭。加上--on-device可根據含義進行排名（請參閱下方的離線層）。 -
即使影片不是英文，也要用英文查詢。 兩個層級都索引英文素材庫，因此以其他文字進行的查詢不會產生可搜尋的詞彙，並會返回空結果。用英文描述動作；螢幕上的文字保持影片所需的任何語言。
查詢中沒有可搜尋的詞彙正是這種情況，並非缺少元件，因此不要將其報告為素材庫缺口。 -
閱讀回應的是哪個層級；絕對不要從出現的結果推斷。 使用
--json時，信封會包含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 "<你執行的查詢>" --wanted "<你需要的動作>" --tier <回答的層級>。你不需要手動組合該命令：catalog --query會預先填寫並印出它，而且每個--json搜尋信封都會將其攜帶為report_gap，其中查詢和層級已經正確——填入--wanted並發送。這是將查詢傳送到任何地方的唯一路徑，而且它是一個單獨的、經過審慎考慮的命令，正因為如此，單純的catalog --query才能保持其不傳送任何東西的承諾。在任一層級回報，只要結果沒有完成所需功能；不要為了等待 on-device 層級而忍住不回報，因為該層級需要同意下載 33 MB，因此在大多數代理執行中都是關閉的——等待它意味著永遠不回報。層級會隨報告一起傳送，因此詞彙失誤與語義失誤之間的區別會保持清晰，無需你自行判斷。回傳的是一個素材庫中尚未擁有的動作清單，直接讀取而非從安裝計數推測，因此重要的措辭是你想要的效果，而非你想像的項目名稱。它不包含評分，也絕不會進入評分指標。 -
提供離線層級；絕不要默默啟用它。 一次性約 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始終以零退出碼結束。在其有效負載上設定閘門：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 "<具體結果或問題>"
保持乾淨執行的回饋簡潔。對於任何錯誤或問題，請在提交前捕捉重現包；不要只發送症狀摘要。包含可重新執行的命令（相對於專案目錄——回饋會提交到公開頻道，因此請勿貼上絕對路徑、家目錄前綴或使用者/機器識別碼）、預期行為與實際行為、確切錯誤（也從堆疊追蹤中移除絕對路徑——保留基底名稱 + 行號，刪除前導目錄）、輸出是否完成/降級/失敗、解決方案以及重現專案狀態。對於描述視覺缺陷（黑色畫格、閃爍、損壞輸出、錯誤畫格、空白輸出、其他視覺異常）且評分 ≤ 7 的情況，也請包含一個 COMPOSITION_STRUCTURE: 區塊——一個保護隱私的結構性解剖（元素普查 + 屬性存在 + 時間軸形狀），以便維護者可以在沒有作品 ZIP 的情況下根據已知的錯誤家族進行模式比對。代理會透過作品普查輔助程式自動填寫此區塊；人類使用者無需手動填寫。如果問題沒有再次重現，請說明情況，但仍包含最後失敗的命令和日誌。僅在獲得同意時使用 --file-issue：它會將最小重現發佈到公開 URL。所需的封包格式和隱私警告位於 references/preview-render.md。
在執行命令之前閱讀對應的參考文件
以下參考文件清單（已截斷，請參考原始文件）