swarm mode

Swarm 模式允许多个 Agent 并行协作，像蜂群一样分工完成复杂任务。

设计理念

问题

复杂任务可以分解为多个独立子任务：

• 分析多个模块

• 并行运行测试和构建

• 同时生成文档和代码

单个 Agent 串行执行效率低。

解决方案

多个 Agent 并行工作：

主 Agent
  ├─→ Agent 1 (任务 A)
  ├─→ Agent 2 (任务 B)
  └─→ Agent 3 (任务 C)
       ↓
    并行执行
       ↓
    结果聚合

核心实现

async function executeSwarm(
  tasks: SwarmTask[]
): Promise<SwarmResult> {
  // 1. 为每个任务创建 Agent
  const agents = tasks.map(task => ({
    id: generateId(),
    task: task,
    worktree: await createWorktree(),
  }));
  
  // 2. 并行启动所有 Agent
  const promises = agents.map(agent =>
    executeAgentInWorktree(agent.id, agent.task, agent.worktree)
  );
  
  // 3. 等待所有完成
  const results = await Promise.allSettled(promises);
  
  // 4. 聚合结果
  return aggregateSwarmResults(results, agents);
}

任务分解

自动分解

async function decomposeTask(
  mainTask: string
): Promise<SwarmTask[]> {
  // 使用 AI 分解任务
  const prompt = `
Decompose this task into independent subtasks:
${mainTask}

Return JSON array of subtasks:
[
  { "description": "...", "dependencies": [] },
  { "description": "...", "dependencies": ["task1"] }
]
  `;
  
  const response = await query([{ role: 'user', content: prompt }]);
  return JSON.parse(response);
}

依赖管理

interface SwarmTask {
  id: string;
  description: string;
  dependencies: string[];  // 依赖的任务 ID
  agent: string;           // 使用的 Agent 类型
}

async function executeWithDependencies(
  tasks: SwarmTask[]
): Promise<SwarmResult> {
  const completed = new Set<string>();
  const results = new Map<string, any>();
  
  while (completed.size < tasks.length) {
    // 找出可以执行的任务（依赖已完成）
    const ready = tasks.filter(task =>
      !completed.has(task.id) &&
      task.dependencies.every(dep => completed.has(dep))
    );
    
    // 并行执行
    const batchResults = await Promise.all(
      ready.map(task => executeTask(task, results))
    );
    
    // 标记完成
    ready.forEach((task, i) => {
      completed.add(task.id);
      results.set(task.id, batchResults[i]);
    });
  }
  
  return { results };
}

Worktree 管理

为每个 Agent 创建 Worktree

async function createSwarmWorktrees(
  count: number
): Promise<string[]> {
  const worktrees = [];
  
  for (let i = 0; i < count; i++) {
    const path = await createWorktree();
    worktrees.push(path);
  }
  
  return worktrees;
}

合并更改

async function mergeSwarmResults(
  worktrees: string[],
  basePath: string
): Promise<void> {
  for (const worktree of worktrees) {
    // 检查冲突
    const conflicts = await detectConflicts(worktree, basePath);
    
    if (conflicts.length > 0) {
      // 解决冲突
      await resolveConflicts(conflicts);
    }
    
    // 合并更改
    await mergeWorktree(worktree, basePath);
  }
}

结果聚合

收集结果

function aggregateSwarmResults(
  results: PromiseSettledResult<any>[],
  agents: SwarmAgent[]
): SwarmResult {
  const successful = results.filter(r => r.status === 'fulfilled');
  const failed = results.filter(r => r.status === 'rejected');
  
  return {
    totalTasks: results.length,
    successful: successful.length,
    failed: failed.length,
    results: successful.map((r, i) => ({
      agent: agents[i].id,
      task: agents[i].task,
      output: r.value,
    })),
    errors: failed.map((r, i) => ({
      agent: agents[i].id,
      task: agents[i].task,
      error: r.reason,
    })),
  };
}

冲突检测

async function detectConflicts(
  worktrees: string[]
): Promise<Conflict[]> {
  const conflicts = [];
  const fileChanges = new Map<string, string[]>();
  
  // 收集每个 worktree 的更改
  for (const worktree of worktrees) {
    const changes = await getChangedFiles(worktree);
    
    for (const file of changes) {
      if (!fileChanges.has(file)) {
        fileChanges.set(file, []);
      }
      fileChanges.get(file).push(worktree);
    }
  }
  
  // 找出冲突（同一文件被多个 Agent 修改）
  for (const [file, worktrees] of fileChanges) {
    if (worktrees.length > 1) {
      conflicts.push({ file, worktrees });
    }
  }
  
  return conflicts;
}

使用示例

并行分析

// 分析多个模块
const modules = ['auth', 'api', 'ui', 'database'];

const tasks = modules.map(module => ({
  id: `analyze-${module}`,
  description: `Analyze ${module} module`,
  dependencies: [],
  agent: 'context-gatherer',
}));

const result = await executeSwarm(tasks);

// 所有模块并行分析完成
console.log(`Analyzed ${result.successful} modules`);

并行测试

// 同时运行不同类型的测试
const testTasks = [
  {
    id: 'unit-tests',
    description: 'Run unit tests',
    agent: 'test-runner',
  },
  {
    id: 'integration-tests',
    description: 'Run integration tests',
    agent: 'test-runner',
  },
  {
    id: 'e2e-tests',
    description: 'Run E2E tests',
    agent: 'test-runner',
  },
];

const result = await executeSwarm(testTasks);

依赖任务

// 有依赖关系的任务
const tasks = [
  {
    id: 'analyze',
    description: 'Analyze codebase',
    dependencies: [],
  },
  {
    id: 'generate-types',
    description: 'Generate TypeScript types',
    dependencies: ['analyze'],
  },
  {
    id: 'generate-docs',
    description: 'Generate documentation',
    dependencies: ['analyze'],
  },
  {
    id: 'validate',
    description: 'Validate generated code',
    dependencies: ['generate-types', 'generate-docs'],
  },
];

// 执行顺序:
// 1. analyze
// 2. generate-types 和 generate-docs (并行)
// 3. validate

性能优化

限制并发数

async function executeSwarmWithLimit(
  tasks: SwarmTask[],
  maxConcurrency: number = 5
): Promise<SwarmResult> {
  const results = [];
  
  for (let i = 0; i < tasks.length; i += maxConcurrency) {
    const batch = tasks.slice(i, i + maxConcurrency);
    const batchResults = await Promise.all(
      batch.map(task => executeTask(task))
    );
    results.push(...batchResults);
  }
  
  return aggregateResults(results);
}

下一步

• 了解 Worktree 隔离 的详细实现

• 探索 Coordinator 的任务编排

• 查看 性能优化 的并发控制