claude-code/docs/tools/file-operations.mdx

---
title: "文件操作工具 - AI 如何安全读写代码"
description: "解析 Claude Code 的文件操作工具设计：FileRead、FileEdit、FileWrite 三大工具的职责划分、安全策略和实现细节。"
keywords: ["文件操作", "FileRead", "FileEdit", "FileWrite", "代码编辑"]
---

{/* 本章目标：介绍文件类工具的设计理念 */}

## 读、写、改——三种操作模式

Claude Code 把文件操作拆分为三个独立工具，而不是一个万能的"文件工具"：

| 工具 | 功能 | 设计考量 |
|------|------|---------|
| **Read** | 读取文件内容 | 只读操作，权限最低，AI 可以随意使用 |
| **Write** | 创建新文件或完全重写 | 高风险操作，需要确认 |
| **Edit** | 精确替换文件中的特定片段 | 中等风险，但比 Write 安全——只改你指定的部分 |

<Tip>
为什么 Edit 和 Write 要分开？因为"编辑一行"和"重写整个文件"的风险完全不同。分离后，权限系统可以对它们施加不同的控制策略。
</Tip>

## 文件读取的智慧

Read 工具不是简单的 `cat` 命令，它有很多精细的设计：

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

## 精确编辑 vs 全量重写

Edit 工具的核心设计是**精确字符串替换**：

- AI 指定 `old_string`（要被替换的原文）和 `new_string`（替换后的新文）
- 系统确保 `old_string` 在文件中**唯一匹配**——如果匹配到多处或零处，操作失败
- 这个设计确保 AI 不会"改错地方"

## 搜索与导航

在动手修改之前，AI 通常需要先"找到目标"。两个搜索工具分工明确：

- **Glob**：按文件名模式搜索（"找到所有 `.ts` 文件"），替代 `find` 命令
- **Grep**：按文件内容搜索（"找到所有包含 `TODO` 的行"），替代 `grep/rg` 命令

两者都经过优化，能在大型项目中快速返回结果，并自动截断过长的输出。

## 文件历史快照

每当 AI 准备修改文件时，系统会自动保存一份快照。这意味着：

- 用户可以随时回滚到 AI 修改前的状态
- 即使 AI 做了错误的编辑，原始内容不会丢失
- 快照与 git 互补——git 追踪已提交的变更，快照保护未提交的工作