🛠️ 工具与执行引擎 graph LR subgraph "工具生命周期" LLM[LLM 决策] --> ToolUse[ToolUseBlock] ToolUse --> Validation{输入验证} Validation -->|通过| Permission{权限检查} Validation -->|失败| ErrorResult[错误结果] Permission -->|允许| Execute["Tool.call()"] Permission -->|拒绝| ErrorResult Permission -->|询问| UserPrompt[用户对话框] UserPrompt -->|允许| Execute UserPrompt -->|拒绝| ErrorResult Execute --> Progress[产出进度] Progress --> Progress Progress --> Result[产出结果] Result --> Transform[mapToolResult] Transform --> ToolResultBlock ErrorResult --> ToolResultBlock ToolResultBlock --> LLM end 工具执行管道：全程异步生成器 Claude Code 工具系统最迷人的方面是在整个执行管道中使用异步生成器。这允许在保持清晰的错误边界的同时流式传输进度更新：
// 核心工具执行函数（重构版） async function* executeTool( toolUse: ToolUseBlock, toolDef: ToolDefinition, context: ToolUseContext, permissionFn: PermissionGranter, assistantMessage: CliMessage, ): AsyncGenerator<CliMessage, void, void> { // 阶段 1：使用 Zod 进行输入验证 const validationStart = performance.now(); const validation = toolDef.inputSchema.safeParse(toolUse.input); if (!validation.success) { // 为 LLM 消费格式化 Zod 错误 const errorMessage = formatZodError(validation.error); yield createToolResultMessage({ tool_use_id: toolUse.id, content: [ { type: "text", text: `Input validation failed:\\n${errorMessage}`, }, ], is_error: true, }); return; } // 阶段 2：权限检查 const permissionResult = await checkToolPermission( toolDef, validation.data, context.getToolPermissionContext(), permissionFn, ); if (permissionResult.behavior === "deny") { yield createToolResultMessage({ tool_use_id: toolUse.id, content: [ { type: "text", text: `Permission denied: ${permissionResult.message}`, }, ], is_error: true, }); return; } if (permissionResult.behavior === "ask") { // 为权限对话框产出 UI 事件 yield { type: "permission_request", toolName: toolDef.name, input: validation.data, suggestions: permissionResult.ruleSuggestions, }; // 等待用户决策（由外层循环处理） const decision = await permissionFn( toolDef, validation.data, permissionResult, ); if (!decision.allowed) { yield createToolResultMessage({ tool_use_id: toolUse.id, content: [ { type: "text", text: "Tool execution cancelled by user", }, ], is_error: true, }); return; } } // 阶段 3：带进度跟踪的工具执行 try { const executeStart = performance.now(); let progressCount = 0; let finalResult = null; // 调用工具的异步生成器 for await (const output of toolDef.call( validation.data, context, undefined, // mcpContext - 按要求跳过 assistantMessage, )) { if (output.type === "progress") { progressCount++; yield { type: "progress", uuid: `progress-${toolUse.id}-${progressCount}`, timestamp: new Date().toISOString(), progress: { toolUseID: toolUse.id, data: output.data, }, }; } else if (output.type === "result") { finalResult = output.data; } } // 阶段 4：结果转换 if (finalResult !== null) { const content = toolDef.mapToolResultToToolResultBlockParam( finalResult, toolUse.id, ); yield createToolResultMessage({ tool_use_id: toolUse.id, content: Array.isArray(content) ? content : [content], is_error: false, executionTime: performance.now() - executeStart, }); } } catch (error) { // 带丰富上下文的错误处理 yield createToolResultMessage({ tool_use_id: toolUse.id, content: formatToolError(error, toolDef), is_error: true, }); } } 性能特征：
...