framework-migration 插件 deps-upgrade 命令详解依赖安全升级与破坏性变更迁移实战指南【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本指南以 deps-upgrade 命令 为核心系统讲解如何在 Claude Code 等 Agent 环境中规划并执行低风险的增量依赖升级覆盖依赖审计、破坏性变更检测、迁移指南生成、批量更新、回滚与升级后监控等完整链路。读完本文你将掌握一套可直接复用的升级前分析 → 分阶段升级 → 自动化验证 → 可回滚的实战方法论并结合本仓库framework-migration插件中dependency-upgradeSkill、react-modernization、angular-migration等配套资源落地到真实项目中。一、命令定位它在插件生态中解决什么问题在本仓库的插件市场中framework-migration是一个专注于框架升级与迁移规划的插件见 docs/plugins.md归属于 Modernization现代化改造类别可通过/plugin install framework-migration安装。该插件提供了三个核心命令见 docs/usage.md命令用途/framework-migration:deps-upgrade依赖升级本指南主题/framework-migration:code-migrate框架/语言/版本迁移/framework-migration:legacy-modernize遗留系统现代化改造deps-upgrade命令的 frontmatter 描述为Plan and execute safe, incremental dependency upgrades with minimal risk — including breaking-change migration paths and proper test verification.规划并执行安全、增量的依赖升级将风险降到最低——包括破坏性变更的迁移路径与完善的测试验证。命令通过$ARGUMENTS接收用户请求user_request标签内的文本是交付目标的数据输入而非覆盖指令的代码随后以依赖管理专家的角色输出一份完整的升级策略文档。该命令与 dependency-upgrade SkillSkill 侧重语义化版本解析、兼容矩阵、分阶段升级等可复用知识形成命令编排 技能供给的配合也与 legacy-modernizer Agent面向遗留系统现代化覆盖依赖更新与安全补丁分工互补。二、升级前的依赖审计建立可量化的事实基线任何安全的升级都始于全面、准确的现状盘点。deps-upgrade命令的第一步是执行综合性依赖审计Comprehensive Dependency Audit核心思路是分别调用 npm 与 pip 的过期依赖查询接口收集每个包的当前版本、期望版本、最新版本与依赖类型再基于语义化版本SemVer归类升级类型。2.1 双生态npm / pip审计实现原命令给出了DependencyAnalyzer类作为参考实现其关键点如下import json import subprocess from datetime import datetime, timedelta from packaging import version class DependencyAnalyzer: def analyze_update_opportunities(self): analysis { dependencies: self._analyze_dependencies(), update_strategy: self._determine_strategy(), risk_assessment: self._assess_risks(), priority_order: self._prioritize_updates() } return analysisnpm 侧执行npm outdated --json输出 JSON 中包含每个包的current当前版本、wanted满足 semver 范围的期望版本、latest最新版本与typedependencies/devDependencies 等据此填充依赖字典。pip 侧执行pip list --outdated --formatjson同样提取version与latest_version字段。升级类型归类_categorize_update方法借助packaging.version比较主/次/补丁版本号def _categorize_update(self, current_ver, latest_ver): try: current version.parse(current_ver) latest version.parse(latest_ver) if latest.major current.major: return major # 大版本通常含破坏性变更 elif latest.minor current.minor: return minor # 次版本向后兼容的新功能 elif latest.micro current.micro: return patch # 补丁向后兼容的缺陷修复 else: return none except: return unknown2.2 审计命令的实操对照与 dependency-upgrade Skill 中给出的命令行操作相互印证日常可直接执行# npm npm outdated # 查看过期依赖 npm audit # 安全漏洞审计 npm audit fix # 自动修复可安全修复的漏洞 # yarn yarn outdated yarn audit # 检查大版本更新 npx npm-check-updates npx npm-check-updates -u # 更新 package.json 中的版本声明同时该 Skill 补充了依赖树分析的实用命令用于回答这个包为什么被安装npm ls package-name # 查看包的安装链路 yarn why package-name npm dedupe / yarn dedupe # 查找并合并重复包 npx madge --image graph.png src/ # 可视化依赖关系图2.3 语义化版本SemVer是风险分级的基石审计中的major/minor/patch分级完全建立在语义化版本规则之上。dependency-upgradeSkill 对此给出了精炼总结MAJOR.MINOR.PATCH例如 2.3.1 MAJOR: 破坏性变更Breaking changes MINOR: 新功能向后兼容 PATCH: 缺陷修复向后兼容 ^2.3.1 2.3.1 3.0.0允许 minor 更新 ~2.3.1 2.3.1 2.4.0仅允许 patch 更新 2.3.1 精确锁定版本理解这三类升级的兼容性语义是后续哪些可以自动合并、哪些必须人工评审决策的依据。三、破坏性变更检测升级前先排雷大版本升级的核心风险来自破坏性变更Breaking Changes。deps-upgrade命令的BreakingChangeDetector类给出了一套系统化检测流程拉取变更日志通过_fetch_changelog(package_name, current_version, target_version)获取两版本之间的 CHANGELOG 文本正则扫描破坏性关键词对 changelog 逐条匹配BREAKING CHANGE:、BREAKING:、removed、deprecated、no longer、renamed、moved to、replaced by等模式并利用_extract_context提取命中点上下文存入api_changes框架特定检测对react、webpack等主流框架执行专项检查工作量估算综合以上信息调用_estimate_effort给出estimated_effortlow/medium/high。3.1 React 专项版本间破坏性变更速查原命令内置了 React 15→16→17→18 的迁移要点可作为变更检测的领域知识参考React 15 → 16PropTypes 拆分到独立包、React.createClass弃用、String refs 弃用——migration_required TrueReact 16 → 17事件委托机制变化、移除事件池No event pooling、effect 清理时机变化React 17 → 18自动批处理Automatic batching、更严格的 StrictMode、Suspense 变化、新的 Root API——migration_required True。这些条目与 react-modernization Skill 中的 React 16 → 17 → 18 升级路径 章节完全一致该 Skill 还补充了 React 18 的createRoot新根 API、flushSync退出批处理、useTransition过渡与 Suspense 数据获取等改造示例说明本仓库将变更检测与具体改造代码通过 Skill 层层展开了。3.2 变更检测的现场操作在真实升级前dependency-upgrade Skill 建议直接核对 CHANGELOG 与 MIGRATION 文档例如curl拉取框架官方 CHANGELOG并结合 npm 的 peer 依赖告警交叉验证兼容性。四、迁移指南生成让升级过程可复制、可执行检测出破坏性变更后deps-upgrade命令通过generate_migration_guide函数为每个大版本升级自动生成一份分步迁移指南Migration Guide。这份指南的骨架固定包含Overview升级起止版本、预计耗时、风险等级、破坏性变更数量Pre-Migration Checklist测试套件通过、Git 提交点/备份、依赖兼容性检查、团队通知Migration Steps六步流程详见下文Rollback Plan一键回滚命令Common Issues Solutions常见问题清单Resources官方迁移指南、Changelog、社区讨论链接。4.1 迁移步骤模板Step 1–6# Step 1: Update Dependencies git checkout -b upgrade/{package_name}-{target_version} npm install {package_name}{target_version} # 如需更新 peer dependencies追加生成命令 # Step 2: Address Breaking Changes → 依据检测结果逐条修复 # Step 3: Update Code Patterns → 生成代码更新建议 # Step 4: Run Codemods (if available) → 运行官方 codemod 自动改写 # Step 5: Test Verify npm run lint npm test npm run type-check # 并附手工测试清单 # Step 6: Performance Validation → 生成性能核验项4.2 Rollback Plan回滚计划# 方式一还原清单文件后重新安装 git checkout package.json package-lock.json npm install # 方式二删除升级分支回到主线 git checkout main git branch -D upgrade/{package_name}-{target_version}4.3 Codemod 与自定义迁移脚本官方迁移指南通常提供自动化改写工具。dependency-upgradeSkill 给出了 jscodeshift 的完整用法含 TSX 解析与 dry-run 预览# 运行 jscodeshift transform示例重命名不安全生命周期方法 npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js src/ # TypeScript 文件需要指定解析器 npx jscodeshift -t transform-url --parsertsx src/ # Dry run 预览改动而不写入 npx jscodeshift -t transform-url --dry src/当没有现成 codemod 时Skill 也提供了自定义迁移脚本模式基于fsglob批量替换旧 API 与 import 语句。这与 code-migrate 命令 中迁移规划 → 分阶段执行 → 双运行时 → 测试验证的思路一致两者互为补充。五、增量升级策略拒绝一次升到底deps-upgrade命令强调不要一次升级所有东西Dont upgrade everything at once!其IncrementalUpgrader类负责规划安全、可停靠的增量升级路径_get_versions_between枚举当前版本与目标版本之间的全部版本_identify_safe_versions识别安全停靠版本safe stopping points判定标准包括每个 minor 版本的最后一个 patch_is_last_patch具备较长稳定期的版本_has_stability_period处于重大 API 变更之前的版本_is_pre_breaking_change_create_upgrade_path基于安全版本构建升级路径并为每一步生成风险等级、破坏性变更摘要、升级命令、测试命令如npm test -- --updateSnapshot、验证命令npm run integration-tests与测试关注点。5.1 分阶段升级实操dependency-upgradeSkill 将增量升级拆为三个阶段# Phase 1: Planning规划 npm list --depth0 # 1. 盘点当前版本 # 2. 阅读 CHANGELOG.md 与 MIGRATION.md 检查破坏性变更 # 3. 制定升级顺序如TypeScript → React → React Router → 测试库 → 构建工具 # Phase 2: Incremental Updates逐包升级每次只动一个 npm install typescriptlatest npm run test npm run build # 每步升级后立即测试 npm install react17 react-dom17 # 大版本一次只跨一个 major npm run test npm install react-router-dom6 # 继续处理其他包 # Phase 3: Validation验证5.2 兼容性守护测试Skill 还提供了一个轻量级的兼容性测试模式用于在 CI 中常驻守护依赖一致性// tests/compatibility.test.js describe(Dependency Compatibility, () { it(should have compatible React versions, () { const reactVersion require(react/package.json).version; const reactDomVersion require(react-dom/package.json).version; expect(reactVersion).toBe(reactDomVersion); }); it(should not have peer dependency warnings, () { // Run npm ls and check for warnings }); });六、自动化测试策略用基线对比验证升级无回归升级成功与否不能靠看起来能跑而要靠升级前后测试基线对比。deps-upgrade命令给出upgrade-tests.js的参考框架将测试分为三层6.1 基线捕获与对比const testSuite { preUpgrade: async () { // 捕获基线单元测试、集成测试、e2e 测试、性能指标、bundle 体积 const baseline { unitTests: await runTests(unit), integrationTests: await runTests(integration), e2eTests: await runTests(e2e), performance: await capturePerformanceMetrics(), bundleSize: await measureBundleSize() }; return baseline; }, postUpgrade: async (baseline) { // 升级后运行同一批测试并对比 const results { /* 同上五项 */ }; const comparison compareResults(baseline, results); return { passed: comparison.passed, failures: comparison.failures, regressions: comparison.regressions, // 回归项 improvements: comparison.improvements // 改善项 }; }, smokeTests: [ async () { await testCriticalUserFlows(); }, // 关键用户路径 async () { await testAPICompatibility(); }, // API 兼容性 async () { await testBuildProcess(); } // 构建流程 ] };6.2 各层级测试的具体形态dependency-upgradeSkill 为单元/集成/视觉回归/E2E 四类测试提供了模板单元测试升级前后npm run test必须保持通过测试工具链本身也要升级如npm install testing-library/reactlatest集成测试验证应用可渲染、可导航render(App /)、fireEvent.click(...)视觉回归测试toMatchSnapshot()快照比对E2E 测试以 Cypress 为例完成登录 → 提交表单 → 跳转仪表盘的用户流验证。七、兼容性矩阵跨依赖冲突的显式化管理升级单个包时其 peerDependencies 往往约束着其他包必须处于特定版本范围。deps-upgrade命令的generate_compatibility_matrix函数为每个待升级依赖生成一张矩阵matrix[dep_name] { current: dep_info[current], target: dep_info[latest], compatible_with: check_compatibility(dep_name, dep_info[latest]), conflicts: find_conflicts(dep_name, dep_info[latest]), peer_requirements: get_peer_requirements(dep_name, dep_info[latest]) }最终以 Markdown 表格输出| Package | Current | Target | Compatible With | Conflicts | Action Required | |---------|---------|--------|-----------------|-----------|-----------------|check_compatibility读取目标版本的 peerDependencies与当前已安装版本做satisfies_version_range校验无冲突标 ✅ Safe to upgrade有冲突标 ⚠️ Resolve conflicts first。dependency-upgradeSkill 以 React 生态为例给出了可读的兼容矩阵范式16.x/17.x/18.x 分别对应的 react-dom、react-router-dom、testing-library/react 版本要求并提示 peer 依赖问题在 npm 7 默认严格校验必要时可用--legacy-peer-deps忽略或--force覆盖。八、回滚策略为每一次升级买保险无论前期分析多充分升级都可能失败因此回滚必须预先就绪。deps-upgrade命令提供了rollback-dependencies.sh参考脚本包含三个函数# 1. create_rollback_point —— 升级前创建回滚点 create_rollback_point() { cp package.json package.json.backup cp package-lock.json package-lock.json.backup git tag -a pre-upgrade-$(date %Y%m%d-%H%M%S) -m Pre-upgrade snapshot # 若存在 database-backup.sh 则同时备份数据库 } # 2. rollback —— 失败时一键回滚 rollback() { mv package.json.backup package.json mv package-lock.json.backup package-lock.json rm -rf node_modules npm ci # 按锁文件干净重装 npm test # 回滚后立即测试 } # 3. verify_rollback —— 回滚后验证 verify_rollback() { npm run test:critical curl -f http://localhost:3000/health || exit 1 }dependency-upgradeSkill 则给出了基于 Git 分支的回滚流git checkout -b upgrade-branch尝试升级测试失败则git checkout main git branch -D upgrade-branch npm install从锁文件还原。两种方案理念一致回滚点是前置动作验证是回滚的必要收尾。九、批量更新策略按风险分组、分优先级执行当项目依赖较多时逐个升级效率过低但一刀切全部升级风险过高。deps-upgrade命令的plan_batch_updates函数给出分组策略先按has_security_vulnerability与update_type将依赖分为四组再按优先级生成批次批次优先级内容策略测试强度Batch 1CRITICAL安全漏洞依赖immediate立即full完整回归Batch 2HIGHpatch 更新grouped分组smoke冒烟Batch 3MEDIUMminor 更新incremental增量regression回归Batch 4LOWmajor 更新individual逐个comprehensive全面这一分组逻辑体现了升级优先级排序的核心思想安全漏洞 补丁 次版本 主版本。主版本major破坏性变更最多必须逐个、规划后、全面测试地处理。十、框架专项升级Angular / React / Vue 的官方路径deps-upgrade命令的framework_upgrades字典预置了三大主流前端框架的升级操作指引将通用方法论落到具体命令10.1 Angular基于ng updateangular: { upgrade_command: ng update, pre_checks: [ ng update angular/core{version} --dry-run, # 先演练 npm audit, ng lint ], post_upgrade: [ ng update angular/cli, npm run test, npm run e2e ], common_issues: { ivy_renderer: Enable Ivy in tsconfig.json, strict_mode: Update TypeScript configurations, deprecated_apis: Use Angular migration schematics } }10.2 Reactnpm codemodreact: { upgrade_command: npm install react{version} react-dom{version}, codemods: [ npx jscodeshift -t react-codemod/rename-unsafe-lifecycles.js src/, npx jscodeshift -t react-codemod/error-boundaries.js src/ ], verification: [ npm run build, npm test -- --coverage, npm run analyze-bundle ] }10.3 Vuevue-codemodvue: { upgrade_command: npm install vue{version}, migration_tool: npx vue-codemod -t transform path, breaking_changes: { 2_to_3: [Composition API, Multiple root elements, Teleport component, Fragments] } }10.4 仓库配套的框架迁移 Skill本插件还为更大规模的框架迁移提供了两个专项 Skill见 framework-migration 插件目录angular-migration SkillAngularJS 1.x → Angular 2 的完整迁移方案包括大爆炸Big Bang、混合增量Hybrid基于 ngUpgrade、垂直切片Vertical Slice三种策略以及 Controller/Directive/Service 到 Angular 组件与依赖注入downgradeInjectable、InjectionToken的逐类转换示例、路由迁移对照react-modernization SkillReact 16→17→18 升级、类组件到 Hooks 的迁移state/生命周期/Context/HOC、React 18 并发特性createRoot、自动批处理、useTransition、Suspense的落地代码。配合 legacy-modernizer Agent 强调的Strangler fig 模式渐进替换 重构前补测试 保持向后兼容 功能开关渐进发布 清晰记录破坏性变更五原则可从升级一个包延伸到改造整个遗留系统。十一、升级后监控用阈值守护线上稳定升级合并只是开始上线后的持续监控才能确认没有引入性能与稳定性回归。deps-upgrade命令的post-upgrade-monitoring.js提供了一套阈值化的健康检查配置const monitoring { metrics: { performance: { page_load_time: { threshold: 3000, unit: ms }, // 页面加载 api_response_time:{ threshold: 500, unit: ms }, // API 响应 memory_usage: { threshold: 512, unit: MB } // 内存占用 }, errors: { error_rate: { threshold: 0.01, unit: % }, // 错误率 console_errors: { threshold: 0, unit: count } // 控制台错误 }, bundle: { size: { threshold: 5, unit: MB }, // bundle 体积 gzip_size: { threshold: 1.5, unit: MB } // gzip 后体积 } }, // checkHealth: 遍历所有指标value threshold 记为 PASS否则 FAIL // generateReport: 输出 ## Post-Upgrade Health Check 指标表✅/❌ };checkHealth对每个指标比较实测值与阈值并返回 PASS/FAILgenerateReport将其渲染为 Markdown 表格便于直接写入升级报告或观察看板。十二、输出格式一份完整的升级交付物deps-upgrade命令要求最终产出覆盖八个模块这也构成了升级任务的验收清单Upgrade Overview可用升级汇总 风险评估Priority Matrix按重要性与安全性排序的更新清单Migration Guides每个 major 升级的分步指南Compatibility Report依赖兼容性分析Test Strategy验证升级的自动化测试方案Rollback Plan明确的回退流程Monitoring Dashboard升级后健康指标Timeline切合实际的升级实施排期。整体原则是聚焦安全、增量的升级在保持依赖更新与安全的同时始终以系统稳定性为第一优先Focus on safe, incremental upgrades that maintain system stability while keeping dependencies current and secure.。十三、把方法论接入你的工作流在安装了framework-migration插件后你可以直接在 Claude Code 中这样调用# 通过 slash command 显式触发 /framework-migration:deps-upgrade 升级项目依赖到最新稳定版重点处理 React 18 与 Webpack 5 的破坏性变更 # 或通过自然语言让 Agent 自行选择 帮我规划一次安全的依赖升级包含风险分级、迁移指南和回滚方案命令会遵循本文所述流程输出完整的升级策略文档对于更复杂的框架级迁移跨框架、跨语言、跨版本平台可进一步使用 code-migrate 命令若目标是整库现代化改造则参考 legacy-modernize 命令 提供的 13 步、5 阶段、带 4 个检查点的强约束工作流含.legacy-modernize/会话状态文件与 strangler fig 基础设施搭建。最后提醒以上所有命令、代码片段与配置均来自本仓库framework-migration插件的真实内容是面向 Claude Code / Codex / Cursor 等 Agent 环境的提示词级参考实现——使用时请根据你项目的实际依赖生态npm/yarn/pnpm、pip/uv 等、包管理器版本与团队约定做适配切勿不经调整地直接套用。【免费下载链接】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），仅供参考