FileWriteTool：写入文件

FileWriteTool 是 Claude Code 中专门用于新建文件或完全覆盖现有文件的底层工具。它并不只是简单的内容重定向，而是深度集成了路径权限校验、文件状态管理、结构化差分（diff）与 Git 追踪机制，确保“全量写入”操作依然处于受控且可审计的工程链路中。

FileWriteTool 主要解决**“整文件写入”**问题，适用于两种典型场景：

• 新建一个文件：从零生成内容并创建对应路径的文件。
• 覆盖现有文件：用一整块新内容完全替换当前目标文件的原有数据。

如果说 FileEditTool 更像精准的手术刀，那么 FileWriteTool 就是“整块材料重新铺设”。Claude Code 在工程设计上明确将这两件事拆分给不同工具，而非全部交由底层 shell 执行，体现了职责分离的设计哲学。

tools/FileWriteTool/FileWriteTool.ts 中定义了严格的输入模式：

const inputSchema = z.strictObject({
  file_path: z.string().describe('The absolute path to the file to write'),
  content: z.string().describe('The content to write to the file'),
})

接口极其精简，仅包含两个核心字段：写到哪里 (file_path) 与 写什么内容 (content)。这明确传递了一个设计信号：Write 的单一职责就是完整写入，而非处理复杂的局部替换逻辑。

不同于简单的“覆盖即结束”，FileWriteTool 通过 outputSchema 返回了详尽的操作上下文：

type: z.enum(['create', 'update'])
structuredPatch: z.array(hunkSchema())
originalFile: z.string().nullable()
gitDiff: gitDiffSchema().optional()

这意味着 Write 并非静默执行，而是主动保留了以下关键审计信息：

• 操作类型：是创建 (create) 还是更新 (update)
• 原文件快照：覆盖前的完整内容 (originalFile)
• 结构化补丁：基于 hunks 的精细化差异 (structuredPatch)
• Git 视角变更：便于版本控制追踪的 diff 数据 (gitDiff)

一次 FileWriteTool 调用会经历清晰的工业级流程：

1. 模型决定新建或整文件覆盖
2. FileWriteTool 接收指令
3. 路径与权限检查
4. 确认目标文件状态
5. 写入完整内容
6. 生成 structuredPatch / gitDiff
7. 回注结果并进入验证阶段

和 Edit 一样，Write 也不是无脑执行。源码中内置了严格的文件新鲜度检查：

if (!readTimestamp || readTimestamp.isPartialView) {
  return {
    result: false,
    message: 'File has not been read yet. Read it first before writing to it.',
  }
}

这强调了 Claude Code 的核心安全原则：先读后写。对于已有文件，必须先获取最新时间戳，有效防止模型基于过期缓存覆盖他人（或后台进程）刚修改过的内容。

即使是全量写入，Claude Code 也拒绝将其视为“黑盒操作”。源码中明确导入了相关工具：

import { countLinesChanged, getPatchForDisplay } from '../../utils/diff.js'
import { fetchSingleFileGitDiff } from '../../utils/gitDiff.js'

写入后系统会自动完成三项工作：

• 统计改动行数：量化变更规模
• 生成可展示 Patch：提供人类可读的差异对比
• 关联 Git 变更视图：无缝对接仓库版本控制

这种设计让前端 UI 与下游模型能够精准理解此次写入的实际影响范围。

明确边界能显著提升开发体验：

• FileEditTool (Edit)：适用于局部修改已有内容（如修改变量名、调整单个函数逻辑）。
• FileWriteTool (Write)：适用于创建新文件或整块重写现有内容。

如果模型只是想改一个函数，Write 往往会显得过重；但如果是生成新配置文件、新组件骨架、新文档，Write 就非常合适。Claude Code 更强调职责清晰，而不是“越万能越好”。

不是。它接入了权限管控、文件时序、Diff 计算和 Git 视图体系。

不对。Claude Code 推崇按操作粒度匹配工具。局部动刀用 Edit，整体重构用 Write。

不完全对。它也能更新已有文件，但核心场景是“整块重写”，而不是针对碎片化内容的小修小补。

• FileWriteTool 专司全量新建与覆盖，通过极简输入实现清晰职责，与 FileEditTool 的局部修改形成互补。
• 输出即审计：不仅返回操作结果，还附带原始快照、结构化 Patch 与 Git diff 数据，确保写入过程完全可追溯。
• 先读后写铁律：内置时序校验拦截未读取文件的覆盖请求，从根本上杜绝基于过期状态的冲突覆盖。
• 全链路工程化：拒绝降级为裸 shell 命令，而是无缝接入权限管控、Diff 计算与 Git 追踪，保持 Claude Code 整体架构的“受控可审计”特性。