外掛安裝: 在執行設定或新鮮度指令之前,如果此技能位於 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 [dir]。它會在 HyperFrames 桌面應用程式中打開專案並將其添加到首頁;在 Claude Code 或 Codex 下,其聊天會接續此對話。如果沒有應用程式,則退出碼為 1 並列印下載連結。使用--json用於代理。 - 驗證輸出: 確認檔案存在且非空。閱讀渲染摘要的第二行(
beginframe與screenshot、GPU、階段計時)。Linux 上的screenshot+software gpu是慢速路徑。使用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並使用其剪輯/時間軸合約。 - 對於淡入/淡出、交叉淡變、軌道增益、音量自動化、閃避、畫外音 carving 或對放置音訊的 FX,請閱讀
/hyperframes-audio。當剪輯放置或畫面時間也發生變化時,請同時載入 core。 - 指定素材、音效、圖片、語音或快速視覺編輯的請求會透過
/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以根據意義進行排名(參見下面的離線層級)。 -
即使影片不是英文,也要用英文查詢。 兩個層級都為英文目錄建立索引,因此使用其他文字的查詢不會產生可搜尋的術語,並且會返回空。用英文描述動作;螢幕上的複製文字保持影片所需的任何語言。
查詢中沒有可搜尋的詞正是這個意思,並非缺少元件,所以不要將其報告為目錄缺口。 -
閱讀是哪個層級回答了;永遠不要從結果出現來推斷。 使用
--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。Server 模式的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 --quality delivery --container docker |
| HeyGen 雲端渲染 | npx hyperframes cloud render --quality delivery --output out.mp4 |
| AWS Lambda 渲染 | npx hyperframes lambda render --function <arn> --payload <file> |
| Google Cloud Run 渲染 | npx hyperframes cloudrun render --service <name> --region <region> |
範例工作流程
# 初始化
npx hyperframes init my-project
cd my-project
# 尋找動畫
npx hyperframes catalog --query "fade in title"
npx hyperframes add fade-in-title
# 編寫和檢查
# ... 編輯 index.html ...
npx hyperframes lint
npx hyperframes check
# 預覽和渲染
npx hyperframes preview --background
npx hyperframes render --quality looks --output final.mp4
故障排除
npx hyperframes doctor:診斷常見問題(Node.js 版本、FFmpeg、依賴項)。npx hyperframes doctor --json:機器可讀的診斷輸出。npx hyperframes clean:清理死渲染和快取。npx hyperframes upgrade:更新 CLI。npx hyperframes info:顯示系統資訊。
其他指令
npx hyperframes benchmark:執行基準測試。npx hyperframes telemetry:管理遙測設定。npx hyperframes transcribe:轉錄音訊。npx hyperframes auth:管理認證。npx hyperframes tts:文字轉語音。npx hyperframes remove-background:移除背景。npx hyperframes skills:管理技能。npx hyperframes compositions:列出合成。npx hyperframes docs:打開文件。npx hyperframes browser:在瀏覽器中打開。npx hyperframes lambda:Lambda 相關指令。npx hyperframes cloudrun:Cloud Run 相關指令。npx hyperframes publish:發布專案。
棄用指令
以下指令已棄用,請勿在新腳本或指令中使用:validate、inspect、layout。請改用 check。
另請參閱
/hyperframes-core:核心合成 API。/hyperframes-keyframes:關鍵影格動畫。/hyperframes-audio:音訊處理。/media-use:素材使用。/hyperframes-registry:套件註冊表。references/:其他參考文件。