Cursor 的 Debug 模式与 Design 模式：两个专门化模式各自改了什么
手上常有两类活儿：一类是复现得出来但读代码读不出原因的 bug，另一类是打开页面一眼看出”这块不对”、但用一句话描述清楚很费劲的界面问题。Cursor 官方文档为这两类活儿各写了一页，一页叫 Debug Mode，一页叫 Design Mode。名字都带 Mode，但它们的介入方式压根不在一个位置上——一个是 Agent 面板里的模式档位，一个是 Agents Window 内置浏览器里的一个开关。这篇按文档把两条路各走一遍，途中标出关键的字段与设置项。
Debug Mode：先拿运行时证据，再动手改
cursor.com/help/ai-features/debug-mode 这一页给的进入方式很直白：打开 Agent 面板（官方文档写明 Mac 上是 Cmd + I，Windows/Linux 上是 Ctrl + I），按 Shift + Tab 循环切换模式，或者用 mode picker dropdown 选；然后描述 bug 或者把错误信息贴进去。cursor.com/docs/agent/debug-mode 页尾的 “Switching modes” 一节写的是同样两条路径。Windows 侧这里没有差异，cursor.com/help/customization/keyboard-shortcuts 的对照表里，“Rotate between Agent modes” 在 Mac 和 Windows/Linux 两栏都是 Shift + Tab；同一张表还列了 “Mode Menu”，Mac 是 Cmd + .，Windows/Linux 是 Ctrl + .。
真正值得看的是 docs/agent/debug-mode 的 “How it works”，它把整个过程拆成了六步：
- Explore and hypothesize：先探索相关文件、建立上下文，并生成多个关于根因的假设；
- Add instrumentation：加入 log statements，这些日志被送到”一个跑在 Cursor 扩展里的本地 debug server”；
- Reproduce the bug：Debug Mode 会要求你去复现，并给出具体的复现步骤；
- Analyze logs：拿复现收集到的日志判断真正的根因；
- Make targeted fix：做一处聚焦的修改；
- Verify and clean up：你重跑复现步骤确认之后，agent 把所有 instrumentation 移除。
六步里只有第三步是文档明写要你动手的交接点（第六步的重跑验证，文档用的是”你可以”这种可选口气），文档自述这么设计的理由是”keeps you in the loop and ensures the agent captures real runtime behavior”（文档自述）。也就是说，这个模式的产出质量取决于你能不能照它给的步骤把问题复现出来；文档在 Tips 一节里也写了，如果是 race conditions 这类难缠的问题，多复现几次可能有帮助。
适用场景文档列了四类：能复现但看不出原因的 bug、race conditions 与时序问题、需要运行时 profiling 才能理解的性能问题与内存泄漏、以及”以前是好的”的回归。help 页把分界线写得更短：知道要建什么就用 Agent mode，不知道为什么坏了就用 Debug mode。
第二步和第六步值得单独提醒一句：这个模式会往你的代码里写日志语句，也会在确认之后把它们删掉。文档没有说明如果中途放弃会话、或者复现失败，这些 instrumentation 会怎么处理，所以改动前留好 Git 提交点是通用做法（这是通用工程习惯，不是官方文档内容）。
Debug Mode 在 CLI 侧：三处文档口径对不上
如果你主要在 Cursor CLI 里干活，这里有个坑。cursor.com/docs/cli/reference/slash-commands 的命令表里明确有一行：
| 命令 | 说明（官方文档原文） |
|---|---|
/debug [prompt] | Toggle Debug mode or submit a prompt in Debug mode |
但 cursor.com/docs/cli/overview 的 “Modes” 一节，正文先写了一句 “The CLI supports the same modes as the editor”，下面那张表却只列了三行——Agent、Plan、Ask，Debug 不在其中；cursor.com/docs/cli/reference/parameters 里 --mode <mode> 的说明写的是”Set agent mode: plan or ask”，同样没有 debug。把这三处放在一起，能得到的结论只有：文档里可以查到在 CLI 会话内用 /debug 切换，但查不到用启动参数直接以 Debug 模式起会话的写法。这是文档口径的问题还是能力的问题，官方文档没有说明这一点。
另有一个同名陷阱：参数参考里确实有一个 --debug，但它挂在 worker 子命令下，说明是”Print worker debug diagnostics before starting bridge mode”，跟这里说的 Debug 模式不是一回事。别看到 --debug 就往命令行上加。
顺带一提，CLI 的 changelog 里出现过 “reproduction-steps decision card” 这个说法，说明上面第三步那个复现交接在 CLI 侧也有对应的交互形态。CLI 迭代很快，这些命令与参数以官方文档和 --help 的实际输出为准。
Design Mode：入口不在模式选择器里
cursor.com/docs/agent/design-mode 开头就把位置写清楚了：Design Mode 待在 Agents Window 里的 browser 中。先打开浏览器，再用 Cmd + Shift + D 开关它，同一个快捷键关掉就回到普通浏览。前置条件是 Agents Window——cursor.com/docs/agent/agents-window 写明用 Cmd + Shift + P → Open Agents Window 进入，并写明它随 Cursor 3 于 2026 年 4 月 2 日正式可用，发布后两周内 Enterprise 管理员可以在 Team settings 里控制放量范围，之后默认对所有用户开放。
文档给的快捷键表如下（原样照抄）：
| Action | Shortcut |
|---|---|
| Toggle Design Mode | Cmd + Shift + D |
| Select an area | Shift + drag |
| Add element to chat | Cmd + L |
| Add element to input | Option + click |
Windows 用户注意：这张表只给了 Mac 的键位，Design Mode 的 Windows 对应键（Cmd + Shift + D、Option + click 分别对应什么）官方文档没有说明这一点。help 那张 Mac / Windows 对照表里也没有 Design Mode 这一行。所以在 Windows 上想用，别照着 Cmd 硬试，以官方文档最新内容和你本机的按键设置为准。
指挥方式文档写了四种：点选单个元素、多选元素（用于”让这个跟那个对齐”这类依赖元素间关系的改动）、在页面上画（annotation 覆在视口的一帧冻结画面上，所以标注对应的是你当时看到的那个页面状态）、以及语音口述（文档写明 agent 在跑的时候麦克风仍然可用，可以接着排下一个改动）。
两个模式的证据来源，差别在这里
docs/agent/design-mode 有一节叫 “What the agent sees”，把选中一个元素之后进入上下文的东西列成了两类：
- Element identity：the xpath、the component、attributes、computed styles，以及 props from the fiber tree；
- A screenshot：布局、周围的元素、以及当时确切的页面状态。
这一节是整页里最实的部分。它说明 Design Mode 的上下文来自 DOM 与组件树加一张截图，而不是你写的一段自然语言描述。顺便说一句，“fiber tree” 是 React 里的说法，但文档并没有写 Design Mode 是否只对某类前端框架生效，这一点官方文档没有说明，别当成支持范围来理解。
把两页并排看，差别就清楚了：Debug Mode 的证据是运行时日志——由 agent 自己插桩、由你去复现产生；Design Mode 的证据是页面当前状态——由你用鼠标指出范围，工具去取元素身份与截图。前者解决”我不知道为什么坏了”，后者解决”我看到了但描述起来太费劲”。
另外，Design Mode 页里 “Work in flow” 一节写明可以在上一个改动还没跑完时就发下一个，“manage several subagents at once”，agent 完成后应用会 hot reload。文档描述的这套体验建立在”应用正跑在那个内置浏览器里”这个前提上（该页多处写的是 running product、running app）；至于应用不具备热重载能力时这一环会怎样，官方文档没有说明这一点。该页还写明这套流程配合”快、且擅长界面工作”的模型更合适，并点了它当时推荐的具体模型——模型阵容变动频繁，具体推荐以官方文档最新内容为准。
边界与需要照实标出的几处
- 移动端的 Design Mode 是另一种形态，且平台在 beta。
cursor.com/docs/cloud-agent/mobile页顶写明 “Cursor for iOS is in beta. Features may change before general availability.”；该页里的 Design Mode 描述是”附上照片、相机拍摄或文件，然后在图片或前端组件上点、画”，跟桌面端在运行中的应用里点选元素不是同一套输入。 - 浏览器工具默认需要逐次审批。
cursor.com/docs/agent/tools/browser写明 browser tools 默认要你批准，可选的审批模式有 Manual approval（文档标注为 recommended）、Allow-listed actions、Auto-run 三档，设置路径写明在 Cursor Settings > Agents > Auto-Run。同一页也明确写了 allow/block 列表是 best-effort protection，并写明不要在不受信任的代码或陌生站点上用 auto-run。Design Mode 跑在这套浏览器能力之上，这些约束同样落在它头上。 - 浏览器的部分能力尚未全量。同一页写明 Network Traffic 这项”currently only available in the Agent panel, coming soon to the layout”。
- 文档内部链接有一处对不上。
cursor.com/help/ai-features/vibe-coding里提到 Design Mode 时，链接指向的是cursor.com/docs/agent/tools/canvas，而那一页讲的是 Canvases（在对话旁渲染的交互式 artifact），跟 Design Mode 是两件事；Design Mode 的正式页是cursor.com/docs/agent/design-mode。翻文档时按标题找，别顺着链接跑偏。 - 规则的生效范围那句话里没有 Design Mode。
cursor.com/help/ai-features/agent写明 project rules、user rules、team rules 在 Agent、Ask、Plan、Debug 四个模式里都会带进对话；Design Mode 没有出现在这个枚举里，而它的开关也确实写在 browser 那一侧、用的是独立快捷键。Design Mode 是否同样纳入 mode picker 的循环、规则是否同样注入，官方文档没有说明这一点。
什么时候两个都不该用
Debug Mode 的适用前提是”能复现”。如果连稳定复现路径都没有，第三步就走不下去。需求本身没想清楚的，cursor.com/docs/agent/plan-mode 那一档更对口——它是先出可评审的实现计划再动手；只想读懂代码不改动的，help 页里的 Ask mode 是只读的。而 Design Mode 的前提是应用跑得起来、能在浏览器里点到那个元素；纯后端改动指不到东西，用不上它。
一句话记法：Debug Mode 换的是证据来源（从读代码换成读运行时日志），Design Mode 换的是指代方式（从写一句话换成用鼠标指）。这两处才是它们各自真正改掉的东西，其余都是外围。
本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。
该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现；
我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。
该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。
本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。
本文对照的是同一产品内的两种形态，依据均为上述官方文档，不对两种形态做优劣排名， 选型结论只在官方文档写明的能力边界内成立。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。