From 5849b8b7f458284e878c174e605e52c6d4ba6c0c Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Mon, 20 Apr 2026 10:50:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20Shell=20=E6=89=A7?= =?UTF-8?q?=E8=A1=8C=EF=BC=8C=E4=BB=8E=E6=BA=90=E7=A0=81=E8=A7=A3=E5=89=96?= =?UTF-8?q?=E6=94=B9=E4=B8=BA=E5=AE=89=E5=85=A8=E8=AE=BE=E8=AE=A1=E5=88=86?= =?UTF-8?q?=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除 TypeScript 代码和源码路径， 聚焦只读判定的复合命令处理、AST 解析的 fail-safe 策略、 自动后台化的阻塞预算设计和专用工具 vs shell 的权衡。 Co-Authored-By: Claude Opus 4.6 --- docs/tools/shell-execution.mdx | 178 +++++++++------------------------ 1 file changed, 47 insertions(+), 131 deletions(-) diff --git a/docs/tools/shell-execution.mdx b/docs/tools/shell-execution.mdx index 9eca2bdd9..3ff295df5 100644 --- a/docs/tools/shell-execution.mdx +++ b/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 命令的隔离执行环境