HyperFrames CLI
封裝 npx hyperframes 以供行銷引擎管線使用。需要 Node.js >= 22 和 FFmpeg 在 PATH 上(npx hyperframes doctor 可進行驗證)。所有指令預設以 DRY_RUN 安全模式執行 — lint/inspect 階段不會有外部呼叫;僅 render 會寫入 MP4。
調用時機
- 在
hyperframes-prompt-builder於outputs/<client>/<date>/<piece-id>/下產生專案後立即執行。 - 每當組合在發佈前需要驗證時(
lint+inspect)。 - 在迭代調整作品時進行本地預覽(
preview)。 - 進行最終渲染以產生可供發佈步驟擷取的成品(
render)。 - 當渲染失敗時進行環境故障排除(
doctor、browser、info)。
輸入
project_path:字串。HyperFrames 專案路徑(必須包含index.html和composition.json)。mode:"lint" | "inspect" | "preview" | "render" | "doctor"。render_opts:物件,可選,僅用於mode = "render"。識別的鍵值:fps:24 | 30 | 60(預設 30)。quality:"draft" | "standard" | "high"(預設"standard";迭代時使用"draft")。format:"mp4" | "webm"(預設"mp4")。variables:物件。以變數 ID 為鍵的 JSON 物件,用於覆蓋data-composition-variables的預設值。strict:布林值。對應--strict。管線中預設為true— 渲染時若出現 lint 錯誤則失敗。strict_variables:布林值。對應--strict-variables。作品執行時預設為true。workers:整數 1-8 或"auto"。預設"auto"。output:字串。outputs/<client>/<date>/<piece-id>/內的輸出檔案路徑。
流程
- 驗證環境:在每次會話首次執行時執行
npx hyperframes doctor。將缺少 FFmpeg 或 Chrome 的情況視為硬性障礙 — 不要嘗試渲染。 - Lint(語法檢查):執行
npx hyperframes lint <project_path> --json。將所有error級別的發現視為阻塞。警告會上報給協調器,由操作者決定。 - Inspect(檢查):執行
npx hyperframes inspect <project_path> --json。在渲染前解決所有報告的文字溢出或畫布逃逸問題。如果溢出是故意為了進場/出場效果,請在元素上標記data-layout-allow-overflow(或對裝飾性元素在上層容器標記data-layout-ignore) — 不要全域靜默規則。 - Preview(預覽)(僅限操作者):執行
npx hyperframes preview <project_path> --port <port>。回傳 Studio 專案 URL(http://localhost:<port>/#project/<project-name>),而非原始index.html路徑。 - Render(渲染):使用從
render_opts解析出的旗標執行npx hyperframes render <project_path>。透過單行 JSON 字串建立--variables引數。作品執行時務必傳入--strict和--strict-variables。 - 驗證輸出:渲染後,檢查 MP4 是否存在且非零大小。記錄至
data/video-usage.jsonl,格式為{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }。
輸出
lint:{ pass: boolean, errors: [...], warnings: [...] }。inspect:{ pass: boolean, findings: [...] }。render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }。preview:{ url: string }。
指令快速參考
npx hyperframes init <name> # 建立專案範本(由提示建構器為每個作品使用一次)
npx hyperframes lint <path> # 驗證標記
npx hyperframes inspect <path> # 佈局/溢出審計
npx hyperframes preview <path> --port 3017 # 本地開發
npx hyperframes render <path> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor # 環境檢查
npx hyperframes info # 版本/環境詳細資訊
不可協商規則
- 未通過
lint和inspect階段前,絕對不進行渲染。管線無法處理格式錯誤的組合。 - 絕對不要全域靜默 lint 或 inspect 的發現 — 修復標記,或使用
data-layout-allow-overflow/data-layout-ignore將特定元素列入白名單。 - 對於宣告了變數的作品,務必傳入
--strict-variables。變數 ID 的拼寫錯誤必須直接失敗,不能靜默回退到預設值。 - 對於最終交付的渲染,使用
--quality high。對於迭代循環,使用--quality draft以節省運算資源。 - 資產預處理(
tts、transcribe、remove-background)不屬於此技能範圍 — 應透過未來的hyperframes-media技能調用,而非在此內聯。
失敗模式
doctor報告缺少 FFmpeg 或 Chrome:請按照專案的設定說明安裝;不要繞過。render因unknown variable失敗:透過--variables傳入的鍵未在data-composition-variables中宣告。請修復標記或移除覆蓋。render超出時間預算:將--quality降為standard,或將組合拆分為子組合並透過--workers並行處理。- 輸出 MP4 大小為零:重新執行
doctor;通常是 Chrome 在錄製過程中崩潰。
相關技能
hyperframes:組合創作規則;產生此技能驗證和渲染的專案。hyperframes-prompt-builder:簡報 → 組合規範;在此技能之前執行。qa-tech-specs:在此技能之後執行,針對渲染的 MP4 驗證平台規格。
上游參考
完整上游技能(所有旗標、故障排除矩陣、參數化渲染):https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli