Communitygithub.com

sq-cm/claude-template

HyperFrames CLI 開發循環 — 使用 `npx hyperframes` 進行專案初始化(init)、驗證(lint, validate, inspect)、預覽、渲染以及環境除錯(doctor, browser, info, upgrade)。在執行這些指令或排除 HyperFrames 建置/渲染環境問題時使用。對於資產前處理指令(`tts`、`transcribe`、`remove-background`),請改用 `hyperframes-media` 技能。

claude-template 是什麼?

此技能定義了 HyperFrames CLI 的完整開發工作流程,從專案初始化(`npx hyperframes init`),到程式碼檢查(`lint`)、執行時期驗證(`validate`,在無頭 Chrome 中載入組合並檢查 JS 錯誤、資源缺失及 WCAG 對比度)、視覺檢查(`inspect`,偵測文字溢出、剪裁等版面問題)、即時預覽(`preview`,支援熱重載及 Studio 專案 URL),以及最終渲染(`render`,支援多種品質、FPS、格式、變數覆蓋及 Docker 模式以達到可重現輸出)。它也提供環境除錯指令,如 `doctor`(檢查 Chrome、FFmpeg、Node、記憶體)、`browser`(管理內建 Chrome)、`info`(版本與環境細節)及 `upgrade`(檢查更新)。此技能適用於所有使用 HyperFrames CLI 的場景,從開發迭代到 CI/CD 代理整合,並與 `hyperframes-media` 技能互補,後者負責 TTS、轉錄及去背等資產前處理。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sq-cm/claude-template/tree/HEAD/.claude/skills/hyperframes-cli

在你喜歡的 AI 中提問

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

說明文件

HyperFrames CLI

所有操作都透過 npx hyperframes 執行。需要 Node.js >= 22 與 FFmpeg。

工作流程

  1. Scaffold — npx hyperframes init my-video
  2. 撰寫 — 編寫 HTML 組合(參見 hyperframes 技能)
  3. Lint(程式碼檢查) — npx hyperframes lint
  4. 執行時期驗證 — npx hyperframes validate
  5. 視覺檢查 — npx hyperframes inspect
  6. 預覽 — npx hyperframes preview
  7. 渲染 — npx hyperframes render

請在預覽前先執行 Lint 與 Inspect。lint 會捕捉缺少 data-composition-id、重疊軌道及未註冊時間軸的情況。inspect 會在無頭 Chrome 中打開渲染組合,掃描時間軸,並報告從氣泡/容器或畫布溢出的文字。

Scaffolding

npx hyperframes init my-video                        # 互動式精靈
npx hyperframes init my-video --example warm-grain   # 選擇範例
npx hyperframes init my-video --video clip.mp4        # 搭配影片檔案
npx hyperframes init my-video --audio track.mp3       # 搭配音訊檔案
npx hyperframes init my-video --example blank --tailwind # 搭配 Tailwind v4 瀏覽器執行環境
npx hyperframes init my-video --non-interactive       # 跳過提示(CI/代理使用)

範本:blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。

init 會建立正確的檔案結構、複製媒體、使用 Whisper 轉錄音訊,並安裝 AI 編碼技能。請使用它而不是手動建立檔案。

使用 --tailwind 時,請注意 scaffold 使用 Tailwind v4.2 的瀏覽器執行環境,而非 Studio 的 Tailwind v3 設定 — 在編輯前請根據 v4 文件檢查 class 與主題 token 語法。

Linting

npx hyperframes lint                  # 目前目錄
npx hyperframes lint ./my-project     # 特定專案
npx hyperframes lint --verbose        # 資訊層級的發現
npx hyperframes lint --json           # 機器可讀

檢查 index.html 及 compositions/ 中的所有檔案。回報錯誤(必須修正)、警告(建議修正)以及資訊(使用 --verbose 時)。

執行時期驗證

npx hyperframes validate                  # 目前目錄
npx hyperframes validate ./my-project     # 特定專案
npx hyperframes validate --json           # 機器可讀
npx hyperframes validate --timeout 5000   # 腳本/媒體較慢時(預設 3000 毫秒)

在無頭 Chrome 中載入組合,並回報 JS 控制台錯誤、資源缺失及 WCAG 對比度問題(--no-contrast 可跳過對比度檢查)。請在 lint 之後、inspect 之前執行。

validate 在上游已棄用,改為 npx hyperframes check,它會在一個瀏覽器工作階段中執行 lint、執行時期、版面、動畫及對比度驗證 — 兩者任一種皆可滿足「lint 與 validate」檢查項目的需求。

視覺檢查

npx hyperframes inspect                 # 檢查時間軸上的渲染版面
npx hyperframes inspect ./my-project    # 特定專案
npx hyperframes inspect --json          # 代理可讀的發現
npx hyperframes inspect --samples 15    # 更密集的時間軸掃描
npx hyperframes inspect --at 1.5,4,7.25 # 明確的主角幀時間戳

請在 lint 與 validate 之後使用,特別是包含對話氣泡、卡片、字幕或緊湊排版的組合。它會回報:

  • 延伸到最近視覺容器或氣泡外部的文字
  • 被自己的固定寬度/固定高度框剪裁的文字
  • 延伸到組合畫布外部的文字
  • 子元素逃出裁剪容器的情況

錯誤應在渲染前修正。警告會提供給代理審查;可加上 --strict 讓警告也導致失敗。重複的靜態問題預設會被摺疊,以使 JSON 輸出對於 LLM 上下文視窗保持精簡。如果溢出是出入動畫有意為之,請在該元素或其父元素上標記 data-layout-allow-overflow。如果某個裝飾性元素不應被審計,請標記 data-layout-ignore。

npx hyperframes layout 仍可作為相同視覺檢查通道的相容性別名使用。

預覽

npx hyperframes preview                   # 提供目前目錄的服務
npx hyperframes preview --port 4567       # 自訂連接埠(預設 3002)

檔案變更時會熱重載。會自動在瀏覽器中開啟 Studio。

當將專案交還給使用者時,請使用 Studio 專案 URL,而不是原始 index.html 路徑:

http://localhost:<port>/#project/<project-name>

請使用預覽輸出中的實際連接埠以及專案目錄名稱。例如,在 codex-openai-video 中執行 npx hyperframes preview --port 3017 後,請回報 http://localhost:3017/#project/codex-openai-video。

請將 index.html 僅視為原始碼上下文。將其連結為實作檔案是可以的,但請不要將其標示為專案或預覽表面。

渲染

npx hyperframes render                                # 標準 MP4
npx hyperframes render --output final.mp4             # 指定輸出名稱
npx hyperframes render --quality draft                # 快速迭代
npx hyperframes render --fps 60 --quality high        # 最終交付
npx hyperframes render --format webm                  # 透明 WebM
npx hyperframes render --docker                       # 位元組一致
標記選項預設值說明
--output路徑renders/name_timestamp.mp4輸出路徑
--fps24, 30, 603060fps 會使渲染時間加倍
--qualitydraft, standard, highstandarddraft 用於迭代
--formatmp4, webmmp4WebM 支援透明度
--workers1-8 或 autoauto每個會啟動一個 Chrome
--docker旗標off可重現的輸出
--gpu旗標offGPU 加速編碼
--strict旗標off在 lint 錯誤時失敗
--strict-all旗標off在錯誤和警告時都失敗
--variablesJSON 物件—覆蓋在 data-composition-variables 中宣告的變數值
--variables-file路徑—包含變數值的 JSON 檔案(--variables 的替代方案)
--strict-variables旗標off在 --variables 中有未宣告的鍵或型別不符時讓渲染失敗

品質指引: 迭代時使用 draft,審查時使用 standard,最終交付時使用 high。

參數化渲染: 組合在其 <html> 根元素上使用 data-composition-variables 宣告其變數 — 這是一個 JSON 宣告陣列(每個條目為 {id, type, label, default}),用於定義結構。內部的腳本透過 window.__hyperframes.getVariables() 讀取解析後的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一個以 id 為鍵的 JSON 物件,用於覆蓋一次渲染中宣告的預設值;缺少的鍵會回退,因此同一個組合可以在開發預覽和生產環境中原樣執行。(子組合宿主也可以使用 data-variable-values 對每個實例進行覆蓋 — 物件結構相同,範圍限於子組合的一次掛載。完整模式請參見 hyperframes 技能。)

資產前處理

npx hyperframes tts、transcribe 和 remove-background 會產生資產(旁白音訊、詞級轉錄、透明影片),這些資產可以被放入組合中。每個指令在首次執行時會下載自己的模型。有關語音選擇、Whisper 模型規則(.en 會翻譯非英語的注意點)、輸出格式選擇(VP9 alpha WebM 與 ProRes)以及 TTS → 轉錄 → 字幕鏈,請使用 hyperframes-media 技能。

疑難排解

npx hyperframes doctor       # 檢查環境(Chrome、FFmpeg、Node、記憶體)
npx hyperframes browser      # 管理內建 Chrome
npx hyperframes info         # 版本與環境詳細資訊
npx hyperframes upgrade      # 檢查更新

如果渲染失敗,請先執行 doctor。常見問題:缺少 FFmpeg、缺少 Chrome、記憶體不足。

其他

npx hyperframes compositions   # 列出專案中的組合
npx hyperframes docs           # 開啟文件
npx hyperframes benchmark .    # 基準測試渲染效能

相關技能