mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 05:45:51 +00:00
0b98ee1f4c
移除 TypeScript 代码和源码路径， 聚焦三类冲突问题、快速恢复路径的设计洞察、 fail-closed 安全防护哲学和子 Agent 自动清理策略。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
100 lines
4.3 KiB
Plaintext
100 lines
4.3 KiB
Plaintext
---
|
||
title: "Worktree 隔离"
|
||
description: "多 Agent 并行工作时，共享同一目录会导致冲突。Git worktree 提供文件系统级隔离，让每个 Agent 拥有独立的工作空间。"
|
||
keywords: ["Worktree", "git worktree", "文件隔离", "多 Agent 隔离", "并行安全"]
|
||
---
|
||
|
||
## 核心问题
|
||
|
||
多 Agent 并行工作时，共享同一工作目录会导致三类冲突：
|
||
|
||
1. **写入冲突**：两个 Agent 同时编辑同一个文件，后写的覆盖前写的
|
||
2. **状态干扰**：Agent A 的测试依赖某个环境状态，Agent B 的修改破坏了它
|
||
3. **不可区分**：半完成的修改混在一起，无法分辨哪些是哪个 Agent 的
|
||
|
||
Git worktree 是 git 原生的解决方案——在同一个仓库中创建多个独立工作目录，每个在自己的分支上。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
<repo-root>/
|
||
├── .claude/
|
||
│ └── worktrees/
|
||
│ ├── fix-auth-bug/ ← Agent A 的独立工作空间
|
||
│ │ └── .git ← 指向主仓库的链接
|
||
│ └── add-dark-mode/ ← Agent B 的独立工作空间
|
||
│ └── ...
|
||
├── src/ ← 主工作目录（不受影响）
|
||
└── .git/ ← 主仓库
|
||
```
|
||
|
||
每个 worktree 是一个完整的文件系统视图，但共享同一个 git 历史。Agent 在自己的 worktree 中修改文件，不会影响主分支或其他 Agent。
|
||
|
||
## 创建与恢复
|
||
|
||
### 创建流程
|
||
|
||
```
|
||
检查是否已在 worktree 中（防嵌套） → 生成 slug → 创建 worktree → 切换进程工作目录
|
||
```
|
||
|
||
**设计细节**：
|
||
- 分支名遵循 `worktree/<slug>` 格式，slug 有严格的字符限制
|
||
- 创建后自动更新进程状态——所有后续文件操作自动在 worktree 中执行
|
||
- 系统提示和 CLAUDE.md 被重新加载，确保 AI 看到 worktree 中的上下文
|
||
|
||
### 快速恢复路径
|
||
|
||
如果目标 worktree 已存在，直接读取指针文件获取 HEAD SHA——纯文件 I/O，无子进程。在大仓库中 `git fetch` 可能需要 6-8 秒，这个优化将恢复延迟降到接近 0。
|
||
|
||
**设计洞察**：恢复（resume）是比创建更频繁的操作。用户可能中断后重新开始，或者 Agent 在之前的 worktree 上继续工作。优化恢复路径比优化创建路径更有价值。
|
||
|
||
### Hook 优先架构
|
||
|
||
如果用户配置了 `WorktreeCreate` hook，系统完全不调用 git，而是执行 hook 命令获取路径。这允许非 git 版本控制系统（如 Pijul、Mercurial）通过 hook 接入隔离机制。
|
||
|
||
## 退出与清理
|
||
|
||
退出支持两种策略：
|
||
|
||
| 策略 | 行为 | 适用场景 |
|
||
|------|------|---------|
|
||
| **keep** | 保留 worktree 和分支 | 后续需要合并或审查 |
|
||
| **remove** | 删除 worktree 和分支 | 确认不再需要 |
|
||
|
||
### Fail-closed 安全防护
|
||
|
||
删除操作有多层安全防护：
|
||
|
||
1. 只允许删除通过 EnterWorktree 创建的 worktree（手动 `git worktree add` 的不会被删）
|
||
2. 有未提交文件或新提交时，拒绝删除（除非显式 `discard_changes: true`）
|
||
3. git 命令失败时，返回"未知"状态，拒绝删除
|
||
|
||
**设计哲学**：宁可让用户手动处理废弃的 worktree，也不冒险丢失工作。磁盘空间比丢失代码便宜得多。
|
||
|
||
### 重新计数
|
||
|
||
validateInput 和实际执行之间可能有新的修改。删除前重新计数变更，确保不会误删。
|
||
|
||
## 与子 Agent 的联动
|
||
|
||
子 Agent 的 `isolation: "worktree"` 参数自动在独立 worktree 中运行。子 Agent 的 worktree 管理与用户会话略有不同：
|
||
|
||
| 维度 | 用户会话 | 子 Agent |
|
||
|------|---------|---------|
|
||
| Session 状态 | 完整持久化 | 无 session 状态 |
|
||
| 清理策略 | 手动退出 | 自动清理（无变更则删除） |
|
||
| 有变更时 | 用户决定 | 保留 worktree，返回路径 |
|
||
|
||
**设计考量**：子 Agent 的 worktree 不需要用户手动管理——如果 Agent 没有产生任何修改，worktree 被自动清理；如果有修改，保留下来供主 Agent 后续合并。
|
||
|
||
## Sparse Checkout 优化
|
||
|
||
大型 monorepo 中，完整检出可能需要数十秒。Sparse checkout 只检出特定目录，将创建时间降到几秒。
|
||
|
||
## 接下来
|
||
|
||
- **子 Agent** — 理解使用 worktree 隔离的子 Agent 创建
|
||
- **协调者与蜂群** — 理解多 Agent 的高级编排
|
||
- **权限模型** — 理解工具权限的安全体系
|