framework-migration 插件实战：用 legacy-modernizer Agent 与 Strangler Fig 模式安全渐进式重构遗留系统

framework-migration 插件实战：用 legacy-modernizer Agent 与 Strangler Fig 模式安全渐进式重构遗留系统

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

导读

本篇文章围绕 GitHub 推荐项目精选 agents24 仓库中 framework-migration 插件 的核心 Agent —— legacy-modernizer.md 展开。该 Agent 专注于遗留系统现代化：从框架升级（jQuery→React、Java 8→17、Python 2→3）、数据库现代化（存储过程→ORM）、单体拆微服务，到依赖更新与安全补丁、API 版本化与向后兼容。配合插件自带的 legacy-modernize.md 命令，读者可以掌握一套「先评估、再建测试、逐步替换、渐进上线、安全退役」的 5 阶段 13 步完整迁移工作流，以及每个阶段必须暂停等待人工审批的 Checkpoint 机制。

一、legacy-modernizer：一个以风险控制为第一原则的现代化专家 Agent

1.1 Agent 定义与元数据

在 legacy-modernizer.md 的文件头（frontmatter）中，可以看到这个 Agent 的注册信息：

name: framework-migration-legacy-modernizer description: Refactor legacy codebases, migrate outdated frameworks, and implement gradual modernization. Handles technical debt, dependency updates, and backward compatibility. Use PROACTIVELY for legacy system updates, framework migrations, or technical debt reduction. model: fable

关键信息解读：

• name：framework-migration-legacy-modernizer，这是插件内部通过 Task 工具调度该 Agent 时使用的subagent_type。在 legacy-modernize.md 的 Step 1 与 Step 12 中，命令正是以subagent_type="framework-migration-legacy-modernizer"的方式调用它。
• description：指明了触发场景（遗留系统更新、框架迁移、技术债削减）与能力范围（技术债处理、依赖更新、向后兼容），并明确要求「PROACTIVELY」使用——即遇到这些场景应主动启用，而非等用户点名。
• model：fable，说明该 Agent 被配置为绑定特定的模型后端执行。

1.2 Focus Areas：六类核心战场

Agent 将工作聚焦在六个方向，覆盖了遗留系统现代化的全部典型场景：

1.3 Approach：五条铁律

Agent 的工作方法并非「一把梭重写」，而是强调渐进与安全：

1. Strangler fig pattern——渐进式替换：像绞杀榕一样，新系统在旧系统「旁边」逐步生长，一点点接管功能，最终自然取代旧系统，而非一次性推翻重来。
2. 先测试后重构：在任何改动之前，先用测试把遗留代码的现有行为「钉死」（即特征化测试/表征测试，characterization tests）。
3. 保持向后兼容：迁移期间旧调用方不应被破坏。
4. 清晰记录破坏性变更：breaking changes 必须有明确的文档与迁移路径。
5. 用功能开关渐进放量：feature flags 控制灰度上线节奏。

1.4 Output：每步都要产出的六类交付物

• 含阶段与里程碑的迁移计划（Migration plan with phases and milestones）
• 保持原有功能语义的重构代码（Refactored code with preserved functionality）
• 针对遗留行为的测试套件（Test suite for legacy behavior）
• 兼容垫片/适配层（Compatibility shim/adapter layers）
• 弃用警告与时间线（Deprecation warnings and timelines）
• 每个阶段的回滚流程（Rollback procedures for each phase）

Agent 的最后一句定位概括了整个插件的设计哲学：「Focus on risk mitigation. Never break existing functionality without migration path.」——一切以风险缓释为核心，任何破坏都必须先给出迁移路径。

二、legacy-modernize 命令：把 Agent 能力落成可执行、可断点审批的 13 步工作流

仅靠 Agent 定义还不够，插件通过 legacy-modernize.md 命令把上述方法论固化成一套完整的编排流程。该命令的完整调用方式为：

legacy-modernize <legacy codebase path or description> [--strategy parallel-systems|big-bang|by-feature|database-first|api-first]

--strategy支持五种迁移策略，未指定时默认parallel-systems（并行系统）。其余策略含义：big-bang（一次性整体切换，适合小型系统）、by-feature（按功能模块迁移）、database-first（数据库先行）、api-first（API 先行）。

2.1 六条 CRITICAL BEHAVIORAL RULES（强制行为规则）

命令开篇即声明了六条不可违背的执行纪律，是保证迁移安全的关键设计：

1. 按顺序执行步骤，禁止跳步、重排或合并步骤；
2. 每步必须写出产物文件（写入.legacy-modernize/目录），后续步骤只从文件读取、不依赖上下文窗口记忆；
3. 到达 PHASE CHECKPOINT 必须停下，通过 AskUserQuestion 等待用户明确批准；
4. 任一步骤失败立即停止，向用户报告错误并询问如何继续，不得静默前进；
5. 只使用插件自带 Agent 或 general-purpose，无跨插件依赖；
6. 禁止自动进入计划模式，该命令本身就是计划，直接执行。

第 2 条尤其值得注意：13 个步骤每个都在.legacy-modernize/下落地一个 md 文件，形成01-legacy-assessment.md到13-documentation.md的完整审计链路，既保证可追溯，也规避了 LLM 上下文窗口丢失信息的风险。

2.2 Pre-flight：会话恢复与状态初始化

命令启动时会先检查.legacy-modernize/state.json是否存在：

• 若存在且status为"in_progress"，读取状态并向用户提供「续跑」或「重新开始（归档旧会话）」两个选项；
• 若存在且status为"complete"，询问是否归档后重新开始。

随后初始化状态文件，默认策略为parallel-systems：

{ "target": "$ARGUMENTS", "status": "in_progress", "strategy": "parallel-systems", "current_step": 1, "current_phase": 1, "completed_steps": [], "files_created": [], "started_at": "ISO_TIMESTAMP", "last_updated": "ISO_TIMESTAMP" }

$ARGUMENTS中 flags 之前的部分被解析为目标描述，记为$TARGET，贯穿后续所有子任务提示词。

2.3 五个阶段与四个 Checkpoint 全景

整个工作流共 13 步、5 个阶段，每个阶段结束都有一个强制性的 PHASE CHECKPOINT，用户只能在「批准继续 / 要求修改 / 暂停存档」三者中选择：

2.4 Phase 1：评估先行，摸清家底再动手

Step 1调用framework-migration-legacy-modernizer子代理，产出技术债清单（过时依赖与废弃 API、安全漏洞与性能瓶颈、架构反模式），并生成现代化就绪报告：组件复杂度评分（1–10）、模块间依赖映射、数据库耦合分析、快速见效项与复杂重构目标的区分，产物为01-legacy-assessment.md。

Step 2调用插件的另一位架构师 Agent —— architect-review.md（framework-migration-architect-review，覆盖 Clean Architecture、DDD、微服务、事件驱动等模式），绘制依赖图并输出集成点目录：内部模块依赖、外部服务集成、共享数据库 schema 与跨系统数据流、需要 Facade/Adapter 层的集成点、需消解的循环依赖与紧耦合，产物为02-dependency-map.md。

Step 3由general-purpose代理扮演业务分析师，产出风险矩阵与迁移路线图。其组件优先级采用加权评分公式：

(Business Value x 0.4) + (Technical Risk x 0.3) + (Quick Win Potential x 0.3)

同时为每个组件给出回滚策略与推荐迁移顺序，产物为03-business-impact.md，随后进入PHASE CHECKPOINT 1等待审批。

2.5 Phase 2：先建测试再重构——特征化测试与契约测试

Step 4覆盖度分析：用覆盖率工具找出未测试路径，对覆盖率 <40% 的组件生成特征化测试（characterization tests）——只记录当前行为、不改功能，为安全重构建立测试护栏，产物为04-test-coverage.md。

Step 5契约测试：为 API、消息队列交互、数据库 schema 建立 consumer-driven contracts，并接入 CI/CD 验证；同时生成响应时间与吞吐量的性能基线，用于验证现代化组件不破坏 SLA，产物为05-contract-tests.md。

Step 6测试数据管理：为并行运行期设计数据生成脚本（覆盖边界场景）、敏感信息脱敏、测试库刷新流程，并建立新旧组件间数据一致性监控，产物为06-test-data.md。随后进入PHASE CHECKPOINT 2。

2.6 Phase 3：绞杀榕基础设施与首波组件现代化

Step 7搭建绞杀榕基础设施：配置 API 网关在旧新组件间路由流量；用环境变量或特性管理服务建立 feature flags；实现按 URL 模式、请求头或用户分段的代理层路由规则；加入熔断器与降级兜底；创建双系统监控的可观测性看板，产物为07-infrastructure.md。

Step 8首波组件现代化：先从评估报告中识别「快速见效」组件，从遗留代码中抽取业务逻辑，用依赖注入、SOLID 原则等现代模式重写；通过 Adapter 模式保证向后兼容；用事件溯源或双写（dual writes）维持数据一致性；遵循 12-factor 原则；最后跑特征化测试验证行为未变。命令还提示：若代码库是 polyglot（多语言），可为每种语言并行启动子代理，产物为08-first-wave.md。

Step 9安全加固：实现 OAuth 2.0/JWT 认证、基于角色的访问控制、输入校验与清洗、SQL 注入与 XSS 防护、密钥管理、OWASP Top 10 合规、安全响应头与限流，并按 Critical/High/Medium/Low 输出安全审计报告，产物为09-security.md。随后进入PHASE CHECKPOINT 3，此时会向用户汇总安全发现。

2.7 Phase 4：性能对比验证与渐进放量

Step 10新旧组件对比压测：模拟生产流量模式，测量响应时间、吞吐量与资源占用；对回归项用索引、缓存、连接池、异步处理优化；并以 SLA 硬性标准验收——P95 延迟须在基线 110% 以内，产物为10-performance.md。

Step 11渐进放量计划：feature flags 按 5% → 25% → 50% → 100% 逐步切换流量；定义自动回滚触发条件（错误率 >1%、延迟 >2 倍基线或业务指标恶化）；每阶段设置 24 小时观察期；产出完整放量 runbook 与每阶段的监控查询和看板，产物为11-rollout.md。随后进入PHASE CHECKPOINT 4。

2.8 Phase 5：退役与知识沉淀

Step 12退役规划：通过流量分析验证无残留依赖（至少 30 天 0 流量）；归档遗留代码并文档化原功能；更新 CI/CD 移除遗留构建；清理废弃数据表与 API 端点；对仍保留的组件给出 sunset 时间线，产物为12-decommission.md。

Step 13文档与知识转移：产出前后架构图、带迁移指南的 API 文档、双系统运行 runbook、常见问题排查指南、经验教训报告、新系统开发者上手指南、迁移中的技术决策与取舍记录，产物为13-documentation.md。

2.9 完成态与成功标准

最后更新state.json的status为"complete"，并汇报 13 个会话文件清单。命令定义了五条可量化的成功标准：

• 所有高优先级组件现代化完成，测试覆盖 >80%；
• 迁移期间零计划外停机；
• 性能指标维持（P95 延迟在基线 110% 以内）；
• 安全漏洞减少 >90%；
• 技术债评分改善 >60%。

三、配套 Skills：把方法论沉淀为可复用模板库

插件将方法论进一步拆成四个领域 Skill，供 Agent 在对应场景直接调用：

3.1 React 现代化：react-modernization/SKILL.md

覆盖 React 16→17→18 升级路径与各版本破坏性变更（React 17 的事件委托变化、事件池移除、JSX 新转换；React 18 的自动批处理、并发渲染、StrictMode 双调用、新 root API、服务端 Suspense）。Skill 提供完整的类组件→函数组件 + Hooks 迁移代码对（状态管理、生命周期方法→useEffect、Context/HOC→自定义 Hook），以及 React 18 并发特性实战（createRoot、useTransition、flushSync、Suspense）。更完整的模式库位于其 references/details.md。

3.2 AngularJS 迁移：angular-migration/SKILL.md

对比三种迁移策略（Big Bang 全量重写、Hybrid 增量、Vertical Slice 垂直切片）的适用场景；给出 ngUpgrade 混合应用引导代码、Controller/Directive→Component、Service→@Injectable的迁移示例，以及双向桥接（downgradeInjectable与InjectionToken+useFactory）和路由迁移方案。

3.3 数据库迁移：database-migration/SKILL.md

覆盖 Sequelize / TypeORM / Prisma 三种 ORM 的迁移写法，重点讲解零停机 schema 变更三步法（新增列+回填→应用切换→删旧列）、大表类型变更的多步策略、事务型迁移与基于备份表的 Checkpoint 回滚。

3.4 依赖升级：dependency-upgrade/SKILL.md

讲解 SemVer 语义化版本规则（^/~范围差异）、依赖审计命令（npm outdated/npm audit/npx npm-check-updates）、兼容性矩阵维护、渐进升级路径（一次一个大版本、逐步验证）、jscodeshift codemod 自动化修复，以及 Renovate / Dependabot 自动更新配置。

四、延伸命令：code-migrate 与 deps-upgrade

插件还提供两个互补命令：

• code-migrate.md 是「代码迁移助手」，专注跨框架/语言/版本/平台的迁移，提供MigrationAnalyzer（复杂度评估）、MigrationPlanner（分阶段计划）、React→Vue 转换器、Python 2→3 AST 转换器、REST→GraphQL 迁移器、SQL→NoSQL 迁移器、MigrationTester（并排对比测试，含 10% 性能回归阈值）与RollbackManager（触发条件：任何 P0 功能不可用、响应时间上升 >50%、数据损坏、错误率上升 >5%）等可复用实现骨架。
• deps-upgrade.md 是「依赖升级策略」，提供依赖审计与更新分级（security 立即处理 / patch 批量 / minor 增量 / major 单独规划）、破坏性变更扫描（扫描 CHANGELOG 中的 BREAKING 关键词）、迁移指南自动生成、升级前后基线对比测试与回滚脚本。

五、使用建议与边界说明

5.1 何时使用 legacy-modernizer

• 老旧代码库需要升级框架或语言版本；
• 存在明显技术债、依赖长期未更新或有安全漏洞；
• 需要把单体拆分为微服务，但不敢一次性重写；
• 任何「既要动代码、又怕破坏现有行为」的场景。

5.2 使用前提与限制

• 该命令依赖 Task 工具与插件内置的framework-migration-legacy-modernizer、framework-migration-architect-review子代理，以及general-purpose代理，且明确要求不使用跨插件依赖；
• 整个流程要求在每个 Checkpoint 由用户明确批准，适合需要强人工把控的严肃生产环境；
• 本文所描述的步骤、策略参数、阈值与成功标准均以 legacy-modernize.md 当前仓库内容为准；不同环境下的模型能力与工具支持可能影响实际执行效果。

六、总结

framework-migration 插件以 legacy-modernizer.md 为「专家大脑」，定义了绞杀榕渐进替换、先测试后重构、保持向后兼容、文档化破坏性变更、特性开关放量五大原则与六类交付物；以 legacy-modernize.md 为「执行骨架」，固化了评估→测试→迁移→放量→退役的 5 阶段 13 步工作流与 4 个强制审批 Checkpoint；再配合四个领域 Skill 与两个辅助命令，形成了一套「有方法论、有流程、有模板、有验收标准」的完整遗留系统现代化解决方案。对于任何团队而言，这套「永远为旧行为兜底、每步都可回滚、全程留痕」的做法，正是安全完成高难度迁移的正确姿势。

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents