Hyperframes 教學手冊
HyperFrames 教學手冊 ⚠️ 版本快照提醒: 本手冊內容係於 2026-07-21 查證撰寫,主要依據 HyperFrames 官方 GitHub Repository(github.com/heygen-com/hyperframes)、官方文件站(hyperframes.heygen.com)、README.md、AGENTS.md、CONTRIBUTING.md、SECURITY.md、CLI Reference、GSAP Integration Guide、AWS Lambda Deploy Guide、Troubleshooting Guide 等第一手來源整理而成。HyperFrames 是一個仍在快速迭代(0.x 版本)的開源專案,CLI flag、Skill 數量、套件結構皆可能隨版本演進而變動,實作前請務必以 npx hyperframes --help、npx hyperframes doctor 與官方文件站最新內容為準。 本手冊不是官方文件的翻譯本。全書所有章節皆經過重新消化整理,並大量加入企業導入視角的架構分析、實務踩雷經驗、最佳實務與 AI Agent 協作建議——這些內容多數不會出現在官方文件中,而是撰寫團隊依據 HTML/影片渲染架構的一般工程常識、與其他無頭瀏覽器渲染系統(如 Puppeteer/Playwright 自動化測試、CI 影片生成管線)的實務經驗類比而來,並會在文中以「實務建議」「踩雷經驗」「企業導入提醒」等字樣明確標示,與官方原文(以引號或「官方文件指出」標註)做區隔,避免讀者誤將顧問建議當成官方保證。 主要參考來源: GitHub:github.com/heygen-com/hyperframes(README、AGENTS.md、CONTRIBUTING.md、SECURITY.md、DESIGN.md、skills/目錄下全部 19 個 Skill、packages/目錄下全部套件、CHANGELOG/Releases) 官方文件站:hyperframes.heygen.com(introduction、quickstart、changelog、guides/gsap-animation、guides/hyperframes-vs-remotion、guides/claude-design、guides/troubleshooting、packages/core、packages/cli、deploy/aws-lambda、deploy/gcp-cloud-run、examples、catalog) 社群playground:hyperframes.dev 本次(2026-07-21)更新已重新查證上述來源之現況,修正若干先前版本的命名誤差(如第六章 Adapter 命名)、CI/雲端渲染新功能(見第十章、第十四章、第三十二章),並補強目錄的章節/小節雙層連結(見下方目錄)。 目錄 使用建議 前言 是什麼 發展背景與解決的問題 與其他影片框架的差異(初覽,完整比較見第四十章) 適合哪些人/不適合哪些人 典型使用情境 第一章 HyperFrames 深度導論 1.1 三大受眾定位再展開 1.2 典型案例深探:從一支 Landing Page 到一支社群影片 第二章 整體系統架構 2.1 分層架構總覽 2.2 資料流與控制流 2.3 Component Diagram:套件依賴關係 第三章 HyperFrames 工作流程 3.1 六步驟完整渲染流程 3.2 HTML → Animation → Frame → Capture → Encode → MP4 各階段細節 第四章 Rendering Engine 4.1 Deterministic Rendering 的技術本質 4.2 Frame Timeline 與 Seek 機制 4.3 Timing / FPS / Resolution / Color / Codec / Quality 全解析 4.4 Color 與 Codec 的取捨建議 第五章 HTML Render Pipeline 5.1 DOM/CSS/JS 三層如何被渲染引擎消費 5.2 Canvas/SVG/WebGL/Three.js 5.3 Video/Audio/Image/Font 的渲染考量 第六章 Animation Adapter 完整解析 6.1 CSS Animation / CSS Transition 6.2 Web Animations API(WAAPI) 6.3 GSAP(官方最推薦) 6.4 Anime.js 6.5 Lottie 6.6 Three.js 6.7 TypeGPU/WebGPU(GPU 加速圖形,官方 Adapter) 6.8 手刻 Canvas 2D 程式化繪圖(技巧,非官方具名 Adapter) 6.9 SVG Animation Animation Adapter 選型總表 第七章 Skill System 7.1 什麼是 HyperFrames Skill 7.2 Router 決策邏輯詳解 7.3 AI 如何呼叫 HyperFrames Skill 7.4 Skill 版本維護協定(一個容易被忽略但很重要的細節) 第八章 AI Agent 整合總覽 8.1 為什麼 HyperFrames 特別強調 Agent 整合 8.2 各 AI 工具整合方式速覽 8.3 AI Agent 建立影片的標準迴圈 8.4 修改影片、重構動畫、自動生成 HTML 的差異 第九章 安裝與環境建置 9.1 系統需求總表 9.2 Windows 安裝流程 9.3 macOS 安裝流程 9.4 Linux(Ubuntu/Debian)安裝流程 9.5 WSL(Windows Subsystem for Linux)注意事項 9.6 Docker 安裝與 --docker 渲染模式 9.7 Podman 安裝與相容性 9.8 Chrome / FFmpeg 手動排除疑難 第十章 CLI 完整參考 10.1 專案建立類 10.2 預覽與發布類 10.3 驗證類 10.4 建置類 10.5 工具類 10.6 認證與雲端渲染類 10.7 完整環境變數表 第十一章 Configuration 完整設定 11.1 設定來源優先順序 11.2 Composition Variables(JSON 參數化) 11.3 JSON 設定範例:一個完整的 meta.json 11.4 YAML/CI 設定範例 第十二章 HTML Structure 12.1 Composition 根節點完整屬性表 12.2 Clip(時間軸元素)屬性表 12.3 Scene(場景)與 Layer(圖層)的組織方式 12.4 完整範例:一個帶有兩個場景的 Composition 第十三章 Animation 實戰 13.1 Timeline 與 Keyframe 混合實戰:一個 10 秒產品介紹片段 13.2 Keyframe 進階技巧:多段 Easing 交錯 13.3 CSS 與 GSAP 混用時的注意事項 第十四章 Media 處理 14.1 Image 14.2 Video 14.3 Audio 14.4 SVG 14.5 Canvas/GPU 圖形 14.6 Font 第十五章 FFmpeg 編碼與最佳化 15.1 FFmpeg 在整體渲染流程中的角色 15.2 容器格式與適用場合 15.3 Codec 參數調校 15.4 AV1 的取捨 15.5 GPU 加速編碼 第十六章 Browser 引擎 16.1 Headless Chrome 作為渲染核心 16.2 CDP(Chrome DevTools Protocol)的角色 16.3 Playwright/Puppeteer 與 HyperFrames 的關係 16.4 瀏覽器 GPU 加速 第十七章 API 參考 17.1 @hyperframes/core 總覽 17.2 核心型別 17.3 解析與 HTML 生成函式 17.4 GSAP 工具函式 17.5 Linter API 17.6 Compiler(Node.js 專用) 17.7 Runtime 與 Frame Adapter 17.8 媒體與樣式常數 17.9 實戰範例:Node.js 批次個人化渲染腳本 第十八章 專案目錄結構 18.1 官方 Monorepo 套件總覽 18.2 一般專案(hyperframes init 產出)的目錄結構 18.3 企業內部建議的擴充目錄慣例 第十九章 Examples 官方範例解析 19.1 官方九大範例模板總覽 19.2 手把手 Walkthrough:以 warm-grain 為基礎客製化一支 15 秒品牌影片 19.3 Catalog Block 範例:data-chart 第二十章 與 Claude Code 整合實戰 20.1 完整流程總覽 20.2 安裝與初始化 20.3 Claude Design 使用建議 20.4 Claude Code 內的典型 Prompt 範例 20.5 Workflow:Claude Code 內的分工模式 第二十一章 與 GitHub Copilot 整合實戰 21.1 現況:官方 Skill 系統尚未原生涵蓋 Copilot 21.2 補強做法:建立專案層級指引文件 21.3 Copilot Chat 實戰 Prompt 範例 21.4 Copilot CLI(gh copilot)搭配 HyperFrames CLI 第二十二章 與 Gemini CLI 整合實戰 22.1 安裝與初始化 22.2 完整流程 22.3 Gemini CLI 實戰 Prompt 範例 第二十三章 與 Cursor 整合實戰 23.1 安裝方式 23.2 Cursor Composer/Chat 實戰範例 23.3 Cursor 與 Claude Code 的分工建議 第二十四章 HyperFrames 協助 AI Agent 開發大型 Web Application 24.1 核心洞察:為什麼影片能加速大型系統開發? 24.2 Vue 3 升級情境 24.3 Angular/React 升級情境 24.4 Spring Boot/Java 升級情境 24.5 Legacy System Modernization 與 Reverse Engineering 24.6 Framework Migration 與 Architecture Documentation 通用模式 第二十五章 企業影片自動化情境 25.1 API 文件影片 25.2 Architecture Demo(見 24.6 完整流程) 25.3 Training Video/教育訓練影片 25.4 CI/CD Demo 25.5 Release Note Video 25.6 系統操作影片 25.7 產品展示影片 25.8 AI 自動生成影片的品質守門機制 第二十六章 CI/CD 自動化 26.1 標準自動化渲染管線設計 26.2 GitHub Actions 完整範例 26.3 GitLab CI 完整範例 26.4 Azure DevOps Pipeline 範例 26.5 Jenkins Declarative Pipeline 範例 第二十七章 Docker 容器化部署 27.1 官方 --docker 模式 vs 自建映像檔 27.2 Dockerfile 範例 27.3 docker-compose.yml 範例:本機開發 + 渲染服務 第二十八章 Kubernetes 部署 28.1 部署模式選型 28.2 一次性渲染 Job 範例 28.3 定期批次渲染 CronJob 範例 28.4 常駐 Studio 預覽服務範例(Deployment + Service) 28.5 其他實務缺口:GPU 排程、Helm、私有 Registry、Pod Security(實務延伸) 第二十九章 Podman 部署 29.1 Podman 與 Docker 的核心差異回顧 29.2 使用 Podman 建置與執行 29.3 Podman Compose 範例 29.4 Podman + systemd(Quadlet)常駐服務範例 第三十章 Enterprise Best Practices 30.1 大型企業導入 HyperFrames 的階段性路徑 30.2 版本管理建議 30.3 資源管理 30.4 Media 管理 30.5 Template 管理 第三十一章 系統維護與升級 31.1 日常維護檢查清單 31.2 升級流程 31.3 如何避免 Breaking Change 造成的衝擊 31.4 Migration Guide:從 Remotion 遷移 第三十二章 Troubleshooting 32.1 環境與安裝類(1–8) 32.2 媒體與編碼類(9–15,第 9 題為官方,其餘為實務延伸) 32.3 動畫與 GSAP 類(16–24,全為實務延伸) 32.4 渲染與效能類(25–33,全為實務延伸) 32.5 CI/CD 與雲端類(34–40,全為實務延伸) 32.6 Skill/AI Agent 協作類(41–50,全為實務延伸) 第三十三章 Performance Tuning 33.1 效能瓶頸的四大來源 33.2 Chrome 層級調校 33.3 Animation 層級調校 33.4 Memory 管理 33.5 GPU 使用建議 33.6 FFmpeg 編碼調校(回顧第十五章並延伸) 第三十四章 Security 34.1 官方安全政策(Vulnerability Disclosure) 34.2 Headless Chrome 沙箱化建議(實務延伸) 34.3 憑證與 API 金鑰管理 34.4 素材與內容審核 34.5 網路層面建議 第三十五章 Logging 與 Monitoring 35.1 CLI 內建的可觀測性能力 35.2 建議監控的關鍵指標 35.3 日誌整合範例(概念示意) 35.4 建立渲染健康度儀表板 第三十六章 最佳實務總彙 36.1 架構與設計(1–10) 36.2 HTML/Composition 撰寫(11–20) 36.3 動畫實作(21–30) 36.4 媒體與素材(31–38) 36.5 CLI 與開發流程(39–48) 36.6 AI Agent 協作(49–58) 36.7 CI/CD(59–66) 36.8 容器化與部署(67–74) 36.9 效能調校(75–82) 36.10 安全(83–90) 36.11 企業治理(91–96) 36.12 團隊協作與文件(97–102) 第三十七章 Coding Style Guide 37.1 官方套件開發慣例(若團隊貢獻或自建 HyperFrames 相關套件) 37.2 Composition 專案的程式碼風格建議(實務延伸) 37.3 Node.js/TypeScript 腳本風格(使用 @hyperframes/core 時) 第三十八章 Prompt Engineering 與完整 Prompt 範例 38.1 讓 AI 工具更容易產生正確 HyperFrames 程式碼的核心原則 38.2 各工具的 Prompt 微調建議 38.3 完整 Prompt 範例庫(50 則,依情境分類) 第三十九章 Case Study 39.1 案例一:電商千人千面促銷影片 39.2 案例二:SaaS 產品「PR 到影片」自動化 39.3 案例三:金融業 Legacy 系統知識傳承 39.4 案例四:跨國零售集團多品牌一致性治理 39.5 案例五:教育科技公司個人化課程證書 39.6 案例六:企業內訓多語系教材規模化 39.7 案例七:新創公司從 Remotion 遷移 39.8 案例八:DevOps 團隊 CI/CD 視覺化 Demo 39.9 案例九:資料視覺化團隊自動化報告影片 39.10 案例十:客服團隊操作教學影片庫 第四十章 與其他框架比較 40.1 HyperFrames vs Remotion(官方比較,詳見前言與第三十一章 31.4) 40.2 HyperFrames vs Motion Canvas 40.3 HyperFrames vs FFCreator 40.4 HyperFrames vs PptxGenJS + FFmpeg 手動管線 40.5 HyperFrames vs Reveal.js Export 40.6 HyperFrames vs Playwright / Puppeteer Screenshot 方案 第四十一章 優缺點分析與未來 Roadmap 41.1 優點總結 41.2 缺點與限制總結 41.3 SWOT 簡要分析 41.4 未來 Roadmap 推論(依官方已知限制與產業趨勢推論,非官方公開路線圖) 第四十二章 附錄 42.1 名詞解釋(Glossary) 42.2 整合總覽表 42.3 CLI 速查表(完整版見第十章) 42.4 API 速查表(完整版見第十七章) 42.5 環境變數速查(彙整自全書各章,完整版見第十章 10.7) 42.6 Mermaid 速查(本書使用過的圖型範例) 42.7 Prompt 速查(完整 50 則見第三十八章) 42.8 Migration Checklist(從其他方案遷移時使用) 42.9 Deployment Checklist(部署上線時使用) 42.10 Security Checklist(資安上線前使用) 42.11 Production Checklist(正式上線最終確認) 42.12 延伸閱讀建議 42.13 全書總 Checklist 使用建議 HyperFrames 橫跨「前端渲染」「影片後製」「CLI/DevOps」「AI Agent 協作」四個領域,不同角色的讀者不需要從頭讀到尾。下表提供建議閱讀路徑: ...