一个插件移植教会我们的事:从 Codex 到 Claude 的工程学

把一个 81 个 MCP 工具的官方插件从 Codex 平台搬到 Claude Code,还顺手做了增强——modretro-chromatic-claude 的价值不止于工具本身:它的移植方法论值得所有想"把 A 平台的好东西搬到 B 平台"的人抄作业。

本文依据

基于仓库 lixiaolin94/modretro-chromatic-claude 的 README 与仓库结构(port/port.mjs、smoke.mjs、e2e-build.mjs、CLAUDE-PORT.md)分析。工具介绍见 上篇。

难点回顾:这不是简单的格式转换

移植对象是 OpenAI DevDay 2026 发布的官方 Chromatic 插件——81 个 MCP 工具、内置图像生成、私有浏览器 API,还捆绑闭源的 Chromatic CLI。搬到 Claude Code 要解决四类问题:插件格式不同(.codex-plugin vs .claude-plugin+.mcp.json+skills+hooks)、平台能力差异(无内置生图与浏览器私有 API)、闭源依赖的分配合规、以及"上游还在更新"的跟进成本。

招式一:可复现移植脚本 + 期望命中声明

移植不是手改一遍了事——作者写了 port/port.mjs:输入上游 zip/目录,输出 Claude 插件。脚本里每一条文本替换都声明了"期望命中次数":上游措辞一变(比如 Codex 改名、字段调整),脚本会立刻报错并指出是哪条规则失配,杜绝产出"看起来移植好了、其实一半没换"的半成品。跟进上游新版本变成了一条命令:node port/port.mjs ~/Downloads/modretro-chromatic.zip。

抄走这条

任何"从上游自动生成产物"的脚本都应该做断言式校验——每条替换声明预期次数,失配即报错。它把"静默的移植腐烂"变成了"响亮的构建失败"。

招式二:smoke + e2e 双层测试

两层测试对应两种场景:改了移植脚本跑 smoke 快速确认;升级依赖或上游版本后跑 e2e 确认真链路没断。这个分层和软件工程的单元/集成测试一模一样——移植脚本也是软件,也要有测试。

招式三:平台差异的两个聪明解法

平台能力不对等时,作者的处理方式值得记下:

招式四:闭源依赖的合规处理

最棘手的是 ModRetro 的闭源 chromatic-cli(串流/烧录/采集必需,且仅授权给官方 Codex 插件)。移植版的处理是教科书级的:

  1. 不随插件分发——规避许可问题;
  2. 首次使用时征求用户同意,再从 npm 官方源下载 @modretro/chromatic-cli-<平台>@1.2.1;
  3. 按上游插件记录的 SHA-256 逐字节校验后安装;
  4. 缓存本地,插件更新后由 SessionStart 钩子离线恢复;
  5. 激活码(开发者模式)完全不碰——"插件和 Claude 永远不会索要或处理激活码";
  6. 烧录前明确告知擦除风险并取得同意;只烧自制游戏,拒绝商业游戏。

结果:闭源依赖留在了官方渠道,用户知情权完整保留,插件作者免责。

写在最后

这个项目展示的其实是一种正在成型的社区分工:官方做平台绑定版,社区做"把能力解放出来"的移植版——Codex 掌机卖 200 美元,移植版把工作流还给所有 Claude Code 用户(GB Studio CLI 4.3.2、GBDK 4.5.0、PyBoy 都是开源依赖,与 Codex 版共用安装目录)。对掌机玩家:装上它,你的 R36S 又多了一个"用 AI 做游戏 → 实机即玩"的入口(ROM 用法见 添加游戏)。

↑