外掛程式安裝： 在執行設定或更新指令之前，請遵循 外掛執行規則，當此技能位於 HyperFrames 外掛程式內部時。獨立安裝則保留下方的更新說明。
HyperFrames CLI
除非專案說明提供了包裝器，否則以 npx hyperframes ... 執行指令。當包裝器存在時，請遵循它。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。
開發循環
- 建立骨架：
npx hyperframes init <project>(居中空白)。或擷取一個網站。僅在要從命名範例開始時傳遞--example=<name>。 - 尋找動態： 如果請求指定了素材、音效、圖片、聲音或快速的視覺編輯，請在提出計劃前透過
/media-use解析它。否則，在親手編寫動畫前，先搜尋已存在的原始動作：npx hyperframes catalog --query "reveal a headline one line at a time"。詢問你想要的效果，而不是你心中想的機制。使用npx hyperframes add <name>安裝 (請見/hyperframes-registry)。只有在找不到符合的動作時才親手編寫。 - 編寫： 使用
/hyperframes-core編寫構圖。若要了解專案時間軸上的內容 (軌道、片段、開始、結束、播放什麼)，請執行npx hyperframes timeline --json，而不要讀取index.html和每個子構圖檔案：巢狀列攜帶著絕對的主要時間軸absStart/absEnd及其所屬的file，而不僅僅是它們的本地子構圖時間。優先使用--json而非文字形式；它花費較少的 token，卻能獲得相同或更好的正確性。請參閱references/upgrade-info-misc.md以取得能回答常見問題的單行指令，而無需讀取整個輸出。 - 在編輯時獲得快速回饋： 在第一次 HTML 傳遞之後以及在結構性變更之後執行
npx hyperframes lint。 - 執行最終閘門： 執行
npx hyperframes check；它會先重新執行 lint，然後才開啟瀏覽器。不要添加多餘的獨立 lint 調用。添加--snapshots以取得帶註解的概覽幀並尋找裁切。 - 檢查子構圖： 當
index.html掛載了data-composition-src時，擷取中間點快照並檢查每個掛載的場景。 - 開啟最終的 Studio 預覽： 執行
npx hyperframes preview --background，確認 URL 回傳 HTTP 200，將時間軸專案 URL 交給使用者，並詢問是要修改還是渲染。保持它活躍直到審查結束。 - 僅在獲得批准後才渲染： 在迭代時使用
--quality draft，在首次真正編碼時 (CLI 預設值) 使用--quality looks，在最終輸出時使用--quality delivery。 - 驗證輸出： 確認檔案存在且非空。閱讀渲染摘要的第二行 (
beginframevsscreenshot、GPU、階段時序)。screenshot+software gpu(在 Linux 上) 是慢速路徑。ffprobe -v error -show_format -show_streams並將持續時間 (以及如果簡報設定的話，還有 fps) 與根目錄的data-duration進行比較。
在你回合中的專案歷史
每次對專案的寫入都會被保存為一個可復原的條目。只在兩個時刻使用它，而不是在每一步驟：
- 回合開始時：
npx hyperframes history begin --who <你的名字> --label "<你即將要做的事>"，然後npx hyperframes history --since mine --who <你的名字>來查看此人自你上一回合以來更改了什麼。承接他們的編輯；絕不要覆寫它們。 - 檢查失敗，或使用者說情況變糟了：
npx hyperframes history undo --who <你的名字>會撤銷你最新的回合，並保留使用者的編輯。不要手動編輯回去。如果發生衝突，它會以退出碼 2 退出並印出兩個選擇。
每個回合都以 npx hyperframes history end 結束，以便你的寫入被標記為你的，而不是「在應用程式外部更改」。當回合處於開啟狀態時，對專案的每次寫入都計為你的，直到 10 分鐘沒有寫入為止；之後回合將自動結束。
強制性的創作者編輯交叉引用
- 在編寫或診斷縮放、嵌入/淡出、重新構圖、攝影機移動或任何關鍵幀動畫之前，請先閱讀
/hyperframes-keyframes。 - 在
hyperframes keyframes之前，請閱讀/hyperframes-keyframes；該指令會顯示動畫軌跡，但不會診斷片段剪輯。 - 對於剪輯、修剪、拼接、重新排序或來源時間編輯，請閱讀
/hyperframes-core並使用其片段/時間軸合約。 - 對於淡入/淡出、交叉淡化、軌道增益、音量自動化、閃避、配音雕刻或對放置的音訊套用 FX，請閱讀
/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 looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check 會先執行 lint，然後使用一個瀏覽器會話和一次搜尋傳遞來稽核執行時期錯誤、失敗的請求、版面配置、*.motion.json 斷言以及 WCAG 對比度。持續性發現會影響退出碼；暫時性的進入或退出發現僅供參考。使用 --strict 來將警告設為影響退出碼。validate、inspect 和 layout 為了相容性仍保留為別名，但不得出現在新的指令或腳本中。
渲染前的預覽
僅在 check 通過後，才開啟最終的構圖預覽 (#project/<name>) 來檢閱已組合的時間軸。聊天中的計劃和 storyboard.html 草稿圖表並不等同於最終影片的批准。渲染始終需要由 hyperframes/references/review-loop.md 定義的最終批准。
子構圖冒煙測試
靜態稽核無法捕捉到所有掛載失敗。當專案使用子構圖時，請為每個主機插槽捕捉至少一個可見的中間點：
npx hyperframes snapshot --at <t1>,<t2>,<t3>
將微小的未設定樣式的內容、畫布大小的圖示、遺失的主要元素或時間軸註冊超時視為阻擋渲染的掛載缺陷。請參閱 hyperframes-core/references/sub-compositions.md 以取得對應的修正。
代理慣例
-
在親手編寫動畫之前，先搜尋目錄。
npx hyperframes catalog --query "<用白話英文描述的節奏>"。搜尋完全是本地的：沒有託管層級、沒有帳號，查詢文字絕不會被發送到任何地方。預設情況下，它會根據與項目名稱、標題、描述和標籤共享的詞彙進行排名，這會遺漏任何未重複使用目錄自身措辭的表述。添加--on-device以根據語義進行排名 (請參閱下方的離線層級)。 -
即使影片不是英文，也要用英文查詢。 兩個層級索引的都是英文目錄，因此以其他文字查詢不會產生可搜尋的詞彙，並且會返回空結果。用英文描述動作；螢幕上的文字則保留影片所需的任何語言。
No searchable words in query正是這個意思，而不是缺少某個元件，所以不要將其報告為目錄缺口。 -
閱讀是哪個層級回應的；永遠不要從出現的結果來推斷。 使用
--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計算索引完全看不到的註冊表項目，任何查詢都永遠無法返回它。重新整理註冊表對兩者都不是解決方案：其 manifest 攜帶 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時沒有提示，但未找到任何結果的搜尋會將相同的請求放入warnings中，因此請讀取該陣列並自行將決定權交給使用者。當使用者詢問下載是什麼、為什麼是這個模型、或者什麼離開機器時，請引導他們前往 https://hyperframes.heygen.com/developers/catalog-search。 -
對於代理和 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 模式是自動的，並建立居中空白骨架。僅在要從命名範例開始時傳遞
--example。使用--non-interactive來在 TTY 上強制僅使用旗標模式。 -
在相同驗證迴圈中的所有指令使用一個
HYPERFRAMES_RUN_ID。 -
當磁碟空間不足時，執行
npx hyperframes clean(加上--dry-run以先列出清單)；它會移除死亡渲染留下的內容以及會自行重建的空閒快取，絕不會移除輸出、來源或正在執行的渲染所使用的任何東西。將 QC 幀寫入暫存目錄，而不是專案目錄。 -
當相應的警告、變數或 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 looks --output out.mp4 |
| 最終本地輸出 | npx hyperframes render --quality delivery --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 |
| 自行管理的 Google Cloud Run 渲染 | npx hyperframes cloudrun render |
在 cloud/lambda/cloudrun 前添加 dry-run 來在不花費的情況下驗證設定。要從該 subtype 的渲染歷史中打開一個渲染，請使用子指令名稱作為關鍵字：npx hyperframes cloud render --open <id>。
鍵盤快捷鍵學習與測試
當任務是學習或測試鍵盤快捷鍵時，執行 npx hyperframes keyframes。該指令會顯示動畫軌跡但不會由片段剪輯決定，因此將其用於攝影機動作、縮放和變形補間的診斷。加入 --repeat 來循環播放，加入 --overlay 來將軌跡疊加到原始幀上，加入 --json 來處理結構化輸出，或加入 --output <file> 來寫入影片。
節拍與速度
使用 npx hyperframes beats --help 來了解節拍偵測和速度匹配。
平台總結
┌──────────────┐
│ 本機 │
│ render, preview, play, │
│ play, lint, check, ... │
└──────┬───────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────▼──────┐ ┌────▼──────┐ ┌────▼──────┐
│ 雲端 │ │ Lambda │ │ Cloud Run │
│(HeyGen)│ │ (AWS) │ │ (GCP) │
└────────────┘ └────────────┘ └────────────┘
以本機開始；按需擴展
npx hyperframes init my-video # 建立骨架
npx hyperframes catalog --query "3D card flip" # 搜尋開發好的動作
npx hyperframes add card-flip-3d # 安裝它
# ... 編寫構圖 ...
npx hyperframes lint # 快速反饋
npx hyperframes check # 最終閘門
npx hyperframes preview --background # 最終預覽
npx hyperframes render --quality delivery --output out.mp4 # 輸出
在本機完成，且無須登入、設定或自動扣款。
內建命令
init, add, catalog, capture, lint, check,
snapshot, compare, grade-compare, preview, play,
present, beats, keyframes
單一或批次 render, publish, cloud, cloudrun,
feedback, lambda, doctor, browser, info, upgrade
skills, compositions, timeline, history, clean,
docs, benchmark, telemetry, transcribe, auth, tts,
remove-background
注意：validate、inspect 和 layout 為了相容性仍保留為別名，但不得出現在新的指令或腳本中。
自動補全
# Bash / Zsh
source <(npx hyperframes completion)
從本機 HTTP 伺服器提供畫面
npx hyperframes preview --port 8080 --background
使用 check 來驗證多個瀏覽器/畫面大小
check 支援 --browser 和 --size。在 .hyperframesrc 中設定預設值。
使用 environment 進行區域差異化
在執行 CLI 指令之前設定 HYPERFRAMES_ENV 以在環境之間切換。允許的值包括 development、staging、production，並會影響雲端端點的目標。
使用 skaffolding 進行多重專案
透過專用資料夾支援同時開發多個專案。init 會為每個專案建立一個新資料夾。
使用 shared 配置進行團隊協作
使用 .hyperframesrc 進行團隊範圍的設定，例如 --browser 和 --size。
從 GitHub 安裝 CLI
請參閱 GitHub 發行版 以取得二進位製檔案的安裝說明。
安裝
# 使用 npx (無需安裝)
npx hyperframes --help
# 全域安裝
npm install -g @hyperframes/cli
# 在專案中安裝
npm install --save-dev @hyperframes/cli
設定
CLI 可以透過 .hyperframesrc 檔案或環境變數來設定。請參閱 docs/configuration.md。
文件
完整的文件可在 hyperframes.heygen.com 取得。