Cursor 快速上手：从安装到第一次有效改动

Cursor 是一款面向软件开发者的编码代理（coding agent），用来构建有一定规模的软件项目。它的定位不是单纯的代码补全，而是让开发者借助它理解代码库、规划并实现功能、修复缺陷、审查改动，并与日常已经在用的工具衔接起来。如果你刚接手一个陌生的仓库、需要快速判断某段逻辑在哪里实现，或者要把一个中等规模的功能从设计推进到合并，Cursor 都能派上用场。站内也有对应的工具条目：Cursor。

下面按「准备 → 操作 → 完整示例 → 注意事项」的顺序展开。文中涉及模型名称、上下文长度、配额与价格的部分，请以官网当前信息为准，产品迭代较快，此处只做结构性说明。

准备工作

账号与下载

使用 Cursor 需要一个账号，登录后即可在客户端内使用。客户端提供各平台的下载入口，安装完成后首次启动会引导登录。账号同时关联用量池与订阅计划，具体计划档位与计费方式请以官网当前信息为准。

把项目放进工作区

Cursor 的核心能力建立在「能读到你的代码」之上，因此第一步是把目标仓库作为工作区打开。打开之后，代理才能索引代码、检索符号、追踪调用关系。如果只是打开一个空目录，理解代码库、规划改动这类能力基本无从发挥。

了解模型与上下文

Cursor 内置多个可选模型，每个模型在默认上下文长度、最大上下文长度与能力标签上有所不同。下表按素材给出的属性整理，仅用于说明「模型之间存在差异」这一事实，具体可用型号与数值请以官网当前信息为准。

模型	默认上下文	最大上下文	能力
Claude Fable 5.1	300k	1M	Agent、Thinking
Claude Opus 5.5	300k	1M	Agent、Thinking
Claude Sonnet 5.5	200k	1M	Agent、Thinking
Composer 2.5	200k	—	Agent、Thinking
Gemini 3.1 Pro	200k	1M	Agent、Thinking
Gemini 3.8 Flash	200k	1M	Agent、Thinking
GPT-5.6 Luna	272k	1M	Agent、Thinking
GPT-5.6 Sol	272k	1M	Agent、Thinking
GPT-5.6 Terra	272k	1M	Agent、Thinking
Grok 4.5	256k	—	Agent、Thinking
Grok 4.6	256k	—	Agent、Thinking
Grok 4.7	256k	500k	Agent、Thinking
Muse Spark 1.3	300k	1M	Agent、Thinking

选择模型时主要看两件事：任务需要多大的上下文，以及是否需要代理式（Agent）行为。上下文越大，能一次性纳入视野的代码与文件越多；代理能力则决定它能否自主执行多步操作，而不只是回答一个问题。

命令面板

客户端内提供命令面板，用于快速检索并执行命令。日常操作中，很多入口都可以通过命令面板触达，不必记住菜单位置。

操作步骤

第一步：让代理理解代码库

打开仓库后，先提出理解类的问题，而不是直接要求改代码。典型问法包括：某个功能在哪些文件里实现、某个请求从入口到落库经过哪些层、某个配置项被哪些模块读取。这一步的价值在于建立对仓库结构的共同认知，后续规划与改动都会建立在这个认知之上。

第二步：用 Plan Mode 规划改动

当需求明确但实现路径不确定时，先进入 Plan Mode。Plan Mode 的作用是把改动范围先界定清楚，再进入实际编辑。对于较大的工作，先规划再动手能显著降低返工概率。规划阶段应当明确：要改哪些文件、新增哪些文件、涉及哪些接口或数据结构、有哪些边界情况需要覆盖。

第三步：让代理执行改动

规划确认后，切换到执行模式，让代理按计划落地代码。代理会读取相关文件、生成修改、并在需要时运行命令。执行过程中可以随时打断、追问或调整方向。

第四步：定位与修复缺陷

遇到缺陷时，把复现步骤、报错信息与相关日志一并提供给代理，让它先复现问题、再收窄根因，最后验证修复。相比直接要求「修好它」，先复现再定位的路径更可靠，也更容易判断修复是否真正生效。

第五步：审查改动

合并之前，用审查能力检查差异（diff）、运行检查项，把问题拦在合并之前。审查环节关注的是：改动是否与计划一致、是否引入了不必要的变更、测试是否覆盖了新增逻辑。

第六步：按需定制

Cursor 支持在一个地方集中添加插件（Plugins）、技能（Skills）、MCP 与规则（Rules）。这些定制项的作用是让代理更贴合你的项目约定与工作习惯。例如规则可以固化代码风格与目录约定，技能可以封装重复出现的操作流程，MCP 用于接入外部能力，插件用于扩展整体功能。

第七步：接入既有工作流

Cursor 可以与 GitHub、GitLab、Azure DevOps、Bitbucket、JetBrains、Slack、Linear 等平台协同。接入之后，代码托管、任务跟踪与沟通渠道中的信息可以更顺畅地进入开发流程。

第八步：使用 Cloud Agents

除了本地使用，Cursor 还提供 Cloud Agents。相关文档覆盖了设置（Setup）、构建（Builds）、能力（Capabilities）、最佳实践（Best Practices）、运行位置选择（Choose Where Cloud Agents Run）、自动化（Automations）、Bugbot、安全代理（Security Agents）、PR 路由与审批（PR Routing & Approval）、发布（Rollouts）、移动端（Mobile）、安全（Security）与自托管机器（Self-Hosted Machines）等主题。团队场景下，还可以结合 Teams 与 Enterprise 相关设置进行统一管理。

第九步：使用 CLI

Cursor 提供命令行界面（CLI），相关文档包括安装（Installation）、能力（Capabilities）、更新日志（Changelog）、Shell 模式（Shell Mode）、ACP、无头与 CI 场景（Headless / CI）以及参考（Reference）。CLI 适合把代理能力嵌入脚本与持续集成流程。安装方式与具体命令请以官网当前信息为准。

第十步：使用 API

Cursor 还提供 API，涵盖认证（Authentication）、速率限制（Rate Limits）与最佳实践（Best Practices）。API 之下分为若干组能力：

Cloud Agents API：创建代理、列出代理、获取代理、创建运行、列出运行、获取运行、流式获取运行、取消运行、列出产物、下载产物、归档代理、取消归档代理、删除代理。
Worker Tokens：列出 worker、获取 worker 摘要、按 ID 获取 worker、列出池、注册池、注销池、列出待处理池请求、监听待处理池请求、认领待处理请求、创建会话令牌、释放认领。
API Key Info：列出模型、列出仓库。
Webhooks：用于接收事件通知。
Admin API：覆盖组织（Organization）、组织成员、组织分组、组织池化用量、组织用量事件、组织每日用量数据、组织支出数据、组织模型访问（预览）、组织 Grok Bot 计算机、团队成员、审计日志、每日用量数据、支出数据、用量事件数据、用户支出限额、批量用户支出限额（预览）、移除团队成员、获取仓库阻止列表、更新仓库阻止列表、删除仓库阻止列表、团队目录分组（列出、获取、创建、更新、删除）、团队成员管理、计费分组（列出、获取、创建、更新、删除、添加成员、移除成员）、模型访问（预览）等。
Grok Bot Analytics API：代理编辑、标签页用量、日活用户、客户端版本、模型用量、热门文件扩展名、MCP 采用率、命令采用率、计划采用率、技能采用率、Ask 模式采用率、对话洞察、排行榜、Bugbot 分析、按用户端点。
AI Code Tracking API：提交指标（JSON / CSV）、代码变更（JSON / CSV）。
Origin Migration API：范围（Scopes）、端点参考、迁移仓库镜像、分离仓库镜像、获取镜像迁移任务、获取活跃镜像迁移任务。
Origin API：基础 URL、协议约定、预览、更新日志、入门、Origin 访问、Origin CLI 安装、安装回执、认证、生成应用签名密钥、应用 JWT、安装访问令牌、Git HTTPS 认证、用户认证的 CLI 请求、发现与签名密钥、代表用户操作、范围、镜像仓库、速率限制、响应头、超出限制、检查剩余配额、通用约定、分页、错误、ID、仓库路径、资源引用、检查运行、尝试与当前尝试、写入排序、时间戳与截止时间、当前限制、实现清单，以及完整的端点参考。

API 的认证方式、速率限制阈值与配额请以官网当前信息为准。使用 API 前建议先阅读认证与速率限制两节，避免在集成阶段反复调试。

第十一步：使用 SDK

Cursor 提供 TypeScript 与 Python 两种 SDK，另有 Bridge 与 BDK 相关文档。SDK 适合把代理能力集成进自有应用或内部平台。

一个完整示例

下面给出一个从零到合并的最小流程，假设你已经安装好客户端并登录。

打开仓库。把目标项目作为工作区打开，等待索引完成。
提出理解类问题。例如询问「用户登录流程从入口到会话建立经过哪些文件」。先确认代理对仓库的理解与你的认知一致。
进入 Plan Mode 规划。描述需求，例如「为登录接口增加失败次数限制，超过阈值后锁定一段时间」。让代理给出改动计划：涉及哪些文件、新增哪些配置、如何处理并发与边界情况。
审阅计划并确认。检查计划是否遗漏了测试、是否会影响既有调用方。确认后再进入执行。
执行改动。让代理按计划落地代码。过程中可以要求它补充单元测试。
运行检查。执行项目已有的测试与静态检查命令。具体命令取决于项目本身，例如：
```
npm test
npm run lint
```
如果项目使用其他工具链，替换为对应的命令即可。
审查差异。逐项检查改动，确认没有夹带无关修改。
提交并合并。按团队约定提交，走既有的评审与合并流程。

如果要把这套流程放进持续集成，可以改用 CLI 的无头模式；如果要让代理在云端运行，则改用 Cloud Agents。两条路径的入口不同，但「先理解、再规划、后执行、最后审查」的顺序是一致的。

注意事项

模型属性会变化。上表中的默认上下文、最大上下文与能力标签只是某一时点的记录，实际可用型号与数值请以官网当前信息为准。
上下文长度不是越大越好。更大的上下文意味着可以一次性纳入更多文件，但也意味着更高的资源消耗。按任务实际需要选择即可。
先规划再执行。对于范围较大的改动，跳过规划直接让代理编辑，容易产生方向性偏差，返工成本更高。
修复缺陷要先复现。把复现步骤、报错与日志一并提供，比只描述现象更容易得到有效修复。
审查不可省略。代理生成的改动同样需要经过差异检查与测试验证，再进入合并。
API 有速率限制。集成前先了解认证方式与速率限制，并参考响应头中的剩余配额信息。
部分 API 处于预览阶段。例如组织模型访问与批量用户支出限额标注为预览，行为可能调整。
价格、配额与计划档位以官网为准。本文不提供具体价格与配额数字。

把上面这些步骤串起来，Cursor 的使用路径大致是：打开仓库建立理解，用 Plan Mode 界定范围，执行改动，修复缺陷，审查差异，再按需通过 Rules、Skills、MCP、插件、Cloud Agents、CLI、API 与 SDK 把能力延伸到团队流程与自有系统里。