HyperFrames Ops
回答環境類問題前，先讀同目錄的 experience.local.md 取得本機最新事實（代理命令、版本快照、歷史 QA）。
零、為什麼需要獨立 Ops 層
第三方 Skills 往往只描述通用能力，無法預知每台機器的網路、代理、Node/FFmpeg 版本、字體快取、登入態和工具組合。直接修改官方 Skill 會導致更新衝突，也會把本機事實混入上游通用說明。
因此把兩層分開：
- 官方 Skills 是能力源，保持可更新、可替換。
hyperframes-ops是本機適配層，記錄最佳實踐、相容性差異、失敗模式和經驗證的繞法。- 遇到創作問題先讀官方 Skill；遇到環境、組合、版本或本機適配問題再讀本 Skill。
- 上游更新使舊經驗失效時，在本地經驗中標記失效並重新驗證，不用舊經驗覆蓋新行為。
一、專案身份（泛化事實）
- HyperFrames 是 HeyGen 官方開源專案：
github.com/heygen-com/hyperframes，npm 包名hyperframes - 定位：用 HTML 寫影片合成、經 headless Chrome 渲染成 mp4 的 CLI（
npx hyperframes） - 環境要求：Node.js >= 22、FFmpeg
二、官方 skills 分發機制
- 官方 skills 隨 CLI 同倉維護、版本化分發，manifest 位於倉庫根：
https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json - 組成：核心集（hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes）+ 工作流集（general-video、slideshow、motion-graphics、music-to-video、pr-to-video、product-launch-video、website-to-video、faceless-explainer、talking-head-recut、embedded-captions、media-use、figma）。以
skills check實際輸出為準 - 管理命令：
npx hyperframes skills check—— 對照 manifest 檢查版本npx hyperframes skills update—— 更新全部已裝 + 清理官方已下架的npx hyperframes init—— 強制同步 skills 到最新（--skip-skills目前被官方禁用）
- 安裝位置：全域
~/.claude/skills/（CLI 自動識別 claude-code） - 命名安全：
skills update的清理邏輯基於 lock 檔案按「來源歸屬」判定，只刪除源於官方倉庫且已下架的 skill。本 skill 雖以hyperframes-開頭，但不在官方 lock 歸屬內，不會被官方更新器誤刪
三、排障路由
| 症狀 | 路由 |
|---|---|
skills check/update/init 拋 AbortError（fetchManifest 超時） | 網路問題：CLI 用 Node 內建 fetch 訪問 raw.githubusercontent.com，直連不通時必須走代理。讀 experience.local.md 拿本機一步到位命令 |
npx hyperframes 其他網路類失敗 | 同上；注意 Node 內建 fetch（undici）預設不讀 HTTP_PROXY 環境變數，Node 24+ 需加 NODE_USE_ENV_PROXY=1（或 --use-env-proxy） |
| 渲染/預覽環境異常 | npx hyperframes doctor、npx hyperframes browser 自檢；確認 Node >= 22、FFmpeg 可用 |
| skill 行為像舊版 | skills check 看版本落差，skills update 拉齊 |
heygen auth login --oauth token 交換失敗（api2.heygen.com connection refused）或曲庫呼叫超時 | heygen CLI 是 Go 程式，認 HTTP(S)_PROXY 環境變數（與 Node fetch 相反，無需額外開關）；受限網路下所有 heygen 命令都要帶代理。OAuth 回調服務只活 5 分鐘且需互動式 shell（背景/nohup 拉起會因收不到回調而超時）。本機命令見 experience.local.md |
| 渲染出來字體不對（標題變寬、溢出容器，lint/inspect 卻全綠） | 內建 18 字體是執行時按需網路拉取（@fontsource → ~/.cache/hyperframes/fonts），拉取失敗靜默回退系統字體。受限網路方案：woff2 下到專案內顯式 @font-face 自託管 |
| 創作類問題（怎麼寫合成、動畫、渲染參數） | 不歸本 skill 管，走官方 hyperframes 入口 skill 的路由表 |
四、經驗寫回協議
- 寫 experience.local.md（本機私有，已被本目錄 .gitignore 忽略）：新踩的坑及驗證過的解法、版本/安裝狀態快照（帶日期）、本機專屬命令、代理與網路事實、歷史 QA
- 寫回本 SKILL.md（進 git、可分享）：官方機制變化（分發方式、命令語義、清理邏輯）、新的泛化排障路由
- 判斷標準：換一台機器仍然成立的 → SKILL.md；只對這台機器成立的 → experience.local.md
- 每次因 HyperFrames 環境問題被呼叫並解決後，把結論按上述分層寫回，註明日期