外掛安裝: 在執行設定或新鮮度命令之前,如果此技能位於 HyperFrames 外掛中,請遵循外掛安裝規則。獨立安裝則保留下方更新說明。
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而非文字形式;它可以用相同或更好的正確性消耗更少的 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。 - 驗證輸出: 確認檔案存在且非空。讀取渲染摘要的第二行(
beginframevsscreenshot、GPU、階段時序)。Linux 上的screenshot+software gpu是慢速路徑。執行ffprobe -v error -show_format -show_streams並比較持續時間(以及簡報中設定的 fps)與根data-duration。
你回合中的專案歷史
對專案的每次寫入都會保留為一個條目,可以復原。只在兩個時刻使用它,而不是在每個步驟上:
- 回合開始:
npx hyperframes history begin --who <your-name> --label "<what you are about to do>",然後執行npx hyperframes history --since mine --who <your-name>來查看此人自你上一回合以來的變更。基於他們的編輯進行建構;切勿覆蓋它們。 - 檢查失敗,或使用者說情況變糟:
npx hyperframes history undo --who <your-name>會撤銷你最新的回合,並保留使用者的編輯不變。不要手動編輯回去。如果發生衝突,它會以退出碼 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/<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 "<the beat, in plain English>"。搜尋完全是本地的:沒有託管層級、沒有帳戶,且查詢文字永遠不會被發送到任何地方。預設情況下,它根據與項目名稱、標題、描述和標籤共享的詞彙進行排名,這會錯過任何未重複使用目錄自身措辭的措辭。加上--on-device以根據含義進行排名(參閱下方的離線層級)。 -
即使影片不是英文,也用英文查詢。 兩個層級都索引英文目錄,因此以其他文字進行的查詢不會產生可搜尋的詞彙,並會返回空結果。用英文描述動作;螢幕上的文字保持影片所需的任何語言。
No searchable words in query正是指這種情況,而不是缺少元件,所以不要將其報告為目錄缺口。 -
讀取哪個層級回答了問題;永遠不要從結果出現來推斷。 使用
--json時,信封攜帶query、tier(on-device或words)、tier_detail、dropped、unindexed、shown、total和results,以及當回答層級產生top_score時的top_score和當請求的層級無法執行時的warnings,或者當搜尋返回空且更好的層級仍在等待某人同意時的warnings。words上的弱結果是預期的;on-device上的相同結果是一個錯誤。top_score僅限於裝置端,背後沒有閾值:排序器會以某種順序為每個查詢返回整個目錄,因此應將其視為證據,而不是通過或失敗。 -
dropped和unindexed是註冊表與裝置端索引之間相反的偏差,重新措辭查詢無法解決任何一個問題。dropped計算此註冊表無法安裝的已排序名稱,因此正在遺失的是最強的匹配項。unindexed計算索引完全看不到的註冊表動作,沒有任何查詢能夠返回這些動作。重新整理註冊表不是兩者的答案:其 manifest 攜帶 24 小時 TTL 並自我修復,而向量是單獨發佈的工件,會提取到~/.hyperframes/catalog/。當unindexed高於零時,使用--on-device重新執行會重新提取該索引,因此這是提供給使用者的補救措施。純粹的過度覆蓋偏差(dropped高於零而unindexed為零)不會觸發重新提取;清除~/.hyperframes/catalog/是擺脫該問題的唯一方法。兩個計數都是名稱的計數,而不是結果的計數,因此任何一個都可能超過total。 -
當搜尋沒有返回任何值得安裝的東西時,請說出來。
npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>。你不必組裝那一行:catalog --query會列印預填好的內容,並且每個--json搜尋信封都將其攜帶為report_gap,其中查詢和層級已經正確 — 填寫--wanted並發送。這是將查詢發送到任何地方的唯一路徑,並且它是一個單獨的有意命令,正是為了確保普通的catalog --query保持其不發送任何內容的承諾。在任一層級上報告,只要結果未能做到所需的事情;不要為了裝置端層級而有所保留,裝置端層級需要一個經過同意的 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。根據其有效負載進行閘控: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 -- |