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 类型
| 类型 | 用途 | 文件 | 特点 |
|---|---|---|---|
| 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
}): 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" // 领导类型（可选）
})
执行流程：
-
名称去重：若团队已存在，生成唯一名称（
generateUniqueTeamName） -
生成领导ID：
formatAgentId(TEAM_LEAD_NAME, teamName)→team-lead@my-team -
创建配置文件：
~/.claude/teams/{team-name}/config.json -
初始化任务列表：
~/.claude/tasks/{sanitized-name}/ -
注册清理钩子：
registerTeamForSessionCleanup -
更新AppState：设置
teamContext和teammates -
记录事件：
tengu_team_created
TeamDelete 工具
TeamDelete()
执行流程：
-
检查活跃成员：过滤
isActive !== false的成员 -
若有活跃成员：返回错误，要求先
requestShutdown -
清理工作树：
destroyWorktree()→git worktree remove --force或rm -rf -
清理目录：删除
~/.claude/teams/{team-name}/和任务目录 -
清理缓存：
clearTeammateColors()、clearLeaderTeamName() -
更新AppState：移除
teamContext和inbox -
注销清理钩子：
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] ----------------^
最佳实践
-
明确 spec：
-
❌ 错误："基于你的发现，修复问题"
-
✅ 正确："修复
src/auth/validate.ts:42，添加 user 字段空检查"
-
-
合理并行：
-
研究阶段：尽可能并行
-
写入阶段：控制并发，避免冲突
-
-
继续 vs 新建：
-
继续（SendMessage）：Worker 已有相关上下文
-
新建（Agent）：需要全新视角或不相关任务
-
-
验证独立：
-
使用独立 Worker 验证
-
不要自我验证
-
📊 工具对照表
| 工具 | 路径 | 用途 | 团队相关 |
|---|---|---|---|
| Agent | src/tools/AgentTool/ | 创建智能体 | ✅ 支持 team_name |
| TeamCreate | src/tools/TeamCreateTool/ | 创建团队 | 主工具 |
| TeamDelete | src/tools/TeamDeleteTool/ | 删除团队 | 主工具 |
| SendMessage | src/tools/SendMessageTool/ | 发送消息 | 主工具 |
| TaskCreate | src/tools/TaskCreateTool/ | 创建任务 | ✅ 团队任务列表 |
| TaskList | src/tools/TaskListTool/ | 列出任务 | ✅ 团队任务列表 |
| TaskUpdate | src/tools/TaskUpdateTool/ | 更新任务 | ✅ 团队任务列表 |
| EnterPlanMode | src/tools/EnterPlanModeTool/ | 进入计划模式 | ✅ 团队计划审批 |
| ExitPlanMode | src/tools/ExitPlanModeTool/ | 退出计划模式 | ✅ 团队计划审批 |
🔧 关键配置
功能开关
# 主动助手模式 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 // 是否异步
})
性能优化
-
并行执行：研究任务并行化，最大化效率
-
缓存友好：使用 prompt caching 减少重复 token
-
后台化：长时间运行的任务自动后台，释放资源
-
增量更新：只传输变更部分，减少网络开销
资源清理
// 会话结束时的清理
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()
}
🎯 最佳实践总结
✅ 推荐做法
-
明确任务描述：使用 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 -
内置 Agent：
src/tools/AgentTool/built-in/
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
4
0- 0
已为社区贡献1条内容
所有评论(0)