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 API

Agent({ // 必需参数 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 类型

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 }): Promise<void> { 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-lead@team-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" // 领导类型（可选） })

执行流程：

1. 名称去重：若团队已存在，生成唯一名称（generateUniqueTeamName）

2. 生成领导ID：formatAgentId(TEAM_LEAD_NAME, teamName)→team-lead@my-team

3. 创建配置文件：~/.claude/teams/{team-name}/config.json

4. 初始化任务列表：~/.claude/tasks/{sanitized-name}/

5. 注册清理钩子：registerTeamForSessionCleanup

6. 更新AppState：设置teamContext和teammates

7. 记录事件：tengu_team_created

TeamDelete 工具

TeamDelete()

执行流程：

1. 检查活跃成员：过滤isActive !== false的成员

2. 若有活跃成员：返回错误，要求先requestShutdown

3. 清理工作树：destroyWorktree()→git worktree remove --force或rm -rf

4. 清理目录：删除~/.claude/teams/{team-name}/和任务目录

5. 清理缓存：clearTeammateColors()、clearLeaderTeamName()

6. 更新AppState：移除teamContext和inbox

7. 注销清理钩子：unregisterTeamForSessionCleanup

SendMessage 工具

单播消息

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(to="member", message)写入邮箱 (~/.claude/mailboxes/)查询新消息返回消息列表loop[轮询检查]SendMessage(to="team-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_MODE=1

系统提示

// 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.0

ERROR: [Mermaid] Lexical error on line 2. Unrecognized text. graph TD A[用户：修复认证模块null pointer] ----------------^

最佳实践

1. 明确 spec：

   • ❌ 错误："基于你的发现，修复问题"

   • ✅ 正确："修复src/auth/validate.ts:42，添加 user 字段空检查"

2. 合理并行：

   • 研究阶段：尽可能并行

   • 写入阶段：控制并发，避免冲突

3. 继续 vs 新建：

   • 继续（SendMessage）：Worker 已有相关上下文

   • 新建（Agent）：需要全新视角或不相关任务

4. 验证独立：

   • 使用独立 Worker 验证

   • 不要自我验证

📊 工具对照表

🔧 关键配置

功能开关

# 主动助手模式 PROACTIVE=1 KAIROS=1 # 协调者模式 CLAUDE_CODE_COORDINATOR_MODE=1 # 工作流脚本 WORKFLOW_SCRIPTS=1 # 计划验证 CLAUDE_CODE_VERIFY_PLAN=1 # 跨进程消息 UDS_INBOX=1 # 自动后台化 CLAUDE_AUTO_BACKGROUND_TASKS=1 # 简化模式（限制工具） CLAUDE_CODE_SIMPLE=1

Agent SDK 配置

# 禁用内置Agent（SDK用户） CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 # 团队命令 CLAUDE_CODE_TEAM_NAME="my-team" # 队友命令 CLAUDE_CODE_AGENT_NAME="researcher" CLAUDE_CODE_AGENT_COLOR="blue" CLAUDE_CODE_PLAN_MODE_REQUIRED="true" # 队友命令 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-lead@auth-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 // 是否异步 })

性能优化

1. 并行执行：研究任务并行化，最大化效率

2. 缓存友好：使用 prompt caching 减少重复 token

3. 后台化：长时间运行的任务自动后台，释放资源

4. 增量更新：只传输变更部分，减少网络开销

资源清理

// 会话结束时的清理 export async function cleanupSessionTeams(): Promise<void> { 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() }

🎯 最佳实践总结

✅ 推荐做法

1. 明确任务描述：使用 3-5 个词的简洁描述

2. 合理并行：研究阶段尽可能并行，写入阶段控制并发

3. 详细 spec：提供文件路径、行号、具体变更要求

4. 利用隔离：复杂变更使用isolation: "worktree"

5. 验证独立：验证使用独立 Agent，保持客观性

6. 清理资源：完成后使用TeamDelete清理团队资源

7. 计划模式：重要变更使用计划模式，确保审批

❌ 避免做法

1. 模糊指令：避免"基于你的发现..."等模糊表述

2. 过度串行：不相关的研究任务不要串行化

3. 忽略验证：不要跳过验证步骤

4. 资源泄漏：不要忘记清理团队和工作树

5. 上下文过载：避免在一个 Agent 中处理过多不相关任务

🎪 高级技巧

1. 分层验证：实现 + 验证使用不同 Agent

2. 知识传递：通过 SendMessage 在 Agent 间传递上下文

3. 分批处理：大任务拆分为多个小 Agent 任务

4. 模板化：常用任务模式保存为模板

5. 监控集成：利用事件日志进行性能分析

🔗 相关链接

• 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

• 内置 Agent：src/tools/AgentTool/built-in/