Communitygithub.com

simpletibr/simplicio-loop-marketing

執行 HyperFrames CLI 開發循環 — 初始化、語法檢查、檢查、預覽、渲染 — 用於由 `hyperframes` 技能編寫的組合。在組合 HTML 寫入磁碟後、標記作品完成前調用。

simplicio-loop-marketing 是什麼?

此技能封裝了 HyperFrames CLI(即 `npx hyperframes`),專為行銷管線中的組合創作與驗證流程設計。它提供了一個嚴謹的開發循環:首先透過 `doctor` 驗證環境(需要 Node.js >= 22 和 FFmpeg),然後進行 `lint`(語法檢查)和 `inspect`(佈局/溢出審計),依序確保組合符合規範;接著可選擇 `preview` 進行本地預覽,最後以 `render` 生成最終 MP4 檔案。渲染支援多種參數調整,如幀率(fps)、品質(quality)、格式(format)以及變數覆蓋(variables),並在預設啟用嚴格模式(`--strict` 和 `--strict-variables`)下確保變數與組合結構的正確性。此技能與 `hyperframes-prompt-builder`(組合規範生成)和 `qa-tech-specs`(渲染結果驗證)等上游與下游技能緊密整合,適合在行銷資產自動化管線中作為中介環節使用。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes-cli

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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>/ 內的輸出檔案路徑。

流程

  1. 驗證環境:在每次會話首次執行時執行 npx hyperframes doctor。將缺少 FFmpeg 或 Chrome 的情況視為硬性障礙 — 不要嘗試渲染。
  2. Lint(語法檢查):執行 npx hyperframes lint <project_path> --json。將所有 error 級別的發現視為阻塞。警告會上報給協調器,由操作者決定。
  3. Inspect(檢查):執行 npx hyperframes inspect <project_path> --json。在渲染前解決所有報告的文字溢出或畫布逃逸問題。如果溢出是故意為了進場/出場效果,請在元素上標記 data-layout-allow-overflow(或對裝飾性元素在上層容器標記 data-layout-ignore) — 不要全域靜默規則。
  4. Preview(預覽)(僅限操作者):執行 npx hyperframes preview <project_path> --port <port>。回傳 Studio 專案 URL(http://localhost:<port>/#project/<project-name>),而非原始 index.html 路徑。
  5. Render(渲染):使用從 render_opts 解析出的旗標執行 npx hyperframes render <project_path>。透過單行 JSON 字串建立 --variables 引數。作品執行時務必傳入 --strict 和 --strict-variables。
  6. 驗證輸出:渲染後,檢查 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

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相關技能