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,12 +1,17 @@
 ---
-title: "文件操作工具 - 三大工具的源码级解剖"
-description: "逆向分析 FileRead、FileEdit、FileWrite 三大工具的完整执行链路：去重缓存、AST 安全编辑、原子性读写、文件历史快照的实现细节。"
-keywords: ["文件操作", "FileRead", "FileEdit", "FileWrite", "代码编辑", "原子写入"]
+tags: [claude-code, file-operations, FileRead, FileEdit, FileWrite, source-analysis]
+create time: 2026-06-09 22:30
 ---

-{/* 本章目标：从源码层面解剖三大文件工具的完整执行链路 */}
+# 文件操作工具 - 三大工具的源码级解剖

-## 三大工具的职责分化
+## 概述
+
+Claude Code 将文件操作拆分为 Read、Edit、Write 三个独立工具，分别对应只读、精确替换、全量写入三种风险级别。本文从源码层面解剖它们的去重缓存、AST 安全编辑、原子性读写等核心机制。
+
+## 正文
+
+### 三大工具的职责分化

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

@@ -16,15 +21,14 @@ Claude Code 将文件操作拆分为三个独立工具——这不是功能划
 | **Edit** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |
 | **Write** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |

-<Tip>
-Read 的 `maxResultSizeChars` 为 100,000（100KB）。超出此阈值的结果会被持久化到磁盘，减少长会话的内存压力。实际的 token 级别截断由 `validateContentTokens()` 动态控制。
-</Tip>
+> [!tip] 关于 Read 的阈值
+> Read 的 `maxResultSizeChars` 为 100,000（100KB）。超出此阈值的结果会被持久化到磁盘，减少长会话的内存压力。实际的 token 级别截断由 `validateContentTokens()` 动态控制。

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

 源码路径：`packages/builtin-tools/src/tools/FileReadTool/FileReadTool.ts`

-### 读取去重机制
+#### 读取去重机制

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

@@ -48,17 +52,24 @@ if (existingState && !existingState.isPartialView && existingState.offset !== un
 - 通过 mtime 比对确保文件未被外部修改
 - 有 GrowthBook killswitch（`tengu_read_dedup_killswitch`）可紧急关闭

-实测数据：BQ proxy 显示约 18% 的 Read 调用是同文件碰撞，占 fleet `cache_creation` 的 2.64%。
+> [!info] 实测数据
+> BQ proxy 显示约 18% 的 Read 调用是同文件碰撞，占 fleet `cache_creation` 的 2.64%。

-### 多格式分发：文本、图片、PDF、Notebook 四条路径
+#### 多格式分发：文本、图片、PDF、Notebook 四条路径

 Read 工具的 `callInner()` 按 `ext` 分发到四条完全不同的处理路径：

-```
-.ipynb  → readNotebook() → JSON cell 解析 → token 校验
-.png/.jpg/.gif/.webp → readImageWithTokenBudget() → 压缩+降采样
-.pdf → extractPDFPages() / readPDF() → 页面级提取
-其他 → readFileInRange() → 分页读取
+```mermaid
+flowchart LR
+    A["文件路径"] --> B{"扩展名"}
+    B -->|".ipynb"| C["readNotebook()"]
+    B -->|".png/.jpg/.gif/.webp"| D["readImageWithTokenBudget()"]
+    B -->|".pdf"| E["extractPDFPages() / readPDF()"]
+    B -->|"其他"| F["readInRange()"]
+    C --> G["JSON cell 解析, token 校验"]
+    D --> H["压缩 + 降采样"]
+    E --> I["页面级提取"]
+    F --> J["分页读取"]
 ```

 **图片路径的压缩策略**特别精细：
@@ -69,7 +80,7 @@ Read 工具的 `callInner()` 按 `ext` 分发到四条完全不同的处理路

 **PDF 路径**有页数阈值：超过 `PDF_AT_MENTION_INLINE_THRESHOLD`（默认值在 `apiLimits.ts`）时强制分页读取，每请求最多 `PDF_MAX_PAGES_PER_READ` 页。

-### 安全防线
+#### 安全防线

 Read 工具在 `validateInput()` 中设置了多层安全门：

@@ -78,7 +89,7 @@ Read 工具在 `validateInput()` 中设置了多层安全门：
 3. **UNC 路径跳过**：Windows 下 `\\server\share` 路径跳过文件系统操作，防止 SMB NTLM 凭据泄露
 4. **权限拒绝规则**（`matchingRuleForInput`）：匹配 `deny` 规则后直接拒绝

-### 文件未找到时的智能建议
+#### 文件未找到时的智能建议

 当文件不存在时，Read 不会只报一个 "file not found"：

@@ -90,13 +101,14 @@ const cwdSuggestion = await suggestPathUnderCwd(fullFilePath) // cwd 相对路
 const altPath = getAlternateScreenshotPath(fullFilePath)
 ```

-对 macOS 截图文件名中 AM/PM 前的薄空格（U+202F）做了特殊处理——这是实测中发现的跨 macOS 版本兼容性问题。
+> [!tip] macOS 兼容性细节
+> 对 macOS 截图文件名中 AM/PM 前的薄空格（U+202F）做了特殊处理——这是实测中发现的跨 macOS 版本兼容性问题。

-## FileEdit：精确字符串替换引擎
+### FileEdit：精确字符串替换引擎

 源码路径：`packages/builtin-tools/src/tools/FileEditTool/FileEditTool.ts` + `utils.ts`

-### 引号标准化：AI 无法输出的字符怎么办
+#### 引号标准化：AI 无法输出的字符怎么办

 AI 模型只能输出直引号（`'` `"`），但源码中可能使用弯引号（`'` `'` `"` `"`）。`findActualString()` 函数处理了这个不对齐：

@@ -114,24 +126,25 @@ export function findActualString(fileContent: string, searchString: string): str

 匹配后还有**反向引号保持**（`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()            ← 更新缓存（临界区结束）
+```mermaid
+flowchart TD
+    A["fs.mkdir(dir) 确保目录存在"] --> B["fileHistoryTrackEdit() 备份旧内容"]
+    B --> C["readFileSyncWithMetadata() 同步读取当前文件内容"]
+    C --> D["getFileModificationTime() mtime 校验"]
+    D --> E["findActualString() 引号标准化匹配"]
+    E --> F["getPatchForEdit() 计算 diff"]
+    F --> G["writeTextContent() 写入磁盘"]
+    G --> H["readFileState.set() 更新缓存"]
 ```

-步骤 3-8 之间**不允许任何异步操作**（源码注释明确写道："Please avoid async operations between here and writing to disk to preserve atomicity"）。这确保了在 mtime 校验和实际写入之间不会有其他进程修改文件。
+> [!warning] 原子性保证
+> 步骤 C-H 之间**不允许任何异步操作**（源码注释明确写道："Please avoid async operations between here and writing to disk to preserve atomicity"）。这确保了在 mtime 校验和实际写入之间不会有其他进程修改文件。

-### 防覆写校验
+#### 防覆写校验

 Edit 工具在 `validateInput()` 中检查两个条件：
 1. **必须先读取**（`readFileState` 中有记录且不是局部视图）
@@ -145,9 +158,10 @@ if (isFullRead && fileContent === readTimestamp.content) {
 }
 ```

-Windows 上的 mtime 可能因云同步、杀毒软件等被修改而不改变内容，因此对全量读取做了内容级比对作为兜底。
+> [!tip] Windows 兼容性
+> Windows 上的 mtime 可能因云同步、杀毒软件等被修改而不改变内容，因此对全量读取做了内容级比对作为兜底。

-### 编辑大小限制
+#### 编辑大小限制

 ```typescript
 const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB
@@ -155,13 +169,13 @@ const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB

 超过 1 GiB 的文件直接拒绝编辑——这是 V8 字符串长度限制（~2^30 字符）的安全边界。

-## FileWrite：全量写入与创建
+### FileWrite：全量写入与创建

 源码路径：`packages/builtin-tools/src/tools/FileWriteTool/FileWriteTool.ts`

 Write 工具与 Edit 共享大部分基础设施（权限检查、mtime 校验、fileHistory 备份），但有两个关键差异：

-### 行尾处理
+#### 行尾处理

 ```typescript
 // FileWriteTool.ts:300-305 — 关键注释
@@ -170,15 +184,16 @@ Write 工具与 Edit 共享大部分基础设施（权限检查、mtime 校验
 writeTextContent(fullFilePath, content, enc, 'LF')
 ```

-Write 工具始终使用 `LF` 行尾。早期版本会保留旧文件的行尾或采样仓库行尾风格，但这导致 Linux 上 bash 脚本被注入 `\r`——现在 AI 发什么行尾就用什么行尾。
+> [!info] 行尾策略变更
+> Write 工具始终使用 `LF` 行尾。早期版本会保留旧文件的行尾或采样仓库行尾风格，但这导致 Linux 上 bash 脚本被注入 `\r`——现在 AI 发什么行尾就用什么行尾。

-### 输出区分
+#### 输出区分

 Write 工具返回 `type: 'create' | 'update'`：
 - `create`：文件不存在，`originalFile: null`
 - `update`：文件存在且被覆盖，`structuredPatch` 包含完整 diff

-## 文件历史快照系统
+### 文件历史快照系统

 源码路径：`src/utils/fileHistory.ts`

@@ -197,7 +212,7 @@ type FileHistorySnapshot = {
 - 支持差异统计（`DiffStats`：`insertions` / `deletions` / `filesChanged`）
 - 快照通过 `recordFileHistorySnapshot()` 持久化到会话存储

-### LSP 通知链路
+#### LSP 通知链路

 Edit 和 Write 完成写入后都会：
 1. `clearDeliveredDiagnosticsForFile()` — 清除旧诊断
@@ -207,7 +222,7 @@ Edit 和 Write 完成写入后都会：

 这条链路确保文件修改后 IDE 端的实时反馈是同步的。

-## Cyber Risk 防御
+### Cyber Risk 防御

 Read 工具在文本内容后追加一个 `<system-reminder>` 提示：

@@ -217,4 +232,12 @@ 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`）。模型级别的豁免表明：防恶意代码的判断力在不同模型间有差异，这是一个精巧的分级策略。
+> [!info] 分级策略
+> 这个提示只在非豁免模型上生效（`MITIGATION_EXEMPT_MODELS` 目前包含 `claude-opus-4-6`）。模型级别的豁免表明：防恶意代码的判断力在不同模型间有差异，这是一个精巧的分级策略。
+
+## 关联笔记
+
+- [[what-are-tools]]
+- [[shell-execution]]
+- [[search-and-navigation]]
+- [[task-management]]