OpenMontage remotion-to-hyperframes 翻译限制解析：Bow-out 规则、带保留翻译模式与 TRANSLATION_NOTES 缺口报告机制

本文围绕 OpenMontage 仓库中 remotion-to-hyperframes 技能的核心参考文档 limitations.md 展开，完整梳理该 Remotion → HyperFrames 翻译工具"明确拒绝翻译哪些模式、哪些模式带保留翻译、哪些模式总能翻译"的能力边界，并结合 lint_source.py 的源码实现与 T4 测试语料（escape-hatch 用例集），说明这些限制在工程上如何被强制执行、如何检测，以及翻译缺口如何通过 TRANSLATION_NOTES.md 规范地报告给用户。

一、limitations.md 在翻译工作流中的定位

OpenMontage 的 remotion-to-hyperframes 技能是一个单向翻译器：把 Remotion（基于 React 的视频组合框架）项目翻译成 HyperFrames（HTML + GSAP）组合。技能的完整工作流定义在 SKILL.md 中，共五步：

1. Lint：运行 lint_source.py 检测源文件中不可翻译的模式；
2. Plan：按源文件使用的 API 加载对应的主题参考文档（timing、sequencing、media、transitions 等）；
3. Generate：产出 index.html 形式的 HF 组合；
4. Validate：通过 SSIM 渲染对比验证翻译保真度；
5. Document gaps：把没有干净翻译的部分写入 TRANSLATION_NOTES.md。

limitations.md 正是这个工作流的"能力边界声明"，它承担两个职责：

• 与 escape-hatch.md 中的 blocker 清单 相区分——blocker 清单由 lint_source.py 强制执法（检测到即拒绝翻译），而 limitations 描述的是已知但尚未修复的翻译缺口：当翻译"能出结果、但结果有损"时，必须在翻译过程中把这些缺口作为翻译笔记呈现给用户；
• 作为第 5 步（Document gaps）的格式规范，规定 TRANSLATION_NOTES.md 的写法。

原文档开头对此的定位非常明确："These are known gaps — surface them to the user as translation notes when translating the surrounding composition."（这些是已知缺口——在翻译周边组合时必须作为翻译笔记向用户呈现。）

二、技能明确拒绝的 React 模式（Bow-out 模式）

这是 limitations 文档的第一节。以下任一模式出现，技能即 bow out（退出翻译），不再产出 HF 输出：

• useState、useReducer 驱动动画
• 依赖数组非空的 useEffect / useLayoutEffect（即带副作用的 effect）
• 异步 calculateMetadata
• 第三方 React UI 库：MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI

这些模式共同的破坏点是：它们违背了 HyperFrames 的 seek 驱动、逐帧确定性 渲染模型——HF 的渲染循环按帧号 seek 时间线并截图，而 React 状态机、副作用和异步元数据都无法在"给定帧号即得确定画面"的约束下可靠运行。强行翻译会产出"看起来对但逐帧校验时静默错误"的 HTML。

与 lint 规则的一一对应

上述拒绝清单与 lint_source.py 中的 5 条 blocker 规则严格对应。从源码的 RULES 列表（lint_source.py#L139-L178）看：

Bow-out 模式	lint 规则 ID	检测方式
useState 驱动动画	r2hf/use-state	正则 \buseState\s*[(<]
useReducer 驱动动画	r2hf/use-reducer	正则 \buseReducer\s*[(<]
非空 deps 的 effect	r2hf/use-effect-deps	自定义括号匹配函数
异步 calculateMetadata	r2hf/async-metadata	正则匹配 async 与 calculateMetadata 的组合
第三方 React UI 库	r2hf/third-party-react-ui	检查 import ... from 的目标包名

值得注意的是 r2hf/use-effect-deps 的实现细节：Remotion 惯例中 useEffect(fn, [])（空依赖数组，仅挂载时执行）是允许的空操作，而 _use_effect_with_deps 匹配器（lint_source.py#L101-L111）先用 _find_matching_paren 找到 useEffect( 对应的右括号（该函数跳过字符串字面量内的括号），再检查整个调用是否以非空的 , [...]) 结尾——只有依赖数组非空时才报 blocker。

第三方 UI 库的检测同样有精确边界：THIRD_PARTY_UI_PACKAGES 集合（lint_source.py#L53-L62）包含 @mui/material、@mui/icons-material、@chakra-ui/react、@mantine/core、antd、@shadcn/ui、@radix-ui、@nextui-org/react 八个包前缀，检测逻辑对每个 import ... from "pkg" 做前缀匹配，避免误报普通工具库。

@remotion/lambda 的特殊地位：警告而非 blocker

原文档特别强调：@remotion/lambda 不在拒绝清单中——它是 warning 而不是 blocker，原因是 Lambda 配置与组合的渲染内容正交（它是分布式渲染的部署配置，不是动画逻辑）。技能的处理策略是：丢弃 @remotion/lambda 的 import 和 renderMediaOnLambda(...) 调用，正常翻译组合的其余部分，并写入一条 TRANSLATION_NOTES.md 条目告知用户 HF 侧需要单独搭建渲染链路。

这一策略在 lint 源码中有明确注释（lint_source.py#L179-L188）："Lambda is a warning, not a blocker: it's deployment config, orthogonal to the rendered composition." 对应的测试用例 05-lambda-config.tsx 注释也解释了为什么不能做成硬 blocker："Treating it as a hard blocker would refuse translation for compositions that are otherwise clean."（若将其视为硬 blocker，会拒绝翻译本来干净的组织。）

三、可以带保留翻译的模式（Patterns with caveats）

这是 limitations 文档的主体部分：以下模式能翻译，但翻译是损真的（lossy），必须在 TRANSLATION_NOTES.md 中如实记录。以下五条逐一继承原文档的示例并补充判定依据。

3.1 <Audio> 上的音量渐变（volume ramp）

Remotion 允许 volume 属性接收一个函数：

<Audio src={...} volume={(f) => interpolate(f, [0, 30], [0, 1])} />

而 HyperFrames 只支持静态的 data-volume 属性。翻译策略二选一：

• 保留渐变：翻译时用 ffmpeg afade 把渐变直接"烤进"音频文件；
• 丢弃渐变：加一条翻译笔记说明。

原文档指出了一个微妙的验证盲区：丢弃渐变这条路产出的视频音频听感不同、但画面完全相同，因此 SSIM（结构相似度，只比较画面帧）对比会通过——评估流水线无法自动发现这个缺口，只能靠人工 flag。这正是"带保留翻译"必须显式写笔记的原因。

3.2 含状态子元素的 <Loop>

<Loop durationInFrames={30}>
  <CounterThatIncrementsViaUseRef />
</Loop>

带 repeat: -1 的循环对纯视觉重复是有效的。但如果循环体内存在跨迭代状态（递增的计数器、随机种子），HyperFrames 无法保证每次迭代产出相同结果——这与 seek 驱动模型冲突（每帧必须能从帧号独立确定）。判定规则：除非循环子元素在每次迭代内完全确定性，否则 bow out。

3.3 带 crossOrigin 的 <Img>

<Img src="https://other-domain.com/x.png" crossOrigin="anonymous" />

HF 渲染器对 CORS 的强制方式与 Remotion 不同。多数公开图片可以正常工作；但带鉴权头下发的私有图片不行。若源使用了 crossOrigin="use-credentials"，则必须在翻译时把资源下载并内联，不能直接引用原 URL。

3.4 <TransitionSeries> 的自定义 presentation

const customPresentation: PresentationComponent = ({ children, presentationProgress }) => {
  return <div style={{ filter: `blur(${(1 - presentationProgress) * 20}px)` }}>{children}</div>;
};

判定标准是 presentation 是否"纯"：仅从 presentationProgress 派生 transform / filter / opacity 的纯展示可以干净地翻译为 GSAP tween；但如果 presentation 内部读取了 useCurrentFrame()，或含有状态化子元素，则无法翻译——bow out。

3.5 代码分割组件（React.lazy）

const HeavyChart = React.lazy(() => import("./HeavyChart"));

React.lazy 是异步的，与确定性渲染模型不符。翻译策略是降级为普通同步 import——产出的 HF 组合会预先包含全部代码。原文档给出的一个实用推论是：bundle 体积不变，因为 HF 本身只交付单一 HTML 文件（HF 侧不存在"懒加载"的概念），所以这通常只是行为差异而非性能损失。

四、总能干净翻译的模式（Patterns that always work）

原文档的这份"安全清单"是判断"是否值得走翻译"的快速依据。全部列于 limitations.md 第 86–99 行：

• <AbsoluteFill> 与 <Sequence>（任意嵌套深度）
• useCurrentFrame() 的一切派生：interpolate、spring、Easing、interpolateColors、手写数学运算
• 简单 props 的 <Audio>、<Video>、<Img>、<IFrame>
• staticFile() 引用
• props 纯函数的自定义 React 子组件
• useCurrentFrame 纯派生的自定义 hooks
• @remotion/lottie（翻译为 HF 的 Lottie adapter）
• @remotion/google-fonts/<Family>（翻译为 <link> 或 @font-face）
• 同步 calculateMetadata（在翻译期求值解决）
• 使用内置 presentation 的 <TransitionSeries>（fade、slide、wipe、clockWipe、flip、iris）

从源码结构看，这份清单与 lint 规则的设计逻辑一致：所有被 lint 视为 warning 的"装饰性"构造（useCallback、useMemo、delayRender）都不在安全清单里也不构成 blocker——它们在翻译第 3 步被丢弃或内联，不影响上述"总能工作"模式的翻译。

五、技能从不尝试翻译的模式（Out-of-scope by design）

以下四项是设计上就排除在翻译范围外的，与"翻译不了"不同，它们根本没有翻译对象：

• HDR 渲染 —— HF 支持 HDR 但 Remotion 不支持，所以"从 Remotion 翻译 HDR"无源可译；
• 可变帧率（VFR） —— 两个工具都假设恒定 fps；
• 多组合的 <Composition> 列表 —— 一次只翻译一个；技能会提示用户选择要翻译哪个组合；
• Remotion Studio 的 props 面板 —— HF Studio 的可视化属性编辑需要不同的基础设施，超出范围。

六、缺口报告规范：TRANSLATION_NOTES.md

当翻译产出了"某样东西"但存在缺口时，必须在 HF 输出旁边生成一份 TRANSLATION_NOTES.md。原文档给出的标准格式（第 115–133 行）如下，注意它逐条给出源文件行号、被丢弃/近似的模式、以及用户可执行的补救命令：

# Translation notes

The following Remotion patterns were translated with caveats:

- `<Audio volume={(f) => ...}>` (line 15): volume ramp dropped — added
  static `data-volume="0.5"`. To preserve the ramp, run
  `ffmpeg -i music.wav -af "afade=t=in:st=0:d=1" music.faded.wav` and
  swap the source file.
- `<HeavyChart>` (line 30): translated as inline HTML. The original
  React.lazy boundary was dropped — bundle size unchanged because HF
  serves a single HTML file.

If any of these caveats matter, consider the runtime interop pattern
instead.

原文档最后一句补充了一个重要的工程事实：这个文件也是技能在翻译过程中与 HF 输出一起生成的，而不是预先存放在技能语料（corpus）里——即它是逐项目产物，模板来自 limitations.md 的格式约定。

七、源码级纵深：blocker 如何被强制执行

这一节从 limitations 文档回到 lint 脚本与测试语料，说明"拒绝清单"在 OpenMontage 中不是纸面承诺，而是有可执行代码和回归测试的机制。

7.1 lint_source.py 的严重度模型与输出结构

lint_source.py 实现三级严重度模型：blocker / warning / info，共 12 条规则（lint_source.py#L139-L231）：

严重度	规则	翻译策略
blocker（5 条）	use-state、use-reducer、use-effect-deps、async-metadata、third-party-react-ui	拒绝翻译，推荐 runtime interop
warning（5 条）	lambda-import、delay-render、use-callback、use-memo、custom-hook	丢弃该构造后继续翻译
info（2 条）	static-file、interpolate-colors	翻译并注明

每条发现（Finding）都携带 file、line、column、severity、rule、message、recommendation 七个字段（lint_source.py#L65-L74），其中 recommendation 是按规则逐条调优好的建议文本，escape-hatch.md 明确要求技能把 lint 输出中的 recommendation "verbatim（逐字）"呈现给用户。

关键的退出码语义（lint_source.py#L354）：return 1 if blockers else 0——有 blocker 返回 1，其余返回 0。这意味着 lint 可以直接作为流水线门禁：SKILL.md 第 1 步的"If any blocker fires, stop"就是基于这个退出码的硬性判定，warning 不会改变退出码，因此不会阻断翻译。

7.2 T4 语料：把 limitations 变成可回归的测试

仓库自带了把这节文档内容固化为测试的语料 tier-4-escape-hatch。T4 是唯一的"纯 lint 层"——不渲染、不做 SSIM 对比，评估对象是"技能是否正确拒绝了每个用例"或"是否正确地丢弃 warning 级装饰后继续翻译"。

8 个用例与预期结果的完整对应（见 expected.json）：

用例	文件	预期发现	技能动作
01	01-use-state.tsx	blocker r2hf/use-state	拒绝翻译，推荐 interop
02	02-use-effect-deps.tsx	blocker r2hf/use-effect-deps	拒绝翻译，推荐 interop
03	03-async-metadata.tsx	blocker r2hf/async-metadata	拒绝翻译，推荐 interop
04	04-third-party-react.tsx	blocker r2hf/third-party-react-ui	拒绝翻译，推荐 interop
05	05-lambda-config.tsx	warning r2hf/lambda-import	丢弃 lambda 代码，其余干净则继续翻译
06	06-warnings-only.tsx	warning delay-render / use-callback / use-memo	丢弃包装器后正常翻译
07	07-custom-hook.tsx	warning r2hf/custom-hook	纯派生 hook 内联其函数体
08	08-mixed.tsx	3 个 blocker + 1 个 warning	拒绝翻译（聚合发现测试）

其中 08-mixed.tsx 值得注意：它在一个文件里同时放入 useState、带 [frame] 依赖的 useEffect、Chakra Card import 和 useCallback，专门测试 linter"发现所有问题而不止于第一个 blocker"的聚合能力——这与 escape-hatch.md 末尾"blocker 与 warning 同时存在时"的结论一致：只要存在任一 blocker，即使组合其余部分干净，也整体 bow out，用户要么对整体改用 runtime interop，要么先把 blocker 模式从 Remotion 源码中重构掉。

验证方式（tier-4-escape-hatch/README.md）：

cd .agents/skills/remotion-to-hyperframes/assets/test-corpus/tier-4-escape-hatch
./validate.sh

该脚本对每个 case 运行 lint_source.py 并断言三件事：预期 blocker 规则以 blocker 严重度触发；预期 warning 规则以 warning（或更重）严重度触发；退出码在预期有 blocker 时为 1、否则为 0。全仓级的编排入口是 run.sh，它会跑 T1–T3（渲染 + SSIM diff）和 T4（lint 校验），输出分层 pass/fail 表和聚合 JSON 报告。

7.3 Bow-out 之后去哪里：runtime interop 模式

limitations 中反复出现的"consider the runtime interop pattern instead"指向 escape-hatch.md 描述的替代路径：与其翻译失败，不如用 runtime 互操作适配器把用户的 Remotion 代码经 esbuild 打包（React + @remotion/player），在 HF 组合 HTML 内挂载一个 Remotion <Player>，挂载后立即暂停，并把 { seekTo(frame), pause(), durationInFrames, fps } 注册到 window.__hfRemotion；此后 HF 的渲染循环逐帧调用 seekTo(frame)。结果是 Remotion 的 React 树在 HF 的确定性帧刻度上渲染——useState、useEffect、第三方 UI 组件全部可用，因为渲染由 Remotion 自己的 reconciler 负责。这条路径正是 blocker 用例在 T4 中 skill_action 为 refuse_translation_recommend_interop 的落点。

八、实践要点速查

结合 limitations 文档与 SKILL.md 的工作流，实际执行一次翻译时的判定顺序是：

1. 先 lint 再动手：python3 .agents/skills/remotion-to-hyperframes/scripts/lint_source.py <remotion-src> --json。退出码为 1 即存在 blocker，停止翻译，向用户逐字呈现 lint 的 recommendation 并推荐 runtime interop；
2. warning 不停车：lambda-import、delay-render、use-callback、use-memo、纯 custom-hook 等在生成阶段丢弃或内联，并在 TRANSLATION_NOTES.md 记一笔；
3. 逐条比对第三节的五条 caveat：volume ramp（决定用 ffmpeg afade 烤渐变还是丢弃并 flag）、有状态 <Loop>、crossOrigin="use-credentials" 的图片（下载内联）、自定义 presentation（非纯即 bow out）、React.lazy（改同步 import）；
4. 对照第四节安全清单：命中的模式直接机械翻译，不需要额外笔记；
5. SSIM 验证有盲区：注意"画面相同但音频不同"的缺口（如丢弃的 volume ramp）无法被 render_diff.sh 的 SSIM 对比捕获，只能靠 TRANSLATION_NOTES.md 的人工声明兜底；
6. 笔记随产物生成：TRANSLATION_NOTES.md 写在 HF 输出旁边，格式遵循本文第六节的模板，逐条给出源行号与用户可执行的补救命令。

九、小结

limitations.md 的价值在于它把"翻译器做不到什么"从模糊印象变成了三层可验证的工程机制：lint 规则（lint_source.py 的 5 条 blocker 正则与括号匹配逻辑）在翻译前硬性执法；T4 语料（8 个 case + expected.json + validate.sh）把这些执法行为固化为回归测试；TRANSLATION_NOTES.md 规范则在"能翻但有损"的灰色地带强制显式披露缺口。对维护该技能的开发者，修改任何规则后运行 ./assets/test-corpus/run.sh 即可端到端验证；对使用方，理解这份能力边界声明能避免两类常见误判——把 warning 当 blocker 放弃本可翻译的组合，或依赖 SSIM 通过就忽视被静默丢弃的音频渐变。