hyperframes-cli

插件安裝： 在執行設定或更新命令前，若此技能位於 HyperFrames 插件中，請遵循插件執行規則。獨立安裝則保留下方的更新說明。

HyperFrames CLI

除非專案說明提供包裝器（wrapper），否則以 npx hyperframes ... 執行命令。若存在包裝器，則遵循之。CLI 需要 Node.js 22 以上版本及 FFmpeg。

開發循環

1. 樣板建立： npx hyperframes init <project>（居中空白）。或擷取現有網站。僅在要從命名範例開始時傳遞 --example=<名稱>。
2. 尋找動作： 若請求指定了素材、聲音、圖片、語音或快速視覺編輯，請在提出計畫前透過 /media-use 解決。否則，在手工撰寫動畫前，先搜尋已存在的原始動作：npx hyperframes catalog --query "reveal a headline one line at a time"。請描述你想要的視覺效果，而非你腦中預想的機制。使用 npx hyperframes add <名稱> 安裝（參見 /hyperframes-registry）。僅在找不到任何合適選項時才手工撰寫。
3. 撰寫： 使用 /hyperframes-core 撰寫合成。若要了解專案時間軸上的內容（軌道、片段、開始、結束、播放什麼），請執行 npx hyperframes timeline --json，而非讀取 index.html 和每個子合成檔案：巢狀行攜帶絕對主時間軸的 absStart/absEnd 及其所屬的 file，而不只是每個子合成內部的本地時間。優先使用 --json 而非文字形式；它在相同或更好的正確性下消耗更少的 token。參見 references/upgrade-info-misc.md 中的一行解答，可回答常見問題而無需閱讀完整輸出。
4. 編輯時快速獲得反饋： 在第一次 HTML 傳遞後及每次結構變更後執行 npx hyperframes lint。
5. 執行最終閘道： 執行 npx hyperframes check；它會在開啟瀏覽器前重新執行 lint。不要預先附加一個多餘的獨立 lint 調用。添加 --snapshots 以取得註解式的總覽影格及尋找裁剪區。
6. 檢查子合成： 當 index.html 掛載 data-composition-src 時，擷取中點快照並檢查每個掛載的場景。
7. 開啟最終 Studio 預覽： 執行 npx hyperframes preview --background，確認 URL 返回 HTTP 200，將時間軸專案 URL 交給使用者，並詢問是要修改還是渲染。保持預覽存活直到審查結束。
8. 僅在批准後渲染： 迭代時使用 --quality draft，首次真實編碼使用 --quality looks（CLI 預設），最終交付使用 --quality delivery。
9. 驗證輸出： 確認檔案存在且非空。讀取渲染摘要的第二行（beginframe vs screenshot、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/<名稱>）以審查組裝好的時間軸。聊天中的計劃和 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，其中 query 和 tier 已經正確——只需填入 --wanted 並發送。這是唯一會將查詢發送到任何地方的路徑，並且它是一個單獨的、刻意的命令，正是為了讓普通的 catalog --query 保持不發送任何內容的承諾。在任一層級上回報，只要結果沒有做到所需的事情；不要為了 on-device 層級而保留，因為它需要同意下載 33 MB，因此在大多數代理人運行中是關閉的——等待它意味著永遠不回報。層級會隨著報告一起傳遞，因此詞彙失誤與語義失誤的區別無需你判斷自己遇到了哪一種。返回的是一個目錄中尚未擁有的動作列表，直接讀取而非從安裝計數猜測，因此重要的措辭是你想要的效果，而非你想像的項目名稱。它不攜帶評分，也永遠不會進入評分指標。

• 提供離線層級；絕不要靜默啟用它。 一次性約 33 MB 的下載（bge-small-en-v1.5 的量化 ONNX 建構加上其 tokenizer，鎖定到固定版本）和來自註冊表的目錄向量，兩者都快取在 ~/.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 始終以零退出。根據其 payload 進行閘控：

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• 非 TTY 模式是自動的，並會建立居中空白範本。僅在要從命名範例開始時傳遞 --example。在 TTY 上使用 --non-interactive 以強制僅使用旗標模式。

• 在相同的驗證循環中對所有命令使用一個 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 l

…

[已截斷以利翻譯]