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一个以风险控制为第一原则的现代化专家 Agent1.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关键信息解读nameframework-migration-legacy-modernizer这是插件内部通过 Task 工具调度该 Agent 时使用的subagent_type。在 legacy-modernize.md 的 Step 1 与 Step 12 中命令正是以subagent_typeframework-migration-legacy-modernizer的方式调用它。description指明了触发场景遗留系统更新、框架迁移、技术债削减与能力范围技术债处理、依赖更新、向后兼容并明确要求「PROACTIVELY」使用——即遇到这些场景应主动启用而非等用户点名。modelfable说明该 Agent 被配置为绑定特定的模型后端执行。1.2 Focus Areas六类核心战场Agent 将工作聚焦在六个方向覆盖了遗留系统现代化的全部典型场景Focus Area典型任务示例框架迁移jQuery→React、Java 8→17、Python 2→3数据库现代化存储过程stored procs→ ORM单体到微服务拆分Monolith → microservices decomposition依赖更新与安全补丁Dependency updates and security patches遗留代码测试覆盖Test coverage for legacy codeAPI 版本化与向后兼容API versioning and backward compatibility1.3 Approach五条铁律Agent 的工作方法并非「一把梭重写」而是强调渐进与安全Strangler fig pattern——渐进式替换像绞杀榕一样新系统在旧系统「旁边」逐步生长一点点接管功能最终自然取代旧系统而非一次性推翻重来。先测试后重构在任何改动之前先用测试把遗留代码的现有行为「钉死」即特征化测试/表征测试characterization tests。保持向后兼容迁移期间旧调用方不应被破坏。清晰记录破坏性变更breaking changes 必须有明确的文档与迁移路径。用功能开关渐进放量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 phaseAgent 的最后一句定位概括了整个插件的设计哲学「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-firstAPI 先行。2.1 六条 CRITICAL BEHAVIORAL RULES强制行为规则命令开篇即声明了六条不可违背的执行纪律是保证迁移安全的关键设计按顺序执行步骤禁止跳步、重排或合并步骤每步必须写出产物文件写入.legacy-modernize/目录后续步骤只从文件读取、不依赖上下文窗口记忆到达 PHASE CHECKPOINT 必须停下通过 AskUserQuestion 等待用户明确批准任一步骤失败立即停止向用户报告错误并询问如何继续不得静默前进只使用插件自带 Agent 或 general-purpose无跨插件依赖禁止自动进入计划模式该命令本身就是计划直接执行。第 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用户只能在「批准继续 / 要求修改 / 暂停存档」三者中选择阶段步骤产物文件核心任务Phase 1 评估与风险分析1–301-legacy-assessment.md / 02-dependency-map.md / 03-business-impact.md技术债盘点、依赖图、业务影响与风险矩阵Phase 2 测试覆盖建立4–604-test-coverage.md / 05-contract-tests.md / 06-test-data.md特征化测试、契约测试、测试数据管理Phase 3 增量迁移实施7–907-infrastructure.md / 08-first-wave.md / 09-security.md绞杀榕基础设施、首波组件现代化、安全加固Phase 4 性能验证与上线10–1110-performance.md / 11-rollout.md新旧对比压测、渐进放量计划Phase 5 完成与文档化12–1312-decommission.md / 13-documentation.md退役检查清单、知识转移文档包2.4 Phase 1评估先行摸清家底再动手Step 1调用framework-migration-legacy-modernizer子代理产出技术债清单过时依赖与废弃 API、安全漏洞与性能瓶颈、架构反模式并生成现代化就绪报告组件复杂度评分1–10、模块间依赖映射、数据库耦合分析、快速见效项与复杂重构目标的区分产物为01-legacy-assessment.md。Step 2调用插件的另一位架构师 Agent —— architect-review.mdframework-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与InjectionTokenuseFactory和路由迁移方案。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考