wangjs-jacky 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 环境问题被调用并解决后，把结论按上述分层写回，注明日期