一个插件移植教会我们的事:从 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 双层测试
- port/smoke.mjs:快速自检——不联网、不碰 USB,几秒内验证插件结构完整;
- port/e2e-build.mjs:真实工具链端到端测试——建工程 → 画精灵 → 构建 → 跑模拟器 → 打开预览,全链路真跑一遍。
两层测试对应两种场景:改了移植脚本跑 smoke 快速确认;升级依赖或上游版本后跑 e2e 确认真链路没断。这个分层和软件工程的单元/集成测试一模一样——移植脚本也是软件,也要有测试。
招式三:平台差异的两个聪明解法
平台能力不对等时,作者的处理方式值得记下:
- 缺内置图像生成 → 换一种表示:Codex 用生图模型,移植版新增
pixel-grid.mjs,让 Claude 用文本网格逐像素画——字符画天然可读可改,还能在生成时同步做 GB 硬件约束检查(调色板/图块预算),反而比"生成一张图再识别网格"更可控; - 缺私有浏览器 API → 降级为等价能力:"Annotate game"(在游戏画面上标注)依赖 Codex 浏览器的私有接口,移植版改用截图 + 模拟器帧 + 文字描述组合实现近似能力。诚实地降级比硬造一个假功能体面得多。
招式四:闭源依赖的合规处理
最棘手的是 ModRetro 的闭源 chromatic-cli(串流/烧录/采集必需,且仅授权给官方 Codex 插件)。移植版的处理是教科书级的:
- 不随插件分发——规避许可问题;
- 首次使用时征求用户同意,再从 npm 官方源下载
@modretro/chromatic-cli-<平台>@1.2.1; - 按上游插件记录的 SHA-256 逐字节校验后安装;
- 缓存本地,插件更新后由 SessionStart 钩子离线恢复;
- 激活码(开发者模式)完全不碰——"插件和 Claude 永远不会索要或处理激活码";
- 烧录前明确告知擦除风险并取得同意;只烧自制游戏,拒绝商业游戏。
结果:闭源依赖留在了官方渠道,用户知情权完整保留,插件作者免责。
写在最后
这个项目展示的其实是一种正在成型的社区分工:官方做平台绑定版,社区做"把能力解放出来"的移植版——Codex 掌机卖 200 美元,移植版把工作流还给所有 Claude Code 用户(GB Studio CLI 4.3.2、GBDK 4.5.0、PyBoy 都是开源依赖,与 Codex 版共用安装目录)。对掌机玩家:装上它,你的 R36S 又多了一个"用 AI 做游戏 → 实机即玩"的入口(ROM 用法见 添加游戏)。