跨文件重构3000行屎山，一次都没翻车

我在凌晨两点用 Cursor 0.5 Agent 模式重构了一个 3000 行的屎山，结果有点意外

说真的，那天晚上我差点把键盘砸了。

2024年12月11日凌晨两点，我盯着屏幕上一个叫 utils.py 的文件。3000行。47个函数。最长那个函数有400行，if-else 套了6层，最深处藏着一段2022年实习生写的正则表达式，注释写着“我也不知道为啥能跑，别动”。

更要命的是，这玩意儿还在生产环境上跑着。每次改这个文件，我都得先在本地跑一遍完整测试，然后部署到 staging 环境观察半小时，最后才敢上生产。同事说我这是“代码恐惧症”，我觉得这叫求生欲。

就在我准备手动拆文件的时候，Cursor 弹了个更新提示：0.5 版本，Agent 模式支持跨文件任务了。

我之前用 AI 重构代码的经历，怎么说呢，翻过车。今年8月用某个工具重构一个 Python 项目，它把我的 SQLAlchemy 模型全改成了普通类，ORM 查询直接报废。所以我对这类东西一直比较谨慎。但这个 utils.py 实在太恶心了，我决定拿它当小白鼠。

0.5 版本到底多了啥

Cursor 0.5 是12月初推的。最大的变化就一个：Agent 能从单文件编辑变成跨文件执行任务了。

0.4 版本的 Agent 只能在你当前打开的文件里改，想让它帮你把一个大文件拆成几个模块？不行。你给它说“把这个函数移到新文件里”，它会很礼貌地告诉你超出能力范围了。

0.5 版本几个关键更新：

• 能自动扫项目结构，理解模块间怎么引用的
• 一次对话能改多个文件
• 遇到复杂任务会先出计划，再执行
• 改了函数签名之后，会自动找到所有调用点同步更新

官方说多文件任务成功率从62%提到了84%，任务时间平均缩短40%。数据好看，但我更信自己测的结果。

实操一：拆那个3000行的屎山

我先用 Cursor 0.5 Agent 试了个简单的：

分析 utils.py 的代码结构，按功能模块拆分成多个文件

Agent 没直接动手，先给我吐了个分析报告。这点让我有点意外：

我分析了 utils.py，发现以下功能模块：
1. 数据处理函数 (12个) - 建议移至 data_utils.py
2. API 客户端封装 (8个) - 建议移至 api_client.py
3. 日志和格式化工具 (15个) - 建议移至 logging_utils.py
4. 验证和类型检查 (7个) - 建议移至 validators.py
5. 未分类的遗留代码 (5个) - 需进一步确认

依赖关系分析：
- api_client.py 依赖 logging_utils.py
- data_utils.py 依赖 validators.py
- 主业务代码同时引用以上所有模块

建议执行顺序：
1. 先拆分 logging_utils.py（无内部依赖）
2. 拆分 validators.py
3. 拆分 api_client.py
4. 拆分 data_utils.py
5. 最后处理遗留代码

按这个计划执行吗？

这个规划能力是0.5最实用的改进。之前0.4的时候，Agent 会直接莽上去改代码，改到一半发现 A 依赖 B 但 B 还没拆分，然后就开始胡搞。

我确认之后，它大概用了3分钟完成全部拆分。做了几件让我省心的事：

1. 每个新文件自动加了正确的 import

2. 项目里其他8个文件中所有的 from utils import xxx 都改成了新路径

3. 注释和 docstring 基本都保留了，没出现“AI吃注释”的情况

但出了个问题。

Agent 把一段“看起来没在用”的遗留代码标记成了 deprecated，直接没迁移。我跑测试的时候挂了2个 case，查了半天才发现那段代码其实在运行时被 getattr 动态调用了。Agent 的静态分析没检测到这种用法。

等等，这里我要更正一下——严格来说不是 Agent 的问题。那段代码确实没有任何静态引用，是我三年前写的一个动态加载机制在运行时才会调用它。换成任何一个基于静态分析的工具都会漏掉。这提醒我一件事：不管你用什么 AI 工具重构，必须跑完整测试。别偷懒。

实操二：Flask 转 FastAPI

第二个测试更有意思。我有个内部 API 服务，Flask 写的，1200行左右，想迁到 FastAPI。这不只是语法替换的问题，涉及到路由定义方式、请求参数验证、响应模型、异常处理，全都得改。

我给 Agent 的指令：

把这个 Flask 应用迁移到 FastAPI，保持所有端点功能不变，
为请求和响应创建 Pydantic 模型，保留现有业务逻辑

Agent 分三步走的。

第一步创建了 schemas.py，把所有请求体和响应体的 Pydantic 模型定义好。我扫了一眼，模型设计得挺合理，还自动处理了几个嵌套结构。

第二步重写主应用文件，把 Flask 路由转成 FastAPI 路由。这里有个细节让我觉得它确实理解框架差异：Flask 的 request.args.get('page', 1) 被自动转成了 page: int = Query(1)，而不是生硬地保留原写法。

第三步更新了 requirements.txt，去掉 Flask，加上 FastAPI 和 uvicorn。

整个过程大概8分钟，生成了4个文件。我跑了一遍集成测试，27个测试过了24个。

失败的3个全跟错误处理有关。Flask 默认在数据库超时时返回500错误页面，FastAPI 的异常处理链路不一样，返回的是 JSON 格式的500，但异常类型映射漏了个边edge case，导致状态码变成了502。

嗯...这个比较复杂。我翻了 FastAPI 的文档，发现是 Agent 在处理 SQLAlchemyError 的子类时，默认全映射到了 HTTPException，但 TimeoutError（我用的数据库驱动抛的是这个）没有被正确捕获。手动加了个 exception handler 解决了。

花了20分钟修这个问题。说实话，如果我自己从头写这个迁移，估计要搞一个下午，而且大概率会漏掉更多边缘情况。Agent 帮我省了大概70%的时间，剩下30%还是得靠自己。

实操三：给5年前的 Django 项目加类型注解

这个场景更贴近日常。我们团队维护着一个2019年的 Django 项目，代码一行类型注解都没有，mypy 跑一遍能报上千个错误。

我挑了个核心模块，800行左右，让 Agent 加完整类型注解：

为这个模块的所有函数添加类型注解，包括参数类型和返回值类型，
复杂类型用 typing 模块的泛型，保持代码风格一致

这次表现接近完美。

Agent 先扫了整个模块，识别出所有函数签名。然后通过分析函数体内的变量使用方式来推断类型。对于它拿不准的类型（比如 ORM 查询返回的对象），会用 Any 标注，并在旁边加注释说明。最后在文件顶部自动加了 from typing import List, Dict, Optional, Any, Union。

整个过程2分钟。跑 mypy，错误从214个降到了17个。

剩下17个错误里，12个是 Agent 推断错了类型——比如把一个可以是 None 的参数标成了非空。另外5个是真正的代码问题，函数确实可能返回不一致的类型。我花了不到10分钟全修完了。

对比一下，之前我给另一个类似规模的模块手写类型注解，花了我整整一下午，写到后面眼睛都花了。这个效率提升是数量级的。

性能表现和坑

用了一周多，我总结下 Agent 模式的实际表现：

速度：

• 单文件简单重构：10到30秒
• 多文件拆分/合并：2到5分钟
• 框架迁移：5到10分钟
• 全项目类型注解：视项目大小，800行模块大概2分钟

准确率（我自己测的）：

• 语法正确率：接近100%，我没遇到语法错误
• 逻辑正确率：大概85%到90%，看任务复杂度
• 需要人工修正的比例：10%到30%

资源消耗：

• Token 消耗挺大的，一次多文件任务可能吃掉50K到200K tokens
• 我用的 M1 Pro，处理时 CPU 占用大概30-40%
• 超大项目（100+文件）规划阶段会明显变慢

已知的坑：

• 对 Python 的动态特性支持不太好，`getattr`、`eval` 这些容易漏
• 复杂设计模式重构容易翻车（比如工厂模式改抽象工厂）
• 对测试文件比较保守，基本不会主动改测试代码——这其实算优点

我踩坑后总结的几条经验

1. 别一次性给太大任务

我犯过这个错：让 Agent 同时重构三个互相依赖的模块。它搞混了依赖关系，生成了循环引用。后来学乖了，把大任务拆小，每步确认后再继续。

2. 让它先出计划，你审过再执行

0.5的规划能力是核心优势，一定要利用。让 Agent 先分析、出方案，你觉得合理再让它动手。能避免很多“AI理解偏了”的翻车现场。

3. 测试必须跑

不管 Agent 看起来多靠谱，改完代码必须跑测试。我在案例一里差点把生产代码搞崩，就是盲目信任了 AI。现在给自己定了个规矩：Agent 改完的代码，测试覆盖率低于80%的模块我一律手动 review 一遍。

4. 配置 .cursorrules

在项目根目录建个 .cursorrules 文件，告诉 Agent 你的代码规范。我设的是：

- 所有函数必须有 docstring
- 类型注解用 Python 3.10+ 语法（list 不是 List）
- 禁止 from module import *
- 修改代码后自动跑 pytest

Agent 会严格遵守这些，省去反复纠正的麻烦。

5. 复杂业务逻辑自己搞

涉及复杂业务规则（计费逻辑、权限控制），我还是手动重构。Agent 对业务语义的理解不够深，容易在细节上翻车。机械性的工作扔给它，思考性的工作留给自己。

值不值得升？

如果你在做大量代码重构，Cursor 0.5 的 Agent 模式值得升级。多文件支持让它实用性强了一大截，从我测的三个案例看，平均能省60-70%的重构时间。

但它不是银弹。

复杂业务逻辑、大量动态特性的代码，还是需要人的判断力兜底。我现在用它的策略很简单：让 Agent 处理那些机械的、重复的、容易出错但不太需要思考的活（拆文件、加注解、框架迁移），把精力留给架构决策和业务逻辑。

话说回来，你们用 AI 重构代码的时候翻过什么离谱的车？我特别想听那种“AI自信满满改完代码，然后CI全红”的故事。上周在 V2EX 上看到一哥们说 AI 把他的数据库迁移文件全删了，理由是“检测到未使用的表结构”，我笑了整整五分钟。

评论区分享你的血泪史，我挑最惨的三位送出我整理的《Cursor Agent 模式避坑指南》。不是那种网上到处抄的官方文档翻译，是我自己踩了一周坑总结出来的东西。

#Cursor #AI编程 #代码重构 #Python #效率工具 #屎山治理