多代理协作概述
当任务复杂时，使用多个 Claude Code 代理分工协作可以大幅提高效率。
核心思想
一个代理负责规划，多个代理分别执行，最后汇总结果。
代理模式
多代理架构
├── 规划代理（Planner）
│ └── 分析任务、拆解步骤
├── 执行代理（Executor）
│ └── 按计划执行具体任务
├── 审查代理（Reviewer）
│ └── 检查结果、提出改进
└── 协调代理（Coordinator）
└── 调度其他代理、整合结果
Agent 类定义
javascript
// agents/planner.md
---
name: planner
description: 负责理解需求、分解任务、制定计划
model: sonnet
tools: Read, Grep, Glob
permissionMode: plan
---
你是一个任务规划专家。
职责：
1. 理解用户需求
2. 分析任务复杂度
3. 拆解为可执行的子任务
4. 制定执行计划
5. 定义验收标准
输出格式：
## 任务理解
[对需求的理解]
## 任务拆解
1. [子任务 1]
2. [子任务 2]
...
## 执行计划
[按顺序执行的步骤]
## 验收标准
[如何验证完成]javascript
// agents/executor.md
---
name: executor
description: 负责按照计划执行具体任务
model: sonnet
tools: Read, Edit, Write, Bash, Grep, Glob
permissionMode: default
---
你是一个任务执行专家。
职责：
1. 理解执行计划
2. 按步骤执行任务
3. 定期汇报进度
4. 记录问题和解决方案
工作方式：
- 严格按照计划执行
- 每完成一步汇报
- 遇到问题及时反馈javascript
// agents/reviewer.md
---
name: reviewer
description: 负责审查结果，提出改进建议
model: sonnet
tools: Read, Grep, Glob
permissionMode: plan
---
你是一个代码审查专家。
职责：
1. 验证执行结果
2. 检查代码质量
3. 发现潜在问题
4. 提出改进建议
5. 评估是否达标
审查维度：
- 功能正确性
- 代码质量
- 性能影响
- 安全风险
- 可维护性协作流程实现
基本协作流程
javascript
// lib/multi-agent/collaboration.js
class AgentCollaboration {
constructor(agents) {
this.agents = agents;
this.results = new Map();
}
async run(task, options = {}) {
const { parallel = false, review = true } = options;
// 1. 规划阶段
console.log("Phase 1: Planning...");
const plan = await this.planner.createPlan(task);
// 2. 执行阶段
console.log("Phase 2: Execution...");
if (parallel) {
await this.executeInParallel(plan);
} else {
await this.executeSequential(plan);
}
// 3. 审查阶段
if (review) {
console.log("Phase 3: Review...");
const reviewResult = await this.reviewer.review(this.results);
if (!reviewResult.passed) {
// 返工
await this.handleRevision(reviewResult.issues);
}
}
// 4. 汇总结果
return this.aggregateResults();
}
async executeInParallel(plan) {
const promises = plan.steps.map((step) =>
this.executor.execute(step)
);
const results = await Promise.all(promises);
results.forEach((result, index) => {
this.results.set(plan.steps[index].id, result);
});
}
async executeSequential(plan) {
for (const step of plan.steps) {
const result = await this.executor.execute(step);
this.results.set(step.id, result);
}
}
}代码生成协作
javascript
// scripts/collaborative-code-gen.js
async function generateAPIProject(spec) {
// 1. 规划代理分析需求
const plan = await planner.analyze({
type: "api-project",
spec,
});
// 2. 创建专门的代理
const agents = {
backend: executor.fork({
role: "backend-dev",
context: plan.modules.filter((m) => m.type === "backend"),
}),
frontend: executor.fork({
role: "frontend-dev",
context: plan.modules.filter((m) => m.type === "frontend"),
}),
tests: executor.fork({
role: "test-dev",
context: plan.testRequirements,
}),
};
// 3. 并行执行
const [backend, frontend, tests] = await Promise.all([
agents.backend.run(),
agents.frontend.run(),
agents.tests.run(),
]);
// 4. 审查结果
const review = await reviewer.review({
backend,
frontend,
tests,
});
if (!review.passed) {
// 协调修复
await coordinator.resolveIssues(review.issues);
}
// 5. 整合输出
return integrator.combine({ backend, frontend, tests });
}代理通信
消息传递
javascript
// lib/agent/message-passing.js
class AgentMessageBus {
constructor() {
this.subscribers = new Map();
}
subscribe(agentId, callback) {
this.subscribers.set(agentId, callback);
}
publish(from, message) {
const recipients = message.to
? [message.to]
: this.subscribers.keys();
recipients.forEach((id) => {
const callback = this.subscribers.get(id);
if (callback) {
callback({ from, ...message });
}
});
}
broadcast(from, message) {
this.subscribers.forEach((callback, id) => {
if (id !== from) {
callback({ from, ...message });
}
});
}
}
// 使用示例
const bus = new AgentMessageBus();
bus.subscribe("planner", (msg) => {
console.log("Planner received:", msg);
});
bus.subscribe("executor", (msg) => {
console.log("Executor received:", msg);
});
bus.publish("coordinator", {
type: "task",
content: "Generate API...",
});共享上下文
javascript
// lib/agent/shared-context.js
class SharedContext {
constructor() {
this.context = {
project: {},
files: new Map(),
decisions: [],
issues: [],
};
}
set(key, value) {
this.context[key] = value;
this.notify("update", { key, value });
}
get(key) {
return this.context[key];
}
addFile(path, content) {
this.context.files.set(path, content);
}
getFile(path) {
return this.context.files.get(path);
}
recordDecision(decision) {
this.context.decisions.push({
...decision,
timestamp: Date.now(),
});
}
getContext() {
return { ...this.context };
}
}实际应用场景
场景 1：大型重构
javascript
async function largeScaleRefactor(refactorSpec) {
// 1. 规划代理制定重构计划
const plan = await planner.createRefactorPlan({
scope: refactorSpec.scope,
constraints: refactorSpec.constraints,
});
// 2. 创建执行团队
const team = {
analyzer: executor.fork({
role: "code-analyzer",
goal: "分析依赖关系和影响范围",
}),
migrator: executor.fork({
role: "code-migrator",
goal: "执行代码迁移",
}),
tester: executor.fork({
role: "integration-tester",
goal: "验证迁移结果",
}),
};
// 3. 分阶段执行
const phases = plan.phases;
for (const phase of phases) {
console.log(`Starting phase: ${phase.name}`);
// 并行执行该阶段的子任务
await Promise.all(
phase.tasks.map((task) => team[task.agent].execute(task))
);
// 审查该阶段结果
const review = await reviewer.review(phase);
if (review.failed) {
throw new Error(`Phase ${phase.name} failed: ${review.reason}`);
}
}
// 4. 最终验证
return await team.tester.runFinalValidation();
}场景 2：文档自动生成
javascript
async function generateProjectDocs(project) {
// 1. 分析项目结构
const structure = await analyzer.analyzeStructure(project);
// 2. 规划文档生成
const docsPlan = await planner.planDocGeneration({
structure,
requirements: project.docRequirements,
});
// 3. 创建文档生成代理
const docsTeam = {
api: executor.fork({
role: "api-doc-writer",
scope: docsPlan.apiDocs,
}),
guides: executor.fork({
role: "guide-writer",
scope: docsPlan.guides,
}),
examples: executor.fork({
role: "example-writer",
scope: docsPlan.examples,
}),
};
// 4. 并行生成
const [apiDocs, guides, examples] = await Promise.all([
docsTeam.api.run(),
docsTeam.guides.run(),
docsTeam.examples.run(),
]);
// 5. 审查一致性
const consistencyReview = await reviewer.checkConsistency({
apiDocs,
guides,
examples,
});
// 6. 整合
return aggregator.combine({
api: apiDocs,
guides,
examples,
});
}最佳实践
1. 合理的任务分配
代理分配原则：
规划代理：
- 任务理解
- 拆解
- 制定计划
执行代理：
- 按计划执行
- 遇到问题反馈
- 记录进度
审查代理：
- 验证结果
- 检查质量
- 提出改进
数量控制：
- 简单任务：1-2 个代理
- 复杂任务：3-5 个代理
- 超大任务：分层次，每层 3-5 个
2. 有效的通信
通信原则：
1. 使用清晰的消息格式
2. 避免频繁通信
3. 使用共享上下文
4. 明确的消息路由
3. 错误处理
javascript
// 错误处理策略
class AgentErrorHandler {
handleError(error, context) {
// 1. 分类错误
if (error.type === "retryable") {
return this.retry(error, context);
}
if (error.type === "escalate") {
return this.escalate(error, context);
}
// 2. 记录
this.logError(error, context);
// 3. 决定
return this.decideNextAction(error, context);
}
}协作效率
多代理协作可以将复杂任务分解并行处理，大幅缩短执行时间。
总结
Claude Code 多代理协作：
- 角色定义：规划、执行、审查等角色
- 通信机制：消息传递和共享上下文
- 协作流程：规划→执行→审查→汇总
- 应用场景：大型重构、文档生成、复杂项目
- 最佳实践：合理分配、有效通信、错误处理
通过多代理协作，可以高效处理复杂任务。