1实现原理 · 为什么它能做到
设计取向是「设计主导的短片」（motion is the message），因此流程被设为自主模式：最多一个澄清问题（导演的第 1 部分），然后一路构建到验证，中途不设评审；只有渲染仍是用户门禁。
skills/motion-graphics/SKILL.md
This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review.
注：这里在做什么：与 product-launch-video / faceless-explainer（多门禁、多评审）相反，短片场景下开故事板与陪跑会话被判定为收益不足，于是把评审压到只剩「预览还是渲染」这一个问题。
资产优先（asset-first）：先决定资产策略并取回真实素材，再围绕「手上有什么」设计镜头，最后才复用目录能力组装；纯代码/文字类分类则完全跳过取材步。
skills/motion-graphics/SKILL.md
**Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities.
注：这里在做什么：把「先设计再找素材」的常见失败顺序反过来。阶段表明确标注 `source ◇` 只在该分类声明了资产时运行（'Pure code/text categories (e.g. `kinetic-type`, most `charts`/`stat`) have `asset_needs: []` and skip straight from plan to design'）。
分类由「要不要搜索」这一问先分叉：形式类（kinetic-type / stat / charts / logo-reveal / lower-thirds / maps）内容由用户提供；搜索类（webpage / news / tweet / asset-fusion）先搜再按返回内容类型决定动画。
skills/motion-graphics/SKILL.md
`plan`'s **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**.
注：这里在做什么：每个分类是一个 `categories/<id>/module.md`（规划 + 构建规则），共享词表在 references/motion-vocabulary.md。设计注记里写明扩展方式：丢一个文件夹 + 在 director.md 注册分类行 + 在 catalog-map.md 加一行，阶段流水线不动。
构建遵循「复用优先」：先 `npx hyperframes add <block>` 取目录积木再就地改造，只有缺口与 asset-fusion 的表现手法才手写。
skills/motion-graphics/SKILL.md
**Reuse-first**: `npx hyperframes add <block>` + customize in place; hand-author only gaps + the asset-fusion affordance. Output `compositions/index.html` honoring the HF contract (paused GSAP timeline on `window.__timelines`, `class="clip"` + stable ids, `tl.seek(0)`, deterministic).
注：这里在做什么：把「LLM 生成模板」换成「组合官方积木 + 规则」，等价于 Remotion 生态里的模板；产出仍须满足 HF 的暂停 GSAP 时间线 + clip 类 + 确定性契约。
坐标不靠模型估计，而是走 locate 协议：先用网格条带做离散选择（比直接回归像素坐标可靠得多），只在环境里恰好有强检测器 key 时才走一次调用的 auto 路径。
skills/motion-graphics/grounding/PROTOCOL.md
Author models are unreliable at **regressing pixel coordinates** on a cluttered full image (measured: weak vision models ~16–24% center error → rings land off-target) but reliable at **picking a numbered strip** (~3–4% with the loop below). So: never eyeball coordinates; localize by discrete choice.
注：这里在做什么：把「视觉定位」做成确定性流程：overlay（9×9 条带）→ region（细分 6×6）→ final → mark（画红框并**读图验证**），并要求失败时按已知方向重试而不是猜坐标。auto 路径的守卫写在同段：'**Never assume the key exists.** No key → path 2.'
地图类的底图必须在无头 Chrome 里「烤」成 MP4：不是为平滑，而是因为 HF 禁止渲染期联网且要求确定性输出——在线瓦片每次渲染都会变。
skills/motion-graphics/categories/maps/bake-basemap.mjs
// Why bake the imagery at all (this is the real reason, not "smoothness"): HF forbids render-time // network and requires deterministic output. Live raster tiles re-fetch every render and can change // → non-deterministic. Baking FREEZES the imagery into pixels = deterministic + offline-reproducible.
注：这里在做什么：脚本用 puppeteer-core 驱动 MapLibre 录屏（camera zoom→hold）成帧序列，并把请求国家的边界投影成屏幕坐标导出 coords.json；边界/填色/标签留给 HF 里的**实时 SVG** 层，保持可编辑。全部参数由 env 驱动（NAME/STYLE/CENTER/ZSTART/ZEND/FPS/DUR/COUNTRIES），Chrome 路径动态解析（CHROME → puppeteer 缓存 → 常见系统路径）。
验证段要求挑「开场态、招牌动作、末帧保持」三个证明时刻，人工看接触表；失败只派一次就地修复（finalize 子代理），且禁止用改时长掩盖缺陷。
skills/motion-graphics/SKILL.md
Choose proof times that show the opening state, signature move, and final hold. Inspect the generated contact or snapshot sheet before continuing. On `lint`, `check`, or snapshot failure, dispatch the repair subagent (`agents/finalize.md`) for one in-place fix pass, then rerun the failed gate. Never change a fixed duration merely to hide a defect.
注：这里在做什么：把「修一次就够」和「不许靠调时长掩盖」写成规则，并配有 Resume 表（无 shot-plan.json → 回到 plan；有 asset_needs 无 assets/ → 回到 source；有 index.html 无快照 → 回到 verify…），支持中断续做。
2核心能力
01动能排版 / 单数字统计 / 图表数据可视化 / logo 演绎与品牌锁定 / 下三分之一与社交贴片
02动画地图（矢量车道 或 烘焙底图车道；高亮区域、连线地点、缩放至某地）
03搜索驱动类：网页/UI 动画（滚动、揭示、光标、标注）、新闻标题卡、推文卡、以及把真实图片的几何融进图表（asset-fusion）
04坐标定位协议（网格条带离散选择 + 可选检测器快路径 + 画框自检）
05底图烘焙（MapLibre + 无头 Chrome → 帧序列 + 国家边界屏幕坐标）
06MP4 或透明叠加层输出（webm/mov），并交出证明时刻与接触表
07中断续做（Resume 表按磁盘状态续跑）与分类扩展（新增 module.md + 注册两行）
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | hyperframes CLI（init / doctor / add / lint / check / snapshot / preview / render / skills update） |
| cli | ffmpeg / ffprobe（探帧率与时长、抽帧、编码） |
| api | Google Generative Language API（可选的视觉检测快路径，仅在环境存在 key 时使用） |
| api | 可选图像生成 key（media-use resolve 的生成分支；未设置则只搜索或不生成） |
| network | 底图瓦片与矢量数据（仅在 maps 分类烘焙底图时联网；烘焙后离线可复现） |
| package | puppeteer-core + 无头 Chrome（底图烘焙录制） |
| network | GSAP CDN（示例资产 _ref-circle-highlight.html 引用） |
| package | 兄弟 skill 依赖（/media-use 的 resolve 与 search 提供者、/hyperframes-animation 的 rules/blueprints、/hyperframes-core 的 brief-contract、/figma） |
4风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- 读环境凭证并拼进 URL 查询串 — locate.mjs 把 GEMINI_API_KEY 直接拼到 `?key=` 上调用 Google API（仅 auto 子命令）。虽然 guard 完善（无 key 即走本地网格循环），但使用该快路径意味着把画面内容（base64 图）发往 Google，且密钥出现在 URL 中（可能进入代理/日志）。
- 第三方远程代码在无头浏览器内执行 — maps 烘焙页会从 jsdelivr 加载 maplibre-gl/topojson-client/world-atlas 并在 Chrome 里执行；虽局限在浏览器沙箱，但属于把远端 JS 引入本机执行环境，供应面与离线复现都需留意（烘焙产物可离线复现，烘焙过程不能）。
- 第三方素材搜索提供者（SerpAPI/Google Images/Noun Project）带来版权与合规不确定 — guide.md 要求 review（use/maybe/reject）并冻结到本地 + 记台账，但没有授权校验机制；商用前需自行确认素材许可，特别是 image/news/tweet 类。
- 平台的硬前提：仅 macOS Apple Silicon 或 Linux x64 — Prerequisites 明写平台与系统工具要求，且 macOS 上建议 `PRODUCER_BROWSER_GPU_MODE=hardware`（否则软件渲染可能超时）。Windows 或低配环境不在支持面内。
- Step 2 示意命令不可直接运行 — phases/source/resolve.mjs 未随包分发（只有 guide.md），照抄 SKILL.md Step 2 的命令会失败；实际取材需由 /media-use 的 resolve 流程驱动（见 second_pass 的 discrepancy 条）。
- 视觉准确率依赖模型读图能力 — 网格循环虽然把坐标选择离散化，但仍要求每个阶段『读图判断条带』；弱视觉模型下条带判读错误会级联放大，协议只能靠 mark 回读做一次纠错。
风险提醒：橙色，评估后使用。触发橙档的两条都成立：① **凭证/环境变量读取**——grounding/locate.mjs 直接读 process.env.GEMINI_API_KEY 并把密钥拼进 URL 查询串去调 generativelanguage.googleapis.com（`?key=${key}`），SKILL.md 也把 GEMINI_API_KEY/GOOGLE_API_KEY 列为可选能力键；② **第三方远程包与镜像**——maps 分类会在无头 Chrome 里加载 jsdelivr 的 maplibre-gl/topojson-client/world-atlas，并从 ArcGIS（arcgisonline.com）与 CartoCDN 拉瓦片；素材来源还依赖第三方搜索提供者（SerpAPI/Google Images/Noun Project）。行为均属能力设计（地图要底图、定位要检测器），且都给了降级路径（无 key 走网格循环、无搜索能力退化为无资产），未发现 TLS 降级、反爬绕过或本地任意代码执行面（子进程调用的都是固定二进制与随包脚本）。
5第二遍独立确认
- [ok] GEMINI_API_KEY 是否真的被读取并外发（橙档判定的关键证据） — locate.mjs:192 `const key = process.env.GEMINI_API_KEY;`；紧接着 key 缺失即报错退出（'auto needs GEMINI_API_KEY; use the grid loop instead (overlay→region→final→mark)'）；存在时把 base64 图像与目标描述 POST 到 generativelanguage.googleapis.com（`?key=${key}`）。调用点真实存在，且仅在 `auto` 子命令触发。
- [ok] 『不假设有检测器』的守卫是否真的生效（避免第一遍误判为『总是联网』） — PROTOCOL.md 明写 '**Never assume the key exists.** No key → path 2.'，且把网格循环列为『the normal case』；SKILL.md 的可选键表也把 GEMINI_API_KEY 标为 optional 并给出 fallback（skip generate / search-only）。因此网络外发是有条件、可预期的，而非默认路径。
- [discrepancy] Step 2 引用的 resolve.mjs 是否随包分发 — SKILL.md Step 2 给出 `(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)`，但 **phases/source/ 下只有 guide.md，没有 resolve.mjs**（全量文件清单已确认）。guide.md 末尾也标了 '> Illustrative: … — or drive media-use's `resolve` procedure directly.'。结论：该命令是示意而非可执行入口，实际取材须由 /media-use 的 resolve 流程驱动；SKILL.md 自身有 'illustrative' 标注，故不算虚假声明，但读者若照抄命令会直接失败——这是对 pin commit 有效的真实出入。
- [ok] 底图烘焙是否真是本地行为而非渲染期联网 — bake-basemap.mjs 头注释与实现一致：在无头 Chrome 内加载 MapLibre + 瓦片，录帧到 frames-<NAME>/，导出 coords.json；SKILL.md 只在该分类下引用它。渲染期（hyperframes render）不触发任何取瓦片行为，符合 HF 的『渲染期禁网』契约——这也是文档给出的烘焙理由，自洽。
- [ok] 『外部资源』逐条回查调用点 — hyperframes init/doctor/add/lint/check/snapshot/preview/render 均在 SKILL.md 出现；ffmpeg/ffprobe 在 locate.mjs 与 bake-basemap.mjs 的 execFileSync/spawnSync 可验；瓦片 URL 与 CDN 在 bake-basemap.mjs:106-119 与 :153 原文；gsap CDN 在 samples HTML 原文；media-use resolve 在 guide.md 原文。
- [unlocatable] 验证：视觉定位协议的准确率声明是否可在源码内定位 — PROTOCOL.md 给出的误差数字（弱模型 16–24%、网格循环 3–4%、'eyeballing 6.5% → this protocol 2.3%'）引用的是一项测量结论，源码内无复现脚本或数据文件；本次为只读侦查且不得运行构建/渲染，故不验证这些数值，仅作为『文档声明』记录，不在结论中当作已核事实使用。
6结论
适合：适合要做单条短动效（通常 10 秒内、最多约 30 秒）、无旁白无实拍主体的场景：动能排版标题、数字/统计冲击、图表数据可视化、logo 演绎与品牌锁定、下三分之一/标注/社交贴片、动画地图、推文/新闻标题卡、网页/UI 演示动画，以及把真实图片几何融进图表的 asset-fusion；也可输出透明叠加层（webm/mov）供后期合成。适合愿意让流程自动跑完（最多一个问题）但要自己决定是否渲染的用户。
不适合：不适合：① 长于约 30 秒、有旁白或多场景的作品——应走 /general-video（description 点名）；② 需要实拍/人物出镜的视频；③ 纯字幕需求（应走 /embedded-captions 或 talking-head-recut 系列）；④ Windows 或非 x64 环境（Prerequisites 明确限定平台）；⑤ 完全离线且无搜索能力的环境——搜索类分类会退化为「无资产」，asset-fusion 类基本不可用；⑥ 不愿把图像发往 Google 的用户（应避免 locate 的 auto 路径，只用本地网格循环）；⑦ 需要严格版权溯源保证的商用素材场景——台账只记来源，不校验许可。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 motion-graphics.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent7966ceeccd29cbdd…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库heygen-com / heygen-com/hyperframes
原始 GitHubheygen-com/hyperframes ↗
Stars44283
最近推送2026-09-06
本 skill commit
b8328f9573许可Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；池内值亦为 Apache-2.0）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。