Cursor 从入门到精通：精通的分界线不在补全速度，在配置是否写成了可执行的边界

Cursor 的入门体验极具欺骗性：装上、打开项目、按 Tab 补全、用 Cmd+K 改一段代码，几分钟就能感受到“AI 在替我写”。但这条路径的天花板同样清晰——到了团队协作、多文件重构、CI 自动化和涉及敏感路径的场景，大量用户发现自己仍然在“每次手动审阅 Agent 的每一步”，Cursor 并没有真正从“更快的补全器”变成“可托付的执行引擎”。这个落差的核心原因，不是模型不够强，而是Cursor 的三层控制面——规则、执行隔离和权限门禁——没有被当成工程配置来写。规则文件写得再长，它本质上只是给 Agent 看的 README，不构成强制边界；真正决定 Agent 能做什么、不能做什么的，是 permissions、sandbox、worktree 和 hooks 这些由代码和配置持有的边界。

规则文件：它是备忘录，不是编译器

Cursor 的 Project Rules 以 .mdc 文件存放在 .cursor/rules/ 下，支持四种触发模式，可以按文件 glob 或 alwaysApply 自动加载。旧版的根级 .cursorrules 单文件已被拆分式规则取代，AGENTS.md 则作为跨工具的纯 Markdown 替代方案存在。一个常见的误解是“规则写了 Agent 就会遵守”。但 Anthropic 在文档中明确说明，这类文件的内容是作为用户消息注入的，不是系统提示词的一部分，遵循度取决于指令的具体程度，而不是文件的存在本身。

因此规则的合理用法，是只写 Agent 无法从代码库自行发现的信息：业务约束、命名约定、禁止触碰的路径、测试的固定命令。项目用 TypeScript 不需要写进规则，Agent 读 tsconfig.json 就知道；写进去只是浪费上下文窗口。规则可以帮助 Agent 做出更一致的选择，但它不能阻止 Agent 执行一条 shell 命令或写入一个敏感文件。后两件事需要的是权限配置，而不是更长的 Markdown。

执行隔离：Plan 模式、Worktree 和 Sandbox 是三个独立旋钮

Cursor 从入门到精通的第一道实际分界线，是学会在正确的模式下做正确的事。CLI 和 Agent 窗口提供的控制项不是同一个东西的不同叫法，而是三个可以独立组合的边界：

--mode plan 让 Agent 只读分析、不进行任何编辑，适合在动代码之前先看清影响面。-w, --worktree 在隔离的 git worktree 中启动任务，写入发生在独立检出副本中，主工作区不受污染。--sandbox enabled 则在平台支持时进一步限制文件系统和网络访问。三者叠加，才能覆盖“先想清楚、再在隔离环境里改、并且改的时候网络和文件系统受约束”的完整链路。

以下是一个把隔离策略写入启动参数的封装，避免每次手动拼参数时遗漏 --worktree 或误用 --yolo：

import subprocess, os

def run_cursor_isolated(task: str, repo: str, mode: str = "plan") -> None:
    cmd = ["agent", "--workspace", repo]
    if mode == "plan":
        cmd += ["--mode", "plan"]          # 只读，不改任何文件
    elif mode == "isolated":
        cmd += ["--worktree", "cursor-task",  # 独立 worktree，主分支不受影响
                "--sandbox", "enabled"]
    else:
        raise ValueError("mode 必须是 plan 或 isolated")
    cmd += ["-p", task]                    # 无头/打印模式，结果可结构化消费
    subprocess.run(cmd, check=True, env={**os.environ,
                   "CURSOR_API_KEY": os.environ["CURSOR_API_KEY"]})

--yolo 和 --force 是应当被明确排除在常规流程之外的选项：它们绕过确认步骤，只适合在已经具备外部隔离的容器中使用，而不是作为“省事”的默认值。

权限门禁：把“能碰什么”写进 cli.json，而不是指望 Agent 自觉

Cursor CLI 的权限系统提供了 Shell、Read、Write、WebFetch 和 Mcp 五类 token，可以在项目级 .cursor/cli.json 或全局 cli-config.json 中声明 allow 和 deny 列表。这是从入门到精通最关键的一层：规则文件告诉 Agent “最好这样做”，权限文件决定 Agent “能不能这样做”。一个最小但有效的项目级权限配置如下，敏感路径和破坏性命令放在 deny 中，只读检查和受控写入放在 allow 中：

{
  "permissions": {
    "allow": [
      "Shell(git)",
      "Shell(ls)",
      "Read(src/**/*.ts)",
      "Write(src/**)",
      "WebFetch(docs.github.com)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/*.key)",
      "Write(.cursor/mcp.json)"
    ]
  }
}

deny 的优先级高于 allow，.env* 和私钥路径必须显式拒绝。.cursor/mcp.json 尤其需要保护：这个文件在打开工作区时被自动加载，command 字段会被执行，历史上曾出现过零点击配置 RCE 的漏洞。把 .cursor/mcp.json 放入 deny 列表，意味着 Agent 不能通过修改自己的 MCP 配置来扩大自己的能力边界。权限的默认姿态应当是 fail-closed：未被明确允许的操作不自动执行，而不是未被明确禁止的操作自动放行。

MCP 与 Hooks：能力扩展的反面是攻击面扩展

MCP 让 Cursor 可以调用外部工具和数据源，但每一个 MCP 服务器都是你主动信任的一段代码和一组指令。最典型的攻击是工具投毒：恶意服务器在工具描述中嵌入隐藏指令，诱导 Agent 读取 .cursor/mcp.json 或 SSH 密钥并外传到攻击者端点，而界面上显示的工具看起来在做一件无害的事。MCP 返回的数据同样可能携带提示注入，因为模型无法可靠区分“要处理的数据”和“要执行的指令”。

精通的标志不是接入尽可能多的 MCP 服务器，而是只接入经过审查的服务器，并用 Hooks 在工具调用前后写入审计和拦截。Cursor 的 Hooks 系统支持 preToolUse、beforeShellExecution、beforeMCPExecution 等拦截点，可以在 Agent 真正执行之前观察、阻止或修改行为。以下是一个最小化的 preToolUse 审计钩子配置，把每一次工具调用的关键信息写入 JSONL 日志，拒绝动作也留下记录：

{
  "hooks": {
    "preToolUse": [
      {
        "command": "python3 .cursor/hooks/audit_pre_tool.py",
        "timeout": 5000
      }
    ]
  }
}

audit_pre_tool.py 从 stdin 读取 hook payload，提取 tool_name、command、file_path 和 session_id，追加到 .cursor/hooks/state/audit.jsonl。如果工具名属于高危集合且参数命中敏感路径，脚本以非零退出码阻止调用。这样“谁在什么会话里试图碰什么”成为可查的证据，而不是事后翻聊天记录。

CI 门禁：Cursor 进入流水线之后，权限必须是代码，不是分类器

Cursor CLI 的 headless 形态（agent -p）使其可以进入 GitHub Actions 等 CI 环境。官方文档推荐生产 CI 使用permission-based restrictions，而不是依赖 Agent 的自我判断。这意味着 CI 中的 Agent 步骤应当只被赋予完成任务所需的最小权限：例如只允许写文件、不允许创建分支和提交 PR，shell 命令限制在必要的测试命令上。Auto-review 的分类器可以作为减少提示疲劳的辅助手段，但 Cursor 自己也在文档中说明分类器是非确定性的，不能作为唯一的安全边界。

一个 CI 门禁的最小结构是：CLI 以 --output-format json 运行，权限配置通过项目级 .cursor/cli.json 或 --api-key 环境变量注入，Agent 的输出先经过机械检查（例如 diff 是否只涉及允许的路径、是否包含禁止的依赖变更），再决定是否允许后续的 PR 步骤。门禁的判定必须由确定性的代码执行，而不是由模型自己说“我完成了”。

Cursor 从入门到精通的距离，不是从 Tab 补全到 Composer 多文件编辑的距离，而是从“相信 Agent 会做对”到“用规则、隔离、权限和钩子把 Agent 限制在可验证的边界内”的距离。规则文件负责一致性，Plan 和 Worktree 负责可逆性，cli.json 的 allow/deny 负责能力边界，Hooks 负责可观测性，CI 中的权限配置负责放行条件。当这五层由代码和配置持有、而不是由提示词口头约定时，Cursor 才真正从“更快的编辑器”变成一条可以被托付、可以被审计、可以被回滚的工程执行链路。