HyperFrames CLI
所有操作都透過 npx hyperframes 執行,除非專案指令指定了本地包裝器。請嚴格遵循本地包裝器。需要 Node.js >= 22 和 FFmpeg。
工作流程
- Scaffold —
npx hyperframes init my-video(或從 URLcapture)。init也會檢查已安裝的技能與 GitHub 上的最新版本,並在有過時技能時更新全域集合。--skip-skills標誌目前已被停用(暫時的,在 skills.sh 註冊表追上進度之前),因此每個init都會執行此檢查並拉取我們最新的技能,無論如何。 - 撰寫 — 編寫 HTML 組合(請參閱
hyperframes-core技能) - Lint —
npx hyperframes lint(靜態,快速 — 在迭代過程中及早執行) - Check —
npx hyperframes check(瀏覽器門檻檢查;加上--snapshots可取得帶註解的影格 + 每個發現的裁剪) - 預覽 / 編輯 —
npx hyperframes preview開啟 Studio,時間軸編輯器,使用者可以在其中手動編輯任何內容(不僅是觀看)。在那裡審查,然後在渲染之前詢問。 - 渲染 — 選擇變體:
- 迭代:
npx hyperframes render --quality draft - 交付:
npx hyperframes render --quality high --output out.mp4 - CI / 跨主機重現:
npx hyperframes render --docker --strict --output out.mp4 - 雲端,零基礎設施:
npx hyperframes cloud render(HeyGen 託管渲染;無需本地 Chrome/FFmpeg/AWS,請參閱下面的雲端) - 雲端,自備 AWS:
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(請參閱下面的 Lambda)
- 迭代:
- 回報回饋 — 驗證輸出後,每個任務執行一次
npx hyperframes feedback --rating <1-5> --comment "..."(請參閱代理慣例)。
在預覽之前執行 check。它首先執行 linter(並在 lint 錯誤時完全跳過瀏覽器),然後在一次瀏覽器會話和一次尋找過程中完成舊版 validate → inspect → snapshot 序列的所有操作:執行時控制台錯誤和失敗的請求、佈局缺陷(文字溢出氣泡/容器或畫布,持續重疊、遮擋)、運動側車驗證(*.motion.json — 在尋找下的入場、交錯順序、在影格內、活躍度)以及 WCAG 對比度。對比度失敗是錯誤,並帶有採樣的前景色/背景色、測量值與所需比率以及建議的符合顏色,因此大多數對比度修正無需截圖。每個發現都帶有選擇器、data-* 身份、組合來源檔案、邊界框和取樣時間 — 直接跳到 HTML。單次取樣的瞬態降級為資訊;跨取樣持續的發現會阻斷退出碼(--strict 也會阻斷警告)。validate、inspect 和 layout 仍然可用,但已棄用為 check 部分的別名。
對於運動密集型工作,優先使用快照驅動的迭代和 *.motion.json 側車檔案 — 請參閱 references/lint-validate-inspect.md 了解規範和運動驗證規範。若要比較代理編寫的候選變體,請使用 npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json] 透過其自己的執行時渲染每個組合,組裝一個帶標籤的工作表,並排檢查,然後選擇。對於顏色分級選擇,請使用顏色特定的同級命令 npx hyperframes grade-compare --for <frame> --grades grades.json(或 --luts a.cube,b.cube)透過真實的 WebGL 分級執行時間將每個分級候選項渲染成一個帶標籤的 PNG,然後選擇贏家。
代理慣例
適用於每個命令的交叉規則:
--json可用於除render、preview和play伺服器模式之外的所有命令。 對於支援的命令的任何代理/CI 調用,請使用它;輸出包括一個_meta信封(CLI 版本、最新可用版本、更新建議)。render僅透過 stdout + 退出碼報告狀態 — 使用下面的渲染後檢查驗證成功。preview --selection --json和preview --context --json是預覽的例外:它們不會啟動伺服器,它們會查詢使用者正在執行的 Studio 會話並退出。doctor --json始終退出 0,即使環境損壞也是如此。根據負載的ok欄位進行門控:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。這使管道免受 CLI 版本變動的影響。- 非 TTY 模式是自動檢測的。 當
stdout不是 TTY(CI、代理、管道輸出)時,CLI 會自動切換到非互動模式;然後init需要--example。傳遞--non-interactive以在 TTY 上強制執行此模式。 - CI 渲染門控:
--strict在 lint 錯誤時失敗,--strict-all在警告時也失敗,--strict-variables在未宣告的--variables鍵時失敗。 - 使用
HYPERFRAMES_RUN_ID關聯驗證循環。 驅動 CLI 按任務/設計元素的協調器應為每個工作單元設置此環境變數一次;每個命令調用都會將其附加到遙測資料,並且check會發出每個門控的細分,使每次任務的往返次數可衡量。 --json中的路徑已被編輯 —$HOME變成字面上的$HOME,因此輸出可以安全地粘貼到錯誤報告和代理上下文中。- 渲染是使用者門控的。 檢查通過後切勿自動渲染。在
preview處暫停,告訴使用者影片可在 Studio 中編輯,並僅在使用者批准後才進行渲染。 - 對使用者導向的編輯使用 Studio 上下文。 當使用者說「這個選中的元素」、「我點擊的東西」、「當前選擇」或類似內容時,要求他們在 Studio 中選擇它,然後執行
npx hyperframes preview --context --json --context-fields selection。使用返回的selection.target.hfId/selector、selection.sourceFile、selection.currentTime和selection.thumbnailUrl來錨定編輯。如果selection為null且errors.selection.code為no-selection,請要求使用者點擊該元素並重新執行;不要從螢幕截圖中猜測。 - 保持 Studio 上下文精簡。
preview --context --json預設返回精簡選擇。新增--context-fields selection、--context-fields selection,lint或--context-fields lint以避免膨脹代理上下文。僅在需要大量欄位(如計算樣式、內聯樣式或文字欄位元資料)時使用--context-detail full。 - 渲染後驗證。 在
render返回退出碼 0 後,確認輸出檔案存在且大小合理,然後再報告成功:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 在成功時列印◇ <path>;對於長時間渲染,也使用ffprobe -i "$OUTPUT" -show_format -v error檢查持續時間是否合理。 - 在成功渲染後報告回饋。 驗證輸出後,每個任務執行一次
npx hyperframes feedback --rating <1-5> --comment "..."以報告運作情況 —5表示順利,較低的分數表示遇到問題。將您遇到的任何錯誤、解決方法、缺少的功能或令人困惑的行為放入--comment中。這是專案的主要訊號通道;保持沉默的渲染會使維護者無法了解情況。僅在遙測資料被禁用或使用者選擇退出時跳過。- 對於可重現的錯誤,請新增
--file-issue— 它將專案的最小重現範例發佈到公共 URL,並打開一個預先填寫了您的評論 + 環境的 GitHub 問題。僅靠評論幾乎無法讓維護者重現;發佈的組合才是使報告可操作化的關鍵。如果失敗的組合不在目前目錄中,請將--dir <project>指向它。 - 編寫維護者可以從中重現的錯誤評論 — 無法行動的複述會浪費報告。 CLI 已附加 os/arch/mem/ffmpeg/CLI-version,因此不要重複這些內容;將評論用於只有您看到的內容。對於錯誤,請包含適用的每一項:
- 確切的錯誤字串,逐字逐句(複製它,不要總結)— 以及渲染是否仍然產生輸出檔案、是否靜默回退(尋找
[Render] … re-rendering via screenshot/falling back日誌行),或者程序是否硬退出且沒有錯誤(Killed: 9、FATAL … heap、Target closed)。「哪個超時 / 哪個失敗模式」是最有用的事實。 - 最小重現範例:仍然顯示它的最小組合(或只是有問題的元素及其 CSS)— 在評論中內嵌它或註明檔案。說出您隔離的觸發條件(例如「僅當文字節點使用
font-family: 苹方時」、「僅在 4K 時」、「僅在存在<video>時」)。 - 您執行的確切命令 + 標誌,以及任何設置的環境變數(
HF_*/PRODUCER_*)。 - 問題所在及位置:影格編號或時間戳記,以及視覺缺陷(空白文字、底部黑色條帶、錯誤字形、凍結畫布)與您的預期。如果保存了螢幕截圖,請提供路徑。
- 如果它僅有時會重現,請說明並提供命中率。
- 確切的錯誤字串,逐字逐句(複製它,不要總結)— 以及渲染是否仍然產生輸出檔案、是否靜默回退(尋找
- 對於可重現的錯誤,請新增
路由
| 想要… | 閱讀 |
|---|---|
Scaffold 一個專案(init、capture、skills) | references/init-and-scaffold.md |
檢查正確性(lint、check、snapshot、已棄用的 validate/inspect) | references/lint-validate-inspect.md |
預覽或渲染(preview、play、render、publish) | references/preview-render.md |
診斷環境(doctor、browser) | references/doctor-browser.md |
雲端渲染,零基礎設施 HeyGen 託管(cloud render / list / get / delete、auth) | references/cloud.md |
在自己的 AWS Lambda 上進行雲端渲染(lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
參數化 / 模板渲染(--variables、--variables-file、--strict-variables、--batch) | references/cloud.md + hyperframes-core(variables-and-media.md) |
其他所有內容(info、upgrade、compositions、docs、benchmark、telemetry、資產預處理) | references/upgrade-info-misc.md |
跨技能交接
- Tailwind 專案(
init --tailwind)→ 在編輯類別或主題 Token 之前使用hyperframes-core(Tailwind 參考)。 - 註冊表區塊/元件(
hyperframes add、hyperframes catalog)→ 使用hyperframes-registry處理安裝路徑、子組合接線和片段合併。 - 資產預處理(
tts、transcribe、remove-background)→ 使用media-use處理語音選擇、Whisper 模型規則、字幕和 TTS 到字幕鏈。 - 參數化渲染(
--variables)→ 透過<html>上的data-composition-variables宣告;有關完整架構,請參閱hyperframes-core。
雲端(HeyGen 託管渲染)
hyperframes cloud render 是零基礎設施的渲染路徑:CLI 壓縮您的專案、上傳、在 HeyGen 的雲端上渲染,並下載 mp4。無需 Chrome、無需 FFmpeg、無需 AWS,而且您按信用付費。這是「在雲端渲染這個」的預設答案;僅當您已經擁有 AWS 並需要分散式/分塊渲染時才使用 Lambda。
npx hyperframes auth login # 一次性登入(與 `heygen` CLI 共用)
npx hyperframes cloud render # 壓縮、上傳、渲染、下載到 renders/<id>.mp4
常用標誌:--composition <html>、--output <path>、--quality draft|standard|high、--fps、--resolution 1080p|4k、--format mp4|webm|mov、--aspect-ratio(從 data-width/data-height 自動檢測)。使用 --no-wait + --callback-url 進行即發即忘;使用 --idempotency-key "$(uuidgen)" 確保重試安全。使用 cloud list / cloud get <id> / cloud delete <id> 管理工作。
慣用的範本工作流程是一次上傳,多次重新渲染:渲染本地專案一次以獲取其 asset_id,然後使用不同的 --variables 針對該資產重新提交(跳過壓縮 + 上傳)。有關完整標誌集、驗證模型、Webhook 和範本循環,請參閱 references/cloud.md。
變數(參數化 / 模板渲染)
任何渲染(本地、雲端或 Lambda)都可以在渲染時填入宣告的範本插槽。宣告位於組合上(data-composition-variables);CLI 表面是:
npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
--strict-variables 會在遇到任何未宣告的鍵或類型不符時使渲染失敗(請在 CI 中使用)。--batch <rows.json> 會為每個資料列渲染一個輸出,使用 {key}/{index} 路徑佔位符,並寫入一個 manifest.json。有關完整架構(宣告類型、data-var-src/data-var-text 宣告式綁定、用於子組合的每個實例 data-variable-values 和優先規則),請使用 hyperframes-core 技能(references/variables-and-media.md)。雲端範本循環位於 references/cloud.md。
Lambda(雲端渲染)
hyperframes lambda 將分散式渲染部署到 AWS Lambda,並從您的筆記型電腦或 CI 驅動渲染。端到端是三個命令:
npx hyperframes lambda deploy # 佈建 SAM 堆疊(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # 拆除(S3 存儲桶)
…
[為翻譯而截斷]