在 AI Agent 开发中，我们常常同时折腾好几件事：改 Prompt、加新工具（Tool）、接新的 LLM、调试线上 Agent 的 bug、跑评估测试……如果都在一个工作区里切来切去，git stash 堆成山，依赖版本互相打架，跑个长评估任务又卡住了主线开发。

git worktree 是解决这类并行开发痛点的利器。本文结合 AI Agent 开发的真实场景，手把手带你掌握它。

一、什么是 Git Worktree？

一句话：git worktree 让你把同一个仓库的不同分支，同时 checkout 到不同的目录里。

正常情况下，一个仓库只有一个"工作区"。你想同时看两个分支，就得 git stash 再 git checkout。而 worktree 可以让你：

my-agent/          # 主工作区，在 main 分支
my-agent-tool/     # 新目录，在 feature/add-search-tool 分支
my-agent-debug/    # 新目录，在 hotfix/prod-bug 分支

三个目录，三个分支，同时存在、互不干扰，而且共享同一份 Git 历史，几乎不占额外磁盘空间。

二、为什么 AI Agent 开发特别需要它？

Agent 开发有几个独特痛点，worktree 几乎是为此而生：

1. 实验并行：Agent 开发本质是"试 Prompt、试工具、试模型"，你经常想同时跑 A 方案和 B 方案对比效果。
2. 依赖隔离：今天试 langchain 0.2，明天试 0.3，依赖冲突是家常便饭。
3. 长任务不阻塞：跑一次 Agent 评估（evals）可能要几十分钟，你不想干等着。
4. 紧急 debug：线上 Agent 出 bug，但你本地正在改一半的新功能。

三、核心命令速查

# 在新目录创建一个 worktree 并切换到指定分支
git worktree add ../my-agent-tool feature/add-tool

# 创建新分支并 checkout 到新目录
git worktree add -b feature/new-llm ../my-agent-llm

# 查看所有 worktree
git worktree list

# 删除 worktree
git worktree remove ../my-agent-tool

# 清理已失效的 worktree 记录
git worktree prune

四、场景实战（AI Agent 开发专属，建议跟着敲）

场景 1：同时实验两个 Agent 方案（最常用）

假设你在做一个客服 Agent，想对比"单 Agent + 多工具"和"多 Agent 协作"两种架构。用 worktree 可以同时开两个，边写边对比：

cd my-agent
# 方案A：主工作区搞单 Agent 架构（main 分支）
# 方案B：开个新 worktree 搞多 Agent 协作
git worktree add -b feature/multi-agent ../my-agent-multi

# 现在打开两个终端，分别 cd 到两个目录
cd ../my-agent-multi
# 在这里写多 Agent 逻辑，改 agent.py、加 planner.py...
# 主工作区那边的代码完全不受影响

对比效果时：两个目录分别 python run_agent.py，用同一份测试问题，输出一目了然。完全不用 stash 来 stash 去。

场景 2：线上 Agent 出 Bug，但你正在改新功能

经典场景：你正在 feature/voice-agent 加语音功能，改了一堆，结果线上客服 Agent 突然乱答。传统做法是 git stash → 切 main → 修 bug → 切回来 stash pop，极易冲突。

# 不用 stash！直接开个 worktree 修 bug
git worktree add ../my-agent-hotfix main

cd ../my-agent-hotfix
# 这里是干净的 main 分支，从容复现、修 bug
git checkout -b hotfix/answer-hallucination
# ... 修复、测试、提交、推送、合并 ...

# 修完删掉这个临时目录
cd ../my-agent
git worktree remove ../my-agent-hotfix

你那个改了一半的语音功能，全程没动过，安心得很。

场景 3：隔离不同的 LLM/框架依赖

Agent 开发经常要试不同框架版本。比如主分支用 langchain，想试 llamaindex，又不想污染主环境：

git worktree add -b feature/llamaindex ../my-agent-lc

cd ../my-agent-lc
# 在这个独立目录里，单独建一个 venv
python -m venv .venv
source .venv/bin/activate
pip install llamaindex

# 这个目录的依赖，和主工作区完全隔离
# 你甚至可以用不同的 .env 放不同的 API key 配置

这是 worktree 相比 git stash 最强大的地方——连文件系统状态（venv、node_modules、.env）都能隔离。

场景 4：跑长时间评估任务，不阻塞主线

Agent 评估（跑几十条测试问题、调多次 LLM）很耗时。你不想为了跑评估就卡住自己写代码。

# 开个 worktree 专门跑评估
git worktree add ../my-agent-eval feature/v2-eval

cd ../my-agent-eval
# 后台跑评估
nohup python eval_agent.py --dataset testset.json > result.log 2>&1 &

# 回主工作区继续开发，互不影响
cd ../my-agent
# 正常写代码、提交

评估跑完了，切过去看 result.log。主线开发一分钟没耽误。

场景 5：Review 团队成员的 Agent 代码

同事提交了一个 PR，加了个新 Tool。你想本地跑起来看看效果，又不想动自己当前的工作：

git fetch origin
git worktree add ../my-agent-review origin/feature/new-rag-tool

cd ../my-agent-review
# 装依赖、跑测试、复现他的效果
pip install -r requirements.txt
python run_agent.py

# review 完删掉
cd ..
git worktree remove ../my-agent-review

五、工作原理（看一眼就懂）

普通 clone 会复制整个 .git。而 worktree 的所有目录共享同一个 .git：

.git/
├── HEAD                    # 主工作区指向的分支
└── worktrees/              # 每个额外 worktree 一个目录
    ├── my-agent-multi/
    │   ├── HEAD            # 这个 worktree 指向 feature/multi-agent
    │   └── index
    └── my-agent-hotfix/
        └── HEAD            # 指向 hotfix/...

所以提交历史、分支、标签全部共享，省空间，且各 worktree 的改动立即可见。

六、注意事项（避坑指南）

1. 同一分支不能同时 checkout 到两个 worktree：会报错。需要的话用 git worktree add --detach 以 detached HEAD 方式。
2. 删目录前先 git worktree remove：直接删文件夹会留下悬空记录，需 git worktree prune 清理。
3. 大模型 cache 要注意：不同 worktree 的 node_modules、.venv 是各自独立的，磁盘占用会增加，记得清理不用的。
4. .env 别提交：每个 worktree 的 API key 配置独立，注意 .gitignore。

七、什么时候不该用？

• 只是线性开发一个 Agent 功能 → git checkout 足够。
• 需要完全独立的仓库（不同远程、不同凭证）→ 用 git clone。
• 引入外部独立项目作为子模块 → 用 git submodule。

八、总结

对 AI Agent 开发者来说，git worktree 几乎是为我们的工作模式量身定做的：实验并行、依赖隔离、紧急 debug、长任务不阻塞——每一项都直击痛点。

记住核心一句话：同一仓库、多个目录、各 checkout 不同分支、共享一切 Git 数据。 下次再为 stash 和切分支头疼时，试试 worktree，你会回不来的。

---

如果这篇文章对你有帮助，欢迎点赞收藏 ❤️ 有 Agent 开发的问题欢迎评论区交流～