Claude Code 工具 详解

Claude Code 工具实现详解

工具总览

核心实现模式

每个工具实现Tool接口，核心方法：

public interface Tool { String name(); // 工具名称 String description(); // LLM 看到的描述（含使用指南） String inputSchema(); // JSON Schema 定义参数 String execute(Map<String, Object> input, ToolContext context); // 执行逻辑 boolean isReadOnly(); // 是否只读（权限判断用） }

Tool 接口定义

public interface Tool { String name(); String description(); String inputSchema(); String execute(Map<String, Object> input, ToolContext context); ​ // 可选重写 default PermissionResult checkPermission(Map<String, Object> input, ToolContext context) { return PermissionResult.ALLOW; } default boolean isEnabled() { return true; } default boolean isReadOnly() { return false; } default String activityDescription(Map<String, Object> input) { return "Running " + name() + "..."; } }

典型实现示例

BashTool（命令执行）

路径:tool/impl/BashTool.java

功能:

• 自动检测 shell：Windows 优先 pwsh，降级到 powershell.exe / cmd.exe

• 危险命令黑名单（rm -rf /,fork bomb等）直接拦截

• 高风险命令（rm -rf,git push -f等）记录警告

• 超时保护（默认 120 秒）

• 流式输出进度报告

危险命令黑名单:

rm -rf /, rm -rf /*, rm -rf ~, mkfs, dd if=, :(){:|:&};:, // fork bomb chmod -R 777 /, git push --force, git push -f, git reset --hard, shutdown, reboot, halt, format c:, del /f /s /q c:\

Shell 检测优先级:

• Windows: pwsh → powershell.exe → cmd.exe

• Unix: bash → sh

GrepTool（内容搜索）

路径:tool/impl/GrepTool.java

功能:

• 优先使用ripgrep (rg)— 支持正则、多输出模式、上下文行

• Windows 降级到findstr，Unix 降级到grep

• 支持content/files_with_matches/count三种输出模式

• 跳过隐藏目录和 node_modules/target/build

输出模式:

• content: 显示匹配行及上下文（默认）

• files_with_matches: 仅显示包含匹配的文件路径

• count: 显示每个文件的匹配数量

WebSearchTool（网络搜索）

路径:tool/impl/WebSearchTool.java

功能:

• 使用 DuckDuckGo HTML 搜索（无需 API Key）

• 正则解析搜索结果（标题、URL、摘要）

• 备用解析模式应对页面结构变化

• 默认返回 8 条结果，最多 20 条

搜索端点:https://html.duckduckgo.com/html/

WebFetchTool（网页获取）

路径:tool/impl/WebFetchTool.java

功能:

• HTTP GET 请求，自动处理重定向

• HTML → 纯文本转换（移除脚本/样式，转换标签为文本格式）

• 响应体最大 100KB，超出截断

• 30 秒超时保护

FileReadTool（文件读取）

路径:tool/impl/FileReadTool.java

功能:

• 文本文件：支持line_start/line_end行范围（1-based）

• 图片文件：返回 Base64 编码 + MIME 类型

• 单次最多读取 2000 行，超出显示... (X more lines)

支持图片格式: png, jpg, jpeg, gif, webp, svg, bmp, ico

输出格式:

1 | 文件第一行 2 | 文件第二行 ...

AgentTool（子 Agent）

路径:tool/impl/AgentTool.java

功能:

• 从 ToolContext 获取 AgentLoop 工厂创建子 Agent

• 子 Agent 拥有独立消息历史，共享工具集

• 用于复杂多步骤任务、并行处理、隔离风险操作

子 Agent 提示词构建:

private String buildSubAgentPrompt(String prompt, String additionalContext) { // 包含任务描述、附加上下文、输出要求 }

SkillTool（Skill 执行）

路径:tool/impl/SkillTool.java

功能:

• 解析.md文件中的!嵌入命令语法

• 支持---分隔的 frontmatter（shell/workDir/effectiveTime 等）

• 命令输出替换占位符后返回内容

嵌入命令语法:

• 代码块:```! command ```

• 行内:!command

工具注册

工具通过ToolRegistry注册到系统：

public class ToolRegistry { public List<ToolCallback> toCallbacks(ToolContext context) { // 将所有 Tool 转为 Spring AI 的 ToolCallback } }

工具调用流程

LLM 返回 tool_calls JSON ↓ AgentToolExecutor.parseArguments() // 用 Jackson 解析 JSON 为 Map ↓ findCallbackByName() // 查找对应的 Tool ↓ checkPermission() // 权限检查 ↓ adapter.call(toolArgs) // 执行工具 ↓ 返回结果文本，加入消息历史

参数解析

// 从 JSON 字符串解析为 Map private Map<String, Object> parseArguments(String toolName, String toolArgs) { return MAPPER.readValue(toolArgs, Map.class); }

工具执行上下文 (ToolContext)

public class ToolContext { Path getWorkDir(); // 工作目录 void reportProgress(String line); // 进度回调 <T> T getOrDefault(String key, T defaultValue); // 扩展属性 }

工具可以通过 ToolContext 传递共享状态，如 AgentTool 通过AGENT_FACTORY_KEY获取 AgentLoop 工厂。