用AI辅助依赖升级，先读项目清单和锁文件，分清直接依赖、间接依赖与兼容范围，再把官方迁移要求对应到实际代码。不要把“安装成功”当作升级完成：锁文件可重复安装、代码接口兼容、关键页面和测试行为稳定，才构成一次能够交付的升级。
对于本地npm项目，可以用墨刀AI客户端整理依赖关系与迁移任务。先让它读取package.json、package-lock.json和相关调用位置，形成升级计划；确认目标版本和改动范围后，再逐批修改，避免把一次库升级变成整个项目的无差别更新。
先分清三个不同的“版本”
package.json里的版本范围、锁文件里解析出的实际版本、当前node_modules里安装的版本，不一定是同一个文本。排查冲突前应同时看清楚，否则AI可能根据一个范围推断项目正在使用的版本，后续迁移建议也就失去依据。
| 材料 | 主要回答 | 容易误读的地方 |
|---|---|---|
| package.json | 项目主动声明了哪些依赖及范围 | 范围不是当前已经安装的精确版本 |
| package-lock.json | 本次解析出的依赖树与具体版本 | 一个包可能在不同依赖路径下出现多个版本 |
| 已安装依赖树 | 本地此刻实际使用了哪些包 | 手动操作或不同安装过程可能使其与期望状态不一致 |
| 官方迁移说明 | 目标版本改变了什么、需要怎样调整 | 说明可能只覆盖特定起始版本，不能跨多代直接套用 |
npm锁文件文档说明，package-lock.json记录生成的精确依赖树。升级前保留清单与锁文件的共同版本，之后才能判断哪些间接依赖跟着变化；直接删掉锁文件重新安装，会同时改变许多原本不在任务范围内的包。
一个插件为什么挡住了主库升级
下面用虚拟包名表示一种常见关系：项目想把ui-core从2.4.0升到3.0.0，但日期组件date-picker-plugin仍声明只兼容ui-core的2.x范围。
业务项目
├─ ui-core 2.4.0 → 计划升级到3.0.0
└─ date-picker-plugin 3.1.0
└─ peerDependencies: ui-core ^2.0.0如果只提高ui-core版本，插件的兼容范围没有随之改变。安装器报冲突是在提醒这组约束不一致。给AI的任务应是找出冲突链和可选方案，而不是要求“忽略报错继续安装”。
npm关于peerDependencies的说明把它用于表达包与宿主工具或库的兼容关系。它与普通直接依赖的用途不同，因此处理时要查插件自身的兼容声明及迁移资料。
- 如果插件已有兼容新主库的版本，评估两者作为同一批次升级。
- 如果插件还未兼容，判断能否推迟主库升级，或替换当前真正使用到的插件能力。
- 如果项目实际没有使用这个插件，先确认引用、动态加载和构建配置，再考虑移除；不能只因文本搜索没有命中就断言无用。
版本范围放宽，也不等于功能已经兼容。即使安装通过，日期输入、时区处理、键盘选择和旧数据展示仍可能发生变化，必须回到项目里的具体调用点检查。
先让AI给出影响地图，不急着改文件
第一轮可以限定为只读任务。准备好当前项目的依赖清单、锁文件、报错全文，以及目标库官方迁移说明；后者应明确对应哪个目标版本。没有找到资料时，就把待查项留在计划里，不让模型补出不存在的API名称。
请分析当前npm项目的一组依赖升级，先不修改文件或安装包。
目标：评估指定主库升级到指定版本的影响。
1. 从package.json与package-lock.json列出当前范围和实际版本。
2. 找出关联插件、peer依赖、运行时版本要求及相关构建工具。
3. 按引用位置列出实际用到的API或组件，不做全库功能综述。
4. 将我提供的官方迁移说明逐条对应到项目文件。
5. 输出：可同批升级的项、必须先处理的项、仍缺资料的项。
每个判断附文件路径或官方来源，不把未核实兼容性写成已支持。npm提供的npm explain可以说明某个包为什么出现在依赖树中。如果某个问题来自间接依赖，应先找到是谁引入了它，再评估上游升级、局部替代或项目已有的覆盖配置，不能简单把同名包另装到顶层就认为问题消失。
把升级拆成能解释结果的批次
批次不是机械地“一次只改一个包”。主库与关联插件可能必须一起升级，才能满足共同的兼容范围；互不相关的图标库与测试框架，则不必混在同一次变更里。
对前面的日期组件，可以把主库、日期插件和所需的适配代码放入同一批次。先在独立分支记录现有页面行为，再按官方说明修改。每完成一批，确认清单、锁文件与源码差异都能解释，再进入下一批。
| 批次 | 本批要解决的事 | 停止并调查的信号 |
|---|---|---|
| 准备 | 确定目标版本、兼容约束与现有验证方法 | 起始版本不明，或找不到对应迁移说明 |
| 关联升级 | 主库、插件及必要适配形成兼容组合 | 仍有peer冲突，或锁文件出现大量无法解释的变化 |
| 行为核对 | 检查日期输入与相关业务结果 | 构建通过，但日期、空值或事件行为改变 |
| 环境复现 | 按锁文件在项目约定环境中重复安装和验证 | 只有原开发目录成功，干净环境无法复现 |
不要把force或忽略peer约束当成固定步骤。某些特殊项目会有经过确认的兼容安排，但该安排需要真实依据与验证，不能由AI看到报错后自动选择。
升级后的检查要落在业务动作上
日期组件能显示出来，只证明最浅的一层。建议选择实际用到它的页面，分别检查初始值、选择日期、清空、禁用状态、表单校验和最终提交值。如果系统涉及跨时区日期，应加上相关场景，而不是只看本机当天日期。
对应测试也要保留旧行为约定。可以让AI根据现有代码补充有具体断言的单元测试，再查看组件升级是否改变了事件参数、默认值或格式。不要因为测试失败就先改预期，使新结果自动“通过”。
对于使用npm锁文件的项目，npm ci用于按锁文件进行安装，清单与锁文件不一致时会报错；它不会替你自动修好这组差异。实际执行仍应遵循项目的包管理器版本、安装配置与既有脚本，不把另一种锁文件体系直接改成npm。
给评审者一份能够回退的升级说明
提交评审时，写清升级原因、当前和目标版本、随同改变的插件、需要适配的业务位置、验证范围与未覆盖部分。锁文件变化较大时，说明变化来自主库依赖链还是包管理器格式，而不是一句“自动生成，不用看”。
升级目的：
本批包及当前→目标版本：
必须一起变更的兼容关系：
源码适配位置：
锁文件主要变化及原因：
已运行的项目检查与结果：
尚未覆盖的页面/环境：
回退需要恢复的清单、锁文件与源码提交：墨刀AI客户端适合帮助整理这些分散材料，把官方说明与本地调用位置对应起来。真正减少返工的，是每一批变更都能回答“为什么改、影响哪里、怎样知道结果正确”，而不是一次把所有版本号推到最新。
