1实现原理 · 为什么它能做到
先做静态 lint 判定「能不能翻译」：脚本用规则扫 Remotion 源码，把发现分成 blocker（拒译并改荐运行时互操作）/ warning（丢掉该构造后照译，但要在 TRANSLATION_NOTES.md 记缺口）/ info（翻译并注明）三级。
skills/remotion-to-hyperframes/scripts/lint_source.py
Blockers (skill should refuse to translate): - r2hf/use-state React state machine drives animation - r2hf/use-effect-deps useEffect/useLayoutEffect with non-empty deps (side effects) - r2hf/use-reducer useReducer drives animation - r2hf/async-metadata calculateMetadata returns a Promise - r2hf/third-party-react-ui Imports a React UI library (shadcn, mui, antd, mantine, chakra)
注：这里在做什么：把「哪些 Remotion 写法在 HF 的 seek 驱动模型里无法确定性表达」前置成可执行的静态检查。blocker 命中即停，改读 references/escape-hatch.md 并给出 PR #214 的运行时互操作建议；warning 不阻断翻译。脚本本身只做文本/正则分析（import 仅 argparse/json/re/sys/dataclasses/pathlib），不执行被扫描的代码。
翻译是机械映射 + 按需加载专题参考：api-map.md 是索引，按源码里出现的 API 只加载对应专题（parameters/sequencing/timing/media/transitions/lottie/fonts），不一次全读。
skills/remotion-to-hyperframes/SKILL.md
Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model
注：这里在做什么：作者明说 ~80% 可机械翻译、20% 有损——把不确定性明确写出来，并用『拒绝 + 改荐』处理那 20%，而不是硬译出一个坏 HTML。
产出形态固定：一个 <div id="stage"> 携带 composition-id/start/duration/fps/尺寸与每个标量 prop 的 data-*，场景 div 平铺带 data-start/data-duration/data-track-index，底部一个 paused GSAP 时间线并注册到 window.__timelines。
skills/remotion-to-hyperframes/SKILL.md
A single `<script>` tag at the bottom containing one paused `gsap.timeline({paused: true})`. Every Remotion `useCurrentFrame()` derivation becomes a tween on this timeline at the right offset. - `window.__timelines["<composition-id>"] = tl;` registers the timeline with HF's runtime.
注：这里在做什么：把 React 的「每帧计算」范式换成「暂停时间线上的补间」范式——这正是无法翻译 useState/useEffect 驱动动画的根因（那些不是帧确定性的）。
验收不是「看起来对」而是可量化的 SSIM：随包四级测试语料 T1–T4 给出各家平均 SSIM 与阈值基线，并要求两侧渲染使用相同像素格式否则量到的是编码器差异。
skills/remotion-to-hyperframes/SKILL.md
Threshold: ~0.02 below `p05` of the source's complexity tier (see `eval.md`'s validated thresholds table). If the diff fails, run [`scripts/frame_strip.sh`](scripts/frame_strip.sh) to see _which_ frames diverged, then re-read the relevant timing/sequencing/media reference.
注：这里在做什么：把「翻译保真」变成可回归的指标。基线表（2026-04-27）：T1 单元素淡入 0.974/阈值 0.95、T2 多场景+spring+音频+图片 0.985/0.95、T3 数据驱动+自定义子组件+计数 0.953/0.90、T4 8 个 lint 逃逸用例 8/8 通过。同段还给出关键坑：'both renders must use matching pixel format'（不设 png + bt709 会量到 ~0.05 SSIM 的编码器差异）。
差异调试有专用工具：frame_strip.sh 生成「基准帧 | 翻译帧」并排条带图定位是哪几帧跑偏；render_diff.sh 输出逐帧 SSIM 并落 summary.json（mean/min/p05/p95/frame_count/pass）。
skills/remotion-to-hyperframes/scripts/render_diff.sh
# render_diff.sh — compute per-frame SSIM between two video files. # # The eval primitive for the remotion-to-hyperframes skill: given a Remotion # render and a HyperFrames render of the same composition, report whether the # translation is visually equivalent.
注：这里在做什么：把「看起来差不多」拆成可定位的诊断链——先 p05/mean 判失败，再用条带图看哪一帧，再回读对应专题参考（timing/sequencing/media）修。
缺口必须留痕：任何没干净翻译的东西（音量斜坡、自定义 presentation、字体替换）都要写成 HF 输出旁的 TRANSLATION_NOTES.md；并明确列出本 skill 不做什么（反向导出、非 Remotion 来源、React 状态机、与 Remotion 并行运行渲染管线）。
skills/remotion-to-hyperframes/SKILL.md
Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a `TRANSLATION_NOTES.md` written next to the HF output.
注：这里在做什么：防止「静默有损」——有损必须显式记录。同时也把『@remotion/lambda 不是 blocker（部署而非动画）』这类判定边界写明，避免误拒。
2核心能力
01Remotion → HyperFrames 的单向源码移植（明确只做这一个方向）
02可执行的可译性 lint（三级发现 + 行/列 + rule id + 建议；支持 --json）
03按 API 主题的映射索引（Composition/Sequence/Series/Loop/Freeze/useCurrentFrame/interpolate/spring/Audio/Video/Img/IFrame/staticFile/TransitionSeries/lottie/google-fonts…）
04分级测试语料 + SSIM 回归基线（T1 单元素淡入 / T2 多场景+spring+音频+图片 / T3 数据驱动+子组件 / T4 八个 lint 逃逸用例）
05差异定位工具：并排帧条带（frame_strip.sh）与逐帧 SSIM 报告（render_diff.sh，含 p05 与 pass 判定）
06自测/冒烟：脚本层不依赖真实 Remotion 或 HF 管线即可验证 harness 输出合理（用 ffmpeg testsrc 造合成输入）
07拒绝与改荐路径：blocker 命中时改荐 PR #214 的运行时互操作，而不是产出坏 HTML
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | hyperframes CLI（渲染翻译产物：npx hyperframes render --skill=remotion-to-hyperframes） |
| cli | Remotion CLI（生成基准渲染：npx remotion render <CompositionId> out/baseline.mp4） |
| cli | ffmpeg / ffprobe（SSIM 比较、帧抽取、条带拼图；脚本缺它即 exit 2） |
| cli | python3（lint_source.py 与 frame_strip.sh 内嵌的 python 片段） |
| package | HF 侧可选包（shader-transitions / lottie 适配器等，由 api-map 引用；HF 侧的 blocks 目录） |
| network | 文档外链（仅参考；fonts.md 里的 Google Fonts 预连接示例属于产出 HTML 的写法，非本 skill 调用） |
| cli | hyperframes skills update（自刷新，需网络） |
4风险提醒 风险提醒：蓝色 · 知晓即可
风险提醒：蓝色 · 知晓即可
- 翻译本身是有损操作，且度量口径可能误导 — 作者自述只有 ~80% 机型可机械翻译；SSIM 是像素相似度，对『动画意图是否正确』（时序语义、交互感）不敏感——高 SSIM 仍可能是错误的翻译（作者也承认 0.05 的差距可能来自编码器设置而非翻译质量，故强制两侧像素格式一致）。
- 门禁依赖使用者自觉执行 eval — Step 4 的 SSIM 比对需要用户在 remotion-src 里 npm install 并渲染基准、再渲染 HF 产物；本文档无法强制。若不跑 eval 直接交付，『看起来对但静默错误』正是作者警告的失败模式。
- 环境前提不轻 — 完整验收需要 Node + Remotion（含浏览器渲染依赖）、HyperFrames CLI、ffmpeg/ffprobe、python3；缺任一项则 lint 与 diff 无法闭环（脚本在缺 ffmpeg 时 exit 2）。
- 被扫描的是用户源码目录（含模型读取） — lint_source.py 会遍历给定的 .ts/.tsx 目录并输出文件名与行号（注释里还专门处理了文件名含非法 surrogate 的情况），模型也会读源码做翻译；源码中的敏感字符串/注释会进入上下文。
- 对复杂 React 组合基本无解 — useState/useReducer/带依赖的 useEffect/异步 calculateMetadata/第三方 UI 库一律拒译，只能改走运行时互操作（两套管线并存）——这意味着大量真实项目其实不在本 skill 可服务范围内。
- 示例 HTML 引用外部 CDN 的 GSAP — tier-1/2/3 的 hf-src/index.html 从 cdnjs 加载 gsap 3.12.5（与其它 skill 用的 jsdelivr 3.14.2 不同版本）；离线跑测试语料需自行替换为本地脚本。
风险提醒：蓝色，知晓即可。行为面干净且可验证：全部脚本为本地工具（python3 静态 lint + ffmpeg/ffprobe 的 SSIM 与拼图），只读写本地文件；整目录零网络调用、零凭证读取、零外部包下载（不走 pip/npm 安装）；唯二需要环境的动作是调用 ffmpeg/ffprobe 与（由使用者执行的）npx 渲染命令。不落黄色是因为没有任何外发行为；不落绿色是因为它确实执行本地脚本并对用户源码目录做读取与产物写入。注意点：被读取的是用户的 Remotion 源码目录（模型会读它以生成翻译），以及测试语料里存在 fetch 示例（仅作 lint 测试输入，不执行）。
5第二遍独立确认
- [ok] 是否真的零网络 / 零凭证（蓝档判定的关键） — 脚本层 fetch/curl/wget/http.request 0 命中；process.env 命中仅 3 处且在 tier-4 的 validate.sh 里读路径变量；无 API_KEY/TOKEN/SECRET/.env/Bearer 命中。27 处 URL 全部可解释为文档链接、示例 HTML 资源或测试夹具端点。
- [ok] 测试夹具里的 fetch / example.com 是否会被执行（是否构成隐藏外发） — 逐文件确认：tier-4 的 8 个 .tsx 与 scripts/tests/fixtures/*.tsx 只被 lint_source.py 以文本方式扫描（脚本无 subprocess/无 import 被扫描模块），run.sh 的 T4 分支只跑 lint 校验（'It runs T1, T2, T3 (render + diff) and T4 (lint validation)'）。不会被渲染或执行，因此不构成外发。
- [ok] 『外部资源』逐条回查调用点 — npx remotion render 与 npx hyperframes render 在 SKILL.md Step 4 原文；ffmpeg/ffprobe 的存在性检查与调用在 render_diff.sh/frame_strip.sh 原文；python3 调用在 frame_strip.sh 原文；shader-transitions 与 lottie 适配器链接在 api-map.md/lottie.md 原文。无推测项。
- [ok] lint 规则是否真能拦住它宣称拦的东西（blocker 是否只是文档口号） — lint_source.py 的 docstring 与 THIRD_PARTY_UI_PACKAGES 集合、rule id（r2hf/use-state、r2hf/use-effect-deps、r2hf/use-reducer、r2hf/async-metadata、r2hf/third-party-react-ui 等）在源码中真实存在，并配有 8 个 tier-4 用例与 validate.sh 断言（'8/8 pass' 基线）。规则实现与文档口径一致。
- [unlocatable] 验证：SSIM 阈值基线表是否可在源码内复算 — SKILL.md 的基线表（T1 0.974、T2 0.985、T3 0.953、T4 8/8，日期 2026-04-27）是历史测量值；复算需要执行 Remotion 与 HF 两条渲染管线（本任务禁止构建/渲染，且环境未验证具备 Remotion）。故该表按『文档声明』记录，不在结论中当作已验证事实。
- [ok] meta.official_desc 与 SKILL.md 原文的逐字比对（体检工具的 ⚠ 项） — 本 skill 的 frontmatter 用 YAML 单引号风格书写：`description: 'Port an existing Remotion (React) composition''s source to …'`——文件里的两个连续单引号是 YAML 的转义语法，解析后的字符串值是带**一个**撇号的 `composition's`。本 JSON 的 meta.official_desc 记录的是解析后的真实描述文本（与 YAML 解析结果一致），因此对**原始文件字节**做朴素逐字比对时会出现一处不可避免的差异（源码里的 `composition''s` vs 记录值的 `composition's`）。这不是改写，也不影响展示层：如实记录为报告口径差异，而非内容出入。
6结论
适合：适合手上已有 Remotion（React）合成源码、且明确要求把它移植成 HyperFrames HTML 的项目；尤其适合想要可回归验收的团队——本 skill 提供四级测试语料与 SSIM 阈值，可把『翻译保真度』纳入 CI 或人工回归。也适合需要判断『这份 Remotion 源码能不能译』的场景（跑一次 lint_source.py 即可得到 blocker/warning 清单）。
不适合：不适合：① 新建 HyperFrames 作品（即使手上有类似 Remotion 视频）——应走 /general-video；② 只是想「做一个像我的 Remotion 视频那样的片子」（description 明确要求视为新建）；③ 反向导出（HF → Remotion 或其他框架）；④ 非 Remotion 来源（After Effects .aep、Framer Motion、纯 React/CSS）；⑤ 状态机驱动的 Remotion 合成（blocker 命中，应改用运行时互操作）；⑥ 不愿跑渲染级 eval 的场景——不跑就无法验证，正确性无从保证。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 remotion-to-hyperframes.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent7dc73746cff19b96…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 为实时上游，内容可能已更新。