claude-code-mirror/claude-code-中文Wiki/10-多智能体协作.md

多智能体协作

Claude Code 的多智能体系统允许创建和协调多个 AI 代理协同工作。本文档详细介绍 AgentTool 和相关协作机制。

1. AgentTool 概述

1.1 核心文件

位置： /src/tools/AgentTool/

主要文件：

• runAgent.ts - Agent 运行核心逻辑
• builtInAgents.ts - 内置 Agent 定义
• loadAgentsDir.ts - Agent 目录加载
• agentMemory.ts - Agent 内存管理
• built-in/ - 内置 Agent 实现

1.2 Agent 定义结构

export type AgentDefinition = {
  agentType: string           // Agent 类型标识
  whenToUse?: string          // 使用建议
  disallowedTools?: string[] // 禁用工具列表
  tools?: string[] | '*'      // 允许的工具
  source?: string             // 来源
  baseDir?: string            // 基础目录
  model?: string              // 模型设置
  permissionMode?: PermissionMode  // 权限模式
  maxTurns?: number           // 最大轮次
  getSystemPrompt?: () => string  // 系统提示
  hooks?: HooksSettings       // 钩子设置
  skills?: string[]           // 预加载技能
  mcpServers?: MCPServerSpec[] // MCP 服务器
  omitClaudeMd?: boolean       // 是否省略 CLAUDE.md
  effort?: EffortValue         // 努力值
  callback?: () => void        // 完成回调
}

2. 子智能体生成

2.1 runAgent 函数

位置： /src/tools/AgentTool/runAgent.ts

runAgent 是创建和运行子智能体的核心函数：

export async function* runAgent({
  agentDefinition,       // Agent 定义
  promptMessages,         // 提示消息
  toolUseContext,         // 工具使用上下文
  canUseTool,             // 工具使用权限检查
  isAsync,                // 是否异步执行
  querySource,            // 查询来源
  model,                  // 模型覆盖
  maxTurns,               // 最大轮次
  allowedTools,           // 允许的工具列表
  // ...
}): AsyncGenerator<Message, void>

2.2 消息过滤

// 过滤不完整的工具调用
export function filterIncompleteToolCalls(messages: Message[]): Message[] {
  // 移除有工具调用但没有结果的助手消息
}

2.3 上下文隔离

// 为子智能体创建隔离的上下文
const agentToolUseContext = createSubagentContext(toolUseContext, {
  options: agentOptions,
  agentId,
  agentType: agentDefinition.agentType,
  messages: initialMessages,
  readFileState: agentReadFileState,
  abortController: agentAbortController,
  getAppState: agentGetAppState,
  shareSetAppState: !isAsync,  // 同步 Agent 共享状态
})

3. 智能体生命周期管理

3.1 生命周期阶段

1. 初始化阶段

   • 创建 Agent ID
   • 设置上下文
   • 初始化 MCP 服务器
   • 注册 Hooks

2. 执行阶段

   • 运行查询循环
   • 处理工具调用
   • 管理会话

3. 清理阶段

   • 清理 MCP 服务器
   • 清除会话 Hooks
   • 释放内存
   • 杀死后台任务

3.2 生命周期钩子

// SubagentStart 钩子
for await (const hookResult of executeSubagentStartHooks(
  agentId,
  agentDefinition.agentType,
  agentAbortController.signal,
)) {
  // 收集额外上下文
}

// SubagentStop 钩子
if (agentDefinition.hooks) {
  clearSessionHooks(rootSetAppState, agentId)
}

4. 内置智能体 (built-in/)

4.1 generalPurposeAgent

位置： /src/tools/AgentTool/built-in/generalPurposeAgent.ts

通用目的 Agent，适用于复杂研究和多步骤任务执行：

export const GENERAL_PURPOSE_AGENT: BuiltInAgentDefinition = {
  agentType: 'general-purpose',
  whenToUse: 'General-purpose agent for researching complex questions...',
  tools: ['*'],  // 允许所有工具
  source: 'built-in',
  getSystemPrompt: getGeneralPurposeSystemPrompt,
}

4.2 planAgent

位置： /src/tools/AgentTool/built-in/planAgent.ts

软件架构师 Agent，用于设计实现计划：

关键特性：

• 只读模式：禁止任何文件修改操作
• 严格禁用工具：Edit, Write, NotebookEdit, Agent
• 允许工具：Read, Glob, Grep, Bash（仅限只读操作）

系统提示片段：

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
- Creating new files (no Write, touch, or file creation of any kind)
- Modifying existing files (no Edit operations)
- Deleting files (no rm or deletion)
...

4.3 verificationAgent

验证 Agent，用于验证任务完成情况：

// 在 TaskUpdateTool 中引用
const VERIFICATION_AGENT_TYPE = 'verification'

// 当满足条件时提示验证
if (allTasks.length >= 3 && !allTasks.some(t => /verif/i.test(t.subject))) {
  verificationNudgeNeeded = true
}

4.4 exploreAgent

探索 Agent，用于代码库探索和搜索：

特性：

• 只读操作
• 使用 find/grep 或 Glob/Grep 进行搜索
• 不加载 CLAUDE.md（节省 token）

4.5 statuslineSetup

状态栏设置 Agent，用于配置状态行显示。

4.6 claudeCodeGuideAgent

Claude Code 指南 Agent，帮助用户学习使用 Claude Code。

5. Agent 内存管理

5.1 Agent 内存结构

位置： /src/tools/AgentTool/agentMemory.ts

export type AgentMemory = {
  sessionId: string
  agentId: string
  messages: Message[]
  toolUseResults: Map<string, ToolResult>
  fileState: FileStateCache
}

5.2 文件状态缓存

// 克隆文件状态缓存
const agentReadFileState = forkContextMessages !== undefined
  ? cloneFileStateCache(toolUseContext.readFileState)
  : createFileStateCacheWithSizeLimit(READ_FILE_STATE_CACHE_SIZE)

// 清理时释放
agentToolUseContext.readFileState.clear()

5.3 转录记录

// 记录初始消息
await recordSidechainTranscript(initialMessages, agentId)

// 记录新消息
await recordSidechainTranscript([message], agentId, lastRecordedUuid)

6. 团队协调器 (coordinator/)

6.1 协调器模式

位置： /src/coordinator/coordinatorMode.ts

协调器模式允许多个 Agent 在团队中协作。

6.2 协调器 Agent

// 获取协调器 Agent
function getCoordinatorAgents(): AgentDefinition[]

7. 团队管理工具

7.1 TeamCreateTool

位置： /src/tools/TeamCreateTool/TeamCreateTool.ts

创建团队，管理团队配置。

7.2 TeamDeleteTool

位置： /src/tools/TeamDeleteTool/TeamDeleteTool.ts

删除团队，清理团队资源。

7.3 团队文件结构

位置： /src/utils/swarm/teamHelpers.ts

export type TeamFile = {
  name: string
  description?: string
  createdAt: number
  leadAgentId: string
  leadSessionId?: string
  hiddenPaneIds?: string[]
  teamAllowedPaths?: TeamAllowedPath[]
  members: Array<{
    agentId: string
    name: string
    agentType?: string
    model?: string
    prompt?: string
    color?: string
    planModeRequired?: boolean
    joinedAt: number
    tmuxPaneId: string
    cwd: string
    worktreePath?: string
    sessionId?: string
    subscriptions: string[]
    backendType?: BackendType
    isActive?: boolean
    mode?: PermissionMode
  }>
}

8. Agent 与技能的集成

8.1 技能预加载

Agent 可以预加载技能：

const skillsToPreload = agentDefinition.skills ?? []
if (skillsToPreload.length > 0) {
  const allSkills = await getSkillToolCommands(getProjectRoot())
  // 加载并注入技能内容
}

8.2 技能名称解析

function resolveSkillName(
  skillName: string,
  allSkills: Command[],
  agentDefinition: AgentDefinition
): string | null {
  // 1. 精确匹配
  if (hasCommand(skillName, allSkills)) return skillName

  // 2. 前缀匹配 (e.g., "my-skill" → "my-plugin:my-skill")
  const qualifiedName = `${pluginPrefix}:${skillName}`
  if (hasCommand(qualifiedName, allSkills)) return qualifiedName

  // 3. 后缀匹配 (e.g., ":my-skill")
  // ...
}

9. MCP 服务器集成

9.1 Agent 专用 MCP 服务器

Agent 可以定义自己的 MCP 服务器：

async function initializeAgentMcpServers(
  agentDefinition: AgentDefinition,
  parentClients: MCPServerConnection[]
): Promise<{
  clients: MCPServerConnection[]
  tools: Tools
  cleanup: () => Promise<void>
}>

9.2 服务器合并

// 合并父级和 Agent 专用的 MCP 客户端
const allTools = uniqBy([...resolvedTools, ...agentMcpTools], 'name')

10. 权限与隔离

10.1 权限模式

const agentPermissionMode = agentDefinition.permissionMode

if (agentPermissionMode &&
    state.toolPermissionContext.mode !== 'bypassPermissions' &&
    state.toolPermissionContext.mode !== 'acceptEdits') {
  toolPermissionContext = {
    ...toolPermissionContext,
    mode: agentPermissionMode
  }
}

10.2 工具过滤

const resolvedTools = resolveAgentTools(
  agentDefinition,
  availableTools,
  isAsync
).resolvedTools

11. 性能优化

11.1 CLAUDE.md 省略

const shouldOmitClaudeMd = agentDefinition.omitClaudeMd &&
  !override?.userContext &&
  getFeatureValue_CACHED_MAY_BE_STALE('tengu_slim_subagent_claudemd', true)

11.2 Git 状态省略

const resolvedSystemContext =
  agentDefinition.agentType === 'Explore' ||
  agentDefinition.agentType === 'Plan'
    ? systemContextNoGit  // 省略 gitStatus
    : baseSystemContext

11.3 推理配置

thinkingConfig: useExactTools
  ? toolUseContext.options.thinkingConfig  // 继承父级
  : { type: 'disabled' as const }          // 禁用

12. Telemetry 与追踪

12.1 Perfetto 追踪

if (isPerfettoTracingEnabled()) {
  registerPerfettoAgent(agentId, agentDefinition.agentType, parentId)
}

// 清理时注销
unregisterPerfettoAgent(agentId)

12.2 转录存储

// 边链转录
await recordSidechainTranscript(initialMessages, agentId)

// Agent 元数据
await writeAgentMetadata(agentId, {
  agentType: agentDefinition.agentType,
  worktreePath,
  description
})