后台代理（预览版）

如何使用后台代理并行处理你的工作。

概述

通过后台代理，你可以启动异步代理，在远程环境中编辑和运行代码。你可以随时查看代理状态、发送后续指令或接管操作。

如何使用

• 按 Cmd + '（或 Ctrl + '）打开后台代理列表，并可选择新建代理。
• 提交提示后，按 Cmd + ;（或 Ctrl + ;）查看状态并进入代理运行的机器。

反馈

欢迎在 Discord 的 #background-agent 频道或通过邮件 background-agent-feedback@cursor.com 提交反馈、bug、功能建议或想法。

设置

首次在新仓库中使用后台代理时，需要为其设置运行环境。可以把它想象成新员工入职——如果每次让他们做任务都要重新克隆仓库和安装依赖，效率会很低！如果你的仓库较复杂，建议预留最多一小时完成设置。

机器环境由 .cursor/environment.json 文件定义，可以提交到仓库（推荐）或仅为个人用户私有。设置流程会引导你配置合适的 environment.json 文件。

你需要配置：GitHub 连接、机器的基础环境、切换分支时需运行的维护命令、每次启动机器时需运行的启动命令。

GitHub 连接

后台代理目前会从 GitHub 克隆你的仓库，并在独立分支上工作，推送更改，方便你接管。

这意味着你需要为仓库（及依赖仓库或子模块）授予读写权限。未来将支持 GitLab、BitBucket 等其他平台。

基础环境

基础环境定义了后台代理运行机器的硬盘内容。你可以交互式或声明式定义基础环境。

• 交互式设置：远程访问一台运行基础 Ubuntu 镜像的机器，手动安装依赖（如 sudo apt-get install python3），然后快照保存。快照后的磁盘状态会用于所有后续后台代理。
• 声明式设置：用 Dockerfile 定义磁盘状态，类似 Devcontainers。注意 Dockerfile 不应 COPY 项目代码，项目会直接从 GitHub 克隆。Dockerfile 只需安装项目所需工具和编译器。

维护命令

为新后台代理设置新机器时，会从基础环境开始，然后运行 environment.json 中配置的 install 命令。这个命令类似开发者切换分支时需要运行的命令，主要用于安装新依赖。

常见 install 命令如 npm install 或 bazel build。

为加快机器启动速度，install 命令运行后会缓存磁盘状态。该命令应可多次运行。只有磁盘状态会被持久化，install 阶段启动的进程不会在代理启动时存活。

启动命令

install 命令后，机器启动，并运行 start 命令和所有终端命令。这样可以启动代理运行时需要的进程。

start 命令通常可省略。常见用法如开发环境依赖 docker，可在 start 命令中加入 sudo service docker start。

终端命令用于你的应用代码，这些终端会在 tmux 会话中运行，你和代理都可访问。例如，许多网站仓库会将 npm run watch 作为终端命令之一。

environment.json 规范

非正式示例：

{
  "snapshot": "snapshot-id",
  "user": "ubuntu",
  "install": "./.cursor/install.sh",
  "start": "sudo service docker start",
  "terminals": [
    {
      "name": "vscode",
      "command": "cd vscode && nvm use && npm run watch",
      "description": "监视 vscode/src 文件夹变更并自动编译。"
    },
    {
      "name": "code.sh",
      "command": "sleep 120 && cd vscode && nvm use && ./scripts/code.sh",
      "description": "运行 vscode 应用，可通过 localhost:6080 使用 web VNC (noVNC) 访问。"
    }
  ]
}

正式规范详见官方文档。

模型

后台代理仅支持 Max Mode 兼容模型，按 token 用量计费。未来可能会对开发环境计算资源收费。

安全性

后台代理的攻击面比现有 Cursor 功能更大。

1. 你需要为 GitHub 应用授予读写权限（用于克隆和推送更改）。
2. 你的代码将在我们的 AWS 基础设施中运行。
3. 我们在开发过程中优先考虑了安全，但基础设施尚未经过第三方审计。
4. 代理会自动运行所有命令（便于自动化测试），但这也可能带来 prompt injection 风险。例如，若代理访问了带有恶意指令的网页，可能会被诱导泄露代码。
5. 若未启用隐私模式，我们会收集提示和开发环境信息用于产品改进。
6. 你可以输入运行开发环境所需的密钥，这些密钥会加密存储（KMS）在我们的数据库中。