Claude Code Agent 与团队系统技术文档

️ 系统架构总览Claude Code CLI (src/main.tsx) ├── QueryEngine # 核心 LLM 查询与模型交互 ├── Tool Registry # 工具注册与管理 (40 工具) ├── Agent System # 智能体创建与生命周期管理 └── Coordinator # 协调者模式 - 多 worker 编排核心组件路径AgentTool:src/tools/AgentTool/AgentTool.tsx(58k tokens) - 核心工具定义runAgent.ts- Agent 运行引擎agentToolUtils.ts- 工具函数与生命周期管理resumeAgent.ts- 暂停/恢复机制forkSubagent.ts- 子 Agent 分叉agentMemory.ts- 内存管理loadAgentsDir.ts- 动态加载 Agent 定义built-in/- 内置 Agent 类型团队工具:src/tools/Team*/和src/tools/SendMessageTool/TeamCreateTool.ts- 创建团队TeamDeleteTool.ts- 删除团队SendMessageTool.ts- 团队成员通信协调者:src/coordinator/coordinatorMode.ts团队管理:src/utils/swarm/- 团队配置文件与会话管理 Agent 智能体系统Agent Tool APIAgent({ // 必需参数 description: 简短描述3-5词, // 用于 UI 显示 prompt: 详细任务指令, // 完整的任务说明 // 可选参数 subagent_type?: worker | explore | plan | general | verification, model?: sonnet | opus | haiku, run_in_background?: boolean, // 是否后台运行 isolation?: worktree, // 工作树隔离 cwd?: /path/to/work, // 工作目录 name?: my-agent, // Agent 名称 team_name?: team-name // 所属团队 })内置 Agent 类型类型用途文件特点general-purpose通用任务built-in/generalPurposeAgent.ts全工具访问代码研究explore探索发现built-in/exploreAgent.ts只读模式快速搜索plan方案制定built-in/planAgent.ts计划生成verification验证检查built-in/verificationAgent.ts独立验证claude-code-guide使用指南built-in/claudeCodeGuideAgent.ts帮助文档Explore Agent只读模式// src/tools/AgentTool/built-in/exploreAgent.ts { agentType: Explore, disallowedTools: [ AGENT_TOOL_NAME, // 禁止创建子Agent FILE_EDIT_TOOL_NAME, // 禁止编辑 FILE_WRITE_TOOL_NAME, // 禁止写入 NOTEBOOK_EDIT_TOOL_NAME, // 禁止编辑Notebook ], model: process.env.USER_TYPE ant ? inherit : haiku, // 快速 omitClaudeMd: true, // 不需要CLAUDE.md }系统提示要点禁止文件修改、删除、移动、创建只能使用Glob、Grep、Read、Bash只读必须快速返回结果支持并行搜索通用 Agent// src/tools/AgentTool/built-in/generalPurposeAgent.ts { agentType: general-purpose, tools: [*], // 所有工具 whenToUse: 通用任务..., }️ 工具访问控制禁止列表// src/constants/tools.ts export const ALL_AGENT_DISALLOWED_TOOLS new Set([ TASK_OUTPUT_TOOL_NAME, // 防止递归 EXIT_PLAN_MODE_V2_TOOL_NAME, // 主线程抽象 ENTER_PLAN_MODE_TOOL_NAME, // 同上 AGENT_TOOL_NAME, // 防止嵌套ant用户除外 ASK_USER_QUESTION_TOOL_NAME, // 需要用户交互 TASK_STOP_TOOL_NAME, // 需要主线程状态访问 ]) ​ export const ASYNC_AGENT_ALLOWED_TOOLS new Set([ FILE_READ_TOOL_NAME, WEB_SEARCH_TOOL_NAME, GREP_TOOL_NAME, GLOB_TOOL_NAME, ...SHELL_TOOL_NAMES, // Bash工具 FILE_EDIT_TOOL_NAME, FILE_WRITE_TOOL_NAME, NOTEBOOK_EDIT_TOOL_NAME, SKILL_TOOL_NAME, // 技能工具 // ...其他工具 ])过滤逻辑// src/tools/AgentTool/agentToolUtils.ts export function filterToolsForAgent({ tools, isBuiltIn, isAsync false, permissionMode, }) { return tools.filter(tool { // 1. MCP 工具全部允许 if (tool.name.startsWith(mcp__)) return true // 2. 计划模式下允许 ExitPlanMode if (toolMatchesName(tool, EXIT_PLAN_MODE_V2_TOOL_NAME) permissionMode plan) { return true } // 3. 检查禁止列表 if (ALL_AGENT_DISALLOWED_TOOLS.has(tool.name)) return false if (!isBuiltIn CUSTOM_AGENT_DISALLOWED_TOOLS.has(tool.name)) return false // 4. 异步 Agent 只能使用允许的工具 if (isAsync !ASYNC_AGENT_ALLOWED_TOOLS.has(tool.name)) { // 特殊处理进程内队友 if (isAgentSwarmsEnabled() isInProcessTeammate()) { if (toolMatchesName(tool, AGENT_TOOL_NAME)) return true // 允许创建同步子Agent if (IN_PROCESS_TEAMMATE_ALLOWED_TOOLS.has(tool.name)) return true } return false } return true }) } Agent 生命周期管理异步 Agent 生命周期// src/tools/AgentTool/agentToolUtils.ts export async function runAsyncAgentLifecycle({ taskId, abortController, makeStream, // 消息流生成器 metadata, description, toolUseContext, rootSetAppState, agentIdForCleanup, enableSummarization, getWorktreeResult }): Promisevoid { let stopSummarization: (() void) | undefined const agentMessages: MessageType[] [] try { // 1. 初始化进度追踪器 const tracker createProgressTracker() const resolveActivity createActivityDescriptionResolver(tools) // 2. 缓存参数回调用于摘要 const onCacheSafeParams enableSummarization ? (params: CacheSafeParams) { const { stop } startAgentSummarization(...) stopSummarization stop } : undefined // 3. 处理消息流 for await (const message of makeStream(onCacheSafeParams)) { agentMessages.push(message) // 更新应用状态 rootSetAppState(prev { const t prev.tasks[taskId] if (!isLocalAgentTask(t) || !t.retain) return prev return { ...prev, tasks: { ...prev.tasks, [taskId]: { ...t, messages: [...(t.messages ?? []), message] }, }, } }) // 更新进度 updateProgressFromMessage(tracker, message, resolveActivity, tools) updateAsyncAgentProgress(taskId, getProgressUpdate(tracker), rootSetAppState) // 发送进度事件 const lastToolName getLastToolUseName(message) if (lastToolName) { emitTaskProgress(tracker, taskId, toolUseContext.toolUseId, description, metadata.startTime, lastToolName) } } // 4. 停止摘要 stopSummarization?.() // 5. 生成最终结果 const agentResult finalizeAgentTool(agentMessages, taskId, metadata) // 6. 标记任务完成必须先于其他操作 completeAsyncAgent(agentResult, rootSetAppState) // 7. 提取消息内容 let finalMessage extractTextContent(agentResult.content, \n) // 8. 安全检查TRANSCRIPT_CLASSIFIER if (feature(TRANSCRIPT_CLASSIFIER)) { const handoffWarning await classifyHandoffIfNeeded({ ... }) if (handoffWarning) { finalMessage ${handoffWarning}\n\n${finalMessage} } } // 9. 获取工作树结果 const worktreeResult await getWorktreeResult() // 10. 发送通知 enqueueAgentNotification({ taskId, description, status: completed, setAppState: rootSetAppState, finalMessage, usage: { totalTokens: getTokenCountFromTracker(tracker), toolUses: agentResult.totalToolUseCount, durationMs: agentResult.totalDurationMs, }, toolUseId: toolUseContext.toolUseId, ...worktreeResult, }) } catch (error) { stopSummarization?.() if (error instanceof AbortError) { // 用户中止 killAsyncAgent(taskId, rootSetAppState) const worktreeResult await getWorktreeResult() const partialResult extractPartialResult(agentMessages) enqueueAgentNotification({ status: killed, ... }) return } // 执行失败 const msg errorMessage(error) failAsyncAgent(taskId, msg, rootSetAppState) const worktreeResult await getWorktreeResult() enqueueAgentNotification({ status: failed, error: msg, ... }) } finally { // 清理 clearInvokedSkillsForAgent(agentIdForCleanup) clearDumpState(agentIdForCleanup) } }任务暂停与恢复// src/tools/AgentTool/resumeAgent.ts export async function resumeAgentBackground({ agentId, prompt, toolUseContext, canUseTool, invokingRequestId, }) { const appState context.getAppState() const task appState.tasks[agentId] // 情况1任务正在运行 if (isLocalAgentTask(task) !isMainSessionTask(task)) { if (task.status running) { // 排队等待下一轮处理 queuePendingMessage(agentId, prompt, ...) return { success: true, queued: true } } // 情况2任务已停止自动恢复 try { const result await resumeAgentBackground({ ... }) return result } catch (e) { return { success: false, message: 无法恢复: ${errorMessage(e)} } } } // 情况3从磁盘 transcript 恢复 try { const result await resumeAgentFromDisk(...) return result } catch (e) { return { success: false, message: 无记录: ${errorMessage(e)} } } }进度追踪// src/tasks/LocalAgentTask/LocalAgentTask.ts export function createProgressTracker(): ProgressTracker { return { lastActivity: null, // 最后活动描述 tokenCount: 0, // token 总数 toolUseCount: 0, // 工具使用次数 lastUpdateTime: Date.now(), } } export function updateProgressFromMessage( tracker: ProgressTracker, message: MessageType, resolveActivity: ActivityResolver, tools: Tools ) { if (message.type assistant) { for (const block of message.message.content) { if (block.type tool_use) { tracker.toolUseCount tracker.lastActivity resolveActivity(block.name) } } } // 更新 token 计数 if (message.message.usage) { tracker.tokenCount getTokenCountFromUsage(message.message.usage) } tracker.lastUpdateTime Date.now() }结果生成// src/tools/AgentTool/agentToolUtils.ts export function finalizeAgentTool( agentMessages: MessageType[], agentId: string, metadata: { ... }, ): AgentToolResult { const lastAssistantMessage getLastAssistantMessage(agentMessages) if (!lastAssistantMessage) { throw new Error(No assistant messages found) } // 提取文本内容跳过纯 tool_use 消息 let content lastAssistantMessage.message.content.filter(_ _.type text) if (content.length 0) { // 回退查找 for (let i agentMessages.length - 1; i 0; i--) { const m agentMessages[i]! if (m.type ! assistant) continue const textBlocks m.message.content.filter(_ _.type text) if (textBlocks.length 0) { content textBlocks break } } } const totalTokens getTokenCountFromUsage(lastAssistantMessage.message.usage) const totalToolUseCount countToolUses(agentMessages) // 记录分析事件 logEvent(tengu_agent_tool_completed, { agent_type: metadata.agentType, model: metadata.resolvedAgentModel, prompt_char_count: metadata.prompt.length, response_char_count: content.length, assistant_message_count: agentMessages.length, total_tool_uses: totalToolUseCount, duration_ms: Date.now() - metadata.startTime, total_tokens: totalTokens, is_built_in_agent: metadata.isBuiltInAgent, is_async: metadata.isAsync, }) return { agentId, agentType: metadata.agentType, content, totalDurationMs: Date.now() - metadata.startTime, totalTokens, totalToolUseCount, usage: lastAssistantMessage.message.usage, } }工作树隔离// src/utils/worktree.ts export async function createAgentWorktree(agentId: string): Promise{ worktreePath: string worktreeBranch: string } { // 创建 git worktree 实现隔离 // git worktree add path branch return { worktreePath: /path/to/.claude/worktrees/${agentId}, worktreeBranch: agent-${agentId} } } export async function removeAgentWorktree(agentId: string) { // git worktree remove --force path // rm -rf path } 团队系统Swarm团队配置文件// src/utils/swarm/teamHelpers.ts export type TeamFile { name: string // 团队名称 description?: string // 描述 createdAt: number // 创建时间 leadAgentId: string // 领导ID (team-leadteam-name) leadSessionId?: string // 领导会话UUID hiddenPaneIds?: string[] // 隐藏的tmux窗格 teamAllowedPaths?: TeamAllowedPath[] // 共享编辑路径 members: Array{ agentId: string // Agent ID name: string // 名称 agentType?: string // 类型 model?: string // 模型 color?: string // 颜色标识 planModeRequired?: boolean // 是否需要计划模式 joinedAt: number // 加入时间 tmuxPaneId: string // tmux窗格ID cwd: string // 工作目录 worktreePath?: string // 工作树路径 sessionId?: string // 会话ID subscriptions: string[] // 订阅 backendType?: BackendType // 后端类型 isActive?: boolean // 是否活跃 mode?: PermissionMode // 权限模式 } }TeamCreate 工具TeamCreate({ team_name: my-team, // 团队名称 description: 团队描述, // 可选 agent_type: researcher // 领导类型可选 })执行流程名称去重若团队已存在生成唯一名称generateUniqueTeamName生成领导IDformatAgentId(TEAM_LEAD_NAME, teamName)→team-leadmy-team创建配置文件~/.claude/teams/{team-name}/config.json初始化任务列表~/.claude/tasks/{sanitized-name}/注册清理钩子registerTeamForSessionCleanup更新AppState设置teamContext和teammates记录事件tengu_team_createdTeamDelete 工具TeamDelete()执行流程检查活跃成员过滤isActive ! false的成员若有活跃成员返回错误要求先requestShutdown清理工作树destroyWorktree()→git worktree remove --force或rm -rf清理目录删除~/.claude/teams/{team-name}/和任务目录清理缓存clearTeammateColors()、clearLeaderTeamName()更新AppState移除teamContext和inbox注销清理钩子unregisterTeamForSessionCleanupSendMessage 工具单播消息SendMessage({ to: teammate-name, message: 消息内容, summary: 摘要5-10词 })广播消息SendMessage({ to: *, message: 广播内容, summary: 广播摘要 })结构化消息// 关机请求 SendMessage({ to: teammate-name, message: { type: shutdown_request, reason: 任务完成 } }) // 关机响应 SendMessage({ to: team-lead, message: { type: shutdown_response, request_id: req-123, approve: true, reason: 已完成 } }) // 计划审批 SendMessage({ to: teammate-name, message: { type: plan_approval_response, request_id: req-456, approve: true, feedback: 计划已批准 } })团队通信机制团队领导邮箱系统团队成员SendMessage(tomember, message)写入邮箱 (~/.claude/mailboxes/)查询新消息返回消息列表loop[轮询检查]SendMessage(toteam-lead, response)写入领导邮箱团队领导邮箱系统团队成员邮箱文件结构~/.claude/mailboxes/ └── {team-name}/ ├── {member-name}/ │ ├── inbox.json # 收到的消息 │ └── pending/ # 待处理 └── team-lead/ └── inbox.json进程内队友In-Process Teammates适用于轻量级协作共享同一 Node.js 进程// src/tasks/InProcessTeammateTask/InProcessTeammateTask.ts // 特点 // - 共享同一进程无进程通信开销 // - 使用共享任务列表协调 // - 支持 SendMessage 通信 // - 适合快速迭代的小任务允许的工具export const IN_PROCESS_TEAMMATE_ALLOWED_TOOLS new Set([ TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_LIST_TOOL_NAME, TASK_UPDATE_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, ...(feature(AGENT_TRIGGERS) ? [CRON_CREATE_TOOL_NAME, ...] : []), ])权限模式系统团队成员可设置不同的权限模式影响工具访问// src/utils/permissions/PermissionMode.ts export type PermissionMode | auto // 自动模式AI 决定 | plan // 计划模式需领导审批 | default // 默认模式询问用户 | micro // 微操作模式 | review // 审查模式模式继承// 领导审批时 const leaderMode appState.toolPermissionContext.mode const modeToInherit leaderMode plan ? default : leaderMode // 团队成员继承领导模式plan → default颜色分配系统// src/utils/swarm/teammateLayoutManager.ts export function assignTeammateColor(agentId: string): string { // 基于 agentId 哈希分配颜色 // 确保同一 Agent 始终使用相同颜色 } export function getTeammateColor(agentId: string): string { // 获取已分配颜色 } export function clearTeammateColors() { // 清理所有颜色分配 }后台任务管理自动后台化120秒无响应// src/tools/AgentTool/AgentTool.tsx const PROGRESS_THRESHOLD_MS 2000 // 2秒后显示后台提示 function getAutoBackgroundMs(): number { if (isEnvTruthy(process.env.CLAUDE_AUTO_BACKGROUND_TASKS) || getFeatureFlag(tengu_auto_background_agents, false)) { return 120_000 // 120秒后自动后台 } return 0 // 禁用 }后台任务通知// 任务完成后发送通知 enqueueAgentNotification({ taskId, description, status: completed, // 或 failed | killed setAppState, finalMessage, usage: { totalTokens, toolUses, durationMs }, worktreePath, // 可选 worktreeBranch // 可选 }) 协调者模式Coordinator Mode启用方式export CLAUDE_CODE_COORDINATOR_MODE1系统提示// src/coordinator/coordinatorMode.ts - getCoordinatorSystemPrompt() You are Claude Code, an AI assistant that orchestrates software engineering tasks across multiple workers. ## 1. Your Role - 帮助用户达成目标 - 指挥工人执行研究、实施、验证 - 合成结果并与用户沟通 - 直接回答可处理的问题不委派无需工具的工作 ## 2. Your Tools - Agent - 创建新工人 - SendMessage - 继续现有工人 - TaskStop - 停止工人 - subscribe_pr_activity - 订阅GitHub PR事件 ## 3. Workers 工人执行自主任务特别是研究、实施或验证。 工人有访问标准工具、MCP工具和项目技能的权限。 ## 4. Task Workflow | 阶段 | 执行者 | 目的 | |------|--------|------| | 研究 | 工人并行 | 探索代码库、理解问题 | | 合成 | 协调者 | 理解结果制定实施规范 | | 实施 | 工人 | 按规范进行更改 | | 验证 | 工人 | 证明代码有效 | ## 5. 并发原则 - **并行优先**独立研究任务同时运行 - **写入串行**同一文件的修改一次一个 - **验证可并行**不同区域的验证可同时进行 ## 6. Worker 提示编写 - 合成研究发现包含具体文件路径、行号 - 从不写“基于你的发现...” - 明确说明完成标准 - 包含目的陈述 工作流示例Syntax error in graphmermaid version 8.14.0ERROR: [Mermaid] Lexical error on line 2. Unrecognized text. graph TD A[用户修复认证模块null pointer] ----------------^最佳实践明确 spec❌ 错误基于你的发现修复问题✅ 正确修复src/auth/validate.ts:42添加 user 字段空检查合理并行研究阶段尽可能并行写入阶段控制并发避免冲突继续 vs 新建继续SendMessageWorker 已有相关上下文新建Agent需要全新视角或不相关任务验证独立使用独立 Worker 验证不要自我验证 工具对照表工具路径用途团队相关Agentsrc/tools/AgentTool/创建智能体✅ 支持 team_nameTeamCreatesrc/tools/TeamCreateTool/创建团队主工具TeamDeletesrc/tools/TeamDeleteTool/删除团队主工具SendMessagesrc/tools/SendMessageTool/发送消息主工具TaskCreatesrc/tools/TaskCreateTool/创建任务✅ 团队任务列表TaskListsrc/tools/TaskListTool/列出任务✅ 团队任务列表TaskUpdatesrc/tools/TaskUpdateTool/更新任务✅ 团队任务列表EnterPlanModesrc/tools/EnterPlanModeTool/进入计划模式✅ 团队计划审批ExitPlanModesrc/tools/ExitPlanModeTool/退出计划模式✅ 团队计划审批 关键配置功能开关# 主动助手模式 PROACTIVE1 KAIROS1 # 协调者模式 CLAUDE_CODE_COORDINATOR_MODE1 # 工作流脚本 WORKFLOW_SCRIPTS1 # 计划验证 CLAUDE_CODE_VERIFY_PLAN1 # 跨进程消息 UDS_INBOX1 # 自动后台化 CLAUDE_AUTO_BACKGROUND_TASKS1 # 简化模式限制工具 CLAUDE_CODE_SIMPLE1Agent SDK 配置# 禁用内置AgentSDK用户 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS1 # 团队命令 CLAUDE_CODE_TEAM_NAMEmy-team # 队友命令 CLAUDE_CODE_AGENT_NAMEresearcher CLAUDE_CODE_AGENT_COLORblue CLAUDE_CODE_PLAN_MODE_REQUIREDtrue # 队友命令 CLAUDE_CODE_TEAMMATE_COMMAND/path/to/claude 使用示例示例1单个 Agent 研究任务Agent({ description: 研究认证模块, prompt: 分析 src/auth/ 目录找出所有会话处理逻辑。重点关注 1. Session 类型的定义 2. 令牌验证流程 3. 过期处理机制 请报告具体文件路径和行号。, subagent_type: explore })输出开始研究认证模块... 分析文件: src/auth/types.ts:15 - Session 类型定义 分析文件: src/auth/validate.ts:42 - 令牌验证逻辑 发现: user 字段可能为 undefined ⏱️ 用时: 12秒 | Token: 2,847 [Agent 输出已保存至: ~/.claude/tasks/agent-a1b2c3/output.json]示例2团队协作修复 Bug// 1. 创建团队 TeamCreate({ team_name: auth-fix-team, description: 修复认证模块 null pointer bug, agent_type: debugger }) // 返回: { team_name: auth-fix-team, lead_agent_id: team-leadauth-fix-team, ... } // 2. 启动多个 Worker 并行研究 Agent({ description: 调查 null pointer bug, prompt: 调查 src/auth/validate.ts:42 的 null pointer。 分析 user 字段何时为 undefined。, subagent_type: worker, team_name: auth-fix-team }) Agent({ description: 分析测试覆盖, prompt: 查找所有 auth 相关测试。 报告测试覆盖率和缺失场景。, subagent_type: worker, team_name: auth-fix-team }) // 3. 收到研究结果后发送消息给特定 Worker SendMessage({ to: agent-xyz, // Worker ID message: 修复方案 1. 在 validate.ts:42 添加 user 字段空检查 2. 如果 user 为 null返回 401 状态码 3. 错误消息: Session expired 请实施此修复并运行相关测试。, summary: 修复 null pointer 方案 }) // 4. Worker 实施修复并报告 // [Worker 自动执行编辑文件、运行测试、提交更改] // 5. 验证修复 Agent({ description: 验证修复效果, prompt: 运行 auth 相关测试 特别验证过期会话的处理。 确保无回归问题。, subagent_type: verification, team_name: auth-fix-team }) // 6. 清理团队 TeamDelete()示例3协调者模式典型对话用户修复认证模块的 null pointer 协调者 Agent({ description: 调查 auth bug, subagent_type: worker, prompt: 调查 src/auth/ 目录找到 null pointer 的根本原因。 重点关注 Session 处理和令牌验证。 }) Agent({ description: 分析 auth 测试, subagent_type: worker, prompt: 查找所有 auth 相关测试文件 报告测试覆盖率和已知问题。 }) 正在并行调查两个角度... task-notification 任务完成: 调查 auth bug 发现 null pointer 在 src/auth/validate.ts:42 根本原因: Session.user 在过期时未置空但令牌仍缓存 /task-notification 您找到 bug 了实施修复 协调者 SendMessage({ to: agent-xyz, message: 修复方案 1. 在 validate.ts:42 添加 user 字段空检查 2. 如果 user 为 null 或 session.expired 为 true 返回 401 状态码和 Session expired 消息 3. 确保有测试覆盖此场景 请实施、提交并报告 commit hash。 }) 实施中... task-notification 任务完成: 修复 null pointer 已修复: src/auth/validate.ts:42 添加了空检查和过期验证 测试通过: 12/12 Commit: a7b3c9d - fix: handle null user in expired sessions /task-notification 协调者修复完成已提交到分支。示例4计划审批工作流// 团队成员创建计划 EnterPlanMode() // 进入计划模式 // ... 创建详细的实施计划 // 完成后退出计划模式 // ExitPlanMode() 会自动触发审批请求 // 团队领导收到计划审批请求 // 在 UI 中查看计划详情 // 领导批准计划 SendMessage({ to: teammate-name, message: { type: plan_approval_response, request_id: req-789, approve: true, feedback: 计划已批准可以实施 } }) // 团队成员收到批准通知 // 开始实施... 性能与监控指标收集// src/services/analytics/index.ts logEvent(tengu_agent_tool_completed, { agent_type: worker, // Agent 类型 model: sonnet, // 使用的模型 prompt_char_count: 1250, // 提示字符数 response_char_count: 3400, // 响应字符数 assistant_message_count: 15, // 助理消息数 total_tool_uses: 23, // 工具使用次数 duration_ms: 45000, // 持续时间毫秒 total_tokens: 15600, // 总 token 数 is_built_in_agent: true, // 是否内置 Agent is_async: true // 是否异步 })性能优化并行执行研究任务并行化最大化效率缓存友好使用 prompt caching 减少重复 token后台化长时间运行的任务自动后台释放资源增量更新只传输变更部分减少网络开销资源清理// 会话结束时的清理 export async function cleanupSessionTeams(): Promisevoid { const sessionCreatedTeams getSessionCreatedTeams() if (sessionCreatedTeams.size 0) return // 1. 终止所有队员进程 await Promise.allSettled( Array.from(sessionCreatedTeams).map(name killOrphanedTeammatePanes(name) ) ) // 2. 清理目录 await Promise.allSettled( Array.from(sessionCreatedTeams).map(name cleanupTeamDirectories(name) ) ) sessionCreatedTeams.clear() } 最佳实践总结✅ 推荐做法明确任务描述使用 3-5 个词的简洁描述合理并行研究阶段尽可能并行写入阶段控制并发详细 spec提供文件路径、行号、具体变更要求利用隔离复杂变更使用isolation: worktree验证独立验证使用独立 Agent保持客观性清理资源完成后使用TeamDelete清理团队资源计划模式重要变更使用计划模式确保审批❌ 避免做法模糊指令避免基于你的发现...等模糊表述过度串行不相关的研究任务不要串行化忽略验证不要跳过验证步骤资源泄漏不要忘记清理团队和工作树上下文过载避免在一个 Agent 中处理过多不相关任务 高级技巧分层验证实现 验证使用不同 Agent知识传递通过 SendMessage 在 Agent 间传递上下文分批处理大任务拆分为多个小 Agent 任务模板化常用任务模式保存为模板监控集成利用事件日志进行性能分析 相关链接Agent 工具src/tools/AgentTool/团队工具src/tools/TeamCreateTool/,src/tools/TeamDeleteTool/,src/tools/SendMessageTool/协调者模式src/coordinator/coordinatorMode.ts团队配置src/utils/swarm/teamHelpers.ts工具配置src/constants/tools.ts内置 Agentsrc/tools/AgentTool/built-in/