Claude Code 的文件读写与编辑链路

为什么文件链路是 Claude Code 的基本盘

再强的 AI 编程工具，如果不能稳定地：

• 读取文件
• 理解文件
• 编辑文件
• 写回文件

那它就只能停留在“建议型助手”的层面。
Claude Code 之所以真正进入工程工作流，文件链路是最底层的原因之一。

从工具注册表看，文件能力是一级公民

在 tools.ts 里，文件工具是基础工具集的一部分：

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool,
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    NotebookEditTool,
    WebFetchTool,
  ]
}

这段代码说明 Claude Code 不把文件能力当成附加功能，而是当成默认运行时的核心组件。

整体链路先看图

FileReadTool 的设计很能说明工程取向

来看它的定义片段：

export const FileReadTool = buildTool({
  name: FILE_READ_TOOL_NAME,
  searchHint: 'read files, images, PDFs, notebooks',
  maxResultSizeChars: Infinity,
  strict: true,
  async description() {
    return DESCRIPTION
  },
  isConcurrencySafe() {
    return true
  },
  isReadOnly() {
    return true
  },
  getPath({ file_path }): string {
    return file_path || getCwd()
  },
})

这段代码至少传达出 4 个信息：

1. 它不是只读文本，还考虑图片、PDF、notebook
2. 工具行为是严格定义的
3. 它显式标记自己是只读工具
4. 它和当前工作目录是绑定的

也就是说，Claude Code 对“读文件”这件事并没有写成一个随便的 fs.readFile 包装，而是完整地工具化了。

为什么读文件工具要这么复杂

因为真实工程环境里的“读文件”，会立刻碰到很多边界问题：

• 文件太大
• 文件不是纯文本
• 路径需要展开和规范化
• 权限规则要生效
• 输出不能把 UI 撑爆

所以一个真正可用的 FileReadTool，必须同时处理内容、路径、权限、摘要和上下文。

读文件和写文件不是同一种风险等级

这在 Claude Code 的设计里很明显。

• FileReadTool 会标记 isReadOnly()
• 编辑类工具则会进入更严格的权限和 diff 流程

编辑链路的关键，不只是写回磁盘

真正重要的是“修改必须可解释”。
Claude Code 在文件编辑这件事上，明显更强调：

• 变更前后差异可展示
• 权限审批能看懂修改内容
• UI 能用 diff 呈现

从源码引用链也能看出来，围绕 FileEditTool / FileWriteTool 有专门的权限请求组件和 diff 组件。

为什么它同时保留 Edit 和 Write

这通常对应两种不同的语义：

• Edit：对已有内容做定向修改
• Write：新建或整体覆盖文件

这两种能力如果混在一起，会带来两个问题：

• 权限模型不清晰
• UI diff 和用户预期不稳定

把它们拆开，系统才更容易做精细控制。

这条链路和 QueryEngine 是怎么配合的

这个闭环说明：
文件工具不是独立功能，而是主循环里最常见的一类执行节点。

真实工程意义

研究 Claude Code 的文件链路，最大的价值不只是看它怎么改文件，而是理解一个结论：

真正可用的 AI 编程系统，必须把“文件操作”从普通脚本调用，升级成带语义、带权限、带 UI、带摘要的系统能力。

这也是为什么很多“玩具 AI 代码助手”很难走远。

小结

Claude Code 的文件链路，本质上是在做三件事：

• 把读取能力系统化
• 把修改能力可视化
• 把写回动作安全化

文件工具之所以重要，不是因为它们存在，而是因为它们被做成了主循环里稳定可靠的执行基础设施。