docs: 重写 Shell 执行，从源码解剖改为安全设计分析

移除 TypeScript 代码和源码路径，
聚焦只读判定的复合命令处理、AST 解析的 fail-safe 策略、
自动后台化的阻塞预算设计和专用工具 vs shell 的权衡。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/tools/shell-execution.mdx

@@ -1,168 +1,84 @@
 ---
-title: "命令执行工具 - BashTool 安全设计与实现"
-description: "从源码角度解析 Claude Code BashTool：只读命令判定、AST 安全解析、自动后台化、输出截断和专用工具 vs shell 命令的设计权衡。"
+title: "Shell 执行"
+description: "AI 执行命令是最危险的能力。BashTool 如何通过只读判定、AST 解析、自动后台化和输出截断在安全与效率间取得平衡。"
 keywords: ["Bash 工具", "命令执行", "Shell 执行", "安全命令", "AI 执行命令"]
 ---
 
-{/* 本章目标：从源码角度揭示 BashTool 的安全设计、执行链路和关键工程决策 */}
+## 核心挑战
 
-## 执行链路总览
+AI 能执行任意 shell 命令是最强大也最危险的能力。一个 `rm -rf /` 就能造成不可逆的破坏。
 
-一条 Bash 命令从 AI 决策到实际执行的完整路径：
+BashTool 的设计核心是在**安全**和**效率**之间取得平衡——让 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)           ← 实际进程创建
-```
+## 只读命令的判定
 
-## 只读命令的判定：为什么 Read 免审批而 Bash 不一定
+BashTool 的 `isReadOnly()` 决定一条命令是否需要用户确认：
 
-BashTool 的 `isReadOnly()` 方法（`packages/builtin-tools/src/tools/BashTool/BashTool.tsx:655`）决定一条命令是否被视为"只读"：
+| 命令类别 | 示例 | 是否只读 |
+|---------|------|:--------:|
+| 搜索类 | `find`、`grep`、`rg`、`which` | ✓ |
+| 读取类 | `cat`、`head`、`wc`、`jq`、`sort` | ✓ |
+| 列表类 | `ls`、`tree`、`du` | ✓ |
+| 中性命令 | `echo`、`true`、`false` | 不影响判定 |
 
-```typescript
-isReadOnly(input) {
-  const compoundCommandHasCd = commandHasAnyCd(input.command)
-  const result = checkReadOnlyConstraints(input, compoundCommandHasCd)
-  return result.behavior === 'allow'
-}
-```
+### 复合命令的处理
 
-判定逻辑基于 4 个命令集合（`BashTool.tsx:120-166`）：
+对于复合命令（`ls dir && echo "---" && ls dir2`），系统拆分后逐段检查——**所有非中性段都必须属于只读集合**，整条命令才被视为只读。
 
-| 集合 | 命令 | 性质 |
-|------|------|------|
-| `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, : | 语义中性（不影响判定） |
+**设计考量**：`echo` 等中性命令不影响判定，因为 `ls && echo "done"` 和单纯的 `ls` 在副作用上没有区别。但如果 `ls && git push`，`git push` 有副作用，整条命令就不能免审批。
 
-对于复合命令（`ls dir && echo "---" && ls dir2`），系统拆分后逐段检查——**所有非中性段都必须属于上述集合**，整条命令才被视为只读。
+## AST 安全解析
 
-```typescript
-// BashTool.tsx — 简化的判定逻辑
-for (const part of partsWithOperators) {
-  if (BASH_SEMANTIC_NEUTRAL_COMMANDS.has(baseCommand)) continue  // 跳过中性段
-  if (!isPartSearch && !isPartRead && !isPartList) {
-    return { isSearch: false, isRead: false, isList: false }  // 有任何一段不通过 → 非只读
-  }
-}
-```
+权限检查不是基于简单的字符串匹配——系统使用 tree-sitter bash 解析器分析命令的抽象语法树。
 
-## AST 安全解析：tree-sitter bash 解析
+**为什么需要 AST 解析**？字符串匹配无法处理 `git push` 被嵌在管道、子 shell 或条件表达式中的情况。AST 解析可以准确提取每个子命令，确保 `git push` 不会因为被嵌在看似无害的上下文中而绕过检查。
 
-`preparePermissionMatcher()`（`BashTool.tsx:663`）在权限检查前用 `parseForSecurity()` 解析命令结构：
+**Fail-safe 策略**：解析失败时，系统假设命令不安全，触发所有安全检查。宁可多确认一次，也不要漏过一个危险命令。
 
-```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。
+长时间运行的命令不应该阻塞 AI 的整个工作循环。
 
-## 超时控制：分级策略
+### 分级超时
 
-```
-用户指定 timeout → 直接使用
-  ↓ 未指定
-getDefaultTimeoutMs()
-  ├── 默认上限：120,000ms（2 分钟）
-  └── 最大上限：600,000ms（10 分钟，用户显式设置时）
-```
+| 场景 | 超时 |
+|------|------|
+| 默认 | 2 分钟 |
+| 用户显式设置 | 最长 10 分钟 |
 
-超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:144`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。
+### 自动后台化
 
-## 自动后台化
+主线程 Agent 有 15 秒的"阻塞预算"——超过这个时间，系统自动将命令转为后台任务，AI 可以继续做其他事。后台任务完成后通过通知机制汇报结果。
 
-长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：
+**设计考量**：一个 `npm install` 可能需要几分钟，不应该让 AI 在此期间完全停滞。自动后台化让 AI 可以在等待安装的同时继续做其他工作——和人类开发者一样。
 
-```typescript
-// BashTool.tsx:1158
-const shouldAutoBackground = !isBackgroundTasksDisabled 
-  && isAutobackgroundingAllowed(command)
-```
+## 输出截断
 
-自动后台化的完整链路：
+命令输出过长时会触发截断，防止海量日志塞进 AI 的上下文窗口。
 
-```
-命令开始执行
-  ↓ 进度轮询
-15 秒内未完成（ASSISTANT_BLOCKING_BUDGET_MS）
-  ↓
-检查 isAutobackgroundingAllowed(command)
-  ↓ 允许
-将前台任务转为后台任务（backgroundExistingForegroundTask）
-  ↓
-shellCommand.onTimeout → spawnBackgroundTask()
-  ↓
-返回 taskId 给 AI，AI 可以继续做其他事
-  ↓
-后台任务完成后通过通知机制汇报结果
-```
+截断不是简单砍尾——系统通过 `isIncomplete` 标记告知 AI 输出不完整。AI 可以决定是否需要用更精确的命令（如 `grep` 管道、`head` 限制）重新获取。
 
-主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 `npm install` 阻塞整个 agentic loop 数分钟。
+**设计哲学**：让 AI 知道"信息不完整"比给它一堆截断的垃圾更有用。AI 会根据不完整的信息自行调整策略。
 
-## 输出截断策略
+## 专用工具 vs Shell 命令
 
-命令输出过长时会触发截断，防止把海量日志塞进 AI 的上下文窗口：
-
-| 截断点 | 位置 | 行为 |
-|--------|------|------|
-| `maxResultSizeChars` | 工具级（通常 100K 字符） | 超长输出在写入消息前截断 |
-| 进度轮询截断 | `onProgress` 回调 | 只传递最后几行作为进度显示 |
-| `totalBytes` 标记 | `isIncomplete` 参数 | 告知 AI 输出被截断 |
-
-截断不是简单砍尾——`isIncomplete` 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。
-
-## 为什么用专用工具而不是直接调 shell
-
-Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。这不仅是用户体验的选择，更是架构层面的设计决策：
+Claude Code 为文件读写、搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令：
 
 | 维度 | 专用工具 | Bash 命令 |
 |------|---------|----------|
-| **权限粒度** | `Read` 是只读操作 → 自动放行 | `Bash: cat file` 需要审批整条命令（cat 在只读集合中但走不同路径） |
-| **输出结构化** | 返回结构化数据，UI 可渲染 diff、高亮 | 纯文本输出，无渲染优化 |
-| **性能优化** | 文件缓存、分页、token 预算控制 | 每次都是新进程，无缓存 |
-| **并发安全** | `isConcurrencySafe()` 返回 `true` → 可并行执行 | Bash 命令可能有副作用，串行执行 |
-| **安全审计** | 工具名精确匹配权限规则 | 需 AST 解析命令结构后匹配 |
+| **权限** | 只读操作自动放行 | 需要整条命令的权限检查 |
+| **输出** | 结构化数据，支持 diff 高亮 | 纯文本，无渲染优化 |
+| **性能** | 文件缓存、分页、token 预算 | 每次新进程，无缓存 |
+| **并发** | 只读操作可并行执行 | 有副作用的命令必须串行 |
 
-`isConcurrencySafe()`（`BashTool.tsx:652`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。
+**设计洞察**：专用工具在安全性和效率上都优于等效的 shell 命令。`Read` 工具知道自己是只读的，所以可以自动放行；而 `cat` 走 BashTool 的权限路径，需要更多检查。
 
-## 进度反馈的流式设计
+## 进度反馈
 
-BashTool 的命令执行是流式的，通过 `onProgress` 回调逐行推送输出：
+BashTool 的命令执行是流式的——输出逐行推送，用户可以实时看到 AI 正在执行什么。这比"命令执行中...请等待"的黑盒体验好得多。
 
-```
-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，避免了忙等待。
+- **任务管理** — TaskCreate/TaskUpdate 的追踪系统
+- **权限模型** — 理解只读判定的完整安全体系
+- **沙箱** — Bash 命令的隔离执行环境