插件安装： 在设置或执行刷新命令之前，如果此技能位于 HyperFrames 插件内部，请遵循插件执行规则。独立安装则保留下面的更新说明。
首先，保持此技能为最新——在运行前请与用户确认：
npx hyperframes skills update remotion-to-hyperframes。如果一切已是最新，则快速无操作；否则，它将刷新此技能及其所依赖的核心领域技能，然后再依赖于它们。
Remotion 到 HyperFrames
入口是
/hyperframes。 仅使用此技能将现有 Remotion（React）合成的源码移植到 HyperFrames，此为单向操作。创建新合成、从非 Remotion 来源（After Effects、Framer Motion、普通 React/CSS——没有可翻译的 Remotion 源码）重新创建、或仅提及 Remotion，以及任何不确定情况 → 请先阅读/hyperframes：意图层负责所有路由决策。
概述
将 Remotion（基于 React 的）视频合成翻译为 HyperFrames（HTML + GSAP）合成。大多数 Remotion 习惯用法都有直接的 HyperFrames 对应项——对于典型的合成，翻译过程约有 80% 是机械性的。此技能编码了这些映射，并阻止翻译不符合 HF 基于时间帧搜索模型的约 20% 模式，转而推荐来自 PR #214 的运行时互操作模式。
该技能附带了一个分层测试语料库（T1–T4，共 4 个测试用例），用于根据测量的 SSIM 阈值对翻译结果进行评分。未经评估不要进行翻译——一个“看起来正确”但比验证基线低 0.05 个 SSIM 的翻译实际上是错误的。
何时使用
仅当用户明确要求从 Remotion 迁移时，才使用此技能。 触发短语示例：
- “将我的 Remotion 项目移植到 HyperFrames”
- “将这段 Remotion 代码转换为 HyperFrames”
- “从 Remotion 迁移”
- “翻译这个 Remotion 合成”
- “将其重写为 HyperFrames HTML”
在以下情况下请不要使用此技能：
- (a) 用户正在创作新的 HyperFrames 合成，即使他们拥有或正在 A/B 测试类似的 Remotion 视频。
- (b) 用户仅顺带提及 Remotion，但没有要求迁移。
- (c) 用户分享 Remotion 代码作为参考材料，而不是要求翻译。
- (d) 用户要求“制作一个和我 Remotion 视频一样的视频”，但没有明确要求迁移源码——这种情况应视为全新的 HyperFrames 构建。
不支持（拒绝——这并非此技能的职责）：
- 反向方向。 将 HyperFrames 合成导出回 Remotion（或任何其他框架）不是一种工作流程——翻译只能是 Remotion → HyperFrames。请直说。
- 非 Remotion 来源。 After Effects 项目 (
.aep)、Framer Motion/纯 React/CSS 动画或任何其他工具的源文件都不是 Remotion 合成——没有可供翻译的 Remotion 源码。通过/general-video原生重新创建，或者如果 HyperFrames 无法表示，则拒绝。
如有疑问，默认通过 /general-video（常规 HyperFrames 创作流程）创作原生 HyperFrames 合成。
工作流程
步骤 1：检查源码
在 Remotion 源码目录上运行 scripts/lint_source.py。该检查可以检测无法干净翻译的模式：
- 阻塞项（拒绝并推荐互操作）：
useState、useReducer、useEffect/useLayoutEffect（带有非空依赖项）、异步calculateMetadata、第三方 React UI 库（MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI）。 - 警告项（删除该结构后继续翻译）：
@remotion/lambda配置、delayRender、useCallback、useMemo、自定义钩子。 - 信息项（翻译时附带说明）：
staticFile、interpolateColors。
如果触发了任何阻塞项，请停止。阅读 references/escape-hatch.md 并展示推荐消息。警告项不会阻止翻译——在步骤 3 中删除有问题的结构，并在 TRANSLATION_NOTES.md 中记录差异。@remotion/lambda 配置是典型的警告案例：技能会删除导入和 renderMediaOnLambda(...) 调用，但会翻译合成的其余部分。
步骤 2：规划翻译
阅读 references/api-map.md——这是每个 Remotion API 及其 HF 对应项或按主题分类的参考索引。根据源码使用的内容，确定需要加载哪些主题参考：
| 源码包含 | 加载参考文件 |
|---|---|
Composition、defaultProps、schema、calculateMetadata | parameters.md |
Sequence、Series、Loop、AbsoluteFill、Freeze | sequencing.md |
useCurrentFrame、interpolate、spring、Easing、interpolateColors | timing.md |
Audio、Video、Img、IFrame、staticFile、delayRender | media.md |
TransitionSeries、@remotion/transitions | transitions.md |
@remotion/lottie | lottie.md |
@remotion/google-fonts/<Family>、Font.loadFont、@font-face | fonts.md |
不要全部加载——只加载特定源码需要的内容。
搜索实时目录，查找该表格未映射的任何视觉效果。 当源码使用了一种没有 HF API 对应项的视觉效果——例如扫描线/CRT 叠加、故障或色差效果、着色器擦拭、胶片颗粒处理——在手动使用 GSAP 编写之前，请运行 npx hyperframes catalog --query "<效果名，用英文描述>" --json。此搜索无需安装任何东西：无需项目、无需事先 add、无需账户。它会从任何目录对整个托管注册表（约 400 个块和组件）进行排序，并且 transitions.md 已经通过 npx hyperframes add sdf-iris 为 clockWipe() / iris() 采用了此方法。真实的组件比手工近似更接近源码，因此通常可以提高 SSIM 而非降低——但步骤 4 中的渲染差异比较仍然是仲裁者。当搜索没有返回合适的结果时，手动编写效果，并在 TRANSLATION_NOTES.md 中记录替换内容（无论哪种情况）。
步骤 3：生成 HF 合成
生成 index.html，包含：
- 根元素
<div id="stage">，携带合成的data-composition-id、data-start="0"、data-duration（以秒计）、data-fps、data-width、data-height，以及每个标量属性一个data-*。 - 每个场景一个宿主
<div>，包含data-composition-src="compositions/<scene>.html"、data-start/data-duration/data-track-index。根元素不包含嵌套布局。 - 每个场景一个
compositions/<scene>.html（一个<template>子合成）：其内联<style>用于布局（CSS 设置每个动画属性的from状态）、其标记，以及一个在场景本地时间轴上的暂停gsap.timeline({paused: true})。每个 Remotion 的useCurrentFrame()推导都会成为该时间轴上的一个补间，偏移量相对于场景开始帧。 - 在每个场景文件中声明
window.__timelines["<scene-id>"] = tl;，并为根元素自己的（可能为空）时间轴声明window.__timelines["<composition-id>"]。
自定义 React 子组件以内联方式转换为重复的 HTML，使用 prop 接口作为模板（关于每个实例的 data-* 模式，请参见 parameters.md）。
步骤 4：验证
运行评估工具——完整指南请参见 references/eval.md。快速路径：
# 渲染 Remotion 基线（在测试用例中执行 npm install 后）
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# 渲染 HF 翻译
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
# SSIM 差异比较
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
阈值：大约比源码复杂性等级 p05 低 0.02（请参见 eval.md 中的验证阈值表）。如果差异比较失败，运行 scripts/frame_strip.sh 查看哪些帧发生了偏离，然后重新阅读相关的时序/序列/媒体参考。
关键点：两个渲染必须使用匹配的像素格式。在 Remotion 源码的 remotion.config.ts 中设置 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")——否则差异比较会测量编码器差异（约 0.05 SSIM 损失），而非翻译保真度。
步骤 5：记录差异
对于任何未能干净翻译的内容（例如被丢弃的音量渐变、近似处理的自定义演示、字体替换），请在 HF 输出旁边编写 TRANSLATION_NOTES.md。格式请参见 references/limitations.md。
此技能明确不做什么
- 翻译 React 状态机。 通过
useState+useEffect驱动动画的合成不是 HyperFrames 基于时间帧搜索模型的确定性帧捕获目标。建议使用运行时互操作模式。 - 与 HyperFrames 并行运行 Remotion 的渲染管线。 这是来自 PR #214 的运行时互操作模式——一个针对无法通过此技能 lint 的合成的单独解决方案。
（@remotion/lambda 不是阻塞项——Lambda 配置属于部署，而非动画。此技能将其作为警告处理并删除，然后翻译其余部分。请参见 references/escape-hatch.md。）
如何评分你自己的翻译
运行测试语料库协调器：
./assets/test-corpus/run.sh
它会运行 T1、T2、T3（渲染 + 差异比较）和 T4（lint 验证），打印每层级的通过/失败表，并输出一个聚合 JSON 报告。使用此工具在干净的检出上验证技能是否端到端工作——并在编辑任何参考文件后作为回归检查。
验证基线（截至 2026-04-27）：
| 层级 | 合成形状 | 平均 SSIM | 阈值 |
|---|---|---|---|
| T1 | 单元素淡入 | 0.974 | 0.95 |
| T2 | 多场景 + spring + 音频 + 图像 | 0.985 | 0.95 |
| T3 | 数据驱动、自定义子组件、数字递增 | 0.953 | 0.90 |
| T4 | 逃生舱口（8 个 lint 案例） | 8/8 通过 | n/a |