外掛安裝: 在執行設定或更新命令之前,如果此技能位於 HyperFrames 外掛中時,請遵循外掛執行規則。獨立安裝則保留下方的更新說明。
HyperFrames CLI
除非專案說明提供了包裝程式,否則請以 npx hyperframes ... 執行命令。如果有包裝程式,請遵守它。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。
開發循環
- 搭建腳手架:
npx hyperframes init <project>(居中空白)。或者捕捉一個網站。只有當要從一個有名字的範例開始時,才傳入--example=<名稱>。 - 找到動作: 如果請求指定了一個素材、聲音、圖片、語音或快速視覺編輯,在提出計劃之前,先透過
/media-use解決它。否則,在手動編寫動畫之前,搜尋一個已經能完成該動作的原始元件:npx hyperframes catalog --query "逐行揭示標題"。描述的應該是你想要的效果,而不是你心中所想的那個機制。使用npx hyperframes add <名稱>安裝(請參閱/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,第一次真正編碼時使用--quality looks(CLI 預設值),最終交付時使用--quality delivery。 - 將專案交給桌面應用程式(如提供): 當渲染的 Framey 行以
hyperframes open …結尾時,提供npx hyperframes open [目錄]。它會在 HyperFrames 桌面應用程式中打開專案並將其添加到首頁;在 Claude Code、Codex 或 Grok 下,其對話會捕獲此對話。如果沒有應用程式,它會退出 1 並列印下載連結。對代理使用--json。當open說要使用者在回來後執行catch-up,或者任何命令以命名它的行結尾時,請在下一次變更之前執行npx hyperframes catch-up [目錄]:它會列出自交接以來在應用程式中被請求和變更的內容。舊版的 CLI 沒有catch-up。 - 驗證輸出: 確認檔案存在且非空。閱讀渲染摘要的第二行(
beginframe與screenshot、GPU、階段計時)。Linux 上的screenshot+software gpu是慢速路徑。執行ffprobe -v error -show_format -show_streams並將持續時間(如果簡報設定了 fps 也包含 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並使用其剪輯 / 時間軸合約。 - 對於淡入 / 淡出、交叉淡入淡出、軌道增益、音量自動化、閃避、語音雕刻或對已放置音訊的效果處理,請閱讀
/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會列印已預填好查詢和層級的report_gap— 填入--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總是退出 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 h… [截斷以進行翻譯] |