《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 將更改應用到主檢出。