Cursor AI 使用与 Git 版本控制指南

【目标】：重构我选中的这段 Python 代码（utils.py 中的数据处理函数）
【约束】：将大函数拆分为 3 个小函数（数据清洗、数据转换、数据输出），保留原有逻辑，函数名符合驼峰式，添加类型注解
【输出格式】：完整的重构后代码 + 说明每个小函数的作用 + 指出重构的优势
【验证要求】：检查重构后代码是否能正常运行，是否有调用错误

场景 2：跨文件逻辑整合

【目标】：整合我项目中 src/utils/下的所有.py 文件，将零散的工具函数（比如时间处理、字符串处理）分类放到对应的文件（time_utils.py、str_utils.py）
【约束】：修改后自动更新所有调用这些函数的文件（比如 main.py 中导入路径），保留原有注释，不改变函数功能
【输出格式】：给出修改后的文件列表 + 每个文件的完整代码 + 说明修改的文件路径
【验证要求】：检查导入路径是否正确，给出测试代码验证所有函数可用

场景 3：性能优化

【目标】：优化我写的「批量读取 CSV 文件」的 Python 代码
【约束】：降低内存占用，提升读取速度，不使用 pandas（仅用内置库），处理大文件（10 万行）不卡顿
【输出格式】：优化后的代码 + 注释说明优化点（比如「逐行读取代替一次性读取」）+ 对比优化前后的性能数据
【验证要求】：检查代码是否能正常读取大文件，给出内存占用和读取时间的测试结果

3. AI 生成代码的「二次校验」技巧（避免 AI 出错）

AI 生成的代码可能有隐藏问题（比如适配性、逻辑漏洞），进阶操作要学会「让 AI 自查 + 工具验证」：

1. 让 AI 自检：在指令末尾加「请自查代码是否有语法错误、逻辑漏洞、依赖缺失，并给出修复方案」；
2. 多版对比：对同一个需求，换不同指令生成 2 版代码，对比逻辑和规范，选择更优的；
3. Cursor 内置校验：选中 AI 生成的代码 → 右键 →「运行代码检查」（或按Ctrl+Shift+M），Cursor 会标注语法错误/不规范的地方。

二、智能代码重构与批量优化（进阶项目级操作）

基础项目级修改你会「输入指令→复制替换」，进阶要做到「精准批量修改 + 安全可控」，核心用 Cursor 的「Edit with AI」和「AI 批量预览」功能。

1. 「Edit with AI」高阶用法（精准控制修改范围）

「Edit with AI」是 Cursor 最强大的批量修改功能，进阶用法是「精准选中 + 高阶指令」，避免修改无关代码：

操作步骤：

1. 打开项目文件夹（确保 Cursor 已索引完成）；
2. 精准选中修改范围（新手进阶技巧）：
   1. 选单个函数：鼠标拖选函数代码块（从def 函数名 (到return/函数结束）；
   2. 选多个文件：左侧资源管理器按住Ctrl（MacCmd）多选文件；
   3. 选指定目录：右键点击目录（比如src/utils）→「在资源管理器中显示」→ 确认范围；
3. 右键选中的内容 → 选择「Edit with AI」；
4. 输入「结构化高阶指令」（参考第一部分模板）；
5. 等待 AI 生成修改预览（Cursor 会标注「新增/删除/修改」的行）；
6. 分步验证：先点击「预览修改」→ 确认无误后点击「应用修改」（新手建议先备份代码）。

示例：批量优化所有 Python 函数的参数校验

【目标】：为选中的 src/utils 下所有.py 文件中的函数添加参数类型校验
【约束】：使用 Python 内置的 typing 模块，仅校验必传参数，不修改原有逻辑，添加参数缺失时的报错提示
【输出格式】：修改后的完整代码 + 注释说明校验逻辑
【验证要求】：检查报错提示是否清晰，函数运行是否正常

2. 跨文件依赖修改（避免「改了 A 漏了 B」）

新手批量修改时容易忽略「依赖关联」（比如改了函数名，没改调用处），进阶技巧：

1. 指令中明确要求「遍历所有调用该函数/模块的文件，同步修改」；
2. 修改后，在 Cursor 中按下Ctrl+Shift+F（MacCmd+Shift+F）→ 搜索修改后的函数名/路径，确认所有调用处都已更新；
3. 用「终端运行项目」验证：比如修改了utils.py中的函数名，运行main.py，看是否有「找不到函数」的报错。

3. 批量修改的「安全模式」（新手必看）

进阶批量修改的核心是「不丢代码、可回滚」：

1. 先暂存修改：修改前，在终端输入git add .（需初始化 Git，见第四部分），把代码暂存，出错可回滚；
2. 分目录修改：先改一个小目录（比如src/test），验证无误后再扩展到全项目；
3. 禁用自动应用：关闭 Cursor 设置中的「AI 自动应用修改」（设置→搜索「AI Auto Apply」→ 取消勾选），确保每次修改都手动确认。

三、自定义 Cursor 配置：打造专属工作流

基础设置你改了语言、字体，进阶要「自定义快捷键、代码片段、AI 行为」，让操作更顺手。

1. 自定义快捷键（适配你的操作习惯）

Cursor 基于 VS Code，支持自定义所有快捷键，新手优先改这 5 个高频操作：

操作步骤：

1. 按下Ctrl+K Ctrl+S（MacCmd+K Cmd+S）打开快捷键面板；
2. 在搜索框输入要修改的功能（比如「AI 续写」「格式化文档」）；
3. 右键该功能 → 选择「更改键绑定」；
4. 按下你想设置的快捷键（比如把「AI 续写」设为Ctrl+Alt+K）；
5. 点击「回车」保存，测试新快捷键是否生效。

新手必改的快捷键推荐：

2. 配置 AI 行为（控制 AI 输出风格）

你可以自定义 AI 的输出习惯，比如「默认加详细注释」「符合你的代码规范」：

1. 按下Ctrl+,（MacCmd+,）打开设置；
2. 在搜索框输入「Cursor AI」，找到以下关键设置：
   1. AI Model：选择更适合新手的「GPT-4o Mini」（响应快，适合日常开发）；
   2. AI Temperature：调为 0.2（数值越低，AI 输出越稳定，不易出错）；
   3. AI Comment Style：选择「Detailed」（默认加详细注释）；
   4. AI Code Style：输入「Python PEP8、JavaScript Airbnb」（指定代码规范）；
3. 保存设置后，AI 生成的代码会默认符合你的要求。

3. 自定义代码片段（重复代码一键生成）

新手常写重复代码（比如 Python 的函数模板、日志打印），自定义代码片段可一键生成：

操作步骤：

1. 打开设置 → 搜索「用户代码片段」→ 点击「打开用户代码片段」；
2. 选择对应的语言（比如「python.json」）；
3. 输入片段配置（示例如下），保存文件；
4. 在代码编辑区输入片段「前缀」（比如log），按Tab键即可生成代码。

示例：Python 日志打印片段

{
 "自定义日志打印": {
  "prefix": "log",
  "body": [
   "import logging",
   "",
   "# 初始化日志配置",
   "logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')",
   "logger = logging.getLogger(__name__)",
   "",
   "logger.info('$1')"
  ],
  "description": "快速生成 Python 日志打印代码"
 }
}

4. 自定义终端配置（适配开发环境）

新手常遇到「终端找不到 Python/Node.js」的问题，进阶配置终端：

1. 打开设置 → 搜索「终端」→ 找到「终端>默认配置文件:Windows」（选 PowerShell）；
2. 找到「终端>集成>Env:添加」→ 点击「编辑在 settings.json 中」；
3. 添加环境变量（比如 Python 路径）：

"terminal.integrated.env.windows": {
 "PATH": "C:\\Python39;${env:PATH}"
}

4. 重启终端，输入python --version，确认能识别 Python。

四、Git+Cursor：版本控制入门（进阶必学）

新手进阶的核心是「不丢代码、能回滚」，Git 是最常用的版本控制工具，Cursor 内置 Git 集成，操作简单：

1. 初始化 Git 仓库（第一步）

1. 打开项目文件夹 → 点击顶部「终端」→「新建终端」；
2. 输入git init（初始化仓库）→ 回车；
3. 输入git config --global user.name "你的名字"（比如「小白」）；
4. 输入git config --global user.email "你的邮箱"（随便填，比如[email protected]）；
5. 输入git add .（暂存所有文件）；
6. 输入git commit -m "初始化项目"（提交代码，备注信息）。

2. Cursor 可视化 Git 操作（不用记命令）

1. 点击左侧边栏的「源代码管理」图标（像分支的图标）；
2. 可看到所有修改过的文件：
   1. 「暂存」：点击文件右侧的「+」；
   2. 「提交」：输入提交备注，点击「√」；
   3. 「查看历史」：点击「···」→「查看提交历史」，可看到所有提交记录；
3. 回滚代码：如果修改错了，右键提交记录 →「还原更改」，即可回到之前的版本。

3. 分支管理（避免修改主代码出错）

新手改代码时，建议新建分支（比如「test」），验证无误后再合并：

1. 终端输入git checkout -b test（创建并切换到 test 分支）；
2. 在 test 分支中修改代码、测试；
3. 验证无误后，输入git checkout main（切回主分支）→ git merge test（合并分支）。

4. AI 辅助解决 Git 问题

遇到 Git 报错（比如「冲突」「暂存失败」），在 AI 面板输入：

【目标】：解决 Git 报错问题
【约束】：用新手能看懂的步骤，不要专业术语，给出每一步的终端命令
【报错信息】：xxx（粘贴你的报错信息）
【操作场景】：我在 Cursor 中修改了 utils.py 文件，提交时提示「未暂存的更改」

五、高级调试与错误排查（AI+ 工具双管齐下）

基础操作中你会让 AI 修 bug，进阶要「自己定位 bug+AI 辅助深层排查」：

1. Cursor 内置调试工具（Python 为例）

新手不用学复杂的调试技巧，掌握「断点调试」即可：

操作步骤：

1. 打开要调试的 Python 文件（比如main.py）；
2. 在代码行左侧点击（行号旁边），出现红色圆点（断点）；
3. 点击右上角「运行和调试」图标（像虫子的图标）→ 点击「创建 launch.json 文件」→ 选择「Python」→「Python 文件」；
4. 点击「启动调试」（绿色三角），代码会运行到断点处暂停；
5. 调试面板可查看：
   1. 「变量」：当前所有变量的值（比如sum=5050）；
   2. 「调用堆栈」：代码执行的路径；
   3. 「单步执行」：点击「下一步」（F10），逐行运行代码，看哪里出错。

2. AI 辅助深层 bug 排查（指令模板）

遇到「AI 第一次没修复的 bug」，用以下模板指令：

【目标】：定位并修复代码中的深层 bug
【约束】：先分析报错原因（根因），再给出修复方案，用大白话解释原因，步骤清晰
【代码】：（粘贴你的完整代码）
【报错信息】：（粘贴终端报错）
【运行场景】：（说明运行环境，比如「Python3.9、Windows10、运行命令 python main.py」）
【已尝试的解决方法】：（说明你之前改了什么，比如「我加了括号，但还是报错」）

示例：解决「模块找不到」深层问题

【目标】：定位并修复「ImportError: No module named 'utils'」报错
【约束】：先分析为什么找不到模块，再给出 2 种解决方法（新手易操作的），解释每个方法的原理
【代码】： import utils print(utils.calc_sum(1, 100))
【报错信息】：ImportError: No module named 'utils'
【运行场景】：Python3.9，Windows10，main.py 和 utils.py 在同一文件夹，运行命令 python main.py
【已尝试的解决方法】：我确认 utils.py 在同一文件夹，但还是报错

六、扩展进阶：不止装基础扩展

基础扩展你装了 Python 和拼写检查，进阶扩展能大幅提升效率，推荐以下 4 个新手友好的进阶扩展：

1. 必装进阶扩展（附安装 + 使用步骤）

2. 扩展管理技巧（避免卡顿）

• 批量禁用扩展：扩展面板→选中多个扩展→右键→「禁用」；
• 自动更新扩展：设置→搜索「扩展>自动更新」→ 勾选「启用自动更新」；
• 扩展同步：登录 Cursor 账号→设置→搜索「同步」→ 勾选「扩展」，多设备同步扩展和配置。

七、进阶练习（动手巩固）

1. 练习 1：用「结构化指令」让 AI 写一个「学生成绩管理系统」（Python），要求分函数、加参数校验、带注释，并用 Git 提交代码；
2. 练习 2：用「Edit with AI」批量修改该系统的所有函数，添加日志打印功能，验证所有函数运行正常；
3. 练习 3：自定义一个「学生成绩录入」的代码片段，输入score按 Tab 一键生成；
4. 练习 4：用断点调试排查「成绩计算错误」的 bug，并用 AI 分析根因。

总结

Cursor 的进阶操作核心是「精准控制 AI」「安全管理代码」「自定义工作流」，不用贪多，先掌握「高阶指令模板」和「Git 版本控制」，再逐步学习调试和扩展配置。记住：进阶的关键是「多练 + 验证」，每改一行代码都要运行验证，出错了先用 Git 回滚，再让 AI 分析原因。