AI 功能排障总览

Cursor 的 AI 功能很多，但排障时先不要问“哪个功能坏了”，而要先判断用户当前在做什么：要改代码、读代码、先出方案、还是调复杂 bug。

1. 一句话判断

大多数“Cursor 不好用”其实是模式选择错了：要改代码用 Agent，要只读理解用 Ask，要先审方案用 Plan，要带运行证据查 bug 用 Debug，要补全正在写的局部代码用 Tab。

先选对模式，再看上下文、索引、权限、网络、模型用量和项目规则。

2. 模式选择

Agent

Agent 是默认主力。官方说明它能搜索代码库、编辑多个文件、运行终端命令，并自行修复错误。

适合：

• 新功能。
• 重构。
• 修 bug。
• 写测试。
• 根据错误输出继续验证。

入口：

• Mac：Cmd + I。
• Windows / Linux：Ctrl + I。

Agent 编辑会进入 diff view。出错时可用 Stop 中断，或对历史消息使用 Restore Checkpoint 回滚。

Ask

Ask 适合只读理解：解释架构、追踪调用链、定位文件、理解错误背景。不要用 Ask 期待它直接改代码。

Plan

Plan 适合跨文件或高风险任务。先让 Cursor 产出方案，确认影响范围、步骤和验证方式，再允许执行。

Debug

Debug 适合有 runtime evidence 的问题，例如报错、日志、失败测试、浏览器异常。给 Debug 的输入要包含复现路径和错误输出。

Tab

Tab 是 AI autocomplete。它基于最近编辑、周围代码和 linter errors 给出灰色建议。

常用操作：

• 接受完整建议：Tab。
• 拒绝：Escape 或继续输入。
• 逐词接受：Mac 用 Cmd + Right；Windows / Linux 用 Ctrl + Right。
• 接受后再次按 Tab，可 jump-in-file 到预测的下一个编辑位置。
• 可在右下角 Tab status indicator 暂停、全局关闭或按扩展名关闭。

Inline Edit

Inline Edit 适合对当前选中区域做局部修改，不适合让它承担跨文件任务。

3. AI 功能排障顺序

按这个顺序排：

1. 模式：是否用错 Agent / Ask / Plan / Debug / Tab。
2. 上下文：是否打开正确 folder，是否用 @file / @folder 指定了关键文件。
3. 索引：codebase indexing 是否完成或需要 reindex。
4. 规则：Rules、AGENTS.md、CLAUDE.md 是否误导了 Agent。
5. 权限：终端命令、文件读取、MCP、浏览器工具是否被拒绝。
6. 网络：streaming、代理、SSL inspection 是否影响响应。
7. 模型与用量：模型是否可用、是否达到 limit、是否被企业策略限制。

4. 给 Agent 的任务格式

一个可执行请求应该包含：

• 目标：要改什么。
• 范围：哪些文件或模块。
• 约束：不要改什么，必须保留什么。
• 验证：跑什么测试、看哪个页面、检查什么日志。
• 回退：失败后如何撤回。

坏请求：

“优化一下项目。”

好请求：

“在登录页增加邮箱格式校验，只改 src/auth 和登录表单组件。完成后跑现有表单测试，并列出 diff 里新增的校验分支。”

5. 商业级验收

• 用户知道 Agent / Ask / Plan / Debug / Tab 的边界。
• Agent 任务能产生可审查 diff。
• 高风险改动先用 Plan。
• 复杂 bug 用 Debug，并提供日志或复现步骤。
• Tab 能被接受、拒绝、暂停和按文件类型关闭。
• 失败时能 Stop、Restore Checkpoint 或回退 diff。
• 模式问题、上下文问题、网络问题、模型用量问题能分开排查。

6. 常见失败点

• 用 Ask 提需求，期待它自动改文件。
• 用 Agent 问大范围问题，没有指定文件、约束和验证。
• Tab 频繁干扰但不知道从 status indicator 关闭。
• 把模型 limit、网络 streaming 或企业权限问题误判为功能 bug。
• 切换任务不新开 chat，导致旧上下文污染。

官方来源

• https://cursor.com/help/ai-features/agent.md
• https://cursor.com/help/ai-features/ask-mode.md
• https://cursor.com/help/ai-features/plan-mode.md
• https://cursor.com/help/ai-features/debug-mode.md
• https://cursor.com/help/ai-features/tab.md
• https://cursor.com/help/ai-features/inline-edit.md

接下来去哪