cursor worktree 怎么用 多 Agent 并行不撞分支

讲清 Agents Window 原生 worktree、IDE 里 /worktree 与 /best-of-n，以及 worktrees.json 配置和清理上限。

cursor worktree 怎么用 多 Agent 并行不撞分支

同一仓库开两个 Agent 改同一目录，冲突和脏工作区是常态。cursor worktree 怎么用？给每个任务单独 checkout，主分支保持干净；Agents Window 里原生支持，IDE 侧用 /worktree 和 /best-of-n 走同一套隔离逻辑。

作者：CodePass 技术编辑

Agents Window 里怎么开 worktree

官方文档写明：页面里描述的 UI 原生 worktree 只在 Agents Window 可用。从 Agents Window 启动或把会话移入 worktree 时，Cursor 会为该 Agent 建独立 checkout，改动不会污染你当前主工作区。

Agent 跑完后在 Agents Window 里审 diff：可以直接在 worktree 里继续改、从该 checkout 提交或开 PR，也可以把结果带回主 workspace。这和「本地 Agent 与 Cloud Agent 切换 runtime」是不同层的事；runtime handoff 见 cursor 本地和云端 agent 怎么切换，worktree 解决的是同一机器上多份文件树并行。

典型场景：你在 main checkout 上改文档，同时让 Agent 在 worktree 里跑一轮测试修复；两边 npm dev server 端口冲突时，worktree 里单独改 .env 或起不同 port，主树不受影响。若任务会从本地试跑变成长跑，可以在 Agents Window 里再 handoff 到 Cloud，但 worktree 里的未提交改动要先决定 commit、stash 还是 /apply-worktree，否则云端 clone 的是远程状态，不是 worktree 里的 WIP。

文档开头有一句容易忽略：Agents Window 的 UI worktree 与 IDE 命令是两条入口，能力重叠但不完全等价。只在 IDE 里干活的人应记住 /worktree；主要用 Agents Window 的人则应在侧边栏里选 worktree 而不是指望 Composer 自动建隔离目录。两边创建的 worktree 都受同一套 worktrees.json 和清理策略约束。

IDE 里的 /worktree 与 /best-of-n

IDE 没有 Agents Window 那套按钮时，用 Worktree Skills 命令。/worktree 把当前会话后半段挪到独立 checkout，适合实验性 refactor、跑 install/build/test 而不动当前分支：

/worktree fix the failing auth tests and update the login copy

审完想合回主 checkout 用 /apply-worktree；隔离目录不要了用 /delete-worktree。查看本机已有 worktree 可跑 git worktree list。很多团队会直接让 Agent「Commit and push these changes, then open a PR」在 worktree 里走完，主 checkout 始终是可编译的 baseline。

/best-of-n 把同一 prompt 分给多个模型并行跑，每个 run 各占一个 worktree，候选之间互不干扰：

/best-of-n sonnet,gpt,composer fix the flaky logout test

文档强调：/best-of-n 只做对比，不会自动 merge 回主 checkout。选定方案后，在 worktree 里 commit/push 开 PR，或 /apply-worktree 手动带回。三个模型并行意味着三份 npm ci 或 pnpm install，磁盘和 CI 时间成倍；任务边界不清时反而浪费算力，可对照 别让 AI agent 白烧 token 先收窄 prompt，再开 best-of-n。

.cursor/worktrees.json 怎么配

创建 worktree 时 Cursor 会读 .cursor/worktrees.json，Agents Window、IDE 和 CLI 共用。查找顺序：先 worktree 路径，再项目根。

三个 setup 键：

键 作用
setup-worktree-unix macOS/Linux 优先于通用键
setup-worktree-windows Windows 优先于通用键
setup-worktree 全平台兜底

每项可以是命令数组（顺序执行），或相对 worktrees.json 的脚本路径。环境文件常用 $ROOT_WORKTREE_PATH 指主 checkout。Node 示例：

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

带数据库迁移的 monorepo 常写成 npm ci → 复制 .env → npm run db:migrate。Python 项目可在数组里 python -m venv venv 再 pip install。复杂流程把 setup-worktree-unix.sh 放在 .cursor/ 下，json 里写文件名即可；Windows 用 .ps1，环境变量写成 $env:ROOT_WORKTREE_PATH。

官方不建议把 node_modules 用 symlink 链进 worktree，容易反噬主树；更稳的是 pnpm、uv、bun 这类快装包管理器。setup 失败时，编辑器 Output 面板选 Worktrees Setup 看逐条命令 stderr，比猜 Agent 为何读不到 .env 快得多。

Windows 路径复制环境变量写 %ROOT_WORKTREE_PATH%\\.env，Unix 用 $ROOT_WORKTREE_PATH/.env；混用团队应在 json 里同时写 setup-worktree-unix 与 setup-worktree-windows，避免 CI mac runner 与开发者 Windows 机各踩一次坑。脚本路径相对 worktrees.json 所在目录，别把 shell 放在 repo 外 unless 你有意共享机器级 setup。

发现、清理与默认上限

Cursor 3.5 起用修改时间 checkpoint 扫描 worktree 根目录，避免 Cursor 关闭期间新建的 worktree 被漏掉，也不再依赖旧的 worktree.discoveryComplete 标志。/worktree 技能或 git worktree add 在外部创建的目录同样会被发现并纳入清理候选。

清理默认机器级生效（所有 workspace 共享配额）：

{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 25
}

cursor.worktreeMaxCount 默认 25，超出会删较旧的；cursor.worktreeCleanupIntervalHours 控制检查间隔，重启后若距上次成功清理超过该间隔，会延迟调度一次 catch-up。新建导致超 cap 时会 debounce 后立即 cleanup，而不是等下一个 interval。长期并行多 Agent 的团队要心里有数：worktree 不是永久沙箱，未 push 的实验分支可能被清掉前备份。

和 Cloud Agent、新手的衔接

worktree 是本地/IDE 侧隔离；Cloud Agent 在远端 VM 里 clone，逻辑类似但路径不同。若主要用 Agents Window 或 /in-cloud，可先读 cursor in-cloud 怎么用 对齐入口。第一次接触 Agent 并行策略，Cursor 新手完全指南 里的会话与工作区概念能少踩「以为 handoff 会自动 merge worktree」这类坑。

实操顺序建议：小改留在主 checkout → 风险 refactor 用 /worktree → 要对比模型再用 /best-of-n → 选定后再 push 或 /apply-worktree。不要把 worktree 当无限磁盘：默认 25 个上限加定时清理，重要 diff 及时 push 到远程分支最省心。

和 monorepo 一起用时，.cursor/worktrees.json 常放在 repo 根，setup 里先 pnpm install --filter=... 再跑单包测试，避免全量 build 拖慢每个 worktree。Agent 在 worktree 里改 package A，主 checkout 继续改 package B 的文档，是 worktree 最省心的用法；若两路都要改同一 package，仍要人工协调 merge，worktree 只隔离文件树，不替你解决语义冲突。

清理被删前若 worktree 里还有未 push 分支，Git reflog 可能仍救得回 commit，但 Cursor 自动 cleanup 不会等你确认。养成在 /delete-worktree 或 apply 前先 git push -u origin HEAD 的习惯，尤其 best-of-n 跑完三个候选只留一个时，另外两个 worktree 里的尝试分支默认不会上远程。Agents Window 与 IDE 共用 cursor.worktreeMaxCount，调大上限前先评估磁盘，monorepo 下单 worktree 体积可能数 GB。

参考资料