Cursor智能体开发：环境配置

Cloud Agent 运行在隔离的 Ubuntu 机器上。我们建议将该环境配置为让 Agent 能访问到与人类开发者使用的相同工具。前往 cursor.com/onboard 配置你的环境。环境选项为你的云端 agent 配置环境主要有两种方式让 Cursor 的 agent 在 cursor.com/onboard 上自动完成环境配置。agent 完成后你可以选择为其虚拟机创建一个快照以便在后续的 agent 中复用。使用 Dockerfile 手动配置环境。如果选择此方式你可以在.cursor/environment.json文件中指定该 Dockerfile。这两种方式都会生成一个环境并允许你指定一个在 agent 启动前运行的更新命令以确保其依赖项是最新的例如npm install、pip install等。环境解析顺序Cursor 按以下顺序解析环境配置并使用第一个匹配项仓库中的.cursor/environment.json个人环境配置团队环境配置这样可以在团队层面提供可预测的默认配置同时在仓库级别没有.cursor/environment.json时仍允许个人用户通过个人环境配置进行覆盖。用户的个人覆盖配置也便于在将新的环境配置推广到整个团队之前先行测试。Agent 驱动的配置推荐系统会提示你连接 GitHub 或 GitLab 账号并选择你要使用的代码仓库。然后你需要向 Cursor 提供安装依赖和运行代码所需的环境变量和机密信息secrets。最后在 Cursor 安装完依赖并验证代码可以正常运行后你可以保存其虚拟机的快照供后续的 Agent 重用。使用 Dockerfile 手动设置 (高级)对于高级场景可使用 Dockerfile 配置环境创建一个 Dockerfile用于安装系统级依赖、使用特定的编译器版本、安装调试器或切换基础操作系统镜像不要COPY整个项目Cursor 会管理工作区并检出正确的提交直接编辑.cursor/environment.json以配置运行时设置以下是一个.cursor/environment.json示例它引用了一个.cursor/Dockerfile(相对路径) 和一个custom_script.sh安装脚本{ build: { dockerfile: Dockerfile, context: .. }, install: pnpm install ./custom_script.sh}如果你的仓库需要 Docker 或 Tailscale请参阅下方的 运行 Docker 和 运行 Tailscale。你通过 Dockerfile 配置环境你无法直接访问远程机器。Dockerfile 仓库的 Computer Use 支持对于基于 Debian/Ubuntu Linux 发行版的 Dockerfile 仓库支持 Computer use。如果你需要支持其他 Linux 发行版请联系支持。资源限制每个 Cloud Agent 都运行在默认 VM 规格上内存和 CPU 资源有限。如果你是 Enterprise 方案用户且你的仓库需要更多资源请联系支持我们可以为你的工作区提高限制。自助配置自定义资源即将上线。更新命令当一台新机器启动时Cursor 会从基础环境开始然后运行update命令 (在environment.json中称为install) 。对于大多数仓库update脚本是npm install、bazel build或类似的依赖准备命令。更新脚本幂等性update脚本必须是幂等的。它可能会运行多次并且可能会在部分缓存的状态下运行。缓存的工作原理在update运行完成后如果耗时超过几秒Cursor 会进行一次内部检查点快照并尝试从该检查点启动后续的云端 Agent。这也是像pnpm install这样的update命令通常能带来快速启动的原因——如果依赖发生了变化该命令只需要执行增量工作。缓存是按尽力原则提供的在不常使用的代码仓库上你可能会遇到较慢的启动时间。如何决定在 update 脚本中放些什么在update中预先缓存一些工作步骤和在运行期间按需执行初始化之间存在取舍。将不常执行或开销较大的命令例如启动服务或构建 Docker 镜像放到update中可能会拖慢启动时间。一个实用的做法是在你的update脚本中只运行基础的、可缓存的依赖更新例如pnpm install然后在 AGENTS.md 中添加说明这样 agent 就能根据每个具体任务自行判断需要运行哪些命令。启动命令在执行install之后机器会启动并运行start命令然后运行配置好的terminals。使用它来启动在 agent 运行期间需要保持运行的进程。在很多仓库中可以省略start。如果你的环境依赖 Docker请在start中添加sudo service docker start。terminals用于运行应用代码进程。这些终端在你和 agent 共享的tmux会话中运行。在 AGENTS.md 中添加云端专用说明云端代理会读取AGENTS.md文件。我们建议为仅针对云端的设置和测试说明添加一个专门的小节标题可使用Cursor Cloud specific instructions。如果该小节内容变得较多我们建议在其中引用其他文件由这些文件提供针对具体任务的详细说明。更多信息请参见我们的 AGENTS.md 文档。环境变量和机密信息云端 Agent 需要环境变量和机密信息例如 API 密钥和数据库凭证。推荐在 Cursor 设置中使用机密信息选项卡管理机密信息最简单的方式是通过 cursor.com。将机密信息添加为键值对。机密信息具有以下特性使用 KMS 进行静态加密以环境变量形式提供给云端代理在你的工作区或团队的云端代理之间共享作为额外的一层安全保障你还可以选择将机密信息指定为脱敏。脱敏的机密信息会在代理发起的提交中被扫描以防止代理意外将机密信息提交到代码仓库中。它们在工具调用结果中也会被脱敏因此不会暴露给代理也不会存储在聊天记录中。登录凭据和 2FA如果您的应用需要登录请将您本地使用的相同凭据添加为机密信息例如用户名、电子邮件和密码。如果您的登录流程使用基于 TOTP 的 2FA也请将 TOTP 密钥 (有时也称为共享密钥或根密钥) 添加为机密信息。智能体可以使用oathtool --totp -b $TOTP_SECRET生成当前的 6 位验证码。具有多个 .env 文件的 Monorepo如果你的 monorepo 有多个.env.local文件将所有.env.local文件中的值添加到同一个 Secrets 选项卡中当键名有重叠时使用唯一的变量名例如NEXTJS_*和CONVEX_*在每个应用中按需引用这些变量如果在创建快照时包含.env.local文件它们可以被保存并供云端 Agent 使用。出于安全和管理的考虑仍然推荐使用 Secrets 选项卡这一方式。environment.json 规范environment.json文件可以像这样{ build: { dockerfile: Dockerfile, context: .. }, install: npm install, terminals: [ { name: Run Next.js, command: npm run dev } ]}重要的路径行为build中的dockerfile和context路径是相对于.cursor的。install命令是从你的项目根目录执行的。完整的 schema 定义见此处。运行 Docker云端 Agent 支持 Docker 工作流。我们在内部将其用于运行许多服务的全栈仓库。对于简单配置安装 Docker 通常就足够了。像docker run hello-world这样的命令通常会在 Docker 安装完成且守护进程运行后正常工作。Docker 在云端 Agent 中存在一些边缘情况因为它运行于另一层容器之内。简单工作流通常可以正常运行。对于更复杂的配置请从下面的fuse-overlayfs和iptables-legacy配置开始。对于更复杂的 Docker 配置请使用fuse-overlayfs、iptables-legacy并确保你的云端 Agent 用户可以运行 Docker。复杂 Docker 配置推荐使用的 Dockerfile安装 Docker 后将sudo service docker start添加到你的start命令中以便在 Agent 开始工作之前让守护进程可用。运行 TailscaleTailscale 在云端 Agent VM 中无法以默认网络模式运行。请改用 userspace networking 模式。使用以下命令启动tailscaledtailscaled --tunuserspace-networking \ --outbound-http-proxy-listenlocalhost:1054 \ --socks5-serverlocalhost:1055然后在你希望流量通过 Tailscale 转发的 shell 中导出这些代理变量export ALL_PROXYsocks5h://localhost:1055/export HTTP_PROXYhttp://localhost:1054/export HTTPS_PROXYhttp://localhost:1054/完成这些后照常运行你的tailscale up ...流程即可。如果你想要一个可用的参考示例一些客户已经成功使用 tailscale-orb 因为它的 Docker 模式遵循这种模式。Userspace networking 不会让 VM 作为 tailnet 出口节点出现。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。