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。
說明
- 透過兩項檢查驗證外部儲存庫:
external/hyperframes/package.json必須存在,且npx hyperframes render --help必須有回應;任一項檢查失敗則快速失敗。 - 解析專案目錄:若提供
project_dir,則使用該目錄;若提供html_scene_path,則從中建立一個暫存專案;若兩者皆未提供,則立即失敗。 - 依序執行預渲染閘門序列:
lint → validate → inspect → render(若任何步驟回傳非零值則中止)。 - 執行
cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>;收集輸出路徑。 - 確認 MP4 檔案存在且非空;回報輸出路徑以及任何
inspect警告。 - 請參閱下方的
## 呼叫模式區段以取得權威的執行步驟。
啟用
無專用斜線命令——此技能沒有對應的 /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_path | string(可選) | 單一 HTML 檔案的絕對路徑。橋接器透過 mktemp -d -t hf-XXXXXX(POSIX 可攜式)建立一個暫存的 hyperframes 專案目錄,將 HTML 寫入為 index.html,進行渲染,然後在報告寫入後進行清理。 |
project_dir | string(可選) | 既有 hyperframes 專案目錄的絕對路徑(包含 index.html,以及可選的 compositions/、assets/)。橋接器直接 cd 到其中——不進行脚手架搭建。支援子合成、音訊和外部資產。 |
若同時提供兩者,project_dir 優先。若兩者皆未提供,則立即失敗。
呼叫模式
-
驗證外部儲存庫——需要兩項檢查:
# 檢查 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"若任一項檢查失敗,則快速失敗。請勿繼續。
-
解析專案目錄。
- 若提供
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" - 否則:立即失敗。
- 若提供
-
執行預渲染閘門序列:
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(一種開發者迴圈的基本功能)。
- 渲染。 從解析後的專案目錄內部執行:
根據需要加入其他旗標(cd "$HF_PROJ_DIR" npx hyperframes render --output <abs-mp4-path>--fps、--quality、--format、--hdr等)——請參閱 TECH-hyperframes-cli-render。
[TECH-hyperframes-cli-render.md] 功能說明 · 使用時機 · 運作方式 · 旗標 · 品質指引 · 透明影片 · 最小範例 · 工作者調整 · 注意事項 · 交叉參考
- 將 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。需要兩個強制輸出:
- 成品——hyperframes 專案資料夾 + 渲染完成的 MP4。路徑從專案推斷(使用者路徑 → 框架慣例 →
./design/<subtype>/→ 備用方案./design/videos/)。 - 工作完成報告位於
$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 屬性解析錯誤、影片編碼失敗、過時的複製。