用途
kinetograph-migrate 用于将已有的 Remotion 视频项目迁移到 Kinetograph 引擎，使视频渲染不再依赖浏览器。迁移过程中，大部分 Remotion 代码可以保持不变；CLI 会将 remotion 以及 24 个 @remotion/* 包映射到 Kinetograph 核心。主要变化在于项目周边的工具链，以及少数没有对应实现的包。渲染路径中不允许出现浏览器，不得添加 Chrome、Puppeteer、Playwright 或 iframe 作为临时方案。
主要能力
该技能提供了一套迁移流程，包括：定位入口与 composition、运行诊断（doctor）、按类型修复问题、代码检查（lint/check）、生成预览条带（strip/still）以及最终渲染（render）。命令通过 npx kinetograph <command> 执行，可添加 --json 获取单个 JSON 对象输出。
诊断命令 kinetograph doctor <entry> 会报告引擎无法绘制的元素、属性及原因，并附上帧范围。无法打包的导入会直接终止命令并指出包名。修复时根据问题类型参考对应文档：@remotion/three 或 three 导入参考 three.md；@remotion/player、renderer、bundler、lambda、cloudrun、cli、配置文件、npm 脚本、webpack 覆盖参考 tooling.md；IFrame、@remotion/webcodecs、@remotion/media-parser 采样回调、@remotion/rive、@remotion/skia、Canvas、WebGL 或 CSS 问题参考 unsupported.md。其他问题根据报告中指定的属性或元素改为引擎支持的形式，或移除，不要猜测，修复后重新运行 doctor。
检查命令 kinetograph lint <entry> 和 kinetograph check <entry> 分别用于代码检查和类型错误检查，需修复所有错误。若出现 react 的“no declaration file”错误，说明未安装 @types/react，应按项目 React 版本添加为开发依赖并告知用户。
预览命令 kinetograph strip <entry> -n 12 -o out/strip.png 生成预览条带，still <entry> <frame> 生成单帧。需与项目预期效果对比，注意 doctor 和 lint 都通过时文本仍可能缺失，应检查每个标题和字幕是否显示。
渲染命令 kinetograph render <entry> --comp <id> -o out/video.mp4 --strict 进行最终渲染，--strict 会在遇到不支持内容的首帧失败，确保不遗漏。可使用 --range 0..30 快速测试，a..b 停在 b-1，a..=b 包含 b。若 --strict 仍失败，剩余问题是真实存在的，应近似处理或移除，并在报告中说明，不得为最终渲染去掉 --strict。
使用方式
迁移按循环进行：先读取 package.json（脚本、依赖）和 remotion.config.ts，搜索 @remotion/(player|renderer|bundler|lambda|cloudrun|cli|three)、from 'three' 和 IFrame，找到调用 registerRoot 的入口文件，运行 kinetograph compositions <entry>。若提示“... is not supported by Kinetograph yet”，该导入即为首个问题。然后运行 doctor，按类型修复，再运行 lint 和 check，生成预览检查，最后用 --strict 渲染。完成后向用户报告：哪些原样移植、哪些被替换（及替换内容）、哪些被省略或近似处理、当前运行项目的命令，并明确说明与 Remotion 的差异。
适用场景
适用于已有 Remotion 项目（使用 remotion 或 @remotion/* 导入）并希望迁移到 Kinetograph 以实现无浏览器渲染的场景。迁移覆盖的包包括 transitions、motion-blur、noise、paths、shapes、layout-utils、animation-utils、captions、google-fonts、fonts、lottie、gif、media-utils、media、light-leaks、starburst、sfx、zod-types、timeline-utils、media-parser、webcodecs、canvas、rive、skia。有意不移植的包包括 three、player、renderer、bundler、cli、lambda、cloudrun、tailwind、tailwind-v4（Tailwind 本身可用）。GSAP 核心及免费插件可用，需在 layout effect 中将暂停的时间线 seek 到 frame / fps，自行播放的补间不会推进。
限制
渲染是帧的纯函数，需将 Date.now()、Math.random() 和定时器替换为帧数学和 random(seed)。没有网络，fetch 仅读取项目文件，远程资源需复制到 public/ 并使用 staticFile。除 kinetograph 本身作为开发依赖外，不得为渲染路径添加依赖（kinetograph 会带来 @kinetographdev/core，3D 元素从中导入）。若 kinetograph 尚未在 npm 上，需询问用户安装来源。工作室或测试用包可以添加。字体方面，未注册的字体可能被绘制为空白且 doctor 不会警告，常见原因是 fontFamily 仅指定系统字体（Helvetica、Arial、sans-serif）。需注册用户有权使用的字体文件：@remotion/google-fonts/<Family>（loadFont()）、从 @kinetographdev/core 的 registerFont({ family, path: staticFile('F.ttf') })，或在导入的 .css 文件中使用 @font-face { src: url(...) }。不得将系统字体复制到项目中。所有省略或近似处理必须在报告中明确说明，不得静默移除功能。