Claude Code 工具 详解

Claude Code 工具实现详解工具总览工具功能只读Read读取文件内容支持行范围和图片Base64✅Write写入文件内容❌Edit替换文件中的文本❌Bash执行 shell 命令PowerShell/cmd/bash❌Grep正则搜索文件内容优先 ripgrep✅Globglob 模式搜索文件✅WebSearchDuckDuckGo HTML 搜索✅WebFetchHTTP GET 获取网页内容✅Agent启动子 Agent 处理复杂任务✅Skill执行 .md 格式的 Skill 脚本❌Tasks任务管理创建/获取/列表/更新/停止/输出✅NotebookEditJupyter notebook 编辑❌LSP语言服务器协议交互✅MCP连接 MCP 服务器工具桥接✅Ask向用户提问获取输入✅Notification发送系统通知✅Config读取/写入配置❌Brief切换简洁输出模式✅核心实现模式每个工具实现Tool接口核心方法public interface Tool { String name(); // 工具名称 String description(); // LLM 看到的描述含使用指南 String inputSchema(); // JSON Schema 定义参数 String execute(MapString, Object input, ToolContext context); // 执行逻辑 boolean isReadOnly(); // 是否只读权限判断用 }Tool 接口定义public interface Tool { String name(); String description(); String inputSchema(); String execute(MapString, Object input, ToolContext context); ​ // 可选重写 default PermissionResult checkPermission(MapString, Object input, ToolContext context) { return PermissionResult.ALLOW; } default boolean isEnabled() { return true; } default boolean isReadOnly() { return false; } default String activityDescription(MapString, Object input) { return Running name() ...; } }典型实现示例BashTool命令执行路径:tool/impl/BashTool.java功能:自动检测 shellWindows 优先 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.exeUnix: bash → shGrepTool内容搜索路径:tool/impl/GrepTool.java功能:优先使用ripgrep (rg)— 支持正则、多输出模式、上下文行Windows 降级到findstrUnix 降级到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) { // 包含任务描述、附加上下文、输出要求 }SkillToolSkill 执行路径:tool/impl/SkillTool.java功能:解析.md文件中的!嵌入命令语法支持---分隔的 frontmattershell/workDir/effectiveTime 等命令输出替换占位符后返回内容嵌入命令语法:代码块:! command 行内:!command工具注册工具通过ToolRegistry注册到系统public class ToolRegistry { public ListToolCallback 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 MapString, 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 工厂。