Claude Code Agent-Teams深度解析：多智能体协作系统的技术实现原理

// utils/agentSwarmsEnabled.ts
export function isAgentSwarmsEnabled(): boolean {
  // Anthropic 内部用户：始终启用
  if (process.env.USER_TYPE === 'ant') {
    return true
  }
  // 外部用户需要同时满足两个条件：
  // 1. 环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true 或 --agent-teams CLI 标志
  if (!isEnvTruthy(process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) && !isAgentTeamsFlagSet()) {
    return false
  }
  // 2. GrowthBook 远程开关 tengu_amber_flint 启用（作为 killswitch）
  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_flint', true)) {
    return false
  }
  return true
}

// tools/TeamCreateTool/TeamCreateTool.ts
async call(input, context) {
  // 1. 唯一性检查 — 每个 Leader 只能管理一个团队
  if (existingTeam) {
    throw new Error(`Already leading team "${existingTeam}".`)
  }

  // 2. 生成唯一团队名 — 冲突时使用 word slug
  const finalTeamName = generateUniqueTeamName(team_name)

  // 3. 创建确定性 Leader Agent ID
  const leadAgentId = formatAgentId(TEAM_LEAD_NAME, finalTeamName)
  // 结果: "team-lead@my-project"

  // 4. 写入 TeamFile (config.json)
  const teamFile: TeamFile = {
    name: finalTeamName,
    createdAt: Date.now(),
    leadAgentId,
    leadSessionId: getSessionId(),
    members: [{ agentId: leadAgentId, name: TEAM_LEAD_NAME, ... }],
  }
  await writeTeamFileAsync(finalTeamName, teamFile)

  // 5. 注册会话清理 — 确保退出时清理孤立目录
  registerTeamForSessionCleanup(finalTeamName)

  // 6. 创建对应的任务列表目录（Team = TaskList，1:1 对应）
  await resetTaskList(taskListId)
  await ensureTasksDir(taskListId)

  // 7. 更新 AppState
  setAppState(prev => ({
    ...prev,
    teamContext: { teamName, teamFilePath, leadAgentId, teammates: {...} },
  }))
}

// utils/swarm/teamHelpers.ts
export type TeamFile = {
  name: string
  description?: string
  createdAt: number
  leadAgentId: string
  leadSessionId?: string     // Leader 的 Session UUID
  hiddenPaneIds?: string[]   // 隐藏的窗格 ID
  teamAllowedPaths?: TeamAllowedPath[]  // 团队级路径权限
  members: Array<{
    agentId: string          // "researcher@my-team"
    name: string             // "researcher"
    agentType?: string
    model?: string
    color?: string
    planModeRequired?: boolean
    joinedAt: number
    tmuxPaneId: string
    cwd: string
    backendType?: BackendType   // 'tmux' | 'iterm2' | 'in-process'
    isActive?: boolean          // false=idle, true/undefined=active
    mode?: PermissionMode       // 当前权限模式
  }>
}

// utils/swarm/backends/types.ts
export type BackendType = 'tmux' | 'iterm2' | 'in-process'

// tools/shared/spawnMultiAgent.ts
async function handleSpawn(input, context) {
  // 优先检查 in-process 模式
  if (isInProcessEnabled()) {
    return handleSpawnInProcess(input, context)
  }
  // Pre-flight: 确保 pane 后端可用
  try {
    await detectAndGetBackend()
  } catch (error) {
    // auto 模式下自动回退到 in-process
    if (getTeammateModeFromSnapshot() !== 'auto') throw error
    markInProcessFallback()
    return handleSpawnInProcess(input, context)
  }
  // 使用分屏或独立窗口
  return input.use_splitpane !== false
    ? handleSpawnSplitPane(input, context)
    : handleSpawnSeparateWindow(input, context)
}

cd /path/to/cwd && env CLAUDECODE=... \
  claude --agent-id "researcher@my-team" \
         --agent-name "researcher" \
         --team-name "my-team" \
         --agent-color "blue" \
         --parent-session-id "xxx" \
         --model "claude-sonnet-4-20250514"

function buildInheritedCliFlags(options) {
  // plan_mode_required 时不继承 bypassPermissions（安全优先）
  if (planModeRequired) {
    // 不继承 --dangerously-skip-permissions
  } else if (permissionMode === 'bypassPermissions') {
    flags.push('--dangerously-skip-permissions')
  } else if (permissionMode === 'auto') {
    flags.push('--permission-mode auto')
  }
  // 继承 --model, --settings, --plugin-dir, --chrome
}

// utils/teammateMailbox.ts
export type TeammateMessage = {
  from: string       // 发送者名称
  text: string       // 消息内容（可以是纯文本或 JSON 结构化消息）
  timestamp: string  // ISO 时间戳
  read: boolean      // 是否已读
  color?: string     // 发送者颜色
  summary?: string   // 5-10 字摘要（UI 预览用）
}

const LOCK_OPTIONS = {
  retries: {
    retries: 10,      // 10 次重试
    minTimeout: 5,     // 最小等待 5ms
    maxTimeout: 100,   // 最大等待 100ms
  },
}

export async function writeToMailbox(recipientName, message, teamName) {
  const lockFilePath = `${inboxPath}.lock`
  const release = await lockfile.lock(inboxPath, { lockfilePath, ...LOCK_OPTIONS })
  try {
    const messages = await readMailbox(recipientName, teamName)
    messages.push({ ...message, read: false })
    await writeFile(inboxPath, JSON.stringify(messages, null, 2), 'utf-8')
  } finally {
    await release()
  }
}

// tools/SendMessageTool/SendMessageTool.ts
async call(input, context) {
  // 1. UDS/Bridge 地址 → 跨会话发送
  if (feature('UDS_INBOX') && parseAddress(input.to).scheme === 'bridge') { ... }

  // 2. 进程内 subagent（通过 agentNameRegistry 查找）
  if (typeof input.message === 'string' && input.to !== '*') {
    const registered = appState.agentNameRegistry.get(input.to)
    if (registered) {
      // 运行中 → 直接加入 pendingMessages 队列
      if (task.status === 'running') {
        queuePendingMessage(agentId, input.message, ...)
      }
      // 已停止 → 自动恢复 (auto-resume)
      else { await resumeAgentBackground(...) }
    }
  }

  // 3. "*" → 广播到所有队友
  if (input.to === '*') return handleBroadcast(...)

  // 4. 名称 → 写入目标邮箱
  return handleMessage(input.to, input.message, ...)

  // 5. 结构化消息 → 分发到对应 handler
  switch (input.message.type) {
    case 'shutdown_request': return handleShutdownRequest(...)
    case 'shutdown_response': ...
    case 'plan_approval_response': ...
  }
}

// utils/swarm/inProcessRunner.ts
export async function runInProcessTeammate(config) {
  while (!abortController.signal.aborted && !shouldExit) {
    // 1. 创建 per-turn AbortController
    //    Escape 键可中断当前轮次但不杀死队友
    const currentWorkAbortController = createAbortController()

    // 2. 检查是否需要自动压缩
    if (tokenCount > getAutoCompactThreshold(model)) {
      const compactedSummary = await compactConversation(allMessages, ...)
      contextMessages = buildPostCompactMessages(compactedSummary)
      allMessages.length = 0
      allMessages.push(...contextMessages)
    }

    // 3. 在双重上下文中执行 runAgent()
    await runWithTeammateContext(teammateContext, async () => {
      return runWithAgentContext(agentContext, async () => {
        for await (const message of runAgent({
          agentDefinition: iterationAgentDefinition,
          promptMessages,
          canUseTool: createInProcessCanUseTool(identity, ...),
          forkContextMessages,
          ...
        })) {
          iterationMessages.push(message)
          allMessages.push(message)
          // 更新进度、追踪工具调用
        }
      })
    })

    // 4. 标记为 idle 并通知 Leader
    updateTaskState(taskId, task => ({ ...task, isIdle: true }))
    await sendIdleNotification(identity.agentName, identity.color, ...)

    // 5. 等待唤醒（轮询邮箱 + 任务列表）
    const waitResult = await waitForNextPromptOrShutdown(...)

    switch (waitResult.type) {
      case 'shutdown_request':
        // 传递给 LLM 模型决策
        currentPrompt = formatAsTeammateMessage(waitResult.request.from, ...)
        break
      case 'new_message':
        currentPrompt = formatAsTeammateMessage(waitResult.from, waitResult.message, ...)
        break
      case 'aborted':
        shouldExit = true
        break
    }
  }
}

// utils/swarm/teammateInit.ts
export function initializeTeammateHooks(setAppState, sessionId, teamInfo) {
  // 1. 读取 TeamFile 获取 Leader 信息
  const teamFile = readTeamFile(teamName)

  // 2. 应用团队级路径权限
  for (const allowedPath of teamFile.teamAllowedPaths) {
    setAppState(prev => ({
      ...prev,
      toolPermissionContext: applyPermissionUpdate(prev.toolPermissionContext, {
        type: 'addRules',
        rules: [{ toolName: allowedPath.toolName, ruleContent: `/${allowedPath.path}/**` }],
        behavior: 'allow',
        destination: 'session',
      }),
    }))
  }

  // 3. 注册 Stop 钩子 — 停止时自动发送 idle_notification
  addFunctionHook(setAppState, sessionId, 'Stop', '', async (messages) => {
    void setMemberActive(teamName, agentName, false)
    const notification = createIdleNotification(agentName, { idleReason: 'available' })
    await writeToMailbox(leadAgentName, { from: agentName, text: JSON.stringify(notification), ... })
    return true
  })
}

// utils/swarm/inProcessRunner.ts — createInProcessCanUseTool()
const setToolUseConfirmQueue = getLeaderToolUseConfirmQueue()

if (setToolUseConfirmQueue) {
  return new Promise(resolve => {
    setToolUseConfirmQueue(queue => [...queue, {
      tool, description, input, toolUseContext, toolUseID,
      permissionResult: result,
      // Worker 标识 — 在 Leader UI 中显示名称和颜色
      workerBadge: { name: identity.agentName, color: identity.color },
      onAllow(updatedInput, permissionUpdates, feedback) {
        persistPermissionUpdates(permissionUpdates)
        // 权限更新回写到 Leader 的共享上下文
        if (permissionUpdates.length > 0) {
          setToolPermissionContext(updatedContext, { preserveMode: true })
        }
        resolve({ behavior: 'allow', updatedInput })
      },
      onReject(feedback) {
        resolve({ behavior: 'ask', message: SUBAGENT_REJECT_MESSAGE })
      },
    }])
  })
}

// Worker 侧：发送请求
const request = createPermissionRequest({ toolName, toolUseId, input, description, ... })
registerPermissionCallback({ requestId: request.id, onAllow, onReject })
await sendPermissionRequestViaMailbox(request)

// Worker 轮询响应 (每 500ms)
const pollInterval = setInterval(async () => {
  const allMessages = await readMailbox(identity.agentName, identity.teamName)
  for (const msg of allMessages) {
    const parsed = isPermissionResponse(msg.text)
    if (parsed && parsed.request_id === request.id) {
      processMailboxPermissionResponse(parsed)
      return
    }
  }
}, PERMISSION_POLL_INTERVAL_MS)

if (feature('BASH_CLASSIFIER') && tool.name === BASH_TOOL_NAME && result.pendingClassifierCheck) {
  const classifierDecision = await awaitClassifierAutoApproval(
    result.pendingClassifierCheck,
    abortController.signal,
  )
  if (classifierDecision) {
    return { behavior: 'allow', updatedInput: input, decisionReason: classifierDecision }
  }
}

// AppState.teamContext
teamContext: {
  teamName: string
  teamFilePath: string
  leadAgentId: string
  teammates: {
    [agentId: string]: {
      name: string
      agentType?: string
      color?: string
      tmuxSessionName: string
      tmuxPaneId: string
      cwd: string
      spawnedAt: number
    }
  }
}

// AppState.tasks[taskId] — InProcessTeammateTaskState
{
  type: 'in_process_teammate'
  identity: TeammateIdentity        // agentId, agentName, teamName, color
  prompt: string
  abortController?: AbortController // 生命周期控制
  currentWorkAbortController?: AbortController // 当前轮次控制
  permissionMode: PermissionMode
  messages?: Message[]              // UI 镜像，上限 50 条
  pendingUserMessages: string[]     // 待传递的用户消息
  isIdle: boolean
  shutdownRequested: boolean
  progress?: AgentProgress
}

// utils/teammateContext.ts
const teammateContextStorage = new AsyncLocalStorage<TeammateContext>()

export type TeammateContext = {
  agentId: string           // "researcher@my-team"
  agentName: string         // "researcher"
  teamName: string
  color?: string
  planModeRequired: boolean
  parentSessionId: string
  isInProcess: true         // 始终为 true
  abortController: AbortController
}

// 在特定上下文中运行
export function runWithTeammateContext<T>(context: TeammateContext, fn: () => T): T {
  return teammateContextStorage.run(context, fn)
}

// utils/swarm/inProcessRunner.ts
function findAvailableTask(tasks: Task[]): Task | undefined {
  const unresolvedTaskIds = new Set(
    tasks.filter(t => t.status !== 'completed').map(t => t.id)
  )
  return tasks.find(task => {
    if (task.status !== 'pending') return false
    if (task.owner) return false
    // 所有前置依赖必须已完成
    return task.blockedBy.every(id => !unresolvedTaskIds.has(id))
  })
}

const notification = createIdleNotification(agentName, {
  idleReason: workWasAborted ? 'interrupted' : 'available',
  summary: getLastPeerDmSummary(allMessages),  // 最后一条 peer DM 的摘要
  completedTaskId,
  completedStatus: 'resolved' | 'blocked' | 'failed',
})