7. BashTool - Shell 命令执行所属分组工具系统概述BashTool 是 Claude Code 中最具破坏力也最常用的工具之一它把模型的文本输出直接交给系统 shell 执行是模型与操作系统交互的万能钥匙。正因为能力强大BashTool 的实现同时承担了三重职责——给模型清晰的 prompt 指引、对命令输出做格式化与安全处理、在终端里渲染出可读的执行过程与结果。本工具目录下文件众多BashTool.tsx承载核心call与权限逻辑prompt.ts生成模型可见的工具描述与 Git/PR 操作长指引utils.ts处理命令输出的截断、图片识别、cwd 重置等UI.tsx负责所有 React 渲染入口。配套还有bashPermissions.ts、bashSecurity.ts、shouldUseSandbox.ts、commandSemantics.ts等安全模块以及底层的utils/Shell.ts、utils/ShellCommand.ts提供进程执行能力。本文聚焦 prompt.ts、utils.ts、UI.tsx 三个核心文件剖析 BashTool 如何在模型友好 / 安全可控 / UI 清晰三者之间取得平衡。源码位置[tools/BashTool/prompt.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/prompt.ts)[tools/BashTool/utils.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/utils.ts)[tools/BashTool/UI.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/UI.tsx)[tools/BashTool/BashTool.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/BashTool.tsx)[utils/Shell.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/utils/Shell.ts)核心实现分析1. prompt.ts分层组装的工具描述getSimplePrompt()是 BashTool 注入到 system prompt 的主体文本。它的构造方式很特别——不是单块字符串而是由多个独立函数拼接而成每一层负责一类关注点工具偏好层明确告诉模型哪些操作应该用专用工具而非 BashFile search: Use Glob、Read files: Use FileReadTool等。这层策略直接降低模型误用 Bash 做文件操作的几率。指令层处理多条命令的并行/串行规则、git 命令的安全约束、sleep命令的反模式警告。沙箱层getSimpleSandboxSection()注入文件系统/网络沙箱的运行时配置。Git/PR 层getCommitAndPRInstructions()是一段非常长的内嵌指引覆盖 commit 流程、PR 创建、git 安全协议。值得注意的是工具偏好与avoidCommands的动态生成constavoidCommandsembedded?cat, head, tail, sed, awk, or echo:find, grep, cat, head, tail, sed, awk, or echo当 ant 原生构建把find/grep别名到内嵌的 bfs/ugrep 时prompt 主动让模型使用这些命令否则劝阻。这是 prompt 与运行时环境双向适配的典型例子。2. 沙箱配置的 token 优化getSimpleSandboxSection()在注入沙箱配置前会做一道去重处理// SandboxManager merges config from multiple sources (settings layers, defaults,// CLI flags) without deduping, so paths like ~/.cache appear 3× in allowOnly.// Dedup here before inlining into the prompt — affects only what the model sees,// not sandbox enforcement. Saves ~150-200 tokens/request when sandbox is enabled.functiondedupT(arr:T[]|undefined):T[]|undefined{if(!arr||arr.length0)returnarrreturn[...newSet(arr)]}注释揭示了细节SandboxManager把多层 settings 合并但不去重导致~/.cache这样的路径在allowOnly中出现三次。这里去重只影响模型看到的文本不影响实际沙箱执行每次请求节省约 150-200 tokens。还有一处把 per-UID 临时目录如/private/tmp/claude-1001/归一化为$TMPDIR“避免破坏跨用户的全局 prompt cache”。3. dangerouslyDisableSandbox 的两套策略getSimpleSandboxSection()根据allowUnsandboxedCommands输出两套截然不同的指引。当允许越狱时You should always default to running commands within the sandbox. Do NOT attempt to set dangerouslyDisableSandbox: true unless:,// ...When you see evidence of sandbox-caused failure:,[Immediately retry with dangerouslyDisableSandbox: true (dont ask, just do it),Briefly explain what sandbox restriction likely caused the failure...,This will prompt the user for permission,],策略是看到沙箱失败证据就立即重试并解释——既不让模型反复纠缠用户又保留了 audit trail。而不允许越狱时则是硬性约束“Commands cannot run outside the sandbox under any circumstances.”4. Git 安全协议的 fail-safe 设计getCommitAndPRInstructions()中嵌入了大量NEVER约束- NEVER update the git config - NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless... - NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless... - NEVER run force push to main/master, warn the user if they request it - CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend...特别值得品味的是amend那条的注释当 pre-commit hook 失败时commit 实际并未发生此时若--amend会修改前一次提交可能毁掉前一次的工作。模型很容易踩这个坑所以用 CRITICAL 标记并给出替代流程fix issue → re-stage → create NEW commit。5. utils.ts命令输出的多形态处理formatOutput()是 utils.ts 中最关键的函数之一它要处理两类截然不同的输出——纯文本与图片 data URIexportfunctionformatOutput(content:string):{totalLines:numbertruncatedContent:stringisImage?:boolean}{constisImageisImageOutput(content)if(isImage){return{totalLines:1,truncatedContent:content,isImage}}constmaxOutputLengthgetMaxOutputLength()if(content.lengthmaxOutputLength){return{totalLines:countCharInString(content,\n)1,truncatedContent:content,isImage}}consttruncatedPartcontent.slice(0,maxOutputLength)constremainingLinescountCharInString(content,\n,maxOutputLength)1consttruncated${truncatedPart}\n\n... [${remainingLines}lines truncated] ...// ...}isImageOutput()用正则匹配data:image/...;base64,前缀命中后内容直接透传给buildImageToolResult()转成 Anthropic SDK 的 image block。这种shell 命令直接吐出图片的能力让模型可以运行matplotlib脚本后立即看到结果。6. 图片输出的尺寸压缩resizeShellImageOutput()解决了一个微妙的问题——shell stdout 被截断到getMaxOutputLength()时截断的 base64 会解码成损坏的图片。函数会从 spill 文件重新读取完整内容再做尺寸压缩// Caps dimensions too: compressImageBuffer only checks byte size, so// a small-but-high-DPI PNG (e.g. matplotlib at dpi300) sails through at full// resolution and poisons many-image requests (CC-304).constresizedawaitmaybeResizeAndDownsampleImageBuffer(buf,buf.length,ext)注释里的 CC-304 是真实案例——高 DPI PNG 虽然字节数小但分辨率高会在多图请求中中毒。这里强制下采样避免该问题。MAX_IMAGE_FILE_SIZE 设为 20MB超过直接返回 null让调用方回退到文本处理。7. cwd 重置机制resetCwdIfOutsideProject()是 BashTool 在每次调用后保护工作目录一致性的关键exportfunctionresetCwdIfOutsideProject(toolPermissionContext:ToolPermissionContext,):boolean{constcwdgetCwd()constoriginalCwdgetOriginalCwd()constshouldMaintainshouldMaintainProjectWorkingDir()if(shouldMaintain||(cwd!originalCwd!pathInAllowedWorkingPath(cwd,toolPermissionContext))){setCwd(originalCwd)if(!shouldMaintain){logEvent(tengu_bash_tool_reset_to_original_dir,{})returntrue}}returnfalse}注意 fast path当 cwd 没变cwd originalCwd时直接跳过pathInAllowedWorkingPath的系统调用——因为originalCwd一定在允许的工作目录里。这是高频路径的优化。当 cwd 漂出允许目录时自动重置并打点上报。8. UI.tsx渲染入口与 sed 编辑特例renderToolUseMessage()处理工具调用气泡。它对sed -i这类原地编辑做了特例exportfunctionrenderToolUseMessage(input,{verbose,theme:_theme}){const{command}inputif(!command)returnnull// Render sed in-place edits like file edits (show file path only)constsedInfoparseSedEditCommand(command)if(sedInfo){returnverbose?sedInfo.filePath:getDisplayPath(sedInfo.filePath)}// ...}parseSedEditCommand()把sed -i s/foo/bar/ file.txt识别成文件编辑操作UI 上就只显示文件路径——视觉上等同于 FileEditTool让用户一眼看出这是一次文件修改而不是一条 shell 命令。这是 UI 把语义还原为意图的范例。9. 命令显示的截断策略非 verbose 模式下命令显示有两道截断constMAX_COMMAND_DISPLAY_LINES2constMAX_COMMAND_DISPLAY_CHARS160if(!verbose){constlinescommand.split(\n)if(isFullscreenEnvEnabled()){constlabelextractBashCommentLabel(command)if(label){/* 用注释作为 label */}}constneedsLineTruncationlines.lengthMAX_COMMAND_DISPLAY_LINESconstneedsCharTruncationcommand.lengthMAX_COMMAND_DISPLAY_CHARSif(needsLineTruncation||needsCharTruncation){// 先按行截再按字符截}}extractBashCommentLabel()在全屏模式下会提取命令开头的注释如# run tests\npytest作为 label 显示——这是给用注释标注意图的命令风格的奖励。10. BackgroundHint 与 ctrlb 后台化BackgroundHint组件让用户能把前台运行中的命令一键后台化exportfunctionBackgroundHint({onBackground}){// ...useKeybinding(task:background,handleBackground,{context:Task})constbaseShortcutuseShortcutDisplay(task:background,Task,ctrlb)constshortcutenv.terminaltmuxbaseShortcutctrlb?ctrlb ctrlb (twice):baseShortcut// ...}注意 tmux 环境下的特殊处理——tmux 默认前缀键也是 ctrlb所以提示用户要按两次。这种环境感知的快捷键提示是细节控的体现。backgroundAll()真正执行后台化把所有前台命令转成 LocalShellTask。11. 进度与结果的渲染分工renderToolUseProgressMessage用ShellProgressMessage组件展示实时输出带 elapsedTime、totalBytes、timeoutMs 等renderToolResultMessage用BashToolResultMessage展示最终结果超时信息从最后一条 progress 中提取exportfunctionrenderToolResultMessage(content,progressMessagesForMessage,{verbose,theme,tools,style}){constlastProgressprogressMessagesForMessage.at(-1)consttimeoutMslastProgress?.data?.timeoutMsreturnBashToolResultMessage content{content}verbose{verbose}timeoutMs{timeoutMs}/}renderToolUseQueuedMessage简短地显示Waiting…——当工具排队等锁时给用户即时反馈。12. 与 Shell.ts/ShellCommand.ts 的关系utils.ts直接调用了setCwdfromutils/Shell.ts。BashTool 的核心call实现在BashTool.tsx中通过ShellCommand抽象执行命令——ShellCommand 处理进程派生、stdout/stderr 流捕获、超时、kill 信号等底层细节让 BashTool 可以专注业务逻辑权限、沙箱决策、输出后处理。这种高层工具 低层 Shell 抽象的分层让 PowerShellTool 可以复用同一套 Shell 基础设施。关键设计要点prompt 分层生成getSimplePrompt由工具偏好、指令、沙箱、Git/PR 四层函数拼接每层独立可演化沙箱配置还能 token 优化去重。环境双向适配embedded search tools、tmux 终端、ant 用户类型等环境差异都会反映到 prompt 文本和 UI 提示里避免一刀切的失配。输出多形态识别formatOutputisImageOutputresizeShellImageOutput让 Bash 输出能优雅处理纯文本、图片 data URI、超大输出三类形态。sed 编辑的 UI 还原parseSedEditCommand把sed -i视为文件编辑操作UI 上只显示文件路径把shell 命令还原为文件修改的语义。Git 安全协议 fail-safeamend、destructive ops、skip hooks 等危险操作都有NEVER… unless约束并在 pre-commit hook 失败场景给出明确替代流程。与其他模块的关系Shell.ts / ShellCommand.ts提供进程派生与流管理BashTool 在其之上构建权限/沙箱/输出处理逻辑。SandboxManagerutils/sandbox/sandbox-adapter.ts提供getFsReadConfig、getFsWriteConfig、getNetworkRestrictionConfig等BashTool 的 prompt 把这些配置内联给模型看运行时由 sandbox 在进程层强制执行。permissions 系统bashPermissions.ts、bashSecurity.ts、commandSemantics.ts、destructiveCommandWarning.ts共同决定一条命令是否需要用户确认shouldUseSandbox.ts决定是否进入沙箱模式。tasks/LocalShellTaskbackgroundAll把前台命令转后台任务由任务系统统一调度与通知。FileEditTool/FileReadToolBashTool 的 prompt 主动引导模型使用这些专用工具sed 解析又把 sed 编辑在 UI 上对齐到 FileEdit 体验形成闭环。小结BashTool 是用 prompt 写运行时规则、用 utils 做输出兜底、用 UI 还原操作语义的集大成者。它的 prompt.ts 不是简单文本而是分层组装、token 优化、环境感知的运行时策略utils.ts 同时处理文本截断、图片解码、cwd 保护三件不同的事UI.tsx 把sed -i渲染成文件编辑、把 ctrlb 后台化做成 tmux 兼容。理解 BashTool 的设计哲学就能理解 Claude Code 工具系统在模型可控性、运行时安全、用户体验三角上的取舍方式。
07-Claude Code中的BashTool-Shell命令执行
发布时间：2026/7/17 3:06:38
7. BashTool - Shell 命令执行所属分组工具系统概述BashTool 是 Claude Code 中最具破坏力也最常用的工具之一它把模型的文本输出直接交给系统 shell 执行是模型与操作系统交互的万能钥匙。正因为能力强大BashTool 的实现同时承担了三重职责——给模型清晰的 prompt 指引、对命令输出做格式化与安全处理、在终端里渲染出可读的执行过程与结果。本工具目录下文件众多BashTool.tsx承载核心call与权限逻辑prompt.ts生成模型可见的工具描述与 Git/PR 操作长指引utils.ts处理命令输出的截断、图片识别、cwd 重置等UI.tsx负责所有 React 渲染入口。配套还有bashPermissions.ts、bashSecurity.ts、shouldUseSandbox.ts、commandSemantics.ts等安全模块以及底层的utils/Shell.ts、utils/ShellCommand.ts提供进程执行能力。本文聚焦 prompt.ts、utils.ts、UI.tsx 三个核心文件剖析 BashTool 如何在模型友好 / 安全可控 / UI 清晰三者之间取得平衡。源码位置[tools/BashTool/prompt.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/prompt.ts)[tools/BashTool/utils.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/utils.ts)[tools/BashTool/UI.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/UI.tsx)[tools/BashTool/BashTool.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/BashTool/BashTool.tsx)[utils/Shell.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/utils/Shell.ts)核心实现分析1. prompt.ts分层组装的工具描述getSimplePrompt()是 BashTool 注入到 system prompt 的主体文本。它的构造方式很特别——不是单块字符串而是由多个独立函数拼接而成每一层负责一类关注点工具偏好层明确告诉模型哪些操作应该用专用工具而非 BashFile search: Use Glob、Read files: Use FileReadTool等。这层策略直接降低模型误用 Bash 做文件操作的几率。指令层处理多条命令的并行/串行规则、git 命令的安全约束、sleep命令的反模式警告。沙箱层getSimpleSandboxSection()注入文件系统/网络沙箱的运行时配置。Git/PR 层getCommitAndPRInstructions()是一段非常长的内嵌指引覆盖 commit 流程、PR 创建、git 安全协议。值得注意的是工具偏好与avoidCommands的动态生成constavoidCommandsembedded?cat, head, tail, sed, awk, or echo:find, grep, cat, head, tail, sed, awk, or echo当 ant 原生构建把find/grep别名到内嵌的 bfs/ugrep 时prompt 主动让模型使用这些命令否则劝阻。这是 prompt 与运行时环境双向适配的典型例子。2. 沙箱配置的 token 优化getSimpleSandboxSection()在注入沙箱配置前会做一道去重处理// SandboxManager merges config from multiple sources (settings layers, defaults,// CLI flags) without deduping, so paths like ~/.cache appear 3× in allowOnly.// Dedup here before inlining into the prompt — affects only what the model sees,// not sandbox enforcement. Saves ~150-200 tokens/request when sandbox is enabled.functiondedupT(arr:T[]|undefined):T[]|undefined{if(!arr||arr.length0)returnarrreturn[...newSet(arr)]}注释揭示了细节SandboxManager把多层 settings 合并但不去重导致~/.cache这样的路径在allowOnly中出现三次。这里去重只影响模型看到的文本不影响实际沙箱执行每次请求节省约 150-200 tokens。还有一处把 per-UID 临时目录如/private/tmp/claude-1001/归一化为$TMPDIR“避免破坏跨用户的全局 prompt cache”。3. dangerouslyDisableSandbox 的两套策略getSimpleSandboxSection()根据allowUnsandboxedCommands输出两套截然不同的指引。当允许越狱时You should always default to running commands within the sandbox. Do NOT attempt to set dangerouslyDisableSandbox: true unless:,// ...When you see evidence of sandbox-caused failure:,[Immediately retry with dangerouslyDisableSandbox: true (dont ask, just do it),Briefly explain what sandbox restriction likely caused the failure...,This will prompt the user for permission,],策略是看到沙箱失败证据就立即重试并解释——既不让模型反复纠缠用户又保留了 audit trail。而不允许越狱时则是硬性约束“Commands cannot run outside the sandbox under any circumstances.”4. Git 安全协议的 fail-safe 设计getCommitAndPRInstructions()中嵌入了大量NEVER约束- NEVER update the git config - NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless... - NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless... - NEVER run force push to main/master, warn the user if they request it - CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend...特别值得品味的是amend那条的注释当 pre-commit hook 失败时commit 实际并未发生此时若--amend会修改前一次提交可能毁掉前一次的工作。模型很容易踩这个坑所以用 CRITICAL 标记并给出替代流程fix issue → re-stage → create NEW commit。5. utils.ts命令输出的多形态处理formatOutput()是 utils.ts 中最关键的函数之一它要处理两类截然不同的输出——纯文本与图片 data URIexportfunctionformatOutput(content:string):{totalLines:numbertruncatedContent:stringisImage?:boolean}{constisImageisImageOutput(content)if(isImage){return{totalLines:1,truncatedContent:content,isImage}}constmaxOutputLengthgetMaxOutputLength()if(content.lengthmaxOutputLength){return{totalLines:countCharInString(content,\n)1,truncatedContent:content,isImage}}consttruncatedPartcontent.slice(0,maxOutputLength)constremainingLinescountCharInString(content,\n,maxOutputLength)1consttruncated${truncatedPart}\n\n... [${remainingLines}lines truncated] ...// ...}isImageOutput()用正则匹配data:image/...;base64,前缀命中后内容直接透传给buildImageToolResult()转成 Anthropic SDK 的 image block。这种shell 命令直接吐出图片的能力让模型可以运行matplotlib脚本后立即看到结果。6. 图片输出的尺寸压缩resizeShellImageOutput()解决了一个微妙的问题——shell stdout 被截断到getMaxOutputLength()时截断的 base64 会解码成损坏的图片。函数会从 spill 文件重新读取完整内容再做尺寸压缩// Caps dimensions too: compressImageBuffer only checks byte size, so// a small-but-high-DPI PNG (e.g. matplotlib at dpi300) sails through at full// resolution and poisons many-image requests (CC-304).constresizedawaitmaybeResizeAndDownsampleImageBuffer(buf,buf.length,ext)注释里的 CC-304 是真实案例——高 DPI PNG 虽然字节数小但分辨率高会在多图请求中中毒。这里强制下采样避免该问题。MAX_IMAGE_FILE_SIZE 设为 20MB超过直接返回 null让调用方回退到文本处理。7. cwd 重置机制resetCwdIfOutsideProject()是 BashTool 在每次调用后保护工作目录一致性的关键exportfunctionresetCwdIfOutsideProject(toolPermissionContext:ToolPermissionContext,):boolean{constcwdgetCwd()constoriginalCwdgetOriginalCwd()constshouldMaintainshouldMaintainProjectWorkingDir()if(shouldMaintain||(cwd!originalCwd!pathInAllowedWorkingPath(cwd,toolPermissionContext))){setCwd(originalCwd)if(!shouldMaintain){logEvent(tengu_bash_tool_reset_to_original_dir,{})returntrue}}returnfalse}注意 fast path当 cwd 没变cwd originalCwd时直接跳过pathInAllowedWorkingPath的系统调用——因为originalCwd一定在允许的工作目录里。这是高频路径的优化。当 cwd 漂出允许目录时自动重置并打点上报。8. UI.tsx渲染入口与 sed 编辑特例renderToolUseMessage()处理工具调用气泡。它对sed -i这类原地编辑做了特例exportfunctionrenderToolUseMessage(input,{verbose,theme:_theme}){const{command}inputif(!command)returnnull// Render sed in-place edits like file edits (show file path only)constsedInfoparseSedEditCommand(command)if(sedInfo){returnverbose?sedInfo.filePath:getDisplayPath(sedInfo.filePath)}// ...}parseSedEditCommand()把sed -i s/foo/bar/ file.txt识别成文件编辑操作UI 上就只显示文件路径——视觉上等同于 FileEditTool让用户一眼看出这是一次文件修改而不是一条 shell 命令。这是 UI 把语义还原为意图的范例。9. 命令显示的截断策略非 verbose 模式下命令显示有两道截断constMAX_COMMAND_DISPLAY_LINES2constMAX_COMMAND_DISPLAY_CHARS160if(!verbose){constlinescommand.split(\n)if(isFullscreenEnvEnabled()){constlabelextractBashCommentLabel(command)if(label){/* 用注释作为 label */}}constneedsLineTruncationlines.lengthMAX_COMMAND_DISPLAY_LINESconstneedsCharTruncationcommand.lengthMAX_COMMAND_DISPLAY_CHARSif(needsLineTruncation||needsCharTruncation){// 先按行截再按字符截}}extractBashCommentLabel()在全屏模式下会提取命令开头的注释如# run tests\npytest作为 label 显示——这是给用注释标注意图的命令风格的奖励。10. BackgroundHint 与 ctrlb 后台化BackgroundHint组件让用户能把前台运行中的命令一键后台化exportfunctionBackgroundHint({onBackground}){// ...useKeybinding(task:background,handleBackground,{context:Task})constbaseShortcutuseShortcutDisplay(task:background,Task,ctrlb)constshortcutenv.terminaltmuxbaseShortcutctrlb?ctrlb ctrlb (twice):baseShortcut// ...}注意 tmux 环境下的特殊处理——tmux 默认前缀键也是 ctrlb所以提示用户要按两次。这种环境感知的快捷键提示是细节控的体现。backgroundAll()真正执行后台化把所有前台命令转成 LocalShellTask。11. 进度与结果的渲染分工renderToolUseProgressMessage用ShellProgressMessage组件展示实时输出带 elapsedTime、totalBytes、timeoutMs 等renderToolResultMessage用BashToolResultMessage展示最终结果超时信息从最后一条 progress 中提取exportfunctionrenderToolResultMessage(content,progressMessagesForMessage,{verbose,theme,tools,style}){constlastProgressprogressMessagesForMessage.at(-1)consttimeoutMslastProgress?.data?.timeoutMsreturnBashToolResultMessage content{content}verbose{verbose}timeoutMs{timeoutMs}/}renderToolUseQueuedMessage简短地显示Waiting…——当工具排队等锁时给用户即时反馈。12. 与 Shell.ts/ShellCommand.ts 的关系utils.ts直接调用了setCwdfromutils/Shell.ts。BashTool 的核心call实现在BashTool.tsx中通过ShellCommand抽象执行命令——ShellCommand 处理进程派生、stdout/stderr 流捕获、超时、kill 信号等底层细节让 BashTool 可以专注业务逻辑权限、沙箱决策、输出后处理。这种高层工具 低层 Shell 抽象的分层让 PowerShellTool 可以复用同一套 Shell 基础设施。关键设计要点prompt 分层生成getSimplePrompt由工具偏好、指令、沙箱、Git/PR 四层函数拼接每层独立可演化沙箱配置还能 token 优化去重。环境双向适配embedded search tools、tmux 终端、ant 用户类型等环境差异都会反映到 prompt 文本和 UI 提示里避免一刀切的失配。输出多形态识别formatOutputisImageOutputresizeShellImageOutput让 Bash 输出能优雅处理纯文本、图片 data URI、超大输出三类形态。sed 编辑的 UI 还原parseSedEditCommand把sed -i视为文件编辑操作UI 上只显示文件路径把shell 命令还原为文件修改的语义。Git 安全协议 fail-safeamend、destructive ops、skip hooks 等危险操作都有NEVER… unless约束并在 pre-commit hook 失败场景给出明确替代流程。与其他模块的关系Shell.ts / ShellCommand.ts提供进程派生与流管理BashTool 在其之上构建权限/沙箱/输出处理逻辑。SandboxManagerutils/sandbox/sandbox-adapter.ts提供getFsReadConfig、getFsWriteConfig、getNetworkRestrictionConfig等BashTool 的 prompt 把这些配置内联给模型看运行时由 sandbox 在进程层强制执行。permissions 系统bashPermissions.ts、bashSecurity.ts、commandSemantics.ts、destructiveCommandWarning.ts共同决定一条命令是否需要用户确认shouldUseSandbox.ts决定是否进入沙箱模式。tasks/LocalShellTaskbackgroundAll把前台命令转后台任务由任务系统统一调度与通知。FileEditTool/FileReadToolBashTool 的 prompt 主动引导模型使用这些专用工具sed 解析又把 sed 编辑在 UI 上对齐到 FileEdit 体验形成闭环。小结BashTool 是用 prompt 写运行时规则、用 utils 做输出兜底、用 UI 还原操作语义的集大成者。它的 prompt.ts 不是简单文本而是分层组装、token 优化、环境感知的运行时策略utils.ts 同时处理文本截断、图片解码、cwd 保护三件不同的事UI.tsx 把sed -i渲染成文件编辑、把 ctrlb 后台化做成 tmux 兼容。理解 BashTool 的设计哲学就能理解 Claude Code 工具系统在模型可控性、运行时安全、用户体验三角上的取舍方式。
实现详解：海量数据处理利器从原理到实战)
