核心摘要
Cursor Cloud Agents 是在远程开发环境中运行的异步编程 Agent,旧名称是 Background Agents。一次运行会把已授权仓库克隆到隔离环境,执行工具和测试,生成审查制品,推送独立分支,并可创建 Draft Pull Request。
更准确的心智模型是拥有受限权限的远程贡献者,而不是可以默认信任的自治同事。产品提供执行基础设施与交付界面;团队仍需负责任务范围、仓库权限、网络策略、Secret、验收测试、代码审查、合并门禁、回滚与事故响应。
目录
- Cloud Agent 是什么
- 一次运行如何从任务走到 Pull Request
- 如何构建可复现环境
- 如何限定一个可交付任务
- 哪些安全控制真正重要
- 如何用 Go 为交付设置门禁
- 如何评测 Cloud Agent
- 常见失败模式
- 常见问题
核心要点
- 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 运行是一组外部可观察的状态迁移:
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 当前按以下顺序解析环境:
- 仓库中的
.cursor/environment.json; - Personal Saved Environment;
- Team Saved Environment。
Self-Hosted Machines 不读取 .cursor/environment.json 完成环境设置,所以必须单独测试该执行路径,不能假定云端配置会自动生效。
一个最小的仓库内配置可以声明 Docker Build 和确定性 Install 命令:
{
"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、必需检查、安全审查与回滚证据的交付:
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 或不可逆数据变更。