Cursor Local + Cloud 并行开发进阶指南

Agents Window、Worktree、Handoff 与 R/Quarto 项目最佳实践

Cursor
工作流
IDE
R
Quarto
Author

Harness 技术文档

Published

May 25, 2026

摘要

Cursor 3+ 将 Local、Worktree、Cloud 三种 Agent 执行环境统一在 Agents Window（Glass） 中编排。本文面向 Windows 11 + 有限硬件 + R/Quarto 技术栈，说明如何进阶使用 Local+Cloud 并行开发、如何在 harness 仓库中配置 Worktree 与 Cloud 上下文，并给出可复制的日常工作流。

本仓库已提供配套配置：

文件 作用
.cursor/worktrees.json Worktree 创建时的 OS 专用 setup
.cursor/setup-worktree-windows.ps1 Windows：复制 .Renviron、可选 renv、运行 quarto check
.cursor/setup-worktree-unix.sh macOS/Linux 等价脚本
.cursor/environment.json Cloud Environment Snapshot ID + 启动时 install 脚本
.cursor/install-cloud.sh Cloud Update script 实现（Quarto 回退安装 + quarto check + renv）
AGENTS.md Agent 通用说明 + Cursor Cloud specific instructions

配置资产（如 MathJax）的验证规程另见 配置资产本地验证与发布工作流。

1. 核心概念

官方文档没有单独命名为「Local + Cloud」的功能页；它指的是在 Agents Window 里同时管理以下执行环境：

flowchart LR
  subgraph local["本机（消耗 CPU/RAM/磁盘）"]
    L[Local Agent]
    W[Worktree Agent]
  end

  subgraph cloud["云端 VM（不占本机算力）"]
    C[Cloud Agent]
  end

  AW[Agents Window] --> L
  AW --> W
  AW --> C
  L <-->|Move to Cloud / Local| C

环境 资源 隔离 典型用途
Local 本机 CPU/RAM 无（直接改当前分支） 小改、Plan、快速验证
Worktree 本机 + 磁盘 独立 checkout/分支 本地并行 1–2 个任务
Cloud 云端 VM 完全隔离 长任务、多路并行、关电脑继续跑

Cloud Agent（原 Background Agents）在隔离 Ubuntu VM 中运行，从 GitHub 干净 checkout 起步；Pro 约 8 个并发 Cloud Agent。

2. 双窗口分工

Cursor 3+ 推荐 Editor + Agents Window 并存：

窗口 打开方式 职责
Editor Window 默认 IDE Tab 补全、精细编辑、diff review、R/Quarto 预览
Agents Window Ctrl+Shift+P → Open Agents Window 启动/管理 Local、Worktree、Cloud Agent；handoff

注意：Cloud Agent 入口、Worktree 原生 UI、Local↔︎Cloud handoff 仅在 Agents Window；经典 Editor 中可用 /worktree 等 Skills，但无 Cloud 启动入口。

3. Worktree 配置（本仓库）

3.1 文件结构

.cursor/
├── worktrees.json              # OS 路由
├── setup-worktree-windows.ps1  # Windows bootstrap
└── setup-worktree-unix.sh      # Unix bootstrap

worktrees.json 将 Windows 与 Unix 分别指向上述脚本；Cursor 在 Agents Window、Editor /worktree、CLI agent --worktree 创建 worktree 时自动执行。

3.2 Setup 做了什么

Windows 脚本（setup-worktree-windows.ps1）依次：

  1. 从主 checkout（ROOT_WORKTREE_PATH）复制 .Renviron（若存在；模板见 .Renviron.example）
  2. 若根目录有 renv.lock → renv::restore()
  3. 若 js/mathjax/test/renv.lock 存在 → 在该沙盒内 restore（可选本地环境，不提交 Git）
  4. 运行 quarto check 验证工具链

不要 symlink node_modules 或 R 库目录（Cursor 官方明确不推荐）。

3.3 调试 Worktree Setup

  1. View → Output → 选择 Worktrees Setup
  2. 终端手动验证：git worktree list
  3. 若 Agent 跳过 setup，在 prompt 中显式要求：「读取并执行 .cursor/worktrees.json 中的全部 setup 命令」

3.4 本机减负设置（User Settings）

低配机器建议在用户级 settings.json 中降低 worktree 上限：

{
  "cursor.worktreeMaxCount": 10,
  "cursor.worktreeCleanupIntervalHours": 4
}

默认全机最多 25 个 worktree；R/Quarto 项目每个 worktree 可能触发 renv::restore()，磁盘占用显著。

4. Cloud Agent 配置

4.1 一次性准备

  1. 连接 GitHub/GitLab（read-write）
  2. 打开 Cloud Agents Dashboard → 创建 Environment
    • 推荐：Agent 引导 setup → 验证 → Save Snapshot
    • 高级：提交 .cursor/environment.json + Dockerfile
  3. Secrets：本仓库通常无密钥；外部 API 任务在 Dashboard 配置
  4. 设置 spend limit 与 on-demand billing

Environment 解析顺序：.cursor/environment.json → 个人环境 → 团队环境。

本仓库已绑定 Snapshot（2026-05-25 保存）：

{
  "name": "harness-r-quarto",
  "snapshot": "snapshot-20260525-faa29445-b11d-4b39-aa1c-793e981fe6ce",
  "install": "bash .cursor/install-cloud.sh"
}

Update 脚本逻辑见 .cursor/install-cloud.sh：

  1. 若 quarto 不可用 → 安装 Quarto 1.9.37（与 Setup 时版本一致）
  2. quarto check
  3. 若存在根目录 renv.lock → renv::restore()

Dashboard 中 Configure update script 应与 install 保持一致，填：

bash .cursor/install-cloud.sh

（push 到 GitHub 后 Cloud Agent 才能执行该脚本；未 push 前可暂用 Dashboard 内联的一行版，见 §4.2 步骤 6。）

4.2 Dashboard Setup 实录（harness）

以下为 huhuaping/harness 首次创建 Cloud Environment 的可复制 checklist：

步骤 操作 本仓库结果
1 Environments → 创建 Environment，选 huhuaping/harness 仓库 scoped Environment
2 New Setup Run → Agent 引导安装 R + Quarto Subagent 分析仓库并执行 setup
3 验证 quarto render（全站 22 个 .qmd） 构建成功；链接警告不影响 Snapshot
4 状态 Ready to save → 点击 Save Successfully saved environment
5 记录 Snapshot ID，写入 .cursor/environment.json 见上文 snapshot 字段
6 Dashboard Update command bash .cursor/install-cloud.sh（与 install 一致）
7 Agents Window → Cloud 冒烟 quarto check + 报告 R/Quarto 版本

本机将配置 push 到 GitHub 时若遇连接失败，见 Cursor IDE 与 v2rayN 指南 §8（harness HTTPS + 10808 实践）。

常见状态解读：

Dashboard 显示 含义
Unconfigured / Inactive Setup 未完成或未 Save Snapshot
Ready to save 验证通过，必须点击 Save 才激活
Active（或 Save 成功后） Snapshot 可用，Cloud Agent 可稳定启动

Setup prompt 精简版（跳过 demo 录屏，适合二次 setup）：

Set up Ubuntu for harness (R + Quarto). Skip demo video and browser recording.
Install R (>= 4.2), Quarto, CRAN packages rmarkdown/knitr/xaringan.
Verify: quarto check; quarto render; cd js/mathjax/test && Rscript Rscript/test-wrap-display-math.R.
Read AGENTS.md "Cursor Cloud specific instructions". Report versions when done.

Snapshot 过期或 Restore 后，在 Dashboard 更新 Snapshot ID 并同步修改 .cursor/environment.json。

Dashboard 内联一行版（与 install-cloud.sh 等价，未 push 脚本时可粘贴）：

quarto --version || (curl -fsSL -o /tmp/quarto.deb "https://github.com/quarto-dev/quarto-cli/releases/download/v1.9.37/quarto-1.9.37-linux-amd64.deb" && sudo dpkg -i /tmp/quarto.deb && rm -f /tmp/quarto.deb) && quarto check && Rscript -e "if (file.exists('renv.lock')) { if (!requireNamespace('renv', quietly=TRUE)) install.packages('renv', repos='https://cloud.r-project.org'); renv::restore(prompt=FALSE) } else { message('No root renv.lock') }"

4.3 AGENTS.md 与 environment.json

根目录 AGENTS.md 末尾 「Cursor Cloud specific instructions」 段落供 Cloud Agent 读取，涵盖：

  • Move to Cloud 前 checklist
  • R/Quarto / MathJax L0–L1 验证命令
  • Windows PowerShell 脚本 勿在 Cloud Linux VM 上测试
  • Move to Local 跨机器限制
  • 低配硬件下的 Local vs Cloud 分工

外部项目复用时：复制 AGENTS.md 结构，替换命令与路径即可。

5. Local ↔︎ Cloud Handoff

5.1 Move to Cloud

会转移 不会转移
对话历史、上下文 未提交的本地改动

铁律：Move to Cloud 前 commit 或 stash。Cloud 从远程仓库的干净 Git 状态起步。

5.2 Move to Local

  • 按钮在 Cloud 任务 CREATING / RUNNING 期间隐藏，结束后才出现
  • 跨机器不可用：B 电脑无法 Move to Local 曾在 A 电脑 Local 启动的会话
  • Workaround：原始机器上 Move to Local，或走 PR + git pull，或 cursor.com/agents

5.3 推荐 Handoff 流程

flowchart TB
  P[Phase 1: Local Plan 拆任务] --> C[Phase 2: Move to Cloud 实现+测试+PR]
  C --> R[Phase 3: Review PR / Remote Desktop 验 UI]
  R --> L[Phase 4: Move to Local 本机调试]
  L --> C2[Phase 5: Move to Cloud 跑全量测试/修 CI]

6. 进阶能力速查

6.1 /multitask（Agents Window，3.2+）

用 async subagents 并行处理请求，而非排队；可自动拆分大任务。队列中已有消息时，可要求 multitask 队列内容。

6.2 Editor Worktree Skills

命令 作用
/worktree <prompt> 本会话在独立 checkout 执行
/apply-worktree 合并回主 checkout
/delete-worktree 删除隔离 checkout
/best-of-n sonnet,gpt,composer <prompt> 多模型并行，各用独立 worktree

6.3 CLI

# 本地 worktree
agent --worktree "run L1 mathjax modules"

# 推到 Cloud（前缀 &）
agent
& migrate mathjax config and update docs

6.4 其他

  • Multi-root workspace（3.2+）：单会话跨多仓库
  • Subagents：.cursor/agents/*.md 自定义
  • Automations：cursor.com/automations 定时 Cloud Agent
  • Remote Desktop：Cloud Agent 可接管 VM 手动测 UI

7. 任务分流（有限硬件）

任务类型 建议环境 原因
Tab 补全、单行小改 Editor Local 延迟最低
Plan、写 spec Local（Plan Mode） 需要人的判断
1 个中等 Agent 任务 Local 或 1 个 Worktree 可控
2+ 并行、全站 quarto render、L1 多模块 Cloud 不占本机
实验性 refactor Worktree 主分支保持干净
关电脑 / 开会前 Move to Cloud VM 继续跑
Windows PowerShell 脚本 Local / Worktree Cloud 为 Linux

并行 Agent 数量建议：本机 Local/Worktree ≤ 1–2；更多并行走 Cloud。

8. 四条可复制工作流

工作流 A：本机规划 + 云端舰队

  1. Editor：Plan Mode 拆任务 → commit spec
  2. Agents Window：启动 2–3 个 Cloud Agent（不同分支/任务）
  3. 关 Cursor 或做别的事
  4. 手机 / cursor.com/agents 看进度
  5. Desktop：Review PR → merge 或 @cursor 修 CI

工作流 B：Local 微调 ↔︎ Cloud 长跑

  1. Local 搭脚手架 → commit
  2. Move to Cloud → 写测试 + 开 PR
  3. Review PR artifacts / Remote Desktop
  4. 需本机 debugger → Move to Local（同一台 Windows）
  5. 再 Move to Cloud 跑全量测试

工作流 C：Worktree 本地并行

  1. Task A → Worktree（feat-a）
  2. Task B → Worktree（feat-b）
  3. 主 checkout 继续改课件
  4. 完成后 one-click 移入 foreground，或 /apply-worktree

工作流 D：配置资产验证（harness 专用）

结合 验证工作流：

  1. Local Plan：在 js/<asset>/test/ 定义 L0/L1 用例
  2. Cloud：并行跑 L1 各模块（独立 R 进程）
  3. Local Review：看 output/modules/ HTML（不提交）
  4. L1 全绿 → Promote canonical → 更新 docs/

9. 常见踩坑

问题 对策
Move to Cloud 后本地改动丢失 先 commit/stash
Move to Local 在另一台电脑不可用 PR 或 cursor.com/agents
多个 worktree 磁盘爆满 降低 worktreeMaxCount
Cloud 缺 R/Quarto Dashboard Snapshot + renv.lock
Editor 找不到 Cloud 入口 用 Agents Window
PowerShell 在 Cloud 上失败 改在 Windows Local/Worktree 验证
Worktree setup 未执行 查 Output → Worktrees Setup；显式 prompt

10. 进阶路线图

阶段 目标 动作
L1 熟悉双窗口 Editor 编辑 + Agents Window 启动 1 个 Cloud Agent
L2 掌握 handoff Local 规划 → commit → Move to Cloud → PR review
L3 本地并行 Worktree + 本仓库 worktrees.json；本机 ≤2 并行
L4 舰队编排 /multitask、多 Cloud Agent、Automations
L5 项目级基础设施 Cloud Environment Snapshot、AGENTS.md、Multi-root

11. 官方文档索引

主题 链接
Agents Window cursor.com/docs/agent/agents-window
Worktrees cursor.com/docs/configuration/worktrees
Cloud Agents cursor.com/docs/cloud-agent
Cloud Best Practices cursor.com/docs/cloud-agent/best-practices
Subagents cursor.com/docs/subagents
CLI cursor.com/docs/cli/using
Changelog 3.2（Multitask） cursor.com/changelog/04-24-26

12. 外部项目如何复用

  1. 复制 .cursor/worktrees.json 与 OS 专用 setup 脚本，按项目调整 renv/quarto/包管理命令
  2. 复制 AGENTS.md 骨架，填写 Cloud specific instructions（验证命令、Secrets、OS 限制）
  3. 在本仓库 docs/ 风格下为新项目写一份 .qmd 说明（若纳入 harness 管理）
  4. Cloud Dashboard 中为该项目保存 Environment Snapshot