modernize-transform 是 smartworldarafath/google_antigravity_plugins 中的一个技能,用于按“绞杀榕”模式将遗留系统逐模块迁移到目标技术栈,且要求为行为等价提供证据。
【用途】 把 $system 中的 $module 转换为 $target_stack,并证明新旧行为一致。产物写入 modernized/$system/$module/。它属于一次只处理一个模块的纵向切片,而非整体重写。
【前置检查与选模块】 代码通常位于 legacy/$system(常为符号链接,需先用 readlink 一行说明其指向);若该路径不存在则停止,并提示执行 /code-modernization:modernize $system --source <代码路径>。若未提供 $module 或 $target_stack,则读取 analysis/$system/MODERNIZATION_BRIEF.md,取其中指定的目标栈,以及最早阶段中 Command: 为 transform、且尚无 modernized/$system/<module>/TRANSFORMATION_NOTES.md 的第一个模块;无 brief 时沿用 INTENT.md 中的目标,并说明所选模块。
【第 0 步:工具链与计划(人工闸门)】 目标栈必检:运行时、包管理器与测试框架需可用(如 java -version 与 mvn -v、node -v 与 npm -v、python3 -V 与 pytest --version),否则停止并提示安装,指向 /code-modernization:modernize-preflight。旧栈只做建议性检查:尝试仅语法编译,旧代码常无法本地构建(如 CICS/IMS 无本地翻译器),此时关闭双执行,改用录制轨迹与金标准样本(生产输出、捕获报表、业务专家确认示例)作为断言依据,并在计划与 TRANSFORMATION_NOTES.md 中注明“等价性基于轨迹;旧系统在此不可执行”。仅在安全环境运行旧系统记录基线,未经批准不得调用生产或第三方服务、注册账号或读写真实数据;录制响应中的令牌、密码、会话 cookie 须替换为固定假值且不得打印。MODERNIZATION_BRIEF.md 具约束力:须满足其范围与进出口条件,入口条件未满足应先满足而非改计划;若无阶段覆盖该模块则询问。需查看模块源码、BUSINESS_RULES.md 中相关规则及 RULE_REVIEWS.json 的裁决:被标为错误的规则不作为基准,标为 discuss 的 P0 规则需在计划闸门先解决。随后呈现计划并停止,未经明确批准不写代码。
【第 1 步:特征化测试】 派发 test-engineer 子代理,为模块编写特征化测试,覆盖每个可观察行为及其具体输入/预期输出,写入 modernized/$system/$module/src/test/,测试名或注释标注所固定的 RULE-NNN 编号;不得将遗留凭据用作测试夹具,使用同形假值,实时值从环境变量读取。展示测试文件并获得确认后继续。
【第 2 步:地道化转换】 在 modernized/$system/$module/src/main/ 编写实现,按目标栈资深工程师的方式从规格出发编写,而非照搬 COBOL 段落或 WS-TEMP-AMT-X 之类命名;使用目标语言惯用法(记录、流、注入、规范错误类型),包含领域模型、服务逻辑、API 与配置,并以简短注释将类关联到所实现的规则编号。
【第 3 步:证明等价,并证明证明会失败】 迭代时只跑本模块测试,第 4 步前跑一次全量。运行测试并展示输出,修复至通过。报告执行的等价用例数 N;零用例不算证明;缺少旧基准或夹具时比对测试必须失败而非跳过。做“金丝雀”验证:临时小改新代码(如舍入方式、阈值偏移一、比较翻转),确认至少一个测试变红后恢复,并在笔记记录“Canary: <改动> → <N> 个测试失败”。旧代码可运行时,用相同输入跑两套系统,分别保存到 analysis/$system/equivalence/legacy/ 与 .../new/,在 cases.json 中列出配对,并运行 python3 "${ANTIGRAVITY_PLUGIN_ROOT}/scripts/compare.py" analysis/$system/equivalence/cases.json --out analysis/$system/EQUIVALENCE.json,由脚本判定异同;仅对合法变化字段(时间戳、生成 ID)做掩码并说明;接受的差异须由人记录在 approvedDifference 中;浮点差异应给容差(相对/绝对及原因),其余字节严格一致。
【第 4 步:笔记与并排对比】 编写 TRANSFORMATION_NOTES.md:映射表(旧文件:行 → 目标文件:行,按行为)、有意偏离及理由、未迁移内容(死代码、不可达分支)及原因、金丝雀结果与执行用例数、对下一个依赖模块的后续事项;并展示一个有代表性行为的并排对比(diff -y --width=160),避免选含凭据的片段并掩码凭据类字面量。可用 /code-modernization:modernize-verify 做独立复核。
【第 5 步:架构评审】 派发 architecture-critic 子代理按目标栈最佳实践评审,采纳 HIGH 级反馈,其余记入笔记。最后汇报测试通过情况、执行用例数、退役的遗留代码行数、产物位置;可运行 python3 "${ANTIGRAVITY_PLUGIN_ROOT}/scripts/build_report.py" $system 刷新报告(失败或缺 python3 时一行说明并继续)。下一步是 brief 的下一个模块,阶段完成时执行 /code-modernization:modernize-harden $system。
【适用场景】 适合有明确目标技术栈、需要逐模块迁移且须证明行为等价的遗留系统现代化项目,尤其适用于旧代码难以本地运行、需依赖录制轨迹和业务专家样本做验证的场景。
【限制】 需人工在计划闸门批准;需目标栈工具链就绪;旧栈无法本地执行时只能做基于轨迹的等价性证明;不得未经批准触碰生产数据或第三方服务;具体支持的技术栈、收费与价格、运行平台等信息资料未提供。