vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
@@ -1,35 +1,35 @@
 ---
-title: "命令执行工具 - BashTool 安全设计与实现"
-description: "从源码角度解析 Claude Code BashTool：只读命令判定、AST 安全解析、自动后台化、输出截断和专用工具 vs shell 命令的设计权衡。"
-keywords: ["Bash 工具", "命令执行", "Shell 执行", "安全命令", "AI 执行命令"]
+tags: [claude-code, bash, shell, security, command-execution]
+create time: 2026-06-09 22:30
 ---

-{/* 本章目标：从源码角度揭示 BashTool 的安全设计、执行链路和关键工程决策 */}
+# 命令执行工具 - BashTool 安全设计与实现

-## 执行链路总览
+## 概述
+
+BashTool 是 Claude Code 中唯一允许执行任意 shell 命令的工具，也是安全风险最高的入口。本文从源码角度揭示它的只读判定、AST 安全解析、自动后台化、输出截断等关键设计，以及"专用工具 vs shell 命令"的架构权衡。
+
+## 正文
+
+### 执行链路总览

 一条 Bash 命令从 AI 决策到实际执行的完整路径：

-```
-AI 生成 tool_use: { command: "npm test" }
-  ↓
-BashTool.validateInput()         ← 基础输入校验
-  ↓
-BashTool.checkPermissions()      ← 权限检查（详见安全体系章节）
-  ├── isReadOnly()? → 自动 allow（只读命令免审批）
-  ├── bashToolHasPermission()    ← AST 解析 + 语义检查 + 规则匹配
-  └── 未匹配 → 弹窗确认
-  ↓
-BashTool.call() → runShellCommand()
-  ↓
-shouldUseSandbox(input)          ← 是否需要沙箱包裹
-  ↓
-Shell.exec(command, { shouldUseSandbox, shouldAutoBackground })
-  ↓
-spawn(wrapped_command)           ← 实际进程创建
+```mermaid
+flowchart TD
+    A["AI 生成 tool_use: npm test"] --> B["BashTool.validateInput() 基础输入校验"]
+    B --> C["BashTool.checkPermissions() 权限检查"]
+    C -->|isReadOnly| D["自动 allow, 只读命令免审批"]
+    C -->|非只读| E["bashToolHasPermission()"]
+    E --> E1["AST 解析 + 语义检查 + 规则匹配"]
+    E1 -->|未匹配| F["弹窗确认"]
+    C -->|通过| G["BashTool.call() → runShellCommand()"]
+    G --> H["shouldUseSandbox(input)"]
+    H --> I["Shell.exec(command)"]
+    I --> J["spawn(wrapped_command) 实际进程创建"]
 ```

-## 只读命令的判定：为什么 Read 免审批而 Bash 不一定
+### 只读命令的判定：为什么 Read 免审批而 Bash 不一定

 BashTool 的 `isReadOnly()` 方法（`packages/builtin-tools/src/tools/BashTool/BashTool.tsx:655`）决定一条命令是否被视为"只读"：

@@ -62,7 +62,7 @@ for (const part of partsWithOperators) {
 }
 ```

-## AST 安全解析：tree-sitter bash 解析
+### AST 安全解析：tree-sitter bash 解析

 `preparePermissionMatcher()`（`BashTool.tsx:663`）在权限检查前用 `parseForSecurity()` 解析命令结构：

@@ -80,21 +80,22 @@ async preparePermissionMatcher({ command }) {
 }
 ```

-关键安全点：对于复合命令 `ls && git push`，解析后拆分为 `["ls", "git push"]`，确保 `git push` 不会因为前半段是只读命令而绕过权限检查。解析失败时采用 fail-safe 策略——假设不安全，触发所有安全 hook。
+> [!warning] fail-safe 策略
+> 对于复合命令 `ls && git push`，解析后拆分为 `["ls", "git push"]`，确保 `git push` 不会因为前半段是只读命令而绕过权限检查。解析失败时采用 fail-safe 策略——假设不安全，触发所有安全 hook。

-## 超时控制：分级策略
+### 超时控制：分级策略

-```
-用户指定 timeout → 直接使用
-  ↓ 未指定
-getDefaultTimeoutMs()
-  ├── 默认上限：120,000ms（2 分钟）
-  └── 最大上限：600,000ms（10 分钟，用户显式设置时）
+```mermaid
+flowchart TD
+    A{"用户指定 timeout?"} -->|是| B["直接使用"]
+    A -->|否| C["getDefaultTimeoutMs()"]
+    C --> D["默认上限: 120,000ms (2 分钟)"]
+    C --> E["最大上限: 600,000ms (10 分钟, 用户显式设置时)"]
 ```

 超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:144`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。

-## 自动后台化
+### 自动后台化

 长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：

@@ -106,25 +107,22 @@ const shouldAutoBackground = !isBackgroundTasksDisabled

 自动后台化的完整链路：

-```
-命令开始执行
-  ↓ 进度轮询
-15 秒内未完成（ASSISTANT_BLOCKING_BUDGET_MS）
-  ↓
-检查 isAutobackgroundingAllowed(command)
-  ↓ 允许
-将前台任务转为后台任务（backgroundExistingForegroundTask）
-  ↓
-shellCommand.onTimeout → spawnBackgroundTask()
-  ↓
-返回 taskId 给 AI，AI 可以继续做其他事
-  ↓
-后台任务完成后通过通知机制汇报结果
+```mermaid
+flowchart TD
+    A["命令开始执行"] --> B["进度轮询"]
+    B --> C{"15 秒内未完成?"}
+    C -->|是| D["检查 isAutobackgroundingAllowed(command)"]
+    D -->|允许| E["将前台任务转为后台任务"]
+    E --> F["shellCommand.onTimeout → spawnBackgroundTask()"]
+    F --> G["返回 taskId 给 AI, AI 可以继续做其他事"]
+    G --> H["后台任务完成后通过通知机制汇报结果"]
+    C -->|否| I["正常返回结果"]
 ```

-主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 `npm install` 阻塞整个 agentic loop 数分钟。
+> [!info] 阻塞预算
+> 主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 `npm install` 阻塞整个 agentic loop 数分钟。

-## 输出截断策略
+### 输出截断策略

 命令输出过长时会触发截断，防止把海量日志塞进 AI 的上下文窗口：

@@ -134,9 +132,10 @@ shellCommand.onTimeout → spawnBackgroundTask()
 | 进度轮询截断 | `onProgress` 回调 | 只传递最后几行作为进度显示 |
 | `totalBytes` 标记 | `isIncomplete` 参数 | 告知 AI 输出被截断 |

-截断不是简单砍尾——`isIncomplete` 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。
+> [!tip] 截断不是简单砍尾
+> `isIncomplete` 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。

-## 为什么用专用工具而不是直接调 shell
+### 为什么用专用工具而不是直接调 shell

 Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。这不仅是用户体验的选择，更是架构层面的设计决策：

@@ -148,21 +147,29 @@ Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read
 | **并发安全** | `isConcurrencySafe()` 返回 `true` → 可并行执行 | Bash 命令可能有副作用，串行执行 |
 | **安全审计** | 工具名精确匹配权限规则 | 需 AST 解析命令结构后匹配 |

-`isConcurrencySafe()`（`BashTool.tsx:652`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。
+> [!info] 并发安全的隐藏设计
+> `isConcurrencySafe()`（`BashTool.tsx:652`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。

-## 进度反馈的流式设计
+### 进度反馈的流式设计

 BashTool 的命令执行是流式的，通过 `onProgress` 回调逐行推送输出：

-```
-runShellCommand()
-  ├── Shell.exec() 启动子进程
-  ├── 每秒轮询输出文件
-  ├── onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete)
-  │   ├── 更新 lastProgressOutput / fullOutput
-  │   └── resolveProgress() → 唤醒 generator yield
-  ├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
-  └── return { code, stdout, interrupted, ... }
+```mermaid
+flowchart TD
+    A["runShellCommand()"] --> B["Shell.exec() 启动子进程"]
+    B --> C["每秒轮询输出文件"]
+    C --> D["onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete)"]
+    D --> E["更新 lastProgressOutput / fullOutput"]
+    E --> F["resolveProgress() 唤醒 generator yield"]
+    F --> G["yield progress output, elapsedTimeSeconds"]
+    G --> H["return code, stdout, interrupted..."]
 ```

 UI 层通过 `useToolCallProgress` hook 实时展示命令输出。`resolveProgress()` 信号机制让 generator 在有新数据时才 yield，避免了忙等待。
+
+## 关联笔记
+
+- [[what-are-tools]]
+- [[file-operations]]
+- [[search-and-navigation]]
+- [[task-management]]