worktree isolation

Worktree 隔离使用 Git worktree 功能为每个异步 Agent 提供独立的工作环境。

设计理念

问题

多个 Agent 并行工作时可能冲突：

• 修改同一文件

• 创建同名文件

• 删除对方需要的文件

解决方案

使用 Git worktree 创建隔离环境：

主工作区
  ├─→ worktree-1 (Agent 1)
  ├─→ worktree-2 (Agent 2)
  └─→ worktree-3 (Agent 3)

每个 Agent 在独立的文件系统副本中工作。

Git Worktree 基础

什么是 Worktree？

Git worktree 允许同一仓库有多个工作目录：

# 创建 worktree
git worktree add ../my-worktree

# 列出所有 worktree
git worktree list

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

优势

• 共享 .git 目录（节省空间）

• 独立的工作目录

• 可以在不同分支工作

核心实现

创建 Worktree

async function createWorktree(
  basePath: string,
  branch?: string
): Promise<string> {
  // 1. 生成唯一路径
  const worktreePath = path.join(
    basePath,
    '.git',
    'worktrees',
    `agent-${Date.now()}-${randomId()}`
  );
  
  // 2. 创建 worktree
  if (branch) {
    await exec(`git worktree add -b ${branch} ${worktreePath}`);
  } else {
    await exec(`git worktree add ${worktreePath}`);
  }
  
  // 3. 复制配置文件
  await copyConfig(basePath, worktreePath);
  
  return worktreePath;
}

复制配置

async function copyConfig(
  from: string,
  to: string
): Promise<void> {
  const configFiles = [
    '.kiro/config.json',
    '.env',
    'package.json',
    'tsconfig.json',
  ];
  
  for (const file of configFiles) {
    const source = path.join(from, file);
    const dest = path.join(to, file);
    
    if (await fs.pathExists(source)) {
      await fs.copy(source, dest);
    }
  }
}

清理 Worktree

async function cleanupWorktree(
  worktreePath: string
): Promise<void> {
  try {
    // 1. 提交未保存的更改
    await exec('git add -A', { cwd: worktreePath });
    await exec('git commit -m "Agent work"', { cwd: worktreePath })
      .catch(() => {}); // 忽略"无更改"错误
    
    // 2. 删除 worktree
    await exec(`git worktree remove ${worktreePath} --force`);
  } catch (error) {
    console.error('Failed to cleanup worktree:', error);
  }
}

更改合并

自动合并

async function mergeWorktree(
  worktreePath: string,
  basePath: string
): Promise<MergeResult> {
  // 1. 获取 worktree 的分支名
  const branch = await getBranchName(worktreePath);
  
  // 2. 切换到主分支
  await exec('git checkout main', { cwd: basePath });
  
  // 3. 尝试合并
  try {
    await exec(`git merge ${branch}`, { cwd: basePath });
    return { success: true };
  } catch (error) {
    // 4. 处理冲突
    const conflicts = await getConflicts(basePath);
    return {
      success: false,
      conflicts: conflicts,
    };
  }
}

冲突解决

async function resolveConflicts(
  conflicts: Conflict[],
  strategy: 'ours' | 'theirs' | 'manual'
): Promise<void> {
  for (const conflict of conflicts) {
    if (strategy === 'ours') {
      // 保留主分支的版本
      await exec(`git checkout --ours ${conflict.file}`);
    } else if (strategy === 'theirs') {
      // 保留 worktree 的版本
      await exec(`git checkout --theirs ${conflict.file}`);
    } else {
      // 手动解决
      await manualResolve(conflict);
    }
    
    await exec(`git add ${conflict.file}`);
  }
  
  await exec('git commit -m "Resolve conflicts"');
}

手动解决

async function manualResolve(conflict: Conflict): Promise<void> {
  // 1. 读取冲突文件
  const content = await fs.readFile(conflict.file, 'utf-8');
  
  // 2. 使用 AI 解决冲突
  const resolved = await resolveWithAI(content, conflict);
  
  // 3. 写回文件
  await fs.writeFile(conflict.file, resolved);
}

async function resolveWithAI(
  content: string,
  conflict: Conflict
): Promise<string> {
  const prompt = `
Resolve this Git conflict:

${content}

Context:
- Main branch: ${conflict.oursDescription}
- Agent branch: ${conflict.theirsDescription}

Return the resolved content without conflict markers.
  `;
  
  const response = await query([{ role: 'user', content: prompt }]);
  return response;
}

状态同步

监控 Worktree

interface WorktreeStatus {
  path: string;
  branch: string;
  hasChanges: boolean;
  ahead: number;  // 领先主分支的提交数
  behind: number; // 落后主分支的提交数
}

async function getWorktreeStatus(
  worktreePath: string
): Promise<WorktreeStatus> {
  const branch = await getBranchName(worktreePath);
  const status = await exec('git status --porcelain', { cwd: worktreePath });
  const hasChanges = status.stdout.trim().length > 0;
  
  // 获取与主分支的差异
  const diff = await exec(
    'git rev-list --left-right --count main...HEAD',
    { cwd: worktreePath }
  );
  const [behind, ahead] = diff.stdout.trim().split('\t').map(Number);
  
  return {
    path: worktreePath,
    branch,
    hasChanges,
    ahead,
    behind,
  };
}

定期同步

async function syncWorktree(
  worktreePath: string
): Promise<void> {
  // 1. 提交本地更改
  await exec('git add -A', { cwd: worktreePath });
  await exec('git commit -m "WIP"', { cwd: worktreePath })
    .catch(() => {});
  
  // 2. 拉取主分支更新
  await exec('git fetch origin main', { cwd: worktreePath });
  
  // 3. 变基到最新
  try {
    await exec('git rebase origin/main', { cwd: worktreePath });
  } catch {
    // 变基失败，中止并报告
    await exec('git rebase --abort', { cwd: worktreePath });
    throw new Error('Rebase failed, manual intervention required');
  }
}

资源管理

Worktree 池

class WorktreePool {
  private available: string[] = [];
  private inUse = new Map<string, AgentInfo>();
  
  async acquire(): Promise<string> {
    if (this.available.length > 0) {
      const worktree = this.available.pop();
      return worktree;
    }
    
    // 创建新的 worktree
    return await createWorktree();
  }
  
  async release(worktree: string): Promise<void> {
    // 清理并回收
    await cleanWorktree(worktree);
    this.available.push(worktree);
  }
  
  async cleanup(): Promise<void> {
    // 清理所有 worktree
    for (const worktree of this.available) {
      await cleanupWorktree(worktree);
    }
    this.available = [];
  }
}

下一步

• 探索 Swarm 模式 的并行协作

• 了解 异步执行 的实现

• 查看 Coordinator 的任务编排