工作树

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

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

在代理窗口中创建工作树

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

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

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

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

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

1. 工作树 路径中
2. 项目根路径中

配置选项

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"  ]}

使用虚拟环境的 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/bashset -e# 安装依赖npm ci# 复制环境文件cp "$ROOT_WORKTREE_PATH/.env" .env# 运行数据库迁移npm run db:migrateecho "Worktree setup complete!"

setup-worktree-windows.ps1 (Windows) ：

$ErrorActionPreference = 'Stop'# 安装依赖npm ci# 复制环境文件Copy-Item "$env:ROOT_WORKTREE_PATH\.env" .env# 运行数据库迁移npm run db:migrateWrite-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。

Cherri Code 如何发现已有的 工作树？

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

工作树 清理

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

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

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

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

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

IDE 中的工作树技能

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

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

如果希望 Cherri Code 在单独的检出中完成当前聊天的后续工作，请使用 /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 将更改应用到主检出。