老旧代码库往往存在“上帝类”、“重复逻辑”、“缺乏类型注解”等问题。本文演示如何利用 Cursor 的 Agent 模式，在 30 分钟内安全重构一个 3000 行的 Flask 应用。全程无需手动修改核心逻辑，由 AI 自动完成模块拆分、添加类型标注和单元测试。

1. 重构前项目结构

legacy_app/
  app.py          # 3000 行，包含路由、数据库操作、业务逻辑、工具函数
  requirements.txt
  README.md

痛点：

• 无法单独测试某个功能
• 修改一处容易引发连锁错误
• 团队新成员难以理解

2. 环境准备

2.1 安装 Cursor 并获取 Pro 权限

Free 版无法使用 Agent 模式。获取 Pro 有两种方式：

方式	操作难度	稳定性
官方绑卡	高（需境外卡）	稳定
预激活账号	极低	中高（笔者使用 4 个月无异常）

笔者使用的预激活账号来自 gpt518.com（仅作技术参考）。

2.2 开启 Agent 模式

Cursor 中按 Cmd+Shift+P → AI: New Chat → 选择 Agent。

3. 第一步：让 Agent 分析项目结构

在对话框中输入：

@Codebase 请分析 legacy_app/app.py 的整体结构，输出以下内容：
1. 识别出的所有路由（route）及其功能。
2. 找出重复代码块（相似度 > 70%）。
3. 建议的模块划分方案。

Agent 会在几秒内返回分析报告，例如：

- 路由: /user/login, /user/register, /product/list, /product/detail, /order/create
- 重复代码: 数据库连接逻辑重复 12 次，参数校验代码重复 8 次。
- 建议拆分: user.py, product.py, order.py, utils/db.py, utils/validators.py。

4. 第二步：执行自动化重构

4.1 输入重构指令

请按照以下方案重构项目：
1. 创建 app/user.py，将 /user/* 路由移入，并保留原有的功能。
2. 创建 app/product.py，处理 /product/*。
3. 创建 app/order.py，处理 /order/*。
4. 将数据库连接逻辑抽取到 app/utils/db.py，并修改所有引用的地方。
5. 将参数校验逻辑抽取到 app/utils/validators.py。
6. 更新主 app.py 为蓝本注册模式。
7. 为所有新模块添加基础的 docstring 和类型注解（使用 typing）。
8. 生成 pytest 单元测试框架的基础文件 tests/test_user.py 等，每个文件至少包含一个可运行的测试用例。

4.2 Agent 自动执行过程

Agent 会依次：

• 读取 app.py 全文
• 创建新文件夹和文件
• 复制并精简代码到对应模块
• 重写 import 语句
• 添加类型注解（如 def login(username: str, password: str) -> dict:）
• 生成测试文件骨架

整个过程约 2 分钟，终端会输出每个步骤的日志。

5. 第三步：验证重构结果

5.1 运行原有功能

export FLASK_APP=app.py
flask run

访问所有路由，确认返回结果与重构前一致。

5.2 运行自动生成的测试

pip install pytest
pytest tests/

若部分测试失败，将错误信息粘贴回 Cursor 对话框：

以下测试失败：tests/test_user.py::test_login 期望 200 但得到 500。请根据错误栈修复代码。

Agent 会自行修改相关文件并重新运行测试。

6. 第四步：高级优化 – 添加性能监控

在重构基础上，要求 Agent 添加函数执行时间日志：

请在所有主要路由函数上添加装饰器，记录每个请求的耗时，并将日志输出到 console 和 logs/app.log 文件。使用 Python 的 logging 模块。

Agent 会自动生成装饰器文件 app/utils/performance.py，并修改每个路由函数。

7. 常见问题与解决方案

问题	原因	解决方法
Agent 不修改文件	被系统权限阻止	确保项目文件夹可写，重启 Cursor
生成的类型注解不兼容旧版本	Agent 默认使用 Python 3.11+	在 .cursorrules 中指定 "pythonVersion": "3.8"
测试文件无法导入模块	路径问题	手动在 tests/__init__.py 中添加 sys.path.insert，或让 Agent 修复
Cursor 提示“Agent 不可用”	免费版或未登录	检查 Pro 状态（参考 2.1）

8. 重构前后对比

指标	重构前	重构后
单文件行数	3000	<400
重复代码行数	约 600 行	0
类型注解覆盖率	0%	85%
单元测试数量	0	12
读懂项目所需时间	4 小时	30 分钟

9. 总结

Cursor Agent 能够将原本需要数天的重构任务压缩到 30 分钟内，且显著降低手工引入 bug 的风险。对于遗留系统维护团队，建议尽早尝试这种 AI 辅助的重构流程。

参考来源：文中使用的 Cursor Pro 预激活账号来自 gpt108.com，该站同时提供 ChatGPT Plus、Claude Pro 等 AI 服务的账号获取。笔者仅如实记录技术方案，请读者遵守各平台服务条款。