《Cursor文档》-工作树

本页介绍的原生 UI 工作树功能仅在代理窗口中可用。在 IDE 中，请使用下方的工作树技能命令。

Media

工作树让智能体可以在彼此隔离的 Git 检出中工作。每项任务都有独立的文件、依赖项和更改，不会影响主检出。

如果想在同一仓库中同时启动多个智能体且避免冲突，请使用工作树。

在代理窗口中创建工作树¶

当你在代理窗口中启动智能体或将其移至工作树时，Cursor 会为该智能体创建单独的检出。智能体会在工作树中继续执行任务，因此更改会与主检出隔离。

智能体完成后，可在代理窗口中审查结果。你可以继续在工作树中工作、从该检出创建提交或 PR，或将结果带回主工作区。

工作树设置是如何运作的？¶

你可以通过 .cursor/worktrees.json 自定义工作树设置。Cursor 在代理窗口、IDE 或 Cursor 命令行界面中创建工作树时，会检查此文件。

Cursor 会按以下顺序查找 .cursor/worktrees.json：

工作树路径中
项目根路径中

配置选项¶

worktrees.json 文件支持三个设置键：

setup-worktree-unix：用于 macOS 和 Linux 的命令或脚本路径。在 Unix 系统上，其优先级高于 setup-worktree。
setup-worktree-windows：用于 Windows 的命令或脚本路径。在 Windows 系统上，其优先级高于 setup-worktree。
setup-worktree：适用于所有操作系统的通用后备项。

每个键均可接受以下任一形式：

shell 命令数组：在工作树中按顺序执行
string 文件路径：相对于 .cursor/worktrees.json 的脚本文件路径

设置配置示例¶

使用命令数组¶

Node.js 项目¶

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

不建议将依赖项通过符号链接引入工作树，这可能导致主工作树出现问题。请改用 bun、pnpm 或 uv 等速度更快的包管理器。

使用虚拟环境的 Python 项目¶

{
  "setup-worktree": [
    "python -m venv venv",
    "source venv/bin/activate && pip install -r requirements.txt",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

包含数据库迁移的项目¶

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

构建并链接依赖项¶

{
  "setup-worktree": [
    "pnpm install",
    "pnpm run build",
    "cp $ROOT_WORKTREE_PATH/.env.local .env.local"
  ]
}

使用脚本文件¶

对于更复杂的设置，请引用脚本文件，而非直接内联命令：

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": [
    "echo 'Using generic fallback. For better support, define OS-specific scripts.'"
  ]
}

将脚本放在与 worktrees.json 同一目录下的 .cursor/ 目录中。

setup-worktree-unix.sh (Unix 和 macOS) ：

#!/bin/bash
set -e

# 安装依赖
npm ci

# 复制环境文件
cp "$ROOT_WORKTREE_PATH/.env" .env

# 运行数据库迁移
npm run db:migrate

echo "Worktree setup complete!"

setup-worktree-windows.ps1 (Windows) ：

$ErrorActionPreference = 'Stop'

# 安装依赖
npm ci

# 复制环境文件
Copy-Item "$env:ROOT_WORKTREE_PATH\.env" .env

# 运行数据库迁移
npm run db:migrate

Write-Host "Worktree setup complete!"

按操作系统区分的配置¶

你可以为不同的操作系统指定不同的设置命令：

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "chmod +x scripts/*.sh"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

调试¶

如需调试工作树设置，请在编辑器中打开“输出”面板，然后选择 Worktrees Setup。

Cursor 如何发现已有的工作树？¶

Cursor 3.5 会记录机器工作树根目录及各工作区子目录的修改时间检查点。启动时，除非这些时间戳表明自上次发现以来没有任何变化，否则 Cursor 会重新扫描文件系统。这样可避免遗漏在 Cursor 关闭期间创建的新工作树，并取消了较早的 worktree.discoveryComplete 标志。

工作树清理¶

本节所述的清理行为适用于 Cursor 3.5 及更高版本。

Cursor 可自动清理较早的工作树，以限制磁盘用量。系统会定期执行清理，并在设备上的所有工作区中保留最新的工作树，总数不超过配置的全局最大数量。

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

使用以下计算机范围的设置控制清理：

cursor.worktreeCleanupIntervalHours：Cursor 检查旧工作树的频率。如果距离上次成功运行已超过此间隔，Cursor 3.5 会在重新启动后安排一次延迟清理以补做清理。
cursor.worktreeMaxCount：Cursor 在清理旧工作树前保留的最大工作树数量。默认每台计算机最多保留 25 个工作树，所有工作区共用这一限额。

Cursor 每次执行清理时都会重新发现工作树根目录，因此在管理器外创建的工作树 (例如通过 /worktree 技能或 git worktree add 创建的工作树) 也符合删除条件。当创建工作树会超出限额时，Cursor 会对突发事件进行去抖处理，并立即开始清理，而非等待下一个间隔。

IDE 中的工作树技能¶

在 IDE 中，您可以使用 /worktree 和 /best-of-n 命令，在隔离的工作树中执行任务。

使用 `/worktree` 进行一次独立运行¶

如果希望 Cursor 在单独的检出中完成当前聊天的后续工作，请使用 /worktree 启动任务。

将实验性改动与主检出隔离
运行安装、构建和测试，不影响当前分支
进行高风险重构，并可轻松清理

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

在许多情况下，你可以直接在工作树中提交并推送。让智能体：

Commit and push these changes, then open a PR

如果要将更改合并到主检出中进行测试，请使用 /apply-worktree。完成独立检出后，请使用 /delete-worktree。

如果要查看代码仓库中的所有 worktree，请运行：

git worktree list

使用 `/best-of-n` 比较多个模型¶

/best-of-n 会同时让多个模型执行同一任务。每次运行都会使用独立的工作树，因此各候选结果彼此隔离，也与您的主检出隔离。

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

适用于以下场景：

使用同一提示词比较不同模型
针对复杂更改尝试多种方案
在应用更改前选出最佳结果

/best-of-n 只会比较运行结果，不会自动将更改合并回主检出。选出最佳结果后，你可以直接在工作树中提交并推送，或使用 /apply-worktree 将更改应用到主检出。