核心摘要

Cursor Cloud Agents 是在远程开发环境中运行的异步编程 Agent,旧名称是 Background Agents。一次运行会把已授权仓库克隆到隔离环境,执行工具和测试,生成审查制品,推送独立分支,并可创建 Draft Pull Request。

更准确的心智模型是拥有受限权限的远程贡献者,而不是可以默认信任的自治同事。产品提供执行基础设施与交付界面;团队仍需负责任务范围、仓库权限、网络策略、Secret、验收测试、代码审查、合并门禁、回滚与事故响应。

目录

核心要点

  • Background Agents 是旧产品名;Cursor 当前文档把远程服务称为 Cloud Agents。
  • Cursor 托管运行位于专用云端 VM,而不是本地 Git Worktree。
  • 环境配置、Saved Build、网络策略和 Credential 类型都是 Release Identity 的组成部分。
  • 除非配置更严格的 Egress Mode,否则运行默认可以访问互联网。
  • Runtime Secret 脱敏只限制值被复制到哪些记录中,并不会把 Secret 从进程环境移除。
  • Draft Pull Request 是交接制品,不是代码已经可以安全合并的证据。

Cloud Agent 是什么

Cursor Cloud Agent 是在远程环境而非开发者笔记本上运行的编程 Agent。它可以从 Cursor 客户端和已连接的集成入口启动,并在本地设备断开后继续工作。

Cursor 当前文档区分三类不应混写的部署边界:

边界 工具执行位置 关键影响
前台/本地 Agent 开发者控制的机器或编辑器沙箱 本地凭证与文件可能进入范围
Cursor 托管 Cloud Agent Cursor 管理的专用远程 VM 代码、环境、Secret、网络和保留数据跨越云边界
Self-Hosted Machines 客户管理的 Worker 基础设施 工具执行位置改变,但更广的 Agent 服务与数据流仍需审查

旧稿把「Background Agent」当成本地 Worktree、云端 VM 和 SSH 的总称,这已不符合当前产品定义。Cursor 的命名说明明确指出 Background Agents 已改名为 Cloud Agents,而 Cloud Agent 文档以远程执行定义该服务。

需要做产品无关的编程 Agent 选型时,请参考 AI 编程工具评测指南。本文只讨论 Cursor 当前 Cloud Agent 的运行契约。

一次运行如何从任务走到 Pull Request

一次 Cloud Agent 运行是一组外部可观察的状态迁移:

flowchart LR A["任务与仓库选择"] --> B["创建隔离环境"] B --> C["克隆已授权仓库"] C --> D["安装并启动环境"] D --> E["修改、测试并收集制品"] E --> F["推送独立分支"] F --> G["创建 Draft Pull Request"] G --> H{"人工与 CI 门禁通过?"} H -- "否" --> I["修改、暂停或丢弃"] H -- "是" --> J["按仓库策略合并"]

Cursor 说明 Source Control 权限有两层:管理员连接并限定 Provider App 范围,每位用户再连接自己的账号,而且只能为自己有权访问的仓库启动任务。这能缩小范围,但并不完整。Repository Token 允许 Push,不等于允许生产发布、数据库迁移、Secret 轮换或跨仓库策略变更。

交付内容至少应包含:

  • 精确 Base Commit 与 Branch;
  • Environment 与 Build Identity;
  • Changed File 清单;
  • 已运行命令及其退出状态;
  • 审查行为所需的截图、视频或日志;
  • 未解决告警与跳过的检查;
  • 尝试或完成的外部副作用;
  • 回滚与对账说明。

Cursor 安全文档说明 Cloud Agent Commit 会被签名。验证签名只能证明 Commit 来自声明的签名身份,不能证明代码正确、Reviewer 已批准,或每个依赖都具备可信来源。

如何构建可复现环境

Cloud Agent 使用隔离 Ubuntu 环境,其中包含克隆仓库、已安装依赖、启动命令、Secret 与网络访问。Cursor 支持 Agent-led Setup、Saved Environment,以及由 .cursor/environment.json 引用 Dockerfile 的配置方式。

Cursor 托管 Cloud Agent 当前按以下顺序解析环境:

  1. 仓库中的 .cursor/environment.json;
  2. Personal Saved Environment;
  3. Team Saved Environment。

Self-Hosted Machines 不读取 .cursor/environment.json 完成环境设置,所以必须单独测试该执行路径,不能假定云端配置会自动生效。

一个最小的仓库内配置可以声明 Docker Build 和确定性 Install 命令:

json
{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "go mod download && go test ./..."
}

这只是配置结构,不是完整生产方案。还应遵守:

  • install 必须幂等,因为每次 Build 都可能在已有磁盘状态上执行。
  • 依赖安装、代码生成和编译放入 install。
  • 长期运行服务放入 start 或 terminals;Build 只保留磁盘状态,不保留进程与导出的 Shell 变量。
  • 不要在 Docker Image 中 COPY 仓库,Cursor 会管理 Checkout。
  • 接受运行证据前,核对本次使用的 Environment 与 Build Version。
  • 把项目行为规则放进经过审查的 AGENTS.md 或 Cursor Rules,不要只留在未跟踪的 Dashboard Note 中。

AGENTS.md 指南说明了如何让仓库指令保持作用域清晰并可验证。

如何限定一个可交付任务

一个适合异步委派的任务,应足够小以便验证,也应足够完整以便交付。任务契约至少回答:

字段 问题
Base 哪个 Commit 与哪些仓库构成起始状态?
Scope 哪些文件或 Package 可以变化?
Outcome 哪个可观察行为必须改变?
Invariant 哪些行为必须保持不变?
Check 哪些命令和 Reviewer 能证明验收?
Authority 允许哪些工具、Secret、网络和外部写入?
Stop Rule 哪些情况必须停止询问,而不是猜测?
Delivery 需要哪个 Branch、PR、制品与风险说明?

并行运行可以提高候选产出量,也会同步放大审查负担、计算成本、分支冲突与依赖压力。只有写集合与验收证据相互独立时,才适合拆成并行任务。比较多个实现时,应固定 Base Revision、Environment、Model Setting、Budget、测试与 Evaluator。

哪些安全控制真正重要

云端执行会改变威胁模型,因为 Repository Content、Package Script、网页、Issue 与 Tool Result 都可能影响会自动运行命令的 Agent。

仓库与身份

  • 只向 Source Control App 授予当前工作负载必需的仓库。
  • 保留触发用户的访问边界,并继续执行正常 Branch Protection。
  • 云角色优先使用短期 OIDC 联邦,而不是长期 Access Key。
  • 把 Multi-repo Environment 视为一个组合爆炸半径。

Secret

Cursor 提供三类不同 Credential:

类型 运行时暴露 合适用途
Environment Variable 对 Agent 进程可见 非敏感 Flag 与公开配置
Runtime Secret 作为环境变量存在,但从模型可见输出和 Commit 中脱敏 进程必须使用的敏感凭证
Build Secret 只在 Docker Build Step 中可用 私有 Registry 与构建期凭证

Runtime Secret 对进入环境 Terminal 的人仍然可见。脱敏是记录控制,不是 Hardware Enclave,也不能证明任意执行代码无法读取该值。

网络与数据

Cursor 文档说明网络默认可访问互联网,也可以设为 Default + Allowlist 或 Allowlist Only。应使用能满足任务的最窄模式,为制品 Host 配置精确域名而不是宽泛 Wildcard,并审计每个新增目的地。

服务还区分 Runtime Workspace、Snapshot、Conversation State 与 Credential。当前安全文档说明 Conversation 默认无限期保留,Snapshot 在 90 天不活跃后过期;Delete Agent API 会删除运行的 Transcript 与 Artifact,但不会按需删除 Snapshot。团队应根据自身套餐与监管要求重新核验这些 Provider Policy,不能假定本地删除会自动传播到所有副本。

通用威胁模型可参考提示注入与 AI Agent 工具安全。

如何用 Go 为交付设置门禁

即使 Agent 的总结很有说服力,合并决策也应是确定性的。下面的 Go 程序会拒绝无法绑定目标 Base、Environment Build、必需检查、安全审查与回滚证据的交付:

go
package main

import (
	"errors"
	"fmt"
)

type Handoff struct {
	BaseCommit        string
	EnvironmentBuild  string
	ChangedFiles      int
	RequiredChecksRun bool
	SecurityReviewed  bool
	RollbackReady     bool
	UnknownEffects    int
}

func validate(h Handoff) error {
	switch {
	case h.BaseCommit == "" || h.EnvironmentBuild == "":
		return errors.New("missing release identity")
	case h.ChangedFiles == 0:
		return errors.New("empty change set")
	case !h.RequiredChecksRun:
		return errors.New("required checks did not run")
	case !h.SecurityReviewed:
		return errors.New("security review missing")
	case h.UnknownEffects > 0:
		return errors.New("external effects need reconciliation")
	case !h.RollbackReady:
		return errors.New("rollback is not ready")
	default:
		return nil
	}
}

func main() {
	handoff := Handoff{
		BaseCommit:        "8d9f0ab",
		EnvironmentBuild:  "build-42",
		ChangedFiles:      6,
		RequiredChecksRun: true,
		SecurityReviewed:  true,
		RollbackReady:     true,
	}
	fmt.Printf("release_ready=%t err=%v\n", validate(handoff) == nil, validate(handoff))
}

这道门禁不会自行判断代码质量。它只把缺失证据变成显式失败,使仓库检查与人工审查不能被流畅的完成说明替代。

如何评测 Cloud Agent

应以人工或确定性基线评测完整工作流:

  • 已验收任务结果,而非代码行数;
  • 首次与最终 CI 通过率;
  • 关键不变量违规;
  • 按严重级别统计的 Review Finding;
  • 无关 Diff 与回滚工作量;
  • 总耗时与人工注意力;
  • 模型、计算、工具和审查成本;
  • Secret 暴露、被拒绝出网与未授权副作用尝试。

由于模型行为具有随机性,应执行多次 Trial,并按任务类型、仓库、语言、改动规模和风险等级切片。聚合通过率可能掩盖 Migration、Authorization、Concurrency 或 Generated Code 上的失败。

编程 Agent 对比指南提供受控实验方法,Agent Harness 评测指南则覆盖 Trajectory、Grader 与 Fault Injection。

常见失败模式

失败 原因 必需响应
Build 过期 依赖或生成状态与 Base Commit 不一致 重建并重新运行相同检查
Setup 假成功 Install 只完成一部分,或服务从未 Ready 断言 Postcondition,而不只看退出码
Secret 外泄 不可信内容影响带网络权限的命令 收紧 Egress、减少 Credential 并审查 Trace
跨仓库漂移 一个仓库变化,但依赖方未同步 使用统一版本化 Multi-repo 契约和联动测试
Artifact 误导 截图或摘要遗漏失败状态 要求原始 Check Status 与可复现命令
外部副作用重复 首次写入提交后超时,重试再次执行 使用 Idempotency Key 并对账
保留策略不匹配 团队假设 Provider 并未提供的删除语义 记录每类数据并验证删除行为

常见问题

Cursor Background Agents 现在叫 Cloud Agents 吗?

是。Cursor 当前文档使用 Cloud Agents,并把 Background Agents 列为旧名称。旧词只应作为搜索别名或历史说明保留。

Cloud Agent 可以跨多个仓库工作吗?

可以,但前提是选定 Environment 包含已授权的 Repo Group。应把这个仓库组视为一个 Release Boundary:记录每个 Base Commit,运行跨仓库兼容性检查,并为每个变化仓库创建可审查的 Pull Request。

隔离 VM 能让 Cloud Agent 自动安全吗?

不能。VM 隔离会限制部分宿主机和跨运行风险,但 Agent 仍可读取仓库数据、执行 Package Script、使用 Credential 并访问允许的网络。最小权限、Egress Control、Runtime Secret 处理、Policy Check、Branch Protection 与 Review 仍不可少。

团队应如何删除 Cloud Agent 数据?

按数据类别映射 Provider Control。Cursor 文档分别提供 Agent 删除 API、Snapshot 滚动过期窗口和 Credential 删除;其中 Agent 删除面向 Conversation 与 Artifact,Snapshot 按不活跃期管理。分配敏感任务前,应重新核验当前套餐和策略。

第一个 Cloud Agent 任务怎么选?

选择低影响且具备确定性 Oracle 的任务,例如针对性补测试、有 Contract Test 的机械迁移,或带链接检查的文档修正。第一次试验不要选择生产 Hotfix、Secret Rotation 或不可逆数据变更。

相关资源