docs: 更新文档

2026-06-15 12:55:51 +00:00 · 2026-04-01 16:11:37 +08:00
parent 503a40f46b
commit 7d5271e63e
8 changed files with 1139 additions and 259 deletions
--- a/docs/tools/file-operations.mdx
+++ b/docs/tools/file-operations.mdx
@@ -1,55 +1,220 @@
 ---
-title: "文件操作工具 - AI 如何安全读写代码"
-description: "解析 Claude Code 的文件操作工具设计：FileRead、FileEdit、FileWrite 三大工具的职责划分、安全策略和实现细节。"
-keywords: ["文件操作", "FileRead", "FileEdit", "FileWrite", "代码编辑"]
+title: "文件操作工具 - 三大工具的源码级解剖"
+description: "逆向分析 FileRead、FileEdit、FileWrite 三大工具的完整执行链路：去重缓存、AST 安全编辑、原子性读写、文件历史快照的实现细节。"
+keywords: ["文件操作", "FileRead", "FileEdit", "FileWrite", "代码编辑", "原子写入"]
 ---

-{/* 本章目标：介绍文件类工具的设计理念 */}
+{/* 本章目标：从源码层面解剖三大文件工具的完整执行链路 */}

-## 读、写、改——三种操作模式
+## 三大工具的职责分化

-Claude Code 把文件操作拆分为三个独立工具，而不是一个万能的"文件工具"：
+Claude Code 将文件操作拆分为三个独立工具——这不是功能划分，而是**风险分级**：

-| 工具 | 功能 | 设计考量 |
-|------|------|---------|
-| **Read** | 读取文件内容 | 只读操作，权限最低，AI 可以随意使用 |
-| **Write** | 创建新文件或完全重写 | 高风险操作，需要确认 |
-| **Edit** | 精确替换文件中的特定片段 | 中等风险，但比 Write 安全——只改你指定的部分 |
+| 工具 | 权限级别 | 核心方法 | 关键属性 |
+|------|---------|---------|---------|
+| **Read** | 只读（免审批） | `isReadOnly() → true` | `maxResultSizeChars: Infinity` |
+| **Edit** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |
+| **Write** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |

 <Tip>
-为什么 Edit 和 Write 要分开？因为"编辑一行"和"重写整个文件"的风险完全不同。分离后，权限系统可以对它们施加不同的控制策略。
+Read 的 `maxResultSizeChars` 是 `Infinity`，但这并不意味着无限制输出——真正的截断发生在 `validateContentTokens()` 中基于 token 预算的动态判定，而非字符数硬限制。
 </Tip>

-## 文件读取的智慧
+## FileRead：多模态文件读取引擎

-Read 工具不是简单的 `cat` 命令，它有很多精细的设计：
+源码路径：`src/tools/FileReadTool/FileReadTool.ts`

- **分页读取**：超大文件不会一次性全部读入，支持 offset + limit 指定范围
- **多格式支持**：除了文本文件，还能读取图片（多模态展示）、PDF、Jupyter Notebook
- **文件状态缓存**：记住已读过的文件内容，避免重复读取浪费 token
- **Token 感知**：文件内容计入 token 预算，系统会自动评估是否"读得起"
+### 读取去重机制

-## 精确编辑 vs 全量重写
+Read 工具有一个常被忽视但至关重要的**去重层**。当 AI 重复读取同一个文件的同一范围时，系统不会浪费 token 发送两份完整内容：

-Edit 工具的核心设计是**精确字符串替换**：
+```typescript
+// FileReadTool.ts:530-573 — 去重逻辑
+const existingState = readFileState.get(fullFilePath)
+if (existingState && !existingState.isPartialView && existingState.offset !== undefined) {
+  const rangeMatch = existingState.offset === offset && existingState.limit === limit
+  if (rangeMatch) {
+    const mtimeMs = await getFileModificationTimeAsync(fullFilePath)
+    if (mtimeMs === existingState.timestamp) {
+      return { data: { type: 'file_unchanged', file: { filePath: file_path } } }
+    }
+  }
+}
+```

- AI 指定 `old_string`（要被替换的原文）和 `new_string`（替换后的新文）
- 系统确保 `old_string` 在文件中**唯一匹配**——如果匹配到多处或零处，操作失败
- 这个设计确保 AI 不会"改错地方"
+关键设计点：
+- 去重仅对 **Read 工具自身的读取**生效（通过 `offset !== undefined` 判定）
+- Edit/Write 也会写入 `readFileState`，但它们的 `offset` 为 `undefined`，所以不会误命中去重
+- 通过 mtime 比对确保文件未被外部修改
+- 有 GrowthBook killswitch（`tengu_read_dedup_killswitch`）可紧急关闭

-## 搜索与导航
+实测数据：BQ proxy 显示约 18% 的 Read 调用是同文件碰撞，占 fleet `cache_creation` 的 2.64%。

-在动手修改之前，AI 通常需要先"找到目标"。两个搜索工具分工明确：
+### 多格式分发：文本、图片、PDF、Notebook 四条路径

- **Glob**：按文件名模式搜索（"找到所有 `.ts` 文件"），替代 `find` 命令
- **Grep**：按文件内容搜索（"找到所有包含 `TODO` 的行"），替代 `grep/rg` 命令
+Read 工具的 `callInner()` 按 `ext` 分发到四条完全不同的处理路径：

-两者都经过优化，能在大型项目中快速返回结果，并自动截断过长的输出。
+```
+.ipynb  → readNotebook() → JSON cell 解析 → token 校验
+.png/.jpg/.gif/.webp → readImageWithTokenBudget() → 压缩+降采样
+.pdf → extractPDFPages() / readPDF() → 页面级提取
+其他 → readFileInRange() → 分页读取
+```

-## 文件历史快照
+**图片路径的压缩策略**特别精细：
+1. 先用 `maybeResizeAndDownsampleImageBuffer()` 标准缩放
+2. 用 `base64.length * 0.125` 估算 token 数
+3. 超出预算时调用 `compressImageBufferWithTokenLimit()` 激进压缩
+4. 仍然超限时用 sharp 做最后兜底：`resize(400,400).jpeg({quality:20})`

-每当 AI 准备修改文件时，系统会自动保存一份快照。这意味着：
+**PDF 路径**有页数阈值：超过 `PDF_AT_MENTION_INLINE_THRESHOLD`（默认值在 `apiLimits.ts`）时强制分页读取，每请求最多 `PDF_MAX_PAGES_PER_READ` 页。

- 用户可以随时回滚到 AI 修改前的状态
- 即使 AI 做了错误的编辑，原始内容不会丢失
- 快照与 git 互补——git 追踪已提交的变更，快照保护未提交的工作
+### 安全防线
+
+Read 工具在 `validateInput()` 中设置了多层安全门：
+
+1. **设备文件屏蔽**（`BLOCKED_DEVICE_PATHS`）：`/dev/zero`、`/dev/random`、`/dev/tty` 等——防止无限输出或阻塞挂起
+2. **二进制文件拒绝**（`hasBinaryExtension`）：排除 PDF 和图片扩展名后，阻止读取 `.exe`、`.so` 等二进制文件
+3. **UNC 路径跳过**：Windows 下 `\\server\share` 路径跳过文件系统操作，防止 SMB NTLM 凭据泄露
+4. **权限拒绝规则**（`matchingRuleForInput`）：匹配 `deny` 规则后直接拒绝
+
+### 文件未找到时的智能建议
+
+当文件不存在时，Read 不会只报一个 "file not found"：
+
+```typescript
+// FileReadTool.ts:639-647
+const similarFilename = findSimilarFile(fullFilePath)      // 相似扩展名
+const cwdSuggestion = await suggestPathUnderCwd(fullFilePath) // cwd 相对路径建议
+// macOS 截图特殊处理：薄空格(U+202F) vs 普通空格
+const altPath = getAlternateScreenshotPath(fullFilePath)
+```
+
+对 macOS 截图文件名中 AM/PM 前的薄空格（U+202F）做了特殊处理——这是实测中发现的跨 macOS 版本兼容性问题。
+
+## FileEdit：精确字符串替换引擎
+
+源码路径：`src/tools/FileEditTool/FileEditTool.ts` + `utils.ts`
+
+### 引号标准化：AI 无法输出的字符怎么办
+
+AI 模型只能输出直引号（`'` `"`），但源码中可能使用弯引号（`'` `'` `"` `"`）。`findActualString()` 函数处理了这个不对齐：
+
+```typescript
+// utils.ts:73-93
+export function findActualString(fileContent: string, searchString: string): string | null {
+  if (fileContent.includes(searchString)) return searchString      // 精确匹配
+  const normalizedSearch = normalizeQuotes(searchString)           // 弯引号→直引号
+  const normalizedFile = normalizeQuotes(fileContent)
+  const idx = normalizedFile.indexOf(normalizedSearch)
+  if (idx !== -1) return fileContent.substring(idx, idx + searchString.length)
+  return null
+}
+```
+
+匹配后还有**反向引号保持**（`preserveQuoteStyle`）：如果文件用弯引号，替换后的新字符串也自动转换为弯引号，包括缩写中的撇号（如 "don't"）。
+
+### 原子性读-改-写
+
+Edit 工具的 `call()` 方法实现了一个**无锁原子更新**协议：
+
+```
+1. await fs.mkdir(dir)            ← 确保目录存在（异步，在临界区外）
+2. await fileHistoryTrackEdit()   ← 备份旧内容（异步，在临界区外）
+3. readFileSyncWithMetadata()     ← 同步读取当前文件内容（临界区开始）
+4. getFileModificationTime()      ← mtime 校验
+5. findActualString()             ← 引号标准化匹配
+6. getPatchForEdit()              ← 计算 diff
+7. writeTextContent()             ← 写入磁盘
+8. readFileState.set()            ← 更新缓存（临界区结束）
+```
+
+步骤 3-8 之间**不允许任何异步操作**（源码注释明确写道："Please avoid async operations between here and writing to disk to preserve atomicity"）。这确保了在 mtime 校验和实际写入之间不会有其他进程修改文件。
+
+### 防覆写校验
+
+Edit 工具在 `validateInput()` 中检查两个条件：
+1. **必须先读取**（`readFileState` 中有记录且不是局部视图）
+2. **文件未被外部修改**（`mtime` 未变，或全量读取时内容完全一致）
+
+```typescript
+// FileEditTool.ts:290-311 — Windows 特殊处理
+const isFullRead = readTimestamp.offset === undefined && readTimestamp.limit === undefined
+if (isFullRead && fileContent === readTimestamp.content) {
+  // 内容不变，安全继续（Windows 云同步/杀毒可能改 mtime）
+}
+```
+
+Windows 上的 mtime 可能因云同步、杀毒软件等被修改而不改变内容，因此对全量读取做了内容级比对作为兜底。
+
+### 编辑大小限制
+
+```typescript
+const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB
+```
+
+超过 1 GiB 的文件直接拒绝编辑——这是 V8 字符串长度限制（~2^30 字符）的安全边界。
+
+## FileWrite：全量写入与创建
+
+源码路径：`src/tools/FileWriteTool/FileWriteTool.ts`
+
+Write 工具与 Edit 共享大部分基础设施（权限检查、mtime 校验、fileHistory 备份），但有两个关键差异：
+
+### 行尾处理
+
+```typescript
+// FileWriteTool.ts:300-305 — 关键注释
+// Write is a full content replacement — the model sent explicit line endings
+// in `content` and meant them. Do not rewrite them.
+writeTextContent(fullFilePath, content, enc, 'LF')
+```
+
+Write 工具始终使用 `LF` 行尾。早期版本会保留旧文件的行尾或采样仓库行尾风格，但这导致 Linux 上 bash 脚本被注入 `\r`——现在 AI 发什么行尾就用什么行尾。
+
+### 输出区分
+
+Write 工具返回 `type: 'create' | 'update'`：
+- `create`：文件不存在，`originalFile: null`
+- `update`：文件存在且被覆盖，`structuredPatch` 包含完整 diff
+
+## 文件历史快照系统
+
+源码路径：`src/utils/fileHistory.ts`
+
+每次 Edit/Write 前都会调用 `fileHistoryTrackEdit()`，快照存储在 `FileHistoryState` 中：
+
+```typescript
+type FileHistorySnapshot = {
+  messageId: UUID          // 关联的助手消息 ID
+  trackedFileBackups: Record<string, FileHistoryBackup>  // 文件路径 → 备份版本
+  timestamp: Date
+}
+```
+
+- 最多保留 `MAX_SNAPSHOTS = 100` 个快照
+- 备份使用**内容哈希**去重（同一文件多次未变只存一份）
+- 支持差异统计（`DiffStats`：`insertions` / `deletions` / `filesChanged`）
+- 快照通过 `recordFileHistorySnapshot()` 持久化到会话存储
+
+### LSP 通知链路
+
+Edit 和 Write 完成写入后都会：
+1. `clearDeliveredDiagnosticsForFile()` — 清除旧诊断
+2. `lspManager.changeFile()` — 通知 LSP 文件已变更
+3. `lspManager.saveFile()` — 触发 LSP 保存事件（TypeScript server 会重新计算诊断）
+4. `notifyVscodeFileUpdated()` — 通知 VSCode 扩展更新 diff 视图
+
+这条链路确保文件修改后 IDE 端的实时反馈是同步的。
+
+## Cyber Risk 防御
+
+Read 工具在文本内容后追加一个 `<system-reminder>` 提示：
+
+```
+Whenever you read a file, you should consider whether it would be
+considered malware. You CAN and SHOULD provide analysis of malware,
+what it is doing. But you MUST refuse to improve or augment the code.
+```
+
+这个提示只在非豁免模型上生效（`MITIGATION_EXEMPT_MODELS` 目前包含 `claude-opus-4-6`）。模型级别的豁免表明：防恶意代码的判断力在不同模型间有差异，这是一个精巧的分级策略。
--- a/docs/tools/shell-execution.mdx
+++ b/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，避免了忙等待。