Communitygithub.com

ngocsangyem/reporeaper

包裝 HeyGen HyperFrames CLI,提供以 HTML 為主的程式化影片生成。適用於短直式/社交影片、產品發布短片、以及由 HTML 組合生成的動態圖形。另請參閱已安裝的 remotion 技能以獲得基於 React 的替代方案。

reporeaper 是什麼?

此技能包裝了 HeyGen 的 [`hyperframes`](https://github.com/heygen-com/hyperframes) CLI,讓開發者能以 HTML 為主要方式程式化生成影片。它非常適合製作 1080×1920 (9:16) 的短直式社交影片、產品發布宣傳片,以及透過 HTML 組合創作的動態圖形,而無需使用 React 組件或時間軸編輯器。支援多種平台,包括任何支援 Node.js 22+ 和 FFmpeg 的環境;可選擇設定 `HEYGEN_API_KEY` 以啟用雲端渲染。其工作流程遵循 `init → edit → preview → lint → render` 的標準循環,並強制使用固定版本的 CLI (`[email protected]`) 以確保穩定性。此技能本身僅為文件與包裝,不包含 HeyGen 的原始碼或代理技能,而是引用超框架的官方文件和其他已安裝技能(如 `ak-remotion`、`ak-html-video`)來處理不同場景。每次渲染前都必須執行 lint 步驟,以捕捉 `data-start` 或 `data-composition-id` 屬性錯誤,減少渲染失敗機率。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ngocsangyem/reporeaper/tree/HEAD/.claude/skills/ak-hyperframes

在你喜歡的 AI 中提問

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

說明文件

ak:hyperframes

包裝 HeyGen 的 hyperframes CLI, 用於以 HTML 為主的程式化影片生成。此技能僅作為文件與包裝, 不包含 HeyGen 的原始碼,也不複製 HeyGen 的代理技能。以下所有指令 皆透過 npx 執行已發布的 npm 套件,並鎖定在已知穩定的版本。

使用時機

  • 由 HTML/CSS 生成的短直式/社交影片(1080×1920,9:16)。
  • 產品發布短片、促銷循環、以 HTML 組合而非 React 組件或時間軸編輯器創作的動態圖形。
  • 任何以 data-composition-id / data-start 時間屬性為組成來源真相的任務(請參閱 references/composition-basics.md)。

不適用於以 React 為主的組合、幀精確的插值曲線、或 Remotion 的音訊/字幕生態系統 ——請參閱已安裝的 remotion 技能以獲得該替代方案(基於 React 的程式化影片)。 不適用於純 FFmpeg/ImageMagick 編碼任務——請參閱 ak-media-processing 技能。

先決條件

  • Node.js 22+
  • FFmpeg 安裝於 PATH
  • 可選:一個 HeyGen 雲端/函式 API 金鑰 (HEYGEN_API_KEY) 用於遠端 渲染;本地渲染無需此金鑰。

開始任何渲染工作前,請執行內建的驗證器:

node scripts/verify-prereqs.mjs
# 或用於機器可讀輸出:
node scripts/verify-prereqs.mjs --json

請參閱 references/env-and-deps.md 以取得各平台的安裝說明及固定版本的驗證備註。

固定 CLI 版本

以下每個呼叫都鎖定 [email protected]——截至 2026-08-07 的最新發布版本 (npm view hyperframes version)。升級時請在一個地方(此檔案 + references/render-workflow.md) 更新此固定版本;請勿在腳本或文件中使用未固定版本的 npx -y hyperframes ...。

工作流程

標準循環為 init → edit HTML → preview → lint → render。每個階段的具體 指令請參閱 references/render-workflow.md;簡要形式如下:

# 1. 建立一個新的組合專案。
npx -y [email protected] init my-composition --resolution portrait

# 2. 編輯生成的 HTML 組合(請參閱 composition-basics.md 了解
#    data-composition-id / data-start / data-width / data-height 合約)。

# 3. 在本地開發伺服器中預覽。
npx -y [email protected] preview my-composition

# 4. 在渲染前檢查組合(捕捉格式錯誤的時間屬性)。
npx -y [email protected] lint my-composition

# 5. 渲染為 MP4。
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4

務必在 render 前先執行 lint——通過 lint 檢查的組合發生渲染失敗的機率遠低於跳過 lint 直接渲染的組合。

組合合約

HyperFrames 組合是普通的 HTML 檔案,透過根元素上的 data-composition-id、data-start、data-width 和 data-height 屬性進行標註。請參閱 references/composition-basics.md 以取得完整的屬性參考及完整的垂直 1080×1920 範例。

參考資料

故障排除

症狀操作
command not found: ffmpeg執行 node scripts/verify-prereqs.mjs 以取得針對您平台的確切修正方式。
npx hyperframes 回報未知的旗標此檔案中的固定版本可能落後於上游;請先執行 npx -y [email protected] --help 確認目前的旗標,再更新固定版本。
render 失敗並產生空白/短 MP4先執行 lint;大多數渲染失敗是由 lint 可捕捉的格式錯誤 data-start/data-composition-id 屬性所導致。
需要遠端/雲端渲染依照 references/env-and-deps.md 設定 HEYGEN_API_KEY,然後使用 hyperframes cloud render(一個獨立的最上層指令,不是 render 的旗標)——請參閱 references/render-workflow.md。

另請參閱

  • 已安裝的 remotion 技能(ak-remotion)— 基於 React 的程式化影片生成;當組合自然是一個 React 組件樹而非 HTML 標記時使用。
  • ak-html-video 技能 — 另一個 HTML 轉 MP4 的包裝器(nexu-io/html-video),擁有自己的模板/Studio 工作流程;當任務明確是 HeyGen HyperFrames 組合時,請使用 ak-hyperframes。
  • ak-motion-graphics 技能 — 用於路由所有儲存庫內的影片/動態技能以及外部動態技能套件的路由器。

相關技能