AI编程 -- Cursor环境配置和简单使用

Cursor 完整使用指南（Windows版）

适用对象：软件工程师、嵌入式开发者、FPGA工程师等需要日常编程的从业者
环境：Windows 10/11，PowerShell 5+
版本：Cursor 4.x（文中截图基于2025年初版本，界面可能略有更新）

1. 核心概念

1.1 三种工作模式

Cursor 提供了三种不同的AI交互模式，适用于不同场景：

模式	快捷键	适用场景	不适用场景
Chat	Ctrl+L	分析现有代码、局部修改、问答	创建新项目
Composer	Ctrl+I	从零创建项目、多文件重构	已有项目的局部修改
Agent	Ctrl+K	复杂多步骤任务（终端操作、文件搜索）	简单问答

理解这三种模式的边界是高效使用Cursor的第一步。大多数日常开发场景下，Chat模式是首选；Composer仅在你需要从零搭建项目时使用；Agent用于需要执行系统命令的复杂任务。

1.2 上下文引用系统

Cursor 最强大的能力之一是上下文引用（Context Reference）。在prompt中引用项目代码，AI才能给出准确的回答；不引用上下文，AI可能生成与项目完全不相关的代码。

引用方式：在prompt中输入 @ 触发引用菜单：

引用符号	功能	触发方式
@codebase	整个项目的所有代码	输入 @codebase
@file	当前打开的文件	输入 @file
@folder	指定文件夹	输入 @folder 后选择
@docs	官方文档	输入 @docs
@web	联网搜索最新信息	输入 @web

最佳实践：始终使用 @codebase 开启对话，让AI基于项目实际代码思考。Chat模式下每次新对话都需要重新引用。

1.3 AGENTS.md

在项目根目录创建 AGENTS.md 文件，可以为Cursor提供项目级指令。Cursor会自动读取该文件，并将其作为对话的全局上下文。

# 本项目是STM32 USB HID固件
## 技术栈
- 固件语言: C (Keil MDK)
- 架构: HAL库
## 规范
- 代码风格: Linux内核风格（Tab缩进，括号换行）
- 文件命名: 小写字母+下划线
## 约束
- 禁止修改中断向量表
- 禁止修改启动文件（startup_xxx.s）

这样设置后，每次对话AI都会遵循这些规范，不需要每次prompt都重复说明。

2. 配置与环境

2.1 Pro试用续期

Cursor Pro提供更强大的模型（Claude 3.7/3.5 Sonnet等），免费试用有两周500次请求限制。

方法一：注销并重新注册同一邮箱账号（可多次使用）

1. Account Setting → Delete Account
2. 用相同邮箱重新注册
3. 登录后恢复500次额度

方法二：当账号MAC被Cursor记录后，使用go-cursor-help工具刷新MAC

# https://github.com/yuaotian/go-cursor-help
# 下载后运行，自动刷新MAC并重新激活试用

2.2 禁用自动更新

新版Cursor可能与现有功能不兼容，建议禁用自动更新。使用前述go-cursor-help工具同样可以锁定版本：

工具说明：目前go-cursor-help适配到Cursor 4.7，需禁用Cursor自动更新至4.8以上版本。

2.3 模型区域限制问题

部分地区直接访问Anthropic API存在限制，导致模型不可用。解决方案：

1. 配置代理：在Cursor Settings → Proxy中填写梯子端口（如 127.0.0.1:7890）
2. 禁用HTTP/2：勾选 Advanced → Network → Disable HTTP/2

注意：梯子推荐使用GitHub free-proxy获取，每日免费使用约4小时。

2.4 模型选择

Cursor支持多种AI模型，按场景选择：

模型	特点	适用场景
Claude 3.7 Sonnet	最新最强，擅长复杂推理	多文件重构、架构设计
Claude 3.5 Sonnet	平衡性能与成本	日常代码修改
GPT-4o	快速响应	简单问答
Claude 3 Opus	超长上下文	超大代码库分析

在Chat右上角的下拉菜单中切换模型。日常开发推荐使用Claude 3.5 Sonnet，复杂任务切换到3.7。

3. Chat模式详解

Chat是Cursor最核心的模式，适用于90%以上的日常开发场景。

3.1 分析项目代码

场景：理解一个陌生项目的架构，或者在现有项目中找到特定功能的实现位置。

# 示例prompt
@codebase 分析这个项目的整体架构，重点关注数据流向。
找出USB HID设备枚举的代码在哪里？

操作步骤：

1. Ctrl+L 打开Chat面板
2. 模型选择 Claude 3.5 或 3.7
3. 输入 @codebase 后输入问题
4. 阅读AI回答，如有需要继续追问

3.2 局部代码修改

场景：修改某个函数的实现逻辑、修复bug、添加日志。

# 示例prompt
@folder/src 修改usbd_conf.c中的HAL_PCD_SetupStageCallback函数，
在其中添加一行日志打印当前_setup请求的bmRequestType和bRequest字段

操作步骤：

1. 选中需要修改的代码（或不选，由AI自动定位）
2. Ctrl+L 打开Chat
3. 输入修改要求
4. AI生成修改后，点击 “Accept” 或 “Reject”

修改结果以Git diff形式展示，可以逐文件确认是否接受：

重要：如果修改不符合预期，点击 “Reject” 拒绝更改，如同Git GUI一样。之后可以在终端中 git diff 查看具体差异。

3.3 结合Web搜索

对于需要最新信息的查询（如某库的最新API、某工具的安装方法），使用 @web 触发联网搜索：

# 示例prompt
@web 查找2025年最新的FreeRTOS LTS版本号，以及新增的主要特性

3.4 调试错误信息

将编译器/运行器的错误信息粘贴给AI，让它分析原因：

# 示例prompt
@codebase 以下是Keil MDK编译报错信息，分析问题原因并给出修复方案：

C:\project\src\main.c(45): error: #20: identifier "HAL_GPIO_Init" is undefined

4. Composer模式详解

4.1 何时使用

Composer适合以下场景：

• 从零创建新项目：项目目录为空，需要AI帮你创建目录结构、配置文件、源代码
• 大规模多文件重构：需要同时修改多个文件且这些修改相互关联
• 创建新模块：新增一个完整的功能模块

4.2 何时避免使用

Composer 不适合 已有项目中的局部修改。原因：

1. Composer的改动会跨越多个文件，可能意外覆盖已有正常工作的代码
2. Composer倾向于重写而非增量修改
3. 对已有项目的修改需求，Chat模式更精准、更安全

最佳实践：如果需要在已有项目中创建新内容（如新增一个驱动模块），先用Composer创建独立文件，再切换到Chat模式与现有代码集成。

4.3 Composer使用示例

# 示例prompt
创建一个基于STM32F4的串口bootloader项目，要求：
1. 使用HAL库
2. 支持USART1，波特率115200
3. 包含YMODEM协议的文件传输功能
4. 支持跳转到用户程序起始地址
5. 添加看门狗防止升级过程跑飞

在Composer中，AI会：

1. 创建 Core/ 目录（Startup、Src、Inc）
2. 生成 linker script
3. 创建 Makefile 或 .uvprojx
4. 实现 bootloader 主体逻辑

强烈建议：使用 Git分支 管理Composer生成的内容。每次Composer大规模修改前，创建新分支确认无误后再合并。

4.4 与Web资料结合

Composer生成代码后，可能存在不符合最新规范的问题。此时需要给AI提供最新的参考文档：

请参考以下规格文档设计USB HID报告描述符：
@web 查找USB HID协议1.11版本的报告描述符规范

同时参考Wireshark USB抓包文件（已上传到项目根目录/usb_capture.pcapng）

5. Agent模式详解

Agent是Cursor最强大的模式，可以自主执行终端命令、创建和编辑文件、搜索代码库，适合需要多步骤操作的任务。

5.1 激活Agent

在Composer界面中点击右上角的 “Agent” 按钮切换到Agent模式（快捷键 Ctrl+K）。

5.2 典型使用场景

任务	Agent行为
创建完整项目	Agent自动创建目录、写文件、初始化Git
批量代码重构	Agent自动搜索目标文件并修改
安装依赖并配置	Agent执行npm/pip install并修改配置文件
运行测试并修复	Agent运行测试、读错误、重写代码

5.3 终端命令执行

Agent可以直接在Windows终端（PowerShell）中执行命令：

# Agent可能执行的操作
npm install pdfplumber
git checkout -b feature/new-module
vivado -mode batch -source build.tcl

5.4 注意事项

• 高风险操作会请求确认：删除文件、重写Git历史等操作需要用户确认
• 监控终端输出：Agent执行命令后会显示终端输出，必要时可中断（Stop按钮）
• 适合陌生领域：在你不熟悉的工具链上，Agent可以帮你探索和执行命令

6. Skills系统

6.1 什么是Skills

Skills是Cursor（基于Claude Code的架构）提供的一种知识封装机制。一个Skill本质上是一个包含指令和示例的Markdown文件（SKILL.md），告诉AI在特定场景下应该如何工作。

Skills的核心优势：

1. 场景化触发：当用户请求涉及Skill描述的场景时，AI自动加载对应Skill的完整指令
2. 标准化工作流：将反复出现的复杂任务（如数据分析、报告生成）封装为可复用流程
3. 版本化管理：每个Skill有独立的目录结构，支持持续迭代升级

6.2 官方Skills一览

Cursor内置了一系列官方Skills，按需使用：

Skill名称	功能
pdf	PDF文本提取、表格解析、合并拆分
docx	Word文档创建与编辑
xlsx	Excel表格处理
pptx	PowerPoint幻灯片制作
frontend-design	React/Web前端界面设计
mcp-builder	MCP服务器开发
skill-creator	创建新的Skills

6.3 安装社区Skills

OpenSkills是第三方Skills管理器（npm包），可以将任何GitHub仓库中的Skills安装到本地：

# 安装OpenSkills
npm install -g openskills

# 验证安装
npx openskills --version
# 输出：openskills/1.x.x

# 安装Anthropic官方Skills库（推荐）
npx openskills install --global anthropics/skills

# 查看已安装的Skills
npx openskills list

安装后，Skills的指令会自动出现在Cursor的上下文窗口中，Cursor在处理相关任务时会自动参考这些指令。

6.4 自定义Skills

对于项目中反复出现的标准化流程（如”从datasheet生成Verilog代码”），可以创建自定义Skills：

1. 在项目根目录创建 .cursor/skills/ 文件夹
2. 创建 SKILL.md，编写技能描述和执行步骤
3. 在 AGENTS.md 中引用该Skill

关于创建自定义Skills的完整流程，见后续系列文章：AI编程(一) - 从datasheet到Verilog原型设计

7. 进阶技巧

7.1 Custom Instructions

在Cursor Settings → Features → Custom Instructions中设置全局自定义指令，让AI在所有对话中遵循：

# 我的编码规范
- 始终使用中文注释
- 函数必须有文档字符串
- 禁止使用Magic Number，必须定义宏或const常量
- 禁止使用Tabs，统一使用4个空格

# 我的项目信息
- 语言：C
- 平台：STM32F4
- 调试器：ST-Link

7.2 快捷键汇总

快捷键	功能
Ctrl+L	打开Chat
Ctrl+I	打开Composer
Ctrl+K	打开Composer（切换到Agent模式）
Ctrl+Shift+L	打开全局Chat（跨项目）
Ctrl+Shift+M	最小化AI面板
Ctrl+Enter	发送消息
Esc	中止AI当前生成
Tab	接受AI补全建议
Ctrl+Shift+Enter	在多行补全中逐行接受

7.3 迭代式开发

不要期待AI一次性给出完美答案。推荐的工作流：

第1轮：提出初步需求
  ↓ AI给出方案
第2轮：针对不完善的地方追问
  ↓ AI修正
第3轮：最终微调
  ↓ 接受代码

每轮对话都是独立的上下文。如果前一轮的回答偏离了方向，不需要撤回——直接在新对话中重新描述需求，并引用上一轮中你觉得有用的部分（用引用功能 @file 引用之前对话中提到的代码片段）。

7.4 ReadLints工具

Cursor内置的ReadLints工具可以读取当前文件的诊断信息（lint错误、编译器警告）：

ReadLints 工具 → 当前文件

这在处理大型代码库时特别有用，AI可以直接针对已有问题给出修复方案，而不是重新生成可能引入新问题的代码。

8. Git集成

8.1 Chat中的Git操作

在Chat中可以让AI帮你撰写Git commit信息、解决合并冲突：

# 示例prompt
@codebase 帮我撰写本次提交的commit信息，修改了以下内容：
- 新增USB MSC设备类支持
- 修复了DMA传输完成标志未清除的bug
- 优化了CDC类TX FIFO管理

commit类型使用feat，格式遵循Conventional Commits规范

8.2 版本控制最佳实践

对于Composer生成的大量代码修改，强烈建议：

# 在Composer修改前，先创建新分支
git checkout -b composer/feature-new-module

# 确认无误后，合并回主分支
git checkout main
git merge composer/feature-new-module

9. Windows环境注意事项

9.1 PowerShell兼容性

Cursor在Windows上使用PowerShell作为默认终端。部分命令行工具在PowerShell中行为与CMD不同：

场景	CMD	PowerShell
命令链	a && b	a; if ($?) { b }
管道	a | b	a | b（相同）
输出重定向	a > file	a | Out-File file
后台运行	start a	Start-Process a

建议：如果AI生成的命令在PowerShell中报错，检查是否使用了CMD特有语法。

9.2 文件路径

Windows使用反斜杠路径，AI生成的代码中有时会混用正斜杠。在跨平台项目中注意：

// 推荐：Windows和Linux都支持的路径写法
#include "C:/project/inc/main.h"    // 正斜杠，兼容Windows
// 或者
#include "..\\inc\\main.h"          // 双反斜杠转义

9.3 中文编码

在Windows中文环境下，Python等工具默认编码可能不是UTF-8。如果遇到中文文件名或内容报错：

# 临时设置环境变量
$env:PYTHONIOENCODING = "utf-8"

# 永久设置（PowerShell profile）
Add-Content $PROFILE 'set PYTHONIOENCODING utf-8'

10. 常见问题

Q1: AI生成的代码编译报错怎么办？

将完整的错误信息粘贴给Chat，附带 @codebase 让AI基于项目上下文分析原因。AI经常能给出比搜索引擎更准确的修复方案。

Q2: Chat和Composer生成的代码风格不一致？

在Custom Instructions中统一设置编码规范（参考7.1节），AI会遵循这些规范。或者在每次对话开始时明确说明风格要求。

Q3: 如何避免AI改坏已有代码？

1. Composer模式：始终使用Git分支管理
2. Chat模式：重要修改前手动 git commit，便于回退
3. 接收修改前用 “Reject” 功能对比差异

Q4: AI不知道我项目的私有库/内部框架？

在 AGENTS.md 中引用这些库的文档路径，或在对话开始时使用 @folder 引用相关代码目录。

Q5: 想让AI参考某篇论文/文档但文件太大？

将关键页面截图或复制关键段落给AI（使用 @file 引用或直接粘贴），不需要提供完整文档。

11. 总结

模式	日常推荐度	核心用途
Chat	⭐⭐⭐⭐⭐	代码分析、局部修改、问答
Composer	⭐⭐⭐	新项目创建、大规模重构
Agent	⭐⭐⭐⭐	多步骤复杂任务

最佳实践总结：

1. 始终引用上下文：用 @codebase、@file、@folder 让AI理解你的项目
2. Chat为主，Composer为辅：日常开发90%用Chat，Composer仅用于新项目创建
3. Git保驾护航：Composer修改前创建分支，Chat修改前手动commit
4. 迭代而非一次到位：多轮对话逐步完善，不要期待AI一次性给出完美答案
5. Custom Instructions标准化：将编码规范和项目信息写入全局设置—本文持续更新。如有疑问或建议，欢迎通过GitHub Issues反馈。