Cursor 3 升级踩坑全记录：从旧版迁移到 Agent 工作台

升级 Cursor 3 第一天，我就遇到了这个报错：

Agent and Edit rely on custom models that cannot be billed to an API key.

自定义 API Key 配好了，Agent 模式用不了。翻了半天才搞清楚：Cursor 3 把功能权限重新划分了，自定义 API Key 不是"能用就全能用"，Agent/Edit/Tab 补全这三个核心功能，必须走 Cursor 订阅。

这篇把升级过程中所有需要注意的点整理出来，包括配置权限、迁移步骤、省钱用法。

---

Cursor 3 核心改了什么

先说清楚变化，再谈迁移。

Cursor 3 最根本的变化是工作模式的转变：过去是"你写代码，AI来补全和建议"；现在是"你提需求，Agent 去执行，你来审查结果"。

核心新增的四个功能：

1. Agents Window（最大的变化）

打开方式：Cmd+Shift+P → 搜索 Agents Window

这个窗口允许你同时运行多个独立 Agent，每个 Agent 在独立环境里工作，互不干扰。实际场景是：可以同时开三个 Agent 分别跑"重构后端接口"、“写前端组件”、“运行单元测试”，三个任务并行，各自在独立的 git worktree 里修改代码。

过去开多个 VS Code 窗口手动管理的方式，在这里被彻底替代了。

2. Design Mode

在浏览器预览页面里，直接框选一个 UI 元素，告诉 Agent"这个按钮改成红色"或"这个布局改成两栏"，Agent 去改代码。不再需要截图、描述、贴代码这一套流程。

3. /worktree 和 /best-of-n

/worktree：让 Agent 在隔离的 git worktree 里工作，主分支不会被乱改。这对多任务并行非常重要。

/best-of-n：让多个模型同时跑同一个任务，对比结果选最优的。需要 Pro 订阅。

4. Await 工具

Agent 在执行长任务时（比如跑构建或测试），可以挂起等待，有结果了再继续，不需要一直轮询。对接 CI/CD 流程很实用。

---

升级前必须知道的：配置这块有坑

这是这篇文章最有价值的部分，官方文档没有说清楚。

自定义 API Key 的权限边界

很多人升级后发现，配好了自定义 API Key，Agent 模式却还是用不了，报错：

Agent and Edit rely on custom models that cannot be billed to an API key.

这是因为 Cursor 3 对功能做了明确的权限划分：

功能	自定义 API Key	需要 Cursor 订阅
Chat 模式	✅	❌
Ask 模式	✅（Free用户不行）	Pro 起
Tab 自动补全	❌	✅
Agent 模式	❌	✅
Edit 模式	❌	✅
/best-of-n	❌	✅

结论很明确：想用 Agent、Edit、Tab 补全这三个核心功能，必须付费订阅。自定义 API Key 只能用于 Chat/Ask。

怎么省钱用 Cursor 3

知道了这个限制，就可以设计一个"省钱工作流"：

日常 Chat、代码解释、小改动 → 用 Chat/Ask 模式 + 自定义 API Key（按用量计费，不消耗 Cursor 月度额度，且可以选性价比最高的模型，比如 Llama 4 Scout API，成本极低）

复杂多文件任务、新功能开发 → 用 Agent 模式，消耗 Cursor 订阅额度，集中用在真正有价值的任务上

这样下来，Cursor Pro 的月度额度基本只被 Agent 消耗，不会被大量日常问答给榨干。

---

迁移步骤：从旧版升到 Cursor 3

方法一：自动更新（最省事）

Cursor 本身会提示更新，右下角有更新提示时直接点 “Restart to Update” 就行。

如果没收到提示：Help → Check for Updates

方法二：手动下载安装

直接去 cursor.com 下载最新版，覆盖安装即可。旧版配置会自动迁移。

方法三：遇到冲突时的处理

如果升级后遇到插件冲突或配置错乱，按这个顺序处理：

1. 先导出旧配置：Cmd+Shift+P → Preferences: Open User Settings (JSON)，复制备份
2. 完全卸载旧版（Windows 要手动删 %APPDATA%\Cursor 目录）
3. 重新安装 Cursor 3
4. 手动把旧配置里有效的部分复制回来

---

升级后的几个使用建议

1. 先把 cursor-context.md 更新一遍

Cursor 3 对上下文的理解更深，旧版的 .cursor/rules 或 cursor-context.md 建议重新整理，补充项目架构说明，多 Agent 并行时这个文件会被每个 Agent 读到。

2. Agent 模式先从小任务开始

新手容易犯的错误是上来就让 Agent 跑一个大任务。建议先用单文件、单功能的小任务熟悉 Agent 的工作方式，看清楚它的操作再慢慢扩大范围。

3. worktree 要用起来

多 Agent 并行时，/worktree 命令能保护主分支不被污染。这是 Cursor 3 在工程实践上很有价值的一个点，别忽略。

---

常见问题汇总

Q：升级后 Tab 补全变慢了？
A：Tab 补全走的是 Cursor 官方通道，国内晚高峰偶有延迟。Agent 模式支持断点续传，断线后会从中断处继续，不影响大任务。

Q：旧版的 Composer 还能用吗？
A：Composer 2 是 Cursor 3 的内置功能，旧版 Composer 的功能已整合进新的 Agent 工作流，不需要单独找了。

Q：自定义 API 配置在哪里？
A：Settings → Models → Custom API Keys，填入 Base URL 和 Key 即可。Chat 模式下可以立即生效。

---

Cursor 3 的核心逻辑变了，从"辅助你写代码"变成了"你审查AI写的代码"。适应这个转变需要一点时间，但熟悉之后多任务并行的效率确实上来了。