first commit

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

@@ -0,0 +1,437 @@
+# 多智能体协作
+
+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 定义结构
+
+```typescript
+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` 是创建和运行子智能体的核心函数：
+
+```typescript
+export async function* runAgent({
+  agentDefinition,       // Agent 定义
+  promptMessages,         // 提示消息
+  toolUseContext,         // 工具使用上下文
+  canUseTool,             // 工具使用权限检查
+  isAsync,                // 是否异步执行
+  querySource,            // 查询来源
+  model,                  // 模型覆盖
+  maxTurns,               // 最大轮次
+  allowedTools,           // 允许的工具列表
+  // ...
+}): AsyncGenerator<Message, void>
+```
+
+### 2.2 消息过滤
+
+```typescript
+// 过滤不完整的工具调用
+export function filterIncompleteToolCalls(messages: Message[]): Message[] {
+  // 移除有工具调用但没有结果的助手消息
+}
+```
+
+### 2.3 上下文隔离
+
+```typescript
+// 为子智能体创建隔离的上下文
+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 生命周期钩子
+
+```typescript
+// 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，适用于复杂研究和多步骤任务执行：
+
+```typescript
+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，用于验证任务完成情况：
+
+```typescript
+// 在 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`
+
+```typescript
+export type AgentMemory = {
+  sessionId: string
+  agentId: string
+  messages: Message[]
+  toolUseResults: Map<string, ToolResult>
+  fileState: FileStateCache
+}
+```
+
+### 5.2 文件状态缓存
+
+```typescript
+// 克隆文件状态缓存
+const agentReadFileState = forkContextMessages !== undefined
+  ? cloneFileStateCache(toolUseContext.readFileState)
+  : createFileStateCacheWithSizeLimit(READ_FILE_STATE_CACHE_SIZE)
+
+// 清理时释放
+agentToolUseContext.readFileState.clear()
+```
+
+### 5.3 转录记录
+
+```typescript
+// 记录初始消息
+await recordSidechainTranscript(initialMessages, agentId)
+
+// 记录新消息
+await recordSidechainTranscript([message], agentId, lastRecordedUuid)
+```
+
+## 6. 团队协调器 (coordinator/)
+
+### 6.1 协调器模式
+
+**位置：** `/src/coordinator/coordinatorMode.ts`
+
+协调器模式允许多个 Agent 在团队中协作。
+
+### 6.2 协调器 Agent
+
+```typescript
+// 获取协调器 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`
+
+```typescript
+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 可以预加载技能：
+
+```typescript
+const skillsToPreload = agentDefinition.skills ?? []
+if (skillsToPreload.length > 0) {
+  const allSkills = await getSkillToolCommands(getProjectRoot())
+  // 加载并注入技能内容
+}
+```
+
+### 8.2 技能名称解析
+
+```typescript
+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 服务器：
+
+```typescript
+async function initializeAgentMcpServers(
+  agentDefinition: AgentDefinition,
+  parentClients: MCPServerConnection[]
+): Promise<{
+  clients: MCPServerConnection[]
+  tools: Tools
+  cleanup: () => Promise<void>
+}>
+```
+
+### 9.2 服务器合并
+
+```typescript
+// 合并父级和 Agent 专用的 MCP 客户端
+const allTools = uniqBy([...resolvedTools, ...agentMcpTools], 'name')
+```
+
+## 10. 权限与隔离
+
+### 10.1 权限模式
+
+```typescript
+const agentPermissionMode = agentDefinition.permissionMode
+
+if (agentPermissionMode &&
+    state.toolPermissionContext.mode !== 'bypassPermissions' &&
+    state.toolPermissionContext.mode !== 'acceptEdits') {
+  toolPermissionContext = {
+    ...toolPermissionContext,
+    mode: agentPermissionMode
+  }
+}
+```
+
+### 10.2 工具过滤
+
+```typescript
+const resolvedTools = resolveAgentTools(
+  agentDefinition,
+  availableTools,
+  isAsync
+).resolvedTools
+```
+
+## 11. 性能优化
+
+### 11.1 CLAUDE.md 省略
+
+```typescript
+const shouldOmitClaudeMd = agentDefinition.omitClaudeMd &&
+  !override?.userContext &&
+  getFeatureValue_CACHED_MAY_BE_STALE('tengu_slim_subagent_claudemd', true)
+```
+
+### 11.2 Git 状态省略
+
+```typescript
+const resolvedSystemContext =
+  agentDefinition.agentType === 'Explore' ||
+  agentDefinition.agentType === 'Plan'
+    ? systemContextNoGit  // 省略 gitStatus
+    : baseSystemContext
+```
+
+### 11.3 推理配置
+
+```typescript
+thinkingConfig: useExactTools
+  ? toolUseContext.options.thinkingConfig  // 继承父级
+  : { type: 'disabled' as const }          // 禁用
+```
+
+## 12. Telemetry 与追踪
+
+### 12.1 Perfetto 追踪
+
+```typescript
+if (isPerfettoTracingEnabled()) {
+  registerPerfettoAgent(agentId, agentDefinition.agentType, parentId)
+}
+
+// 清理时注销
+unregisterPerfettoAgent(agentId)
+```
+
+### 12.2 转录存储
+
+```typescript
+// 边链转录
+await recordSidechainTranscript(initialMessages, agentId)
+
+// Agent 元数据
+await writeAgentMetadata(agentId, {
+  agentType: agentDefinition.agentType,
+  worktreePath,
+  description
+})
+```