扩展与集成第 15 章
Teams 多代理协作
Swarm 编排架构
核心洞察
Swarm 通过 iTerm/Tmux/InProcess 三种后端,支持从本地到分布式的多代理协作
学习
概念讲解与核心设计分析
15.1 TeamCreateTool 与 TeamDeleteTool
Claude Code 的多代理协作系统通过 TeamCreateTool 和 TeamDeleteTool 提供团队管理能力:
- TeamCreateTool — 创建并行工作团队。协调者代理(Coordinator)可以定义团队的组成、每个成员的任务和协作策略。团队成员以并行方式执行各自的任务,共享必要的上下文和权限
- TeamDeleteTool — 删除团队中的工作者。当某个工作者完成任务或不再需要时,协调者可以通过此工具回收资源
团队创建后,每个成员都是一个独立的代理实例,拥有独立的上下文窗口和工具集,但通过共享内存机制实现信息同步。
15.2 Swarm 编排架构
utils/swarm/ 目录包含 22+ 个文件,构成了完整的 Swarm 编排系统:
三种执行后端
- ITermBackend — iTerm2 终端后端,每个工作者在独立的 iTerm 标签页中运行,适合 macOS 开发环境下的可视化调试
- TmuxBackend — Tmux 会话后端,每个工作者在独立的 Tmux 窗格中运行,适合远程服务器和 CI/CD 环境
- InProcessBackend — 进程内后端,所有工作者在同一进程中运行,通过异步任务切换实现并行。资源开销最小,适合轻量级协作
15.3 Swarm 核心模块
- inProcessRunner.ts — 进程内队友执行器,管理工作者的生命周期、任务分配和结果收集
- permissionSync.ts — 权限同步模块,确保所有工作者共享一致的权限状态。当一个工作者获得用户授权后,其他工作者自动继承该权限
- teamHelpers.ts — 团队辅助函数,包括工作者状态查询、负载均衡和健康检查
- teammateInit.ts — 队友初始化模块,处理工作者的上下文准备、工具注册和 MCP 连接
- teammateModel.ts — 队友模型选择,根据任务类型和复杂度为每个工作者选择最合适的 AI 模型
- teammatePromptAddendum.ts — 队友附加提示词,为工作者注入协作相关的额外指令
15.4 协调者模式
coordinator/coordinatorMode.ts 实现了多代理编排的协调者模式。协调者负责:
- 分析任务并拆解为可并行执行的子任务
- 创建工作者团队并分配任务
- 监控工作者进度,处理失败和重试
- 汇总所有工作者的结果,生成最终输出
15.5 团队内存同步与安全
services/teamMemorySync/ 提供团队级别的内存同步服务:
- 工作者之间共享关键发现和上下文信息
- 防止重复工作和冲突操作
- 内置秘密扫描(Secret Scanning),防止敏感信息在工作者之间泄露
tasks/InProcessTeammateTask/ 定义了进程内队友的任务类型,管理任务的创建、执行和完成生命周期。
架构
模块关系与设计决策
Teams/Swarm 多代理协作架构图
协调者层 (Coordinator)
coordinatorMode.ts
任务拆解 & 编排
TeamCreateTool
TeamDeleteTool
↓
Swarm 编排层 (utils/swarm/)
ITermBackend
iTerm2 标签页
TmuxBackend
Tmux 窗格
InProcessBackend
进程内异步
teammateInit
teammateModel
teammatePrompt
↓
工作者层 (Workers)
Worker A
前端重构
Worker B
后端 API
Worker C
测试编写
↓
共享层
permissionSync
权限同步
teamMemorySync
内存同步
secretScanning
秘密扫描
源码
共 3 个关键代码示例
01
TeamCreateTool 与协调者模式TypeScript
// TeamCreateTool: 创建并行工作团队
const TeamCreateTool = {
name: 'TeamCreate',
description: '创建一个并行工作团队来执行多个子任务',
inputSchema: {
type: 'object',
properties: {
workers: {
type: 'array',
items: {
type: 'object',
properties: {
name: { type: 'string' },
task: { type: 'string' },
tools: {
type: 'array',
items: { type: 'string' }
}
}
}
},
backend: {
type: 'string',
enum: ['iterm', 'tmux', 'in-process']
}
}
},
execute: async (input: TeamCreateInput) => {
const backend = selectBackend(input.backend);
const workers = await Promise.all(
input.workers.map(w =>
backend.spawnWorker({
name: w.name,
task: w.task,
tools: w.tools
})
)
);
return { teamId: generateId(), workers };
}
};
// coordinatorMode.ts: 协调者编排模式
async function coordinatorMode(
task: string,
context: CoordinatorContext
): Promise<CoordinatorResult> {
// 1. 分析任务,拆解为子任务
const subtasks = await analyzeAndDecompose(task);
// 2. 创建工作者团队
const team = await TeamCreateTool.execute({
workers: subtasks.map(st => ({
name: st.name,
task: st.description,
tools: st.requiredTools
})),
backend: context.preferredBackend || 'in-process'
});
// 3. 监控进度
const results = await monitorTeam(team.teamId);
// 4. 汇总结果
return {
summary: aggregateResults(results),
teamId: team.teamId
};
}02
Swarm 执行后端与进程内运行器TypeScript
// 三种执行后端接口
interface SwarmBackend {
spawnWorker(config: WorkerConfig): Promise<Worker>;
killWorker(workerId: string): Promise<void>;
getWorkerStatus(workerId: string): WorkerStatus;
}
// InProcessBackend: 进程内后端
class InProcessBackend implements SwarmBackend {
private workers = new Map<string, InProcessWorker>();
async spawnWorker(
config: WorkerConfig
): Promise<Worker> {
const worker = new InProcessWorker(config);
this.workers.set(worker.id, worker);
// 初始化队友
await teammateInit(worker, {
tools: config.tools,
model: teammateModel.select(config.task),
prompt: config.task
+ '\n'
+ teammatePromptAddendum.get()
});
// 异步启动执行
worker.run().catch(err => {
worker.status = 'failed';
worker.error = err;
});
return worker;
}
async killWorker(workerId: string): Promise<void> {
const worker = this.workers.get(workerId);
if (worker) {
await worker.abort();
this.workers.delete(workerId);
}
}
getWorkerStatus(workerId: string): WorkerStatus {
const worker = this.workers.get(workerId);
return worker?.status || 'unknown';
}
}
// TmuxBackend: Tmux 会话后端
class TmuxBackend implements SwarmBackend {
async spawnWorker(
config: WorkerConfig
): Promise<Worker> {
// 创建 Tmux 窗格
const paneId = await execCommand(
'tmux split-window -h -P -F "#{pane_id}"'
);
// 在窗格中启动 Claude Code 子进程
await execCommand(
'tmux send-keys -t ' + paneId
+ ' "claude --agent-mode --task '
+ escapeShell(config.task) + '" Enter'
);
return { id: paneId, status: 'running' };
}
async killWorker(workerId: string): Promise<void> {
await execCommand('tmux kill-pane -t ' + workerId);
}
getWorkerStatus(workerId: string): WorkerStatus {
// 检查 Tmux 窗格是否存在
return 'running';
}
}03
权限同步与团队内存TypeScript
// permissionSync.ts: 工作者间权限同步
class PermissionSync {
private sharedPermissions = new Map<string, boolean>();
private listeners: PermissionListener[] = [];
// 当一个工作者获得权限时,广播给所有工作者
grantPermission(
workerId: string,
permission: string
): void {
this.sharedPermissions.set(permission, true);
// 通知所有其他工作者
for (const listener of this.listeners) {
listener.onPermissionGranted(permission);
}
}
// 检查权限是否已被任一工作者获得
hasPermission(permission: string): boolean {
return this.sharedPermissions.get(permission) || false;
}
subscribe(listener: PermissionListener): void {
this.listeners.push(listener);
}
}
// teamMemorySync: 团队内存同步服务
class TeamMemorySync {
private sharedMemory: SharedMemoryEntry[] = [];
// 工作者共享发现
shareDiscovery(
workerId: string,
discovery: string
): void {
// 秘密扫描:检查是否包含敏感信息
if (containsSecrets(discovery)) {
console.warn(
'Secret detected in worker ' + workerId
+ ' output, redacting...'
);
discovery = redactSecrets(discovery);
}
this.sharedMemory.push({
workerId,
content: discovery,
timestamp: Date.now()
});
}
// 获取所有共享内存
getSharedMemories(): SharedMemoryEntry[] {
return [...this.sharedMemory];
}
// 检查是否有工作者已经处理过某个文件
isFileBeingProcessed(filePath: string): boolean {
return this.sharedMemory.some(
m => m.content.includes(filePath)
&& m.content.includes('processing')
);
}
}
// teammatePromptAddendum.ts: 队友附加指令
const teammatePromptAddendum = {
get(): string {
return [
'你是团队中的一个工作者。',
'与其他工作者协作完成任务。',
'通过共享内存报告重要发现。',
'避免修改其他工作者正在处理的文件。',
'完成任务后生成简洁的结果摘要。'
].join('\n');
}
};互动
步进式流程演示
互动演示
多代理协作交互式演练
Step 1: 协调者分析任务
用户请求:"重构整个认证模块,更新 API、前端组件和测试"。协调者分析任务后,识别出三个可并行执行的子任务。
// 任务拆解结果
subtasks: [
{ name: 'api-worker', task: '重构认证 API 端点' },
{ name: 'frontend-worker', task: '更新前端认证组件' },
{ name: 'test-worker', task: '编写新的测试用例' }
]
Step 2: 创建工作者团队
TeamCreateTool 根据环境选择执行后端。本地开发使用 InProcessBackend,CI 环境使用 TmuxBackend。每个工作者被分配独立的工具集和上下文。
// InProcessBackend 模式
Worker A [api-worker]: 工具: Read, Write, Bash, Grep
Worker B [frontend-worker]: 工具: Read, Write, Glob, LSP
Worker C [test-worker]: 工具: Read, Write, Bash
Step 3: 并行执行与同步
三个工作者并行执行各自任务。permissionSync 确保权限共享——当 api-worker 获得写入 src/auth/ 的权限后,其他工作者自动继承。teamMemorySync 共享关键发现,防止冲突。
// 权限同步
api-worker 获得权限: Write src/auth/api.ts
→ frontend-worker 自动继承 Write 权限
→ test-worker 自动继承 Write 权限
// 内存同步
api-worker 共享: "API 接口签名已变更为..."
→ frontend-worker 读取并调整调用方式
→ test-worker 读取并更新测试断言
Step 4: 结果汇总
所有工作者完成后,协调者汇总结果。包括修改的文件列表、测试执行结果和潜在的冲突检测。最终生成完整的重构报告返回给用户。
// 汇总报告
{
filesModified: 12,
testsAdded: 8,
testsPassed: '8/8',
conflicts: 0,
summary: '认证模块重构完成...'
}
相关源文件
tools/TeamCreateTool/utils/swarm/coordinator/