HyperFrames CLI
除非專案說明提供了包裝器,否則使用 npx hyperframes ... 執行命令。若有包裝器,請遵循它。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。
開發循環
- 架構:
npx hyperframes init <project>(居中空白)。或捕獲一個網站。僅當要從指定範例開始時,才傳遞--example=<name>。 - 尋找動作: 如果需求指定了素材、音效、圖片、語音或快速視覺編輯,請在提出計劃之前,先透過
/media-use解析它。否則,在手動編寫動畫之前,請搜尋現有基本動作:npx hyperframes catalog --query "以一行文字揭示標題"。請描述您想要的效果,而不是您心中所想的方法。使用npx hyperframes add <name>安裝(參見/hyperframes-registry)。只有在找不到合適的基本動作時,才手動編寫。 - 編寫: 使用
/hyperframes-core編寫合成。若要知道專案時間軸上的內容(軌道、片段、開始、結束、播放內容),請執行npx hyperframes timeline --json,而不是讀取index.html和每個子合成檔案:巢狀列攜帶絕對主時間軸的absStart/absEnd及其所屬的file,而不僅僅是它們在每個子合成中的本地時間。相對於文字形式,優先使用--json;它消耗較少的 tokens,但能達到相同或更好的正確性。請參閱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。 - 驗證輸出: 確認檔案存在且非空。讀取渲染摘要的第二行(
beginframevsscreenshot、GPU、階段時間)。screenshot+software gpu在 Linux 上為慢速路徑。執行ffprobe -v error -show_format -show_streams並將持續時間(以及如果簡報有設定的 fps)與根目錄的data-duration進行比較。
強制性創作者編輯交叉引用
- 在編寫或診斷縮放、切入/切出、重構圖、攝影機移動或任何關鍵幀動作之前,請先閱讀
/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/<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以根據含義進行排序(請參閱下面的離線層級)。 -
即使影片不是英文,也請用英文查詢。 兩個層級都索引了一個英文目錄,因此使用另一種文字進行的查詢不會產生可搜尋的詞彙,並會返回空結果。用英文描述動作;螢幕上的文字則保留影片所需的任何語言。
查詢中沒有可搜尋的詞彙恰恰就是指這種情況,而不是缺少元件,因此不要將其報告為目錄缺口。 -
讀取是哪個層級回答了問題;永遠不要從結果的外觀來推斷。 使用
--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。根據其負載內容設定閘門:
npx hyperframes doctor --json | jq -e '.ok' >/dev/null
- 非 TTY 模式是自動的,並會建立居中空白專案。僅當要從指定範例開始時,才傳遞
--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 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 <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 "<具體結果或摩擦點>"
保持乾淨執行的回饋簡潔。對於任何錯誤或摩擦,請在提交前捕獲一個重現包;不要僅發送症狀摘要。包括可重新執行的命令(相對於專案目錄 — 回饋會提交到公共頻道,因此不要貼上絕對路徑、家目錄前綴或用戶/機器識別碼)、預期行為與實際行為、確切的錯誤訊息(也請去掉絕對路徑...)
(基於 [原文截斷] 進行翻譯)