第 21 章 · Worktree 与写入冲突

本章目标：理解 Git worktree 怎样隔离多个 Agent 的文件系统，以及为什么“不会互相覆盖”仍不等于“结果可以自动合并”。

1. Worktree 提供什么

Git worktree 让同一仓库拥有多个独立工作目录，每个目录检出不同分支。Agent A 与 Agent B 可以同时修改各自文件，不会在磁盘上立刻覆盖对方。它非常适合并行原型、独立审查修复和长任务隔离。

Worktree 共享 Git 对象库，却拥有独立工作树和索引。任务结束后，可以比较 diff、挑选方案、提交或合并。

2. 隔离的边界

Worktree 只隔离仓库文件，不自动隔离数据库、端口、缓存、环境变量和外部服务。如果两个 Agent 都启动 3000 端口，仍会冲突；如果都写同一测试数据库，仍会互相污染。

完整环境隔离还需要独立端口、临时目录、数据库 schema、容器或云环境。项目配置应能根据 worktree 生成唯一资源名。

3. 文件冲突与语义冲突

Git 能检测同一行文本冲突，却检测不了语义冲突。一个 Agent 把接口参数改名，另一个 Agent 在不同文件继续使用旧参数，文本可以顺利合并但程序会失败。因此合并后必须运行集成测试和类型检查。

更早的防御是明确任务边界和接口契约。把“先确定共享接口”放在并行实现之前，可以减少后期合并成本。

4. Handoff

任务可能在本地工作树开始，后来移到独立 worktree；也可能在隔离环境完成后交回主工作区。Handoff 需要保存任务历史、分支基点、未提交 diff 和验证状态。

安全交接不能假设目标工作区干净。若用户已有修改，应创建补丁、提交或使用三方合并，而不是复制文件覆盖。

5. 清理与持久性

临时 worktree 完成后要终止进程、清理临时资源并决定是否保留分支。删除目录前确认有价值的 diff 已提交或导出。长期 worktree 则应作为独立项目管理，避免主仓库移动后路径失效。

调度器需要登记 worktree_owner、branch、base_commit 和 status，防止两个任务误用同一目录。

6. 合并协议

推荐流程：

1. 子 Agent 在独立 worktree 完成并自测；
2. Reviewer 只读审查该 diff；
3. 主 Agent确认接口和任务范围；
4. 合并到集成分支；
5. 运行跨任务验证；
6. 处理冲突并记录选择理由。