docs: 更新文档

docs/tools/shell-execution.mdx

@@ -1,54 +1,168 @@
 ---
-title: "命令执行工具 - Bash Tool 安全设计与实现"
-description: "详解 Claude Code 的 Bash 工具：AI 如何安全地在终端执行命令，包含命令白名单、超时控制、沙箱隔离和输出截断策略。"
+title: "命令执行工具 - BashTool 安全设计与实现"
+description: "从源码角度解析 Claude Code BashTool：只读命令判定、AST 安全解析、自动后台化、输出截断和专用工具 vs shell 命令的设计权衡。"
 keywords: ["Bash 工具", "命令执行", "Shell 执行", "安全命令", "AI 执行命令"]
 ---
 
-{/* 本章目标：介绍 Bash 工具的能力与安全设计 */}
+{/* 本章目标：从源码角度揭示 BashTool 的安全设计、执行链路和关键工程决策 */}
 
-## AI 能执行命令意味着什么
+## 执行链路总览
 
-这是 Claude Code 最强大也最敏感的能力。AI 可以：
+一条 Bash 命令从 AI 决策到实际执行的完整路径：
 
-- 运行构建命令（`npm run build`、`cargo build`）
-- 执行测试（`pytest`、`jest`）
-- 使用 git（`git status`、`git commit`）
-- 调用系统工具（`curl`、`docker`、`kubectl`）
+```
+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)           ← 实际进程创建
+```
 
-几乎你在终端里能做的事，AI 都能做。
+## 只读命令的判定：为什么 Read 免审批而 Bash 不一定
 
-## 安全设计
+BashTool 的 `isReadOnly()` 方法（`BashTool.tsx:437`）决定一条命令是否被视为"只读"：
 
-强大的能力需要严格的控制：
+```typescript
+isReadOnly(input) {
+  const compoundCommandHasCd = commandHasAnyCd(input.command)
+  const result = checkReadOnlyConstraints(input, compoundCommandHasCd)
+  return result.behavior === 'allow'
+}
+```
 
-<AccordionGroup>
-  <Accordion title="权限确认">
-    默认情况下，每条命令执行前都需要用户手动确认。用户可以设置白名单规则，让特定命令自动放行。
-  </Accordion>
-  <Accordion title="沙箱隔离">
-    在支持的平台上，命令可以运行在沙箱环境中——限制文件系统访问范围、禁止网络请求、阻止危险操作。
-  </Accordion>
-  <Accordion title="超时控制">
-    每条命令都有超时限制（默认 2 分钟，最长 10 分钟），防止 AI 启动一个永远不会结束的进程。
-  </Accordion>
-  <Accordion title="输出截断">
-    命令输出过长时自动截断，避免把海量日志全部塞进 AI 的上下文。
-  </Accordion>
-</AccordionGroup>
+判定逻辑基于 4 个命令集合（`BashTool.tsx:60-78`）：
 
-## 前台与后台
+| 集合 | 命令 | 性质 |
+|------|------|------|
+| `BASH_SEARCH_COMMANDS` | find, grep, rg, ag, ack, locate, which, whereis | 搜索类 |
+| `BASH_READ_COMMANDS` | cat, head, tail, wc, stat, file, jq, awk, sort, uniq... | 读取/分析类 |
+| `BASH_LIST_COMMANDS` | ls, tree, du | 列表类 |
+| `BASH_SEMANTIC_NEUTRAL_COMMANDS` | echo, printf, true, false, : | 语义中性（不影响判定） |
 
-有些命令需要等待结果（比如 `git status`），有些适合在后台运行（比如 `npm install`）：
+对于复合命令（`ls dir && echo "---" && ls dir2`），系统拆分后逐段检查——**所有非中性段都必须属于上述集合**，整条命令才被视为只读。
 
-- **前台执行**：AI 等待命令完成，拿到输出后继续思考
-- **后台执行**：命令在后台运行，AI 可以继续做其他事，稍后再检查结果
+```typescript
+// BashTool.tsx:95 — 简化的判定逻辑
+for (const part of partsWithOperators) {
+  if (BASH_SEMANTIC_NEUTRAL_COMMANDS.has(baseCommand)) continue  // 跳过中性段
+  if (!isPartSearch && !isPartRead && !isPartList) {
+    return { isSearch: false, isRead: false, isList: false }  // 有任何一段不通过 → 非只读
+  }
+}
+```
+
+## AST 安全解析：tree-sitter bash 解析
+
+`preparePermissionMatcher()`（`BashTool.tsx:445`）在权限检查前用 `parseForSecurity()` 解析命令结构：
+
+```typescript
+async preparePermissionMatcher({ command }) {
+  const parsed = await parseForSecurity(command)
+  if (parsed.kind !== 'simple') {
+    return () => true  // 解析失败 → fail-safe，触发所有 hook
+  }
+  // 提取子命令列表，剥离 VAR=val 前缀
+  const subcommands = parsed.commands.map(c => c.argv.join(' '))
+  return pattern => {
+    return subcommands.some(cmd => matchWildcardPattern(pattern, cmd))
+  }
+}
+```
+
+关键安全点：对于复合命令 `ls && git push`，解析后拆分为 `["ls", "git push"]`，确保 `git push` 不会因为前半段是只读命令而绕过权限检查。解析失败时采用 fail-safe 策略——假设不安全，触发所有安全 hook。
+
+## 超时控制：分级策略
+
+```
+用户指定 timeout → 直接使用
+  ↓ 未指定
+getDefaultTimeoutMs()
+  ├── 默认上限：120,000ms（2 分钟）
+  └── 最大上限：600,000ms（10 分钟，用户显式设置时）
+```
+
+超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:129`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。
+
+## 自动后台化
+
+长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：
+
+```typescript
+// BashTool.tsx:880
+const shouldAutoBackground = !isBackgroundTasksDisabled 
+  && isAutobackgroundingAllowed(command)
+```
+
+自动后台化的完整链路：
+
+```
+命令开始执行
+  ↓ 进度轮询
+15 秒内未完成（ASSISTANT_BLOCKING_BUDGET_MS）
+  ↓
+检查 isAutobackgroundingAllowed(command)
+  ↓ 允许
+将前台任务转为后台任务（backgroundExistingForegroundTask）
+  ↓
+shellCommand.onTimeout → spawnBackgroundTask()
+  ↓
+返回 taskId 给 AI，AI 可以继续做其他事
+  ↓
+后台任务完成后通过通知机制汇报结果
+```
+
+主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 `npm install` 阻塞整个 agentic loop 数分钟。
+
+## 输出截断策略
+
+命令输出过长时会触发截断，防止把海量日志塞进 AI 的上下文窗口：
+
+| 截断点 | 位置 | 行为 |
+|--------|------|------|
+| `maxResultSizeChars` | 工具级（通常 100K 字符） | 超长输出在写入消息前截断 |
+| 进度轮询截断 | `onProgress` 回调 | 只传递最后几行作为进度显示 |
+| `totalBytes` 标记 | `isIncomplete` 参数 | 告知 AI 输出被截断 |
+
+截断不是简单砍尾——`isIncomplete` 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。
 
 ## 为什么用专用工具而不是直接调 shell
 
-<Note>
-Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。原因有三：
-</Note>
+Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。这不仅是用户体验的选择，更是架构层面的设计决策：
 
-1. **权限粒度更细**：`Read` 是只读操作可以自动放行，但 `Bash: cat file` 需要审批整条命令
-2. **输出结构化**：专用工具的返回值是结构化的，方便 UI 渲染（高亮、diff 视图等）
-3. **性能优化**：专用工具可以做缓存、分页、token 预算控制，shell 命令做不到
+| 维度 | 专用工具 | Bash 命令 |
+|------|---------|----------|
+| **权限粒度** | `Read` 是只读操作 → 自动放行 | `Bash: cat file` 需要审批整条命令（cat 在只读集合中但走不同路径） |
+| **输出结构化** | 返回结构化数据，UI 可渲染 diff、高亮 | 纯文本输出，无渲染优化 |
+| **性能优化** | 文件缓存、分页、token 预算控制 | 每次都是新进程，无缓存 |
+| **并发安全** | `isConcurrencySafe()` 返回 `true` → 可并行执行 | Bash 命令可能有副作用，串行执行 |
+| **安全审计** | 工具名精确匹配权限规则 | 需 AST 解析命令结构后匹配 |
+
+`isConcurrencySafe()`（`BashTool.tsx:434`）是一个常被忽视但重要的设计——只有只读命令可以在 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, ... }
+```
+
+UI 层通过 `useToolCallProgress` hook 实时展示命令输出。`resolveProgress()` 信号机制让 generator 在有新数据时才 yield，避免了忙等待。