FileWriteTool：文件写入

在 Claude Code 的 53 个内置工具中，文件操作 trio —— FileReadTool、FileEditTool、FileWriteTool —— 构成了 Agent 与本地文件系统交互的核心通道。如果说 FileReadTool 是感知器、FileEditTool 是手术刀，那么 FileWriteTool 就是重锤：它不追求精确切除，而是直接以全新内容覆盖整个文件。这种"全量替换"的语义决定了它在 Agent 工作流中的特殊定位 —— 既强大又危险，需要严格的边界约束。

本文基于 Claude Code v2.1.88 的源码，深入解析 FileWriteTool 的架构设计、写入策略、路径处理、覆盖保护机制，以及它与 FileEditTool 之间的分工边界。

一、FileWriteTool 的定位与分工边界

1.1 何时写、何时改

FileWriteTool 与 FileEditTool 看似都是"往文件里写内容"，但二者的使用场景有着清晰的分工。源码中的工具描述明确界定了这一边界（src/tools/FileWriteTool/prompt.ts，第 1–21 行）：

export function getWriteToolDescription(): string {
  return `Writes a file to the local filesystem.

Usage:
- This tool will overwrite the existing file if there is one at the provided path.${getPreReadInstruction()}
- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`
}

从这段描述可以提炼出三条核心规则：

1. 创建新文件 —— 这是 FileWriteTool 的首要职责。当 Agent 需要生成一个全新的配置文件、测试文件或模块时，FileWriteTool 是最佳选择。
2. 完全重写 —— 当文件需要大规模重构，修改内容超过原有内容的 50% 甚至更多时，使用 FileEditTool 逐段替换反而效率低下，此时应使用 FileWriteTool 进行整体覆盖。
3. 编辑已有文件用 Edit —— 对于局部修改（如修改函数签名、替换变量名、修复 bug），FileEditTool 只传输 diff，能显著减少 token 消耗和出错概率。

flowchart TD
    A[需要写入文件] --> B{文件是否存在?}
    B -->|不存在| C[使用 FileWriteTool
创建新文件]
    B -->|存在| D{修改范围?}
    D -->|局部修改 / 小范围调整| E[使用 FileEditTool
发送 diff]
    D -->|完全重写 / 大规模重构| F[使用 FileWriteTool
覆盖写入]

1.2 输入输出 Schema

FileWriteTool 的接口极其精简，只有两个输入参数（src/tools/FileWriteTool/FileWriteTool.ts，第 32–42 行）：

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

file_path 必须是绝对路径，这是与 FileEditTool 保持一致的设计：避免相对路径因 cwd 变化导致的歧义。content 则接收模型生成的完整文件内容，包含换行符和缩进。

输出 Schema 则包含了更丰富的元信息（src/tools/FileWriteTool/FileWriteTool.ts，第 44–63 行）：

const outputSchema = lazySchema(() =>
  z.object({
    type: z
      .enum(['create', 'update'])
      .describe(
        'Whether a new file was created or an existing file was updated',
      ),
    filePath: z.string().describe('The path to the file that was written'),
    content: z.string().describe('The content that was written to the file'),
    structuredPatch: z
      .array(hunkSchema())
      .describe('Diff patch showing the changes'),
    originalFile: z
      .string()
      .nullable()
      .describe(
        'The original file content before the write (null for new files)',
      ),
    gitDiff: gitDiffSchema().optional(),
  }),
)

注意 type 字段会区分 create（新建）和 update（覆盖），这一信息不仅用于 UI 渲染，还决定了 mapToolResultToToolResultBlockParam 中返回给模型的确认消息内容。

二、路径处理：从输入到绝对路径

2.1 expandPath：路径解析的核心

用户输入的 file_path 虽然是绝对路径要求，但实际场景中可能出现 ~（主目录）、POSIX 路径在 Windows 上运行、甚至包含空字节等边缘情况。expandPath 函数（src/utils/path.ts，第 27–88 行）负责将所有输入统一归一化为平台原生的绝对路径：

export function expandPath(path: string, baseDir?: string): string {
  const actualBaseDir = baseDir ?? getCwd() ?? getFsImplementation().cwd()

  if (typeof path !== 'string') {
    throw new TypeError(`Path must be a string, received ${typeof path}`)
  }

  if (path.includes('\0') || actualBaseDir.includes('\0')) {
    throw new Error('Path contains null bytes')
  }

  const trimmedPath = path.trim()
  if (!trimmedPath) {
    return normalize(actualBaseDir).normalize('NFC')
  }

  if (trimmedPath === '~') {
    return homedir().normalize('NFC')
  }

  if (trimmedPath.startsWith('~/')) {
    return join(homedir(), trimmedPath.slice(2)).normalize('NFC')
  }

  let processedPath = trimmedPath
  if (getPlatform() === 'windows' && trimmedPath.match(/^\/[a-z]\//i)) {
    processedPath = posixPathToWindowsPath(trimmedPath)
  }

  if (isAbsolute(processedPath)) {
    return normalize(processedPath).normalize('NFC')
  }

  return resolve(actualBaseDir, processedPath).normalize('NFC')
}

这个函数的几个安全细节值得注意：

• 空字节检测：\0 是 C 风格字符串的终止符，允许空字节进入文件路径可能引发底层系统的路径截断或意外行为。
• NFC 规范化：.normalize('NFC') 处理 Unicode 组合字符，避免 é（U+0065 U+0301）和 é（U+00E9）在路径比较时被视为不同路径。
• Windows POSIX 路径转换：识别 /c/Users/... 这类来自 WSL 或 Git Bash 的路径格式并自动转换。

2.2 目录自动创建

FileWriteTool 在写入前会自动确保父目录存在（src/tools/FileWriteTool/FileWriteTool.ts，第 162 行）：

await getFsImplementation().mkdir(dir)

这里调用的是 FsOperations 接口中定义的 mkdir，在 NodeFsOperations 实现中对应 fs.promises.mkdir(dirPath, { recursive: true })（src/utils/fsOperations.ts，第 264–275 行）。recursive: true 确保即使多级目录缺失也能一次性创建，无需手动逐级 mkdir。

有趣的是，源码中的注释特意指出这个目录创建操作必须放在原子性临界区之外：

Must stay OUTSIDE the critical section below (a yield between the staleness check and writeTextContent lets concurrent edits interleave), and BEFORE the write (lazy-mkdir-on-ENOENT would fire a spurious tengu_atomic_write_error inside writeFileSyncAndFlush_DEPRECATED before ENOENT propagates back).

这意味着 mkdir 是一个可能挂起事件循环的异步操作，如果在"检查文件是否被修改"和"实际写入"之间执行，可能让第三方编辑器趁虚而入修改文件内容。

三、写入策略：原子写入与降级保障

3.1 原子写入的实现

Claude Code 的文件写入并非直接 fs.writeFileSync(path, content)，而是采用了先写临时文件、再原子重命名的策略。这一逻辑封装在 writeFileSyncAndFlush_DEPRECATED 中（src/utils/file.ts，第 290–373 行）：

export function writeFileSyncAndFlush_DEPRECATED(
  filePath: string,
  content: string,
  options: { encoding: BufferEncoding; mode?: number } = { encoding: 'utf-8' },
): void {
  const fs = getFsImplementation()

  let targetPath = filePath
  try {
    const linkTarget = fs.readlinkSync(filePath)
    targetPath = isAbsolute(linkTarget)
      ? linkTarget
      : resolve(dirname(filePath), linkTarget)
  } catch {
    // ENOENT or EINVAL — keep targetPath = filePath
  }

  const tempPath = `${targetPath}.tmp.${process.pid}.${Date.now()}`

  let targetMode: number | undefined
  let targetExists = false
  try {
    targetMode = fs.statSync(targetPath).mode
    targetExists = true
  } catch (e) {
    if (!isENOENT(e)) throw e
    if (options.mode !== undefined) {
      targetMode = options.mode
    }
  }

  try {
    const writeOptions = {
      encoding: options.encoding,
      flush: true,
    }
    if (!targetExists && options.mode !== undefined) {
      writeOptions.mode = options.mode
    }

    fsWriteFileSync(tempPath, content, writeOptions)

    if (targetExists && targetMode !== undefined) {
      chmodSync(tempPath, targetMode)
    }

    fs.renameSync(tempPath, targetPath)
  } catch (atomicError) {
    // Clean up temp file
    try {
      fs.unlinkSync(tempPath)
    } catch { /* ignore */ }

    // Fallback to non-atomic write
    fsWriteFileSync(targetPath, content, { encoding: options.encoding, flush: true })
  }
}

这段代码包含了多层工程考量：

符号链接透写：通过 readlinkSync 检测目标路径是否为符号链接。如果是，则将内容写入链接指向的真实路径，同时保留符号链接本身。这对开发工作流中的配置文件链接（如 ~/.bashrc 链接到 dotfiles 仓库）至关重要。

临时文件命名：${targetPath}.tmp.${process.pid}.${Date.now()} 同时包含进程 ID 和时间戳，避免多进程并发时的文件名冲突。

权限保留：对于已存在的文件，先 statSync 获取原文件的 mode（权限位），写入临时文件后通过 chmodSync 恢复，确保文件权限不因覆盖而意外变更。

降级回退：原子写入在极少数场景下可能失败（如跨文件系统的重命名不支持原子性），此时捕获异常、清理临时文件，降级为直接覆盖写入。

3.2 换行符处理

FileWriteTool 在写入时不会盲目保留旧文件的换行符风格，而是遵循模型显式传入的内容（src/tools/FileWriteTool/FileWriteTool.ts，第 213–215 行）：

// 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')

这里的 'LF' 参数看似矛盾 —— 实际上 writeTextContent 的逻辑是：如果传入 'CRLF'，会将内容中的 \n 统一替换为 \r\n；传入 'LF' 则基本保持原样（仅做 \r\n 到 \n 的规范化避免双换行）。对于 FileWriteTool，源码明确注释：模型发送的换行符就是它的意图，不要猜测和转换。

这与早期版本形成对比 —— 过去 Claude Code 会尝试采样仓库内其他文件的换行符风格来推断新文件的换行符，但这在写入 bash 脚本到 Linux 时引发了 \r 污染问题。

四、覆盖保护：mtime 检查与读后再写

4.1 read-before-write 强制约束

FileWriteTool 有一个严格的前置条件：如果目标文件已存在，必须先通过 FileReadTool 读取过该文件（src/tools/FileWriteTool/FileWriteTool.ts，第 128–137 行）：

const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp || readTimestamp.isPartialView) {
  return {
    result: false,
    message:
      'File has not been read yet. Read it first before writing to it.',
    errorCode: 2,
  }
}

readFileState 是一个全局状态映射，记录了 Agent 在本轮会话中读取过的文件路径、读取时间戳、内容以及是否为部分视图（offset/limit 限定范围）。如果文件从未被读取，或者上次读取只看了前 50 行（isPartialView: true），写入请求会被直接拒绝。

这一设计防止了模型在"不知道文件当前内容"的情况下盲目覆盖，避免数据丢失。

4.2 mtime staleness 检测

即使文件被读取过，在读取和写入之间仍可能有外部进程修改文件（例如用户在其他编辑器中手动编辑、linter 自动格式化、构建工具生成代码）。Claude Code 通过**修改时间戳（mtime）**检测这种并发修改（src/tools/FileWriteTool/FileWriteTool.ts，第 139–149 行）：

const lastWriteTime = Math.floor(fileMtimeMs)
if (lastWriteTime > readTimestamp.timestamp) {
  return {
    result: false,
    message:
      'File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.',
    errorCode: 3,
  }
}

Math.floor 的使用并非随意 —— 不同文件系统的时间戳精度不同（ext4 支持纳秒级，FAT32 仅支持 2 秒级），向下取整能消除亚毫秒精度差异导致的假阳性比较失败。

4.3 写入时刻的内容二次确认

在 validateInput 阶段通过 mtime 检查之后，call 方法还会在执行写入前再次读取磁盘上的当前内容，进行更精确的内容比对（src/tools/FileWriteTool/FileWriteTool.ts，第 181–200 行）：

let meta: ReturnType<typeof readFileSyncWithMetadata> | null
try {
  meta = readFileSyncWithMetadata(fullFilePath)
} catch (e) {
  if (isENOENT(e)) {
    meta = null
  } else {
    throw e
  }
}

if (meta !== null) {
  const lastWriteTime = getFileModificationTime(fullFilePath)
  const lastRead = readFileState.get(fullFilePath)
  if (!lastRead || lastWriteTime > lastRead.timestamp) {
    const isFullRead =
      lastRead &&
      lastRead.offset === undefined &&
      lastRead.limit === undefined
    if (!isFullRead || meta.content !== lastRead.content) {
      throw new Error(FILE_UNEXPECTEDLY_MODIFIED_ERROR)
    }
  }
}

这里有一个精妙的 fallback 机制：如果 mtime 显示文件被修改了，但上一次是完整读取（非部分视图），且磁盘上的内容与 readFileState 中缓存的内容完全一致，则视为"无实质变化"（可能是 Windows 上的云同步工具或杀毒软件 touch 了文件），允许继续写入。

FILE_UNEXPECTEDLY_MODIFIED_ERROR 的常量定义为（src/tools/FileEditTool/constants.ts，第 7–8 行）：

export const FILE_UNEXPECTEDLY_MODIFIED_ERROR =
  'File has been unexpectedly modified. Read it again before attempting to write it.'

4.4 危险文件保护

在权限层面，filesystem.ts 中维护了一份危险文件和目录黑名单（src/utils/permissions/filesystem.ts，第 34–55 行）：

export const DANGEROUS_FILES = [
  '.gitconfig',
  '.gitmodules',
  '.bashrc',
  '.bash_profile',
  '.zshrc',
  '.zprofile',
  '.profile',
  '.ripgreprc',
  '.mcp.json',
  '.claude.json',
] as const

export const DANGEROUS_DIRECTORIES = [
  '.git',
  '.vscode',
  '.idea',
  '.claude',
] as const

这些文件通常包含可执行配置或敏感认证信息。Claude Code 的权限系统会对写入这些路径的操作施加更严格的确认策略，防止 Agent 在未经用户明确同意的情况下修改 Shell 配置或注入恶意代码。

五、与相邻工具的协作关系

flowchart LR
    subgraph "感知层"
        A[GlobTool
确认路径存在]
        B[FileReadTool
读取验证]
    end
    subgraph "执行层"
        C[FileWriteTool
创建/覆盖]
        D[FileEditTool
局部修改]
    end
    subgraph "校验层"
        E[LSP Manager
诊断刷新]
        F[Git Diff
变更追踪]
    end

    A -->|发现文件| B
    B -->|完整读取| C
    B -->|定位行号| D
    C -->|通知变更| E
    C -->|生成 patch| F
    D -->|通知变更| E
    D -->|生成 patch| F

5.1 FileReadTool：前置依赖

如前文所述，FileWriteTool 强制要求已读取文件。readFileState 是连接二者的桥梁 —— FileReadTool 在读取成功后将路径、内容、时间戳存入状态；FileWriteTool 在执行前查询该状态。

5.2 FileEditTool：互补替代

当文件已存在且需要局部修改时，FileEditTool 是更优选择。它通过 old_string / new_string 的精确替换实现编辑，只传输变更部分，token 效率远高于 FileWriteTool 传输整份文件内容。但 FileEditTool 对字符串匹配有严格要求，一旦模型生成的 old_string 与磁盘内容存在细微差异（如多余的空格），编辑就会失败。此时回退到 FileWriteTool 做全量覆盖是一种常见的自纠正策略。

5.3 GlobTool：路径预检

在写入新文件前，Agent 有时会先用 GlobTool 检查目标路径是否已存在同名文件（尤其是不同扩展名的情况）。file.ts 中还专门提供了 findSimilarFile 函数（src/utils/file.ts，第 139–166 行），用于在同一个目录下查找同名不同扩展名的文件，避免重复创建。

5.4 LSP 联动与 VSCode 通知

写入完成后，FileWriteTool 会主动通知外部系统（src/tools/FileWriteTool/FileWriteTool.ts，第 218–236 行）：

const lspManager = getLspServerManager()
if (lspManager) {
  clearDeliveredDiagnosticsForFile(`file://${fullFilePath}`)
  lspManager.changeFile(fullFilePath, content).catch((err: Error) => {
    logForDebugging(`LSP: Failed to notify server of file change...`)
    logError(err)
  })
  lspManager.saveFile(fullFilePath).catch((err: Error) => {
    logForDebugging(`LSP: Failed to notify server of file save...`)
    logError(err)
  })
}

notifyVscodeFileUpdated(fullFilePath, oldContent, content)

LSP（Language Server Protocol）通知确保 TypeScript、Python 等语言服务器能及时获取文件变更，重新计算诊断信息（错误、警告）。notifyVscodeFileUpdated 则支持 VSCode 的 diff 视图实时展示 Agent 的修改。这种"写后即广播"的设计让 Claude Code 与主流 IDE 的集成体验更加流畅。

六、权限与安全纵深

6.1 路径解析安全检查

fsOperations.ts 中的 getPathsForPermissionCheck（src/utils/fsOperations.ts，第 117–218 行）实现了符号链接链的完整追踪：

export function getPathsForPermissionCheck(inputPath: string): string[] {
  let path = inputPath
  if (path === '~') {
    path = homedir().normalize('NFC')
  } else if (path.startsWith('~/')) {
    path = nodePath.join(homedir().normalize('NFC'), path.slice(2))
  }

  const pathSet = new Set<string>()
  pathSet.add(path)

  // Follow the symlink chain, collecting ALL intermediate targets
  try {
    let currentPath = path
    const visited = new Set<string>()
    const maxDepth = 40

    for (let depth = 0; depth < maxDepth; depth++) {
      if (visited.has(currentPath)) break
      visited.add(currentPath)

      if (!fsImpl.existsSync(currentPath)) {
        const resolved = resolveDeepestExistingAncestorSync(fsImpl, path)
        if (resolved !== undefined) {
          pathSet.add(resolved)
        }
        break
      }

      const stats = fsImpl.lstatSync(currentPath)
      if (!stats.isSymbolicLink()) break

      const target = fsImpl.readlinkSync(currentPath)
      const absoluteTarget = nodePath.isAbsolute(target)
        ? target
        : nodePath.resolve(nodePath.dirname(currentPath), target)

      pathSet.add(absoluteTarget)
      currentPath = absoluteTarget
    }
  } catch { /* continue with what we have */ }

  return Array.from(pathSet)
}

这段代码解决了符号链接可能带来的目录遍历逃逸问题。例如，如果工作目录中有一个 ./data -> /etc/cron.d/ 的符号链接，Agent 写入 ./data/myjob 实际上会写到系统级的 cron 目录。通过追踪 symlink chain 并将所有中间目标和最终 resolved 路径都加入权限检查集合，Claude Code 的权限规则能够拦截这种逃逸攻击。

6.2 UNC 路径阻断

在 Windows 平台上，fs.existsSync('\\malicious-server\share') 会触发 SMB 认证，可能导致 NTLM 凭据泄露。源码在多处对 UNC 路径进行提前阻断（src/utils/fsOperations.ts，第 75–78 行）：

if (filePath.startsWith('//') || filePath.startsWith('\\')) {
  return { resolvedPath: filePath, isSymlink: false, isCanonical: false }
}

七、总结

FileWriteTool 的设计体现了 Claude Code 在"能力"与"安全"之间的精细平衡：

维度	设计要点
分工边界	新文件/全量重写用 Write，局部修改用 Edit
路径处理	expandPath 统一归一化，支持 ~、Windows POSIX 路径、NFC Unicode
目录创建	mkdir recursive 自动创建父目录，且刻意置于原子区外
原子写入	临时文件 + renameSync，失败降级直接写入
权限保留	statSync 读取旧文件 mode，chmodSync 恢复权限
symlink 透写	检测并跟随符号链接，保留链接本身
覆盖保护	强制 read-before-write + mtime staleness 检测 + 内容二次确认
权限安全	symlink chain 追踪、UNC 路径阻断、危险文件黑名单
生态联动	LSP didChange/didSave 通知、VSCode diff 更新

从工程角度看，FileWriteTool 的代码量不大（核心逻辑约 100 行），但每一行都承载着生产环境中的血泪教训：Windows 云同步工具 touch 文件引发的误报、跨文件系统 rename 的原子性缺失、Bash 脚本的 CRLF 污染、符号链接的目录遍历攻击……这些细节的堆叠，才使得 Agent 在真实开发场景中既能高效协作，又不会成为数据安全的隐患。