Cursor 是基于 VS Code 演进的 AI 原生编辑器：既能像传统 IDE 一样写代码，也能用 Agent 跨文件改仓库、跑命令；同一个对话面板还可以用来整理 Markdown 文档、说明书与项目笔记。本文按「安装 → 初次设置 → 四种模式 → 写代码 → 编辑文档 → 常用技巧」展开，方便从零跟一遍。
一、安装 Cursor
1. 下载
打开官网下载页：https://cursor.com/download（或从 https://cursor.com 进入 Download）。
按系统选择安装包：
| 系统 | 说明 |
| --- | --- |
| macOS | 注意区分 Apple Silicon（M 系列）与 Intel；也有 Universal 包 |
| Windows | 64 位安装包 |
| Linux | 常见为 AppImage / .deb / .rpm |
2. 安装步骤（简版）
- macOS：打开
.dmg，把 Cursor 拖入「应用程序」。首次打开若被拦截，到「系统设置 → 隐私与安全性」允许，或按系统提示确认。 - Windows：运行安装程序，按向导完成；可用开始菜单启动。
- Linux：按发行版安装对应包，或给 AppImage 执行权限后启动。
3. 账号与登录
启动后按提示注册 / 登录 Cursor 账号。写代码与 Agent 能力通常需要可用额度或订阅计划（以官网当前套餐为准）。
二、第一次打开：把环境准备好
1. 可选：导入 VS Code 配置
若你本来用 VS Code，首次启动可选择导入扩展、快捷键与部分设置。Cursor 配置目录独立（常见为 ~/.cursor/），一般不会与 VS Code 互相覆盖。
2. 打开文件夹
File → Open Folder 打开你的项目根目录（建议是 Git 仓库）。Cursor 会对代码库建立索引，便于后续问答与跨文件修改；大仓库首次索引可能稍慢，之后多为增量更新。
3. 建议先做的设置
- 隐私模式（Privacy Mode）：团队/商业代码建议开启（路径通常在 Settings → General → Privacy），降低代码被用于训练等风险（以产品当前条款为准）。
- 终端可用：确保本机 Node / Python / 包管理器等工具已安装，Agent 才能真正「跑起来验证」。
- Rules（可选）：在项目里加
.cursor/rules或用户规则，固定语言、目录约定、禁止事项，让 Agent 更稳。
三、先搞清四种模式
打开 Agent 面板后，可用 Shift + Tab 或模式选择器切换：
| 模式 | 适合做什么 | 会不会改文件 |
| --- | --- | --- |
| Agent | 写功能、重构、修 bug、跑命令 | 会 |
| Ask | 读代码、问架构、解释实现 | 不会（只读） |
| Plan | 复杂需求：先出方案，你确认后再动手 | 确认后会 |
| Debug | 难复现问题，需要运行证据辅助排查 | 会 |
经验法则：
- 日常开发默认 Agent
- 只想搞懂代码用 Ask
- 大改动先用 Plan，避免一上来乱改
- 玄学 bug 用 Debug
官方说明见：Agent mode
四、用 Cursor 写代码（从补全到 Agent）
1. Tab 行内补全
像普通 AI 编辑器一样，输入时会出现补全建议，按 Tab 接受。适合函数片段、样板代码、重复模式。
2. 选中后局部改写（Inline Edit）
- 选中一段代码
- Mac：
Cmd + K；Windows/Linux：Ctrl + K - 用自然语言描述目标，例如：「改成 async/await，并补上错误处理」
- 预览 diff，接受或拒绝
适合「就这一段」的小改动，不必开完整 Agent。
3. Agent：跨文件完成任务
- 打开 Agent 面板：Mac
Cmd + I；Windows/LinuxCtrl + I - 用完整句子描述任务，尽量写清范围与验收标准
- 回车后，Agent 会搜索仓库、改多个文件、必要时跑终端命令
- 在 diff 里逐项审查；不对的地方拒绝或继续追问
好提示词示例：
在 client_side 里给登录页增加「记住我」复选框：
1) 改 UI 与表单状态
2) 把选择写入 localStorage
3) 下次打开自动勾选
4) 不要改无关文件建议同时说明：
- 技术栈与目录边界（如「只动
src/pages」） - 成功标准（如「
npm test通过」） - 禁止事项（如「不要升级依赖」）
4. 审查、中断与回滚
- 审查：看 diff，只接受正确变更
- 中断：任务跑偏时点 Stop
- 回滚：在对话消息上使用 Restore Checkpoint，回到某次回复之前的文件状态
- 排队：Agent 忙时仍可提交下一条指令，完成后自动继续
5. Plan 模式写大功能
复杂需求建议流程：
- 切到 Plan
- 让它先调研仓库并提出方案（可追问澄清）
- 你审阅方案后再 Build / 批准执行
- 执行阶段再切回 Agent 细节打磨
6. 用 @ 引用上下文
在对话里用 @ 引用文件、文件夹、文档或符号，减少 Agent「猜错位置」。写代码时优先 @ 相关模块；改接口时把类型定义与调用方一起挂上。
7. Rules / Skills（进阶）
- Rules：长期生效的团队约定（命名、目录、提交前检查）
- Skills：可复用工作流说明（例如「按我们的发帖规范写文章」）
两者都能显著降低「每次重复交代」的成本。
五、用 Cursor 编辑文档（Markdown / 说明文 / 知识库）
Cursor 本质是编辑器，因此 README、设计文档、接口说明、会议纪要 都可以在同一套 Agent 流程里完成；差别只是目标从「改 .ts」变成「改 .md / 文案结构」。
1. 直接编辑 Markdown
- 打开或新建
README.md、docs/*.md - 用预览（若已装 Markdown 预览扩展）边写边看
- 需要大段改写时：选中段落 →
Cmd/Ctrl + K，或开 Agent 说明「保持标题层级，补全安装步骤」
2. 让 Agent 写文档的标准提示
请根据当前仓库真实结构更新 docs/getting-started.md：
- 安装步骤分 macOS / Windows / Linux
- 写清如何启动开发服务器
- 增加常见报错与解决
- 不要编造仓库里不存在的脚本
- 保持现有标题风格关键点：要求它先读真实文件（package.json、启动脚本），避免「文档与代码不一致」。
3. Ask 模式先摸清再动笔
写架构说明前，先切 Ask：
用通俗语言解释这个项目的目录职责，并列出对外最重要的 5 个入口文件。确认理解后，再切 Agent 生成/改写文档，准确率更高。
4. 文档与代码一起改（推荐）
做功能时顺带要求：
实现功能 X，并同步更新 README 的「功能列表」与「环境变量」两节。这样文档不会落后于实现。
5. 长文结构模板（可直接让 Agent 套用）
# 标题
## 背景
## 安装
## 快速开始
## 核心概念
## 常见问题
## 相关链接让 Agent「按模板填充，缺信息就标注 TODO」，比一次生成超长散文更好维护。
6. 校对与压缩
对已有文档可用：
请校对这篇 Markdown：修正错别字，删空话，保留所有命令与路径不改错，输出完整文件。六、一条可复制的每日工作流
- 打开仓库，确认分支干净或先建 feature 分支
- Ask：快速理解要动的模块
- Plan（可选）：复杂改动先出方案
- Agent：实现代码 + 跑测试/启动验证
- 文档：同步 README / changelog
- 人工过 diff → 提交
七、常用快捷键速查
| 操作 | macOS | Windows / Linux |
| --- | --- | --- |
| 打开 Agent | Cmd + I | Ctrl + I |
| 行内编辑 | Cmd + K | Ctrl + K |
| 切换模式 | Shift + Tab | Shift + Tab |
| 接受补全 | Tab | Tab |
（部分键位可能随版本/自定义键位变化，以编辑器内快捷键设置为准。）
八、官方入口
- 官网：https://cursor.com
- 下载：https://cursor.com/download
- Agent 说明：https://cursor.com/help/ai-features/agent
- Cloud Agents：https://cursor.com/agents
九、小结
- 安装：官网下载 → 安装 → 登录 → 打开项目文件夹
- 写代码：Tab 补全做小步；
Cmd/Ctrl+K做局部；Agent 做跨文件任务；Plan 控大改 - 写文档：把 Markdown 当一等公民；Ask 先摸清，Agent 再改写；功能与文档尽量同一次完成
- 关键习惯：提示词写清边界与验收；每一步看 diff；用 Rules 固化团队约定