Communitygithub.com

Emasoft/ai-maestro-webdesign

透過外部 Hyperframes 單一儲存庫將 HTML 合成渲染成 MP4 影片。觸發條件為「將 HTML 渲染成影片」、「HTML 轉 MP4」、「網站轉影片」、「從 HTML 建立影片」、「將合成內容柵格化為 mp4」。不會對一般性的「動畫」/「影片」觸發——這些會導向其他工具或使用者自己的管道。請在透過 Hyperframes 將 HTML 渲染成 MP4 時使用。請以「將 HTML 渲染成影片」或「HTML 轉 MP4」觸發。

ai-maestro-webdesign 是什麼?

Hyperframes Bridge 是一項 AI 代理技能,專為將 HTML 合成內容渲染成 MP4 影片而設計。它透過 shell-out 模式與外部 Hyperframes 單一儲存庫 (`external/hyperframes/`) 協作,接收單一 HTML 場景檔案或完整的 Hyperframes 專案目錄作為輸入。該技能強制執行一個預渲染閘門序列(lint → validate → inspect → render),然後才呼叫 `npx hyperframes render --output <mp4>` 指令。它支援 Claude Code、Coder、Cursor 和 Codex 等主要 AI 代理平台,並作為設計管線中階段 B(輸出)的終端步驟運作。其主要優勢在於透過明確的合約和錯誤處理,提供了一個自主、自包含的橋接器,可將靜態 HTML 合成轉換為影片輸出,同時避免重新實作 Hyperframes 的內部管線。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Emasoft/ai-maestro-webdesign/tree/HEAD/skills/amw-hyperframes-bridge

在你喜歡的 AI 中提問

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

說明文件

Hyperframes Bridge

由 SKILL 編排。 外部相依包裝器。實際的 Hyperframes 單一儲存庫位於 ../../external/hyperframes/(若使用者選擇加入,由 /amw-init 步驟 6 複製;或由本技能在首次渲染時作為備用方案複製)。此技能記錄了 shell-out 模式;它不包含該單一儲存庫。

概覽

透過 shell-out 到 Hyperframes 單一儲存庫 (external/hyperframes/),將 HTML 合成內容渲染成 MP4 影片。接受單一 HTML 場景檔案或完整的 Hyperframes 專案目錄。在呼叫 npx hyperframes render --output <mp4> 之前,先執行強制性的預渲染閘門(lint → validate → inspect → render)。回傳 MP4 路徑和工作完成報告。外掛程式內不重新實作 Hyperframes 管線——僅限 shell-out。

說明

  1. 透過兩項檢查驗證外部儲存庫:external/hyperframes/package.json 必須存在,且 npx hyperframes render --help 必須有回應;任一項檢查失敗則快速失敗。
  2. 解析專案目錄:若提供 project_dir,則使用該目錄;若提供 html_scene_path,則從中建立一個暫存專案;若兩者皆未提供,則立即失敗。
  3. 依序執行預渲染閘門序列:lint → validate → inspect → render(若任何步驟回傳非零值則中止)。
  4. 執行 cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>;收集輸出路徑。
  5. 確認 MP4 檔案存在且非空;回報輸出路徑以及任何 inspect 警告。
  6. 請參閱下方的 ## 呼叫模式 區段以取得權威的執行步驟。

啟用

無專用斜線命令——此技能沒有對應的 /amw-* 快捷鍵。由 design-principles 編排器在主代理模式下,當已核准的設計需要 MP4 影片輸出時,作為階段 B 的最後步驟呼叫。編排器可直接應用此技能中的完整 Hyperframes shell-out 管線和合成技術,無需命令層級限制。

此技能是自主且自包含的——任何代理(主代理、子代理或外部編排器)皆可透過閱讀此 SKILL.md 及其參考資料來使用。此技能的技術不僅限於匹配命令所暴露的範圍。

流程中的位置

輸出(階段 B——終端)。HTML 轉 MP4 影片渲染管線。僅在使用者明確想要將 HTML 合成柵格化為影片檔案時觸發。在合成創作完成後最後執行。

觸發條件

僅在請求符合下列任一項時才呼叫此技能:

  • "將此 HTML 渲染成影片" / "渲染為 MP4"
  • "HTML 轉 MP4" / "網站轉影片" / "頁面轉影片"
  • "從此 HTML 合成內容建立影片"
  • "將合成內容柵格化為影片"
  • 明確提及 Hyperframes / hyperframes render / .hf.html

請勿在一般性提及「動畫」、「運動」、「影片播放」或「動畫元件」時呼叫——這些屬於:

  • ../amw-design-principles/starter-components/animations.html(瀏覽器內的 Stage + Sprite 時間軸)
  • ../amw-pretext/(排版運動——pretext-art/ 已棄用,會重新導向)
  • 使用者自己的管線

先決條件

  • runtime_binaries(系統先決條件): Node.js >= 22、git

  • runtime_binaries(由 /amw-init 安裝): Bun(Hyperframes 的套件管理器)、FFmpeg。Chrome 由 Hyperframes 本身透過 hyperframes browser ensure 管理(內部使用 Puppeteer + @puppeteer/browsers——非 Playwright)。

  • 外部來源: ../../external/hyperframes/——從 https://github.com/heygen-com/hyperframes 複製的 Hyperframes 單一儲存庫。請鎖定 v0.4.30 或更新版本以支援 inspect、--hdr 和 data-variable-values。若資料夾不存在,/amw-init 或此技能必須在繼續之前複製它:

    git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes
    cd external/hyperframes && bun install
    

輸入合約

橋接器接受兩個互斥的輸入。請僅提供其中一個:

欄位類型說明
html_scene_pathstring(可選)單一 HTML 檔案的絕對路徑。橋接器透過 mktemp -d -t hf-XXXXXX(POSIX 可攜式)建立一個暫存的 hyperframes 專案目錄,將 HTML 寫入為 index.html,進行渲染,然後在報告寫入後進行清理。
project_dirstring(可選)既有 hyperframes 專案目錄的絕對路徑(包含 index.html,以及可選的 compositions/、assets/)。橋接器直接 cd 到其中——不進行脚手架搭建。支援子合成、音訊和外部資產。

若同時提供兩者,project_dir 優先。若兩者皆未提供,則立即失敗。

呼叫模式

  1. 驗證外部儲存庫——需要兩項檢查:

    # 檢查 1 —— package.json 存在(單一儲存庫已複製)
    test -f "external/hyperframes/package.json" || exit-fail "找不到單一儲存庫"
    # 檢查 2 —— CLI 有回應(安裝功能正常)
    # @hyperframes/cli 並未發佈到 npm —— 必須從單一儲存庫工作區內部執行
    (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "hyperframes CLI 無法運作——請在 external/hyperframes/ 內部執行 bun install"
    

    若任一項檢查失敗,則快速失敗。請勿繼續。

  2. 解析專案目錄。

    • 若提供 project_dir:直接使用它。設定 HF_PROJ_DIR="$project_dir"。
    • 若提供 html_scene_path:建立一個暫存專案:
      HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)"
      cp "$html_scene_path" "$HF_PROJ_DIR/index.html"
      
    • 否則:立即失敗。
  3. 執行預渲染閘門序列:lint → validate → inspect → render。

    cd "$HF_PROJ_DIR"
    npx hyperframes lint
    npx hyperframes validate
    npx hyperframes inspect --json  # 若有任何錯誤則中止(使用 --strict 時非零退出)
    

    請參閱 TECH-hyperframes-cli-lint、TECH-hyperframes-cli-validate、TECH-hyperframes-cli-inspect。

[TECH-hyperframes-cli-inspect.md] 功能說明 · 使用時機 · 運作方式 · 旗標 · 輸出(JSON 模式) · 最小範例 · 選擇性退出的屬性 · 注意事項 · 交叉參考 [TECH-hyperframes-cli-validate.md] 功能說明 · 使用時機 · 運作方式 · 輸出 · 警告出現時機 · 最小範例 · 注意事項 · 交叉參考 [TECH-hyperframes-cli-lint.md] 功能說明 · 使用時機 · 運作方式 · 最小範例 · 注意事項 · 交叉參考

閘門序列注意事項: 橋接器的序列(lint → validate → inspect → render)刻意擴展了上游的序列(lint → inspect → preview → render——請參閱 Hyperframes CLI SKILL.md,位於已販售的 external/hyperframes/ 單一儲存庫內部),透過為無人值守的階段 B 管線加入 validate,並移除 preview(一種開發者迴圈的基本功能)。

  1. 渲染。 從解析後的專案目錄內部執行:
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <abs-mp4-path>
    
    根據需要加入其他旗標(--fps、--quality、--format、--hdr 等)——請參閱 TECH-hyperframes-cli-render。

[TECH-hyperframes-cli-render.md] 功能說明 · 使用時機 · 運作方式 · 旗標 · 品質指引 · 透明影片 · 最小範例 · 工作者調整 · 注意事項 · 交叉參考

  1. 將 MP4 路徑回傳給呼叫者。若專案目錄是暫存脚手架(html_scene_path 路徑),則在報告寫入後將其移除。

HTML 合成規則(Hyperframes 專屬)

合成使用純 HTML,並在 #stage 根元素及其子元素(軌道 / 剪輯 / 疊層)上使用 data-* 時間軸屬性。這與 ../amw-design-principles/starter-components/animations.html 中的 Stage + Sprite 心智模型相同——Hyperframes 透過多軌道音訊/視訊混合和離螢幕確定性渲染對其進行了擴展。

關鍵屬性(權威結構描述位於 external/hyperframes/packages/core/ 中,複製後即可使用):

  • data-composition-id——舞台層級識別碼
  • data-start、data-duration——秒數,每個剪輯
  • data-track-index——圖層排序(視訊 / 疊層 / 音訊軌道)
  • data-width、data-height——舞台層級畫布尺寸

請勿將 Framer Motion、GSAP-as-dependency 或任何第三方動畫執行時期引入橋接器中。Hyperframes 有自己的框架適配器模式;若使用者想要在合成中使用 GSAP,那是 Hyperframes 的職責,而非橋接器的。

參考資料

完整參考索引:INDEX.md——32 個 TECH-*.md 檔案,分為捕捉管線(7 步驟)、CLI 命令(12 個)、合成創作(7 個)、註冊表(4 個)等群組。每個檔案都有自己的目錄;僅載入您需要的檔案。

範例

請參閱 ./references/TECH-hyperframes-capture-step-*.md(7 步驟網站轉影片管線)中每個步驟的參考檔案內的工作範例,以及 TECH-hyperframes-composition-core 中的合成創作指南。

[TECH-hyperframes-composition-core.md] 功能說明 · 使用時機 · 運作方式 · 方法(敘事順序) · 單一檔案骨架 · 視覺識別閘門(必須——在編寫 HTML 之前) · 注意事項 · 交叉參考

輸出

一個渲染完成的 MP4 影片檔案加上一份工作完成報告。MP4 由從解析後的專案目錄執行的 npx hyperframes render --output <mp4> 產生;橋接器在回報成功前會確認檔案存在且非空。完整合約如下。

輸出與完成檢查清單

完整輸出合約(成品路徑推斷規則、工作完成報告格式、強制檢查清單)位於 TECH-output-contract。需要兩個強制輸出:

  1. 成品——hyperframes 專案資料夾 + 渲染完成的 MP4。路徑從專案推斷(使用者路徑 → 框架慣例 → ./design/<subtype>/ → 備用方案 ./design/videos/)。
  2. 工作完成報告位於 $MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.md,列出每個成品以及每個項目的檢查清單判定。

在回報完成之前:TECH-output-contract 中的每個檢查清單項目必須為 PASS 或 N/A。任何 FAIL 都會觸發修正迴圈。

資源

  • ../amw-design-principles/starter-components/animations.html——約 50 行的 Stage + Sprite 時間軸引擎,用於瀏覽器內預覽;Hyperframes 共享相同的節奏。
  • ../../bin/amw-html-export.py——不是替代品。 html-export 將單一畫面渲染為 PNG/PDF;Hyperframes 使用 Puppeteer + Chrome(由 hyperframes browser ensure 管理)+ FFmpeg 渲染多畫面 MP4。
  • ../amw-dev-browser/——不是替代品。 dev-browser 用於輸入/自動化;Hyperframes 是輸出柵格化器。
  • /amw-init——安裝 Bun、FFmpeg,並在首次使用時複製 external/hyperframes/。用於渲染的 Chrome 由 Hyperframes 本身透過 hyperframes browser ensure 佈建。
  • 外部儲存庫:https://github.com/heygen-com/hyperframes

不可協商事項

  • 使用外部單一儲存庫進行 shell-out。請勿在外掛程式內重新實作其管線。
  • 將 Hyperframes 原始碼販售到 skills/ 中——500 多個檔案對一個技能來說範圍過大。
  • 請勿用 dev-browser 替代 Hyperframes——它們解決的是相反的問題(輸入 vs. 輸出)。
  • 請勿用 html-export.py 替代——單一畫面 PNG 不是影片。
  • 使用者在首次使用前必須執行 /amw-init 以安裝 Bun + FFmpeg 並複製外部儲存庫。Chrome 在複製後執行 (cd external/hyperframes && npx hyperframes browser ensure) 一次來佈建。

錯誤處理

常見失敗模式及修正步驟位於 TECH-error-handling。涵蓋:缺少外部儲存庫、Bun / FFmpeg / Chrome 佈建、HTML 屬性解析錯誤、影片編碼失敗、過時的複製。

相關技能