完整指南Claude Code 40 工具系统源码解析BashTool 与 FileEditTool 的 5 大设计模式【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/gh_mirrors/claudecode5/claude-codeClaude Code 是一个运行在终端里的 AI 编程智能体它内置了40 多个工具其中最能代表其工程水准的就是BashTool命令执行工具和FileEditTool文件编辑工具。这篇文章带你从源码层面拆解 Claude Code 工具系统的整体架构从统一的buildTool设计模式到 BashTool 的多层命令安全校验链再到 FileEditTool 的先读后写原子化文件修改机制一次看懂这套工具系统为什么既强大又安全。一、40 工具全清单先看全貌Claude Code 的每个工具都是一个自包含模块统一放在src/tools/工具名/目录下每个工具模块固定包含四件套组成部分作用示例文件主实现输入 Schema 执行逻辑 权限检查BashTool.tsxUI 渲染终端里的调用/结果展示UI.tsxPrompt注入给模型的用法说明prompt.ts辅助函数工具专属校验/解析逻辑utils.ts官方文档 docs/tools.md 里有完整目录按职责可分为六大类文件系统类FileRead、FileWrite、FileEdit、Glob、Grep、NotebookEdit 命令执行类Bash、PowerShellWindows、REPL 智能体编排类AgentTool、SendMessage、TeamCreate、PlanMode 进出 任务管理类TaskCreate / TaskUpdate / TaskList / TaskOutput 网络类WebFetch、WebSearch MCP 集成类MCPTool、ListMcpResources、ToolSearch所有工具最终在 src/tools.ts 中统一注册见 src/tools.ts#L197-L204由查询引擎在 LLM 的工具调用循环中调度。二、统一设计模式buildTool 的7 件套Claude Code 所有工具都遵循同一个模板方法模式定义在 src/Tool.ts 中。每个工具必须回答以下 7 个核心问题输入 SchemainputSchema用 Zod 定义参数API 层严格校验执行逻辑call真正干活的异步函数返回{ data, newMessages? }权限检查checkPermissions返回是否放行、是否需要询问用户并发安全性isConcurrencySafe能否与其他工具并行跑只读标记isReadOnly/破坏性标记isDestructive决定权限提示策略进度与 UIrenderToolUseMessage/renderToolResultMessage终端渲染结果落库mapToolResultToToolResultBlockParam把结果转成回传给模型的文本。特别值得一提的是buildTool的失败关闭fail-closed默认值见 src/Tool.ts#L757-L769const TOOL_DEFAULTS { isConcurrencySafe: () false, // 默认假设不安全不允许并行 isReadOnly: () false, // 默认假设会写文件 isDestructive: () false, // 默认不标记为破坏性 checkPermissions: (input) Promise.resolve({ behavior: allow, updatedInput: input }), // ... } 设计哲学宁可默认不安全也不默认安全。工具想获得并行/只读待遇必须显式声明并证明。三、BashTool 拆解安全至上的命令执行BashTool 是 Claude Code 里最重的工具目录 src/tools/BashTool/ 下足足有 18 个文件其中 bashPermissions.ts 长达 2600 行。3.1 多层安全校验链BashTool 不直接执行命令而是先走一条层层递进的安检流水线在 BashTool.tsx 中串联校验层文件职责AST 安全解析bashSecurity.ts用 tree-sitter 把命令解析成语法树检测重定向、命令替换等危险结构路径约束pathValidation.ts拦截越出工作目录的路径操作只读校验readOnlyValidation.ts在只读场景下拦截写操作破坏性警告destructiveCommandWarning.tsrm -rf类命令额外提示沙箱判定shouldUseSandbox.ts决定是否在沙箱中隔离执行一个精巧的细节源码给复合命令设了安检上限——// bashPermissions.ts#L103超过 50 个子命令时回退为询问用户安全默认值 export const MAX_SUBCOMMANDS_FOR_SECURITY_CHECK 50无法证明安全的命令一律降级为询问用户而不是放行。️3.2 通配符权限规则BashTool 的权限采用前缀通配符模式规则形如Bash(git *)允许所有 git 命令匹配逻辑在 bashPermissions.ts 的bashToolHasPermission中实现。用户批准一次后可以选择记住此规则下次同类命令不再打扰。3.3 体验细节折叠与自动后台BashTool.tsx#L55-L72 里定义了几组命令白名单grep/find/rg归为搜索命令、cat/head归为读取命令、ls/tree归为列目录命令。这些命令的输出在 UI 中会被折叠成一行摘要避免刷屏执行超过2 秒显示进度助手模式下阻塞超过15 秒自动转入后台任务LocalShellTask。四、FileEditTool 拆解如何安全地改一个文件FileEditToolsrc/tools/FileEditTool/FileEditTool.ts只有 6 个文件却浓缩了 5 个经典设计模式。4.1 输入设计old_string → new_string 的精确替换输入 Schema定义在 types.ts只有 4 个字段file_path、old_string、new_string、replace_all。它不整文件覆盖而是找到这段替换成那段——天然产生最小的 Diff。4.2 模式一先读后写Read-Before-WritevalidateInputFileEditTool.ts#L137-L362会检查readFileState缓存// 文件必须先用 FileReadTool 读过否则直接拒绝 if (!readTimestamp || readTimestamp.isPartialView) { return { result: false, message: File has not been read yet. Read it first... } } 这保证模型永远基于它亲眼看过的内容做修改杜绝盲改。4.3 模式二原子读-改-写 陈旧性检查执行阶段FileEditTool.ts#L427-L491有两条铁律所有await都放在临界区之外注释明确写着避免异步操作保持原子性写盘前用文件 mtime 对比读取时间戳若用户或 linter 在期间改过文件抛出FILE_UNEXPECTEDLY_MODIFIED_ERROR防止写覆盖并发修改。4.4 模式三智能容错引号归一化findActualString处理直引号/弯引号差异preserveQuoteStyle在替换时保留文件原有引号风格编码感知自动识别 UTF-16LE BOM、CRLF 换行写回时原样保留FileEditTool.ts#L607-L624防呆提示文件不存在时会建议你是不是想用src/app.ts编辑.ipynb会提示改用 NotebookEditTool大小护栏超过1 GiB的文件直接拒绝编辑防止 OOMFileEditTool.ts#L84安全细节Windows 下对 UNC 路径跳过文件系统探测避免 NTLM 凭据泄露。4.5 模式四写入后的生态联动写盘不是终点FileEditTool.ts#L493-L525通知LSP 服务器didChange/didSave让 TS 语言服务器立即产出新的诊断通知VS Code弹出 Diff 视图用户可以肉眼确认改动更新readFileState时间戳让下一次编辑基于新内容记录文件历史快照支持回滚 埋点统计tengu_edit_string_lengths。五、权限模型4 种模式 通配符规则所有工具共用一套权限系统src/hooks/toolPermission/四种模式覆盖不同信任级别模式行为default潜在破坏性操作逐个询问plan先展示完整计划一次性确认auto由 ML 分类器自动判定BashTool 的toAutoClassifierInput专为它服务bypassPermissions全部放行危险需谨慎规则支持通配符如Bash(git *)、FileEdit(/src/*)、FileRead(*)允许/拒绝/询问三档规则可按来源分层配置。六、如何自己读这套源码建议按以下路径快速上手30 分钟先读 src/Tool.ts 的Tool接口——它就是工具协议的全部契约再读 FileEditTool.ts 的validateInputcall——626 行覆盖了校验、原子性、联动三大块注释极其详尽最后扫一遍 docs/tools.md 的分类表格对照 src/tools/ 目录结构把 40 工具对号入座。总结Claude Code 的工具系统给所有想做 AI Agent 的开发者上了三堂课① 用统一接口buildTool抹平 40 工具的差异② 用失败关闭的默认值守住安全底线③ 用先读后写 原子修改 生态联动让自动化修改既快又可控。BashTool 和 FileEditTool 正是这三堂课最完整的答案。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/gh_mirrors/claudecode5/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 完整指南：Claude Code 40+ 工具系统源码解析，BashTool 与 FileEditTool 的 5 大设计模式
完整指南Claude Code 40 工具系统源码解析BashTool 与 FileEditTool 的 5 大设计模式【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/gh_mirrors/claudecode5/claude-codeClaude Code 是一个运行在终端里的 AI 编程智能体它内置了40 多个工具其中最能代表其工程水准的就是BashTool命令执行工具和FileEditTool文件编辑工具。这篇文章带你从源码层面拆解 Claude Code 工具系统的整体架构从统一的buildTool设计模式到 BashTool 的多层命令安全校验链再到 FileEditTool 的先读后写原子化文件修改机制一次看懂这套工具系统为什么既强大又安全。一、40 工具全清单先看全貌Claude Code 的每个工具都是一个自包含模块统一放在src/tools/工具名/目录下每个工具模块固定包含四件套组成部分作用示例文件主实现输入 Schema 执行逻辑 权限检查BashTool.tsxUI 渲染终端里的调用/结果展示UI.tsxPrompt注入给模型的用法说明prompt.ts辅助函数工具专属校验/解析逻辑utils.ts官方文档 docs/tools.md 里有完整目录按职责可分为六大类文件系统类FileRead、FileWrite、FileEdit、Glob、Grep、NotebookEdit 命令执行类Bash、PowerShellWindows、REPL 智能体编排类AgentTool、SendMessage、TeamCreate、PlanMode 进出 任务管理类TaskCreate / TaskUpdate / TaskList / TaskOutput 网络类WebFetch、WebSearch MCP 集成类MCPTool、ListMcpResources、ToolSearch所有工具最终在 src/tools.ts 中统一注册见 src/tools.ts#L197-L204由查询引擎在 LLM 的工具调用循环中调度。二、统一设计模式buildTool 的7 件套Claude Code 所有工具都遵循同一个模板方法模式定义在 src/Tool.ts 中。每个工具必须回答以下 7 个核心问题输入 SchemainputSchema用 Zod 定义参数API 层严格校验执行逻辑call真正干活的异步函数返回{ data, newMessages? }权限检查checkPermissions返回是否放行、是否需要询问用户并发安全性isConcurrencySafe能否与其他工具并行跑只读标记isReadOnly/破坏性标记isDestructive决定权限提示策略进度与 UIrenderToolUseMessage/renderToolResultMessage终端渲染结果落库mapToolResultToToolResultBlockParam把结果转成回传给模型的文本。特别值得一提的是buildTool的失败关闭fail-closed默认值见 src/Tool.ts#L757-L769const TOOL_DEFAULTS { isConcurrencySafe: () false, // 默认假设不安全不允许并行 isReadOnly: () false, // 默认假设会写文件 isDestructive: () false, // 默认不标记为破坏性 checkPermissions: (input) Promise.resolve({ behavior: allow, updatedInput: input }), // ... } 设计哲学宁可默认不安全也不默认安全。工具想获得并行/只读待遇必须显式声明并证明。三、BashTool 拆解安全至上的命令执行BashTool 是 Claude Code 里最重的工具目录 src/tools/BashTool/ 下足足有 18 个文件其中 bashPermissions.ts 长达 2600 行。3.1 多层安全校验链BashTool 不直接执行命令而是先走一条层层递进的安检流水线在 BashTool.tsx 中串联校验层文件职责AST 安全解析bashSecurity.ts用 tree-sitter 把命令解析成语法树检测重定向、命令替换等危险结构路径约束pathValidation.ts拦截越出工作目录的路径操作只读校验readOnlyValidation.ts在只读场景下拦截写操作破坏性警告destructiveCommandWarning.tsrm -rf类命令额外提示沙箱判定shouldUseSandbox.ts决定是否在沙箱中隔离执行一个精巧的细节源码给复合命令设了安检上限——// bashPermissions.ts#L103超过 50 个子命令时回退为询问用户安全默认值 export const MAX_SUBCOMMANDS_FOR_SECURITY_CHECK 50无法证明安全的命令一律降级为询问用户而不是放行。️3.2 通配符权限规则BashTool 的权限采用前缀通配符模式规则形如Bash(git *)允许所有 git 命令匹配逻辑在 bashPermissions.ts 的bashToolHasPermission中实现。用户批准一次后可以选择记住此规则下次同类命令不再打扰。3.3 体验细节折叠与自动后台BashTool.tsx#L55-L72 里定义了几组命令白名单grep/find/rg归为搜索命令、cat/head归为读取命令、ls/tree归为列目录命令。这些命令的输出在 UI 中会被折叠成一行摘要避免刷屏执行超过2 秒显示进度助手模式下阻塞超过15 秒自动转入后台任务LocalShellTask。四、FileEditTool 拆解如何安全地改一个文件FileEditToolsrc/tools/FileEditTool/FileEditTool.ts只有 6 个文件却浓缩了 5 个经典设计模式。4.1 输入设计old_string → new_string 的精确替换输入 Schema定义在 types.ts只有 4 个字段file_path、old_string、new_string、replace_all。它不整文件覆盖而是找到这段替换成那段——天然产生最小的 Diff。4.2 模式一先读后写Read-Before-WritevalidateInputFileEditTool.ts#L137-L362会检查readFileState缓存// 文件必须先用 FileReadTool 读过否则直接拒绝 if (!readTimestamp || readTimestamp.isPartialView) { return { result: false, message: File has not been read yet. Read it first... } } 这保证模型永远基于它亲眼看过的内容做修改杜绝盲改。4.3 模式二原子读-改-写 陈旧性检查执行阶段FileEditTool.ts#L427-L491有两条铁律所有await都放在临界区之外注释明确写着避免异步操作保持原子性写盘前用文件 mtime 对比读取时间戳若用户或 linter 在期间改过文件抛出FILE_UNEXPECTEDLY_MODIFIED_ERROR防止写覆盖并发修改。4.4 模式三智能容错引号归一化findActualString处理直引号/弯引号差异preserveQuoteStyle在替换时保留文件原有引号风格编码感知自动识别 UTF-16LE BOM、CRLF 换行写回时原样保留FileEditTool.ts#L607-L624防呆提示文件不存在时会建议你是不是想用src/app.ts编辑.ipynb会提示改用 NotebookEditTool大小护栏超过1 GiB的文件直接拒绝编辑防止 OOMFileEditTool.ts#L84安全细节Windows 下对 UNC 路径跳过文件系统探测避免 NTLM 凭据泄露。4.5 模式四写入后的生态联动写盘不是终点FileEditTool.ts#L493-L525通知LSP 服务器didChange/didSave让 TS 语言服务器立即产出新的诊断通知VS Code弹出 Diff 视图用户可以肉眼确认改动更新readFileState时间戳让下一次编辑基于新内容记录文件历史快照支持回滚 埋点统计tengu_edit_string_lengths。五、权限模型4 种模式 通配符规则所有工具共用一套权限系统src/hooks/toolPermission/四种模式覆盖不同信任级别模式行为default潜在破坏性操作逐个询问plan先展示完整计划一次性确认auto由 ML 分类器自动判定BashTool 的toAutoClassifierInput专为它服务bypassPermissions全部放行危险需谨慎规则支持通配符如Bash(git *)、FileEdit(/src/*)、FileRead(*)允许/拒绝/询问三档规则可按来源分层配置。六、如何自己读这套源码建议按以下路径快速上手30 分钟先读 src/Tool.ts 的Tool接口——它就是工具协议的全部契约再读 FileEditTool.ts 的validateInputcall——626 行覆盖了校验、原子性、联动三大块注释极其详尽最后扫一遍 docs/tools.md 的分类表格对照 src/tools/ 目录结构把 40 工具对号入座。总结Claude Code 的工具系统给所有想做 AI Agent 的开发者上了三堂课① 用统一接口buildTool抹平 40 工具的差异② 用失败关闭的默认值守住安全底线③ 用先读后写 原子修改 生态联动让自动化修改既快又可控。BashTool 和 FileEditTool 正是这三堂课最完整的答案。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/gh_mirrors/claudecode5/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考