跨文件重构最难处理的，往往不是某一行代码，而是改动会扩散到哪里。一次依赖升级，可能同时牵动导入路径、类型定义、封装层和测试。Agent 如果收到一句“全部迁移”就直接动手，补丁很快会变大，开发者却很难判断问题从哪一步开始。
先把“V5”说清楚
现有可引用材料中，v5 指的是 AI SDK v5，不是已经得到官方资料确认的 Cursor V5 产品版本。
2025 年 11 月 16 日，Ray Fernando 发布了视频 Cursor Agent Window: AI SDK v5 Migration First Try。他在视频说明中提到，这次依赖迁移被搁置了 2 个月，因为这类升级经常带来破坏性改动；Cursor 推出 Agent Window 和 Plan Mode 后，他尝试用它们完成一次真实的 AI SDK v4 到 v5 迁移。
Cursor 官网把产品定位为 AI coding agent，并列出了 Agents、Tab 和 Changelog 等入口。基于现有资料，可以讨论 Agent Window 和 Plan Mode 如何参与重构，但无法确认所谓“Cursor V5”是否强制启用计划流程，也不能把自动创建临时分支、自动标记所有引用写成已经确定的产品能力。
计划先过人这一关
Plan Mode 最实用的地方，是在代码变化之前先生成一份可审查的任务清单。开发者可以先给 Agent 一条明确限制：暂时不要修改文件，只检查仓库并说明准备怎么做。
例如，处理 AI SDK v4 到 v5 迁移时，可以这样提要求：
先不要修改代码。请检查当前仓库，并列出：
- AI SDK v4 的直接引用位置
- 可能受影响的封装层、调用方和测试
- 建议的修改顺序
- 仓库中已有的验证命令
- 暂时无法确认的风险点
等待我确认计划后再开始修改。
这份计划的价值不在于格式整齐，而在于开发者可以删掉某一步、缩小范围，或者要求 Agent 重新检查遗漏。遇到无法判断的地方，也应该明确标成未知项，不能为了让清单显得完整而编造文件路径、行号或测试命令。
别让计划只剩四句空话
“升级依赖、修复类型、运行测试、更新文档”看起来像计划，其实几乎不能指导执行。真正有用的清单，至少要回答几个具体问题：
- 改动边界在哪里：只处理迁移必须修改的代码，还是顺便清理旧封装？
- 兼容要求是什么：旧调用方式需要暂时保留，还是可以同步删除？
- 怎样判断完成：运行哪些现有测试、类型检查或构建命令？
- 什么情况应该停下：出现新的运行时错误，还是发现迁移范围超出预估？
对依赖迁移来说，通常可以先处理依赖声明和编译错误，再检查封装层与调用位置，最后更新测试和示例。具体顺序仍要服从仓库现状，不能套用固定模板。
小步改，Git 来兜底
分支隔离不必包装成 Cursor 的自动能力，它本来就是 Git 该承担的工作。
确认计划后，可以先建立迁移分支，只授权 Agent 处理一批能够独立验证的改动。补丁生成后查看 Diff，运行仓库已有的检查命令；结果符合预期，再提交这一批。如果测试失败或改动越界，就回到上一个提交点，而不是让 Agent继续在错误基础上追加修改。
一个提交最好只表达一个可验证的意图，例如更新依赖、调整一组调用方，或者补齐相关测试。依赖升级、格式化和无关重构混在同一个补丁里，会让审查和回滚都变得困难。
Diff 里要找的是风险
Diff 审查不能只看代码能否通过编译。跨文件迁移更需要检查行为有没有悄悄变化：
- 函数参数、返回值和异步处理方式是否改变；
- 导入路径、封装函数和调用方是否保持一致；
- 兼容层是否被过早删除；
- 测试是否覆盖了新调用路径，而不只是继续运行旧用例；
- 锁文件、生成代码和配置是否出现了无关变动。
如果一个补丁同时夹带大面积格式化或无关清理，可以让 Agent 重新生成更小的修改。补丁越聚焦，开发者越容易说明每个文件为什么要改。
Plan Mode 不是保险单
计划仍可能漏掉运行时配置、动态导入、代码生成结果，以及只存在于团队约定里的限制。现有素材也没有提供可核验数据，证明 Plan Mode 能把测试失败率降低到某个具体幅度。
所谓 Agentic Workflow，落到代码库里就是几个明确的检查点：计划要经过确认，补丁要经过 Diff 审查，改动要通过现有测试，提交还要能够回滚。Cursor 可以承担搜索、整理和重复修改，范围、兼容要求与最终合并仍由开发者决定。
对于 AI SDK v4 到 v5 这类迁移，速度不是唯一指标。每改一个文件，都应该能回答三个问题：为什么改、如何验证、出错后怎么撤回。能回答清楚，Agent 生成的代码才真正具备合并条件。
