FileEditTool：文件编辑

在 Claude Code 的工具体系中，FileEditTool 是最核心、也最复杂的工具之一。如果说 ReadTool 和 LSPTool 负责"看见"代码，FileEditTool 则负责"改变"代码。它需要在不破坏文件完整性的前提下，精准地完成文本替换、Diff 计算、冲突检测和用户确认等一系列操作。

本文将深入解析 FileEditTool 的完整架构，从输入参数的定义到编辑策略的实现，从 Diff 渲染到并发冲突处理，全面揭示这个关键工具的工程细节。

一、FileEditTool 整体架构

1.1 文件位置与模块划分

FileEditTool 的源码位于 src/tools/FileEditTool/ 目录下，采用高度模块化的设计：

src/tools/FileEditTool/
├── FileEditTool.ts    # 主工具实现：buildTool 配置、权限检查、调用逻辑
├── types.ts           # Zod Schema 定义：输入输出类型、Diff 结构
├── utils.ts           # 编辑工具函数：引号规范化、模糊匹配、Patch 生成
├── UI.tsx             # React 组件：工具消息渲染、拒绝提示、Diff 展示
├── constants.ts       # 常量定义：工具名称、权限模式、错误信息
└── prompt.ts          # 工具描述 Prompt（供模型调用时参考）

对应的 Diff 展示组件位于 src/components/FileEditToolDiff.tsx，该文件约 21KB，是整个编辑流程中用户交互的关键界面。

1.2 Tool 接口定义

FileEditTool 通过 buildTool 工厂函数注册到 Claude Code 的工具系统中（src/tools/FileEditTool/FileEditTool.ts，第 68–120 行）：

export const FileEditTool = buildTool({
  name: FILE_EDIT_TOOL_NAME,  // 'Edit'
  searchHint: 'modify file contents in place',
  maxResultSizeChars: 100_000,
  strict: true,
  async description() {
    return 'A tool for editing files'
  },
  async prompt() {
    return getEditToolDescription()
  },
  userFacingName,
  getToolUseSummary,
  getActivityDescription(input) {
    const summary = getToolUseSummary(input)
    return summary ? `Editing ${summary}` : 'Editing file'
  },
  get inputSchema() {
    return inputSchema()
  },
  get outputSchema() {
    return outputSchema()
  },
  // ... 更多生命周期钩子
})

buildTool 来自 src/Tool.ts，它为每个工具定义了统一的生命周期：

flowchart TD
    A[模型生成 Tool Use] --> B[validateInput]
    B --> C{验证通过?}
    C -->|否| D[返回错误/请求确认]
    C -->|是| E[checkPermissions]
    E --> F{权限允许?}
    F -->|否| G[Permission Request]
    F -->|是| H[call 执行编辑]
    H --> I[生成 Output]
    I --> J[UI 渲染结果]
    J --> K[用户确认/拒绝]

1.3 输入参数 Schema

FileEditTool 的输入参数通过 Zod 严格定义（src/tools/FileEditTool/types.ts，第 8–22 行）：

const inputSchema = lazySchema(() =>
  z.strictObject({
    file_path: z.string().describe('The absolute path to the file to modify'),
    old_string: z.string().describe('The text to replace'),
    new_string: z
      .string()
      .describe(
        'The text to replace it with (must be different from old_string)',
      ),
    replace_all: semanticBoolean(
      z.boolean().default(false).optional(),
    ).describe('Replace all occurrences of old_string (default false)'),
  }),
)

四个核心参数的含义非常清晰：

参数	类型	说明
file_path	string	待编辑文件的绝对路径
old_string	string	要被替换的原文本
new_string	string	用于替换的新文本
replace_all	boolean	是否替换所有匹配项，默认 false

这里的 semanticBoolean 是一个预处理函数，允许模型以更自然的方式表达布尔值（如 "yes"、"no"、"true" 等），提升了模型的调用成功率。

输出 Schema 则包含了编辑前后的完整上下文（src/tools/FileEditTool/types.ts，第 45–62 行）：

const outputSchema = lazySchema(() =>
  z.object({
    filePath: z.string(),
    oldString: z.string(),
    newString: z.string(),
    originalFile: z.string(),
    structuredPatch: z.array(hunkSchema()),
    userModified: z.boolean(),
    replaceAll: z.boolean(),
    gitDiff: gitDiffSchema().optional(),
  }),
)

structuredPatch 字段存储了结构化的 Diff Patch，gitDiff 则提供了与 Git 兼容的 diff 格式，便于与版本控制系统集成。

二、结构化编辑策略

FileEditTool 的核心编辑策略基于纯字符串匹配，而非正则表达式。这一设计选择看似简单，实则深思熟虑——正则表达式虽然强大，但容易出现意料之外的匹配行为，而字符串匹配的可预测性更高，更适合由 LLM 生成的编辑指令。

2.1 基于字符串匹配的编辑流程

编辑操作的核心逻辑在 getPatchForDisplay 函数中实现（src/utils/diff.ts，第 95–137 行）：

export function getPatchForDisplay({
  filePath,
  fileContents,
  edits,
  ignoreWhitespace = false,
}: {
  filePath: string
  fileContents: string
  edits: FileEdit[]
  ignoreWhitespace?: boolean
}): StructuredPatchHunk[] {
  const preparedFileContents = escapeForDiff(
    convertLeadingTabsToSpaces(fileContents)
  )
  const result = structuredPatch(
    filePath,
    filePath,
    preparedFileContents,
    edits.reduce((p, edit) => {
      const { old_string, new_string } = edit
      const replace_all = 'replace_all' in edit ? edit.replace_all : false
      const escapedOldString = escapeForDiff(
        convertLeadingTabsToSpaces(old_string)
      )
      const escapedNewString = escapeForDiff(
        convertLeadingTabsToSpaces(new_string)
      )

      if (replace_all) {
        return p.replaceAll(escapedOldString, () => escapedNewString)
      } else {
        return p.replace(escapedOldString, () => escapedNewString)
      }
    }, preparedFileContents),
    undefined,
    undefined,
    {
      context: CONTEXT_LINES,
      ignoreWhitespace,
      timeout: DIFF_TIMEOUT_MS,
    },
  )
  // ... 返回处理后的 hunks
}

编辑流程遵循以下步骤：

1. 预处理：将文件内容和编辑字符串中的制表符转换为空格（convertLeadingTabsToSpaces），确保 Diff 显示的一致性。
2. 转义处理：对 & 和 $ 字符进行转义（escapeForDiff），因为 diff 库在处理这些字符时存在已知问题。
3. 字符串替换：根据 replace_all 标志，使用 String.prototype.replace 或 String.prototype.replaceAll 执行替换。
4. Diff 计算：调用 structuredPatch 计算变更前后的结构化 Patch。
5. 反转义：将转义字符恢复为原始形式。

2.2 多位置匹配处理

当 replace_all 为 true 时，工具会替换文件中所有匹配的 old_string。这为批量重命名、统一格式调整等场景提供了便利。但需要注意的是，这种全局替换具有一定的风险——如果 old_string 过于通用（如 "a"、" "），可能会导致意料之外的修改。

对于单次替换（replace_all: false），系统仅替换第一个匹配项。这种保守策略确保了编辑的可预测性，降低了"误伤"概率。

2.3 模糊匹配：引号规范化

实际使用中，LLM 生成的编辑指令常常包含直引号（' 和 "），而目标文件中可能使用了弯引号（'、'、"、"）。FileEditTool 通过 findActualString 函数实现了智能的引号规范化匹配（src/tools/FileEditTool/utils.ts，第 48–65 行）：

export function findActualString(
  fileContent: string,
  searchString: string,
): string | null {
  // 首先尝试精确匹配
  if (fileContent.includes(searchString)) {
    return searchString
  }

  // 尝试规范化引号后的匹配
  const normalizedSearch = normalizeQuotes(searchString)
  const normalizedFile = normalizeQuotes(fileContent)

  const searchIndex = normalizedFile.indexOf(normalizedSearch)
  if (searchIndex !== -1) {
    return fileContent.substring(searchIndex, searchIndex + searchString.length)
  }

  return null
}

normalizeQuotes 函数（src/tools/FileEditTool/utils.ts，第 30–39 行）将四种弯引号统一转换为直引号：

export function normalizeQuotes(str: string): string {
  return str
    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"')
}

更有趣的是 preserveQuoteStyle 函数（src/tools/FileEditTool/utils.ts，第 73–94 行）。当系统检测到文件使用了弯引号，而模型提供了直引号时，它会自动将替换文本中的引号转换为与文件风格一致的弯引号：

export function preserveQuoteStyle(
  oldString: string,
  actualOldString: string,
  newString: string,
): string {
  if (oldString === actualOldString) {
    return newString  // 未发生规范化，无需处理
  }

  const hasDoubleQuotes =
    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE)
  const hasSingleQuotes =
    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE)

  let result = newString
  if (hasDoubleQuotes) result = applyCurlyDoubleQuotes(result)
  if (hasSingleQuotes) result = applyCurlySingleQuotes(result)
  return result
}

这里使用了一个简单的启发式规则判断引号的"开闭"状态：如果引号前是空白字符、字符串开头或开括号，则视为 opening quote；否则视为 closing quote。对于缩写形式（如 don't），则使用右单弯引号作为撇号。

这种设计体现了 Claude Code 对细节的关注——它不仅要求编辑正确，还追求编辑后的代码在风格上与原始文件保持一致。

三、Diff 生成与展示

Diff 是 FileEditTool 与用户交互的核心媒介。用户在确认编辑前，需要清晰地看到变更内容。Claude Code 为此构建了一套完整的 Diff 计算和渲染体系。

3.1 Diff 数据流架构

flowchart LR
    A[FileEditTool.call] --> B[applyEdits]
    B --> C[计算 structuredPatch]
    C --> D[FileEditToolDiff 组件]
    D --> E[loadDiffData]
    E --> F{文件大小}
    F -->|小文件| G[全文件 Diff]
    F -->|大文件| H[上下文扫描]
    H --> I[分段 Diff + 行号调整]
    G --> J[StructuredDiffList 渲染]
    I --> J

3.2 Diff 计算的核心逻辑

Diff 计算在 src/utils/diff.ts 中实现。getPatchForDisplay 函数使用 diff 库的 structuredPatch 方法生成标准 Unix Diff 格式的结构化表示。一个关键的工程细节是字符转义处理：

const AMPERSAND_TOKEN = '<<:AMPERSAND_TOKEN:>>'
const DOLLAR_TOKEN = '<<:DOLLAR_TOKEN:>>'

function escapeForDiff(s: string): string {
  return s.replaceAll('&', AMPERSAND_TOKEN).replaceAll('$', DOLLAR_TOKEN)
}

function unescapeFromDiff(s: string): string {
  return s.replaceAll(AMPERSAND_TOKEN, '&').replaceAll(DOLLAR_TOKEN, '$')
}

这种转义机制解决了底层 diff 库对 & 和 $ 字符的解析问题，确保了包含这些特殊字符的代码（如 HTML 实体、Shell 变量、模板字符串）能够正确生成 Diff。

3.3 大文件优化：上下文扫描

对于大型文件，全量读取和 Diff 计算可能消耗过多资源。FileEditToolDiff 组件实现了智能的上下文扫描机制（src/components/FileEditToolDiff.tsx，第 80–110 行）：

async function loadDiffData(file_path: string, edits: FileEdit[]): Promise<DiffData> {
  const valid = edits.filter(e => e.old_string != null && e.new_string != null)
  const single = valid.length === 1 ? valid[0]! : undefined

  // 当 old_string 超过 CHUNK_SIZE 时，直接对输入进行 Diff，跳过文件读取
  if (single && single.old_string.length >= CHUNK_SIZE) {
    return diffToolInputsOnly(file_path, [single])
  }

  try {
    const handle = await openForScan(file_path)
    if (handle === null) return diffToolInputsOnly(file_path, valid)

    // 多编辑或空 old_string 需要完整文件内容进行顺序替换
    if (!single || single.old_string === '') {
      const file = await readCapped(handle)
      // ... 全文件 Diff
    }

    // 扫描 old_string 所在上下文区域
    const ctx = await scanForContext(handle, single.old_string, CONTEXT_LINES)
    if (ctx.truncated || ctx.content === '') {
      return diffToolInputsOnly(file_path, [single])
    }
    // 基于上下文切片生成 Diff，并调整行号
    const normalized = normalizeEdit(ctx.content, single)
    const hunks = getPatchForDisplay({...})
    return {
      patch: adjustHunkLineNumbers(hunks, ctx.lineOffset - 1),
      // ...
    }
  }
}

这里有几个关键优化点：

• 分块阈值（CHUNK_SIZE）：当 old_string 超过阈值时，认为编辑范围本身就很大，直接对工具输入进行 Diff，避免额外的文件 I/O。
• 上下文扫描（scanForContext）：对于常规编辑，只读取 old_string 所在位置的前后几行上下文，而非整个文件。
• 行号调整（adjustHunkLineNumbers）：由于 Diff 是基于文件切片计算的，需要将 Patch 中的行号偏移调整为文件绝对行号（src/utils/diff.ts，第 18–28 行）：

export function adjustHunkLineNumbers(
  hunks: StructuredPatchHunk[],
  offset: number,
): StructuredPatchHunk[] {
  if (offset === 0) return hunks
  return hunks.map(h => ({
    ...h,
    oldStart: h.oldStart + offset,
    newStart: h.newStart + offset,
  }))
}

3.4 终端中的 Diff 渲染

FileEditToolDiff 组件（src/components/FileEditToolDiff.tsx）是一个 React 组件，使用 Ink 框架在终端中渲染 Diff。它利用 React 18 的 Suspense 和 use Hook 实现了异步 Diff 数据的加载：

export function FileEditToolDiff(props) {
  // ... React Compiler memoization
  const [dataPromise] = useState(() => loadDiffData(props.file_path, props.edits))
  return (
    <Suspense fallback={<DiffFrame placeholder={true} />}>
      <DiffBody promise={dataPromise} file_path={props.file_path} />
    </Suspense>
  )
}

StructuredDiffList 组件负责最终的终端渲染，支持：

• 语法高亮：根据文件扩展名选择对应的高亮器
• 行号显示：原始行号和修改后行号并排展示
• 增删标记：+ 和 - 前缀配合颜色区分
• 折叠未变更区域：仅展示变更点周围的上下文行

3.5 用户确认流程

Diff 展示的最终目的是让用户在应用变更前进行确认。Claude Code 提供了 /accept 和 /reject 等命令来控制编辑的应用。在用户拒绝编辑时，系统会渲染拒绝提示（renderToolUseRejectedMessage），展示如果接受将会发生什么变更：

export function renderToolUseRejectedMessage(input, options) {
  const isNewFile = oldString === ''
  if (isNewFile) {
    return <FileEditToolUseRejectedMessage
      file_path={filePath}
      operation="write"
      content={newString}
      firstLine={firstLineOf(newString)}
      verbose={verbose}
    />
  }
  return <EditRejectionDiff
    filePath={filePath}
    oldString={oldString}
    newString={newString}
    replaceAll={replaceAll}
    style={style}
    verbose={verbose}
  />
}

这种"即使拒绝也要展示 Diff"的设计，帮助用户理解决策的后果，提升了交互的透明度。

四、冲突处理与并发控制

文件编辑的最大风险之一是并发修改。当 Claude Code 正在处理一个编辑请求时，外部程序（如用户的 IDE、Git 操作、构建工具）可能同时修改了同一个文件。如果系统盲目应用编辑，极有可能破坏文件内容。

4.1 文件修改时间戳检测

FileEditTool 在 validateInput 阶段实现了严格的并发检测（src/tools/FileEditTool/FileEditTool.ts，第 220–260 行）：

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

if (readTimestamp) {
  const lastWriteTime = getFileModificationTime(fullFilePath)
  if (lastWriteTime > readTimestamp.timestamp) {
    // 时间戳显示文件被修改，但在 Windows 上时间戳变化不一定意味着内容变化
    const isFullRead =
      readTimestamp.offset === undefined &&
      readTimestamp.limit === undefined
    if (isFullRead && fileContent === readTimestamp.content) {
      // 内容未变，安全继续
    } else {
      return {
        result: false,
        behavior: 'ask',
        message: FILE_UNEXPECTEDLY_MODIFIED_ERROR,
        errorCode: 7,
      }
    }
  }
}

这里采用了双重验证策略：

1. 时间戳比对：记录文件读取时的 mtime，编辑前再次检查。如果时间戳更新，说明文件可能被外部修改。
2. 内容比对（Windows 兜底）：Windows 系统下，云同步、杀毒软件等操作可能导致时间戳变化而内容不变。对于完整读取的文件，系统会逐字节比对内容，避免误报。

4.2 必须先读后写的强制约束

FileEditTool 强制要求文件必须先被 ReadTool 读取，才能进行编辑。这是通过 readFileState 映射实现的：

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

这一约束确保了：

• 模型在编辑前已经"看到"了文件的最新内容
• old_string 是基于实际文件内容生成的，而非记忆中的陈旧版本
• 降低了因文件状态不一致导致的编辑失败率

4.3 编辑失败的处理与回滚

当编辑无法完成时（如 old_string 在文件中找不到匹配），系统会返回详细的错误信息，引导模型修正编辑指令：

if (old_string === new_string) {
  return {
    result: false,
    behavior: 'ask',
    message: 'No changes to make: old_string and new_string are exactly the same.',
    errorCode: 1,
  }
}

Claude Code 并未实现传统数据库意义上的"事务回滚"——文件编辑是原子的 writeTextContent 操作。但系统通过以下机制保证了数据安全：

• 文件历史追踪：fileHistoryTrackEdit 记录了每次编辑的元数据，支持事后追溯
• Git 集成：fetchSingleFileGitDiff 计算编辑前后的 Git Diff，用户可以随时通过 Git 回退
• 写入原子性：writeTextContent 通常使用临时文件 + 重命名的方式实现原子写入，避免写入过程中断导致文件损坏

4.4 空字符串编辑的语义

FileEditTool 对空字符串有特殊处理逻辑，区分了"创建新文件"和"编辑空文件"两种场景：

// 文件不存在 + old_string === '' = 创建新文件（合法）
if (fileContent === null && old_string === '') {
  return { result: true }
}

// 文件存在且有内容 + old_string === '' = 错误（试图创建已存在的文件）
if (old_string === '' && fileContent.trim() !== '') {
  return {
    result: false,
    behavior: 'ask',
    message: 'Cannot create new file - file already exists.',
    errorCode: 3,
  }
}

// 文件存在但为空 + old_string === '' = 合法（替换空内容）
if (old_string === '' && fileContent.trim() === '') {
  return { result: true }
}

这种精细的语义划分，使得同一个工具可以同时支持文件创建和文件编辑，而无需引入额外的 CreateFileTool。

五、验证机制

5.1 输入层验证

validateInput 是 FileEditTool 最复杂的方法之一，包含了多层验证逻辑：

安全性验证：

// 阻止 UNC 路径，防止 Windows NTLM 凭据泄露
if (fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//')) {
  return { result: true }  // 跳过文件系统操作，让权限检查处理
}

// 阻止在团队记忆文件中写入密钥
const secretError = checkTeamMemSecrets(fullFilePath, new_string)
if (secretError) {
  return { result: false, message: secretError, errorCode: 0 }
}

文件大小限制：

const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024  // 1 GiB

const { size } = await fs.stat(fullFilePath)
if (size > MAX_EDIT_FILE_SIZE) {
  return {
    result: false,
    behavior: 'ask',
    message: `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
    errorCode: 10,
  }
}

1GB 的限制与 V8/Bun 引擎的字符串长度上限（约 2^30 字符）相匹配，防止在读取超大文件时发生 OOM。

编码检测与换行符统一：

const fileBuffer = await fs.readFileBytes(fullFilePath)
const encoding: BufferEncoding =
  fileBuffer.length >= 2 &&
  fileBuffer[0] === 0xff &&
  fileBuffer[1] === 0xfe
    ? 'utf16le'
    : 'utf8'
fileContent = fileBuffer.toString(encoding).replaceAll('\r\n', '\n')

系统支持 UTF-8 和 UTF-16LE 编码，并统一将 Windows 风格的 \r\n 换行符转换为 Unix 风格的 \n，确保 Diff 计算的一致性。

5.2 LSP 诊断联动

编辑完成后，FileEditTool 会主动触发 LSP（Language Server Protocol）诊断更新（src/tools/FileEditTool/FileEditTool.ts，第 340–360 行附近）：

// 清除该文件之前已交付的诊断信息
clearDeliveredDiagnosticsForFile(fullFilePath)
// 通知 LSP 服务器文件已更新
getLspServerManager()?.didChange(fullFilePath, newContent)
// 通知 VSCode MCP 文件已更新
notifyVscodeFileUpdated(fullFilePath)

这种联动机制确保了：

• 编辑器中的错误/警告标记实时更新
• 类型检查、语法高亮等语言特性基于最新文件内容
• 与外部 IDE 的状态保持同步

5.3 文件完整性验证

编辑完成后，系统会再次读取文件内容，确认写入操作成功：

const originalFile = fileContent  // 编辑前的内容
const newFileContent = // ... 应用编辑后的内容
writeTextContent(fs, fullFilePath, newFileContent)

writeTextContent（来自 src/utils/file.ts）内部实现了安全的文件写入逻辑，包括目录自动创建、权限处理等。FsOperations 接口（src/utils/fsOperations.ts）抽象了所有文件系统操作，便于测试和替代实现：

export type FsOperations = {
  cwd(): string
  existsSync(path: string): boolean
  stat(path: string): Promise<fs.Stats>
  readFile(path: string, options: { encoding: BufferEncoding }): Promise<string>
  readFileSync(path: string, options: { encoding: BufferEncoding }): string
  readFileBytesSync(path: string): Buffer
  writeFileSync(path: string, data: string): void
  appendFileSync(path: string, data: string, options?: { mode?: number }): void
  mkdirSync(path: string, options?: { mode?: number }): void
  // ... 更多操作
}

5.4 错误报告与用户提示

当验证失败时，FileEditTool 不仅返回错误码，还提供了智能的用户提示：

• 文件不存在：系统会尝试查找相似文件名（findSimilarFile），并建议当前工作目录下的可能路径：

  const similarFilename = findSimilarFile(fullFilePath)
  const cwdSuggestion = await suggestPathUnderCwd(fullFilePath)

• Jupyter Notebook 拦截：如果用户试图编辑 .ipynb 文件，系统会提示使用专用的 NotebookEditTool。
• 权限拒绝：matchingRuleForInput 会检查文件权限配置，对 deny 规则覆盖的路径拒绝编辑。

六、性能与可观测性

6.1 Diff 超时保护

Diff 计算设置了 5 秒的超时保护（src/utils/diff.ts，第 7 行）：

export const DIFF_TIMEOUT_MS = 5_000

对于极端复杂的变更（如整个文件被重写），structuredPatch 可能消耗大量 CPU 时间。超时机制确保了 UI 不会被阻塞。

6.2 变更统计与成本追踪

每次编辑完成后，系统会统计增删行数并上报到成本追踪器（src/utils/diff.ts，第 33–60 行）：

export function countLinesChanged(
  patch: StructuredPatchHunk[],
  newFileContent?: string,
): void {
  let numAdditions = 0
  let numRemovals = 0

  if (patch.length === 0 && newFileContent) {
    numAdditions = newFileContent.split(/\r?\n/).length
  } else {
    numAdditions = patch.reduce(
      (acc, hunk) => acc + count(hunk.lines, _ => _.startsWith('+')),
      0,
    )
    numRemovals = patch.reduce(
      (acc, hunk) => acc + count(hunk.lines, _ => _.startsWith('-')),
      0,
    )
  }

  addToTotalLinesChanged(numAdditions, numRemovals)
  getLocCounter()?.add(numAdditions, { type: 'added' })
  getLocCounter()?.add(numRemovals, { type: 'removed' })
  logEvent('tengu_file_changed', { lines_added: numAdditions, lines_removed: numRemovals })
}

这些数据不仅用于内部成本核算，还通过 logEvent 上报到分析系统，帮助产品团队了解用户的使用模式。

6.3 Analytics 的安全设计

值得注意的是，Claude Code 的 Analytics 系统采用了特殊的设计来防止敏感数据泄露（src/services/analytics/index.ts）：

export type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = never

这种"标记类型"（Marker Type）强制开发者在记录日志时显式确认数据不包含代码片段或文件路径。对于需要记录 PII 的场景，还有专门的前缀通道：

export type AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED = never

以 _PROTO_ 为前缀的键会被路由到受访问控制的 BQ 列，并在发往 Datadog 之前被自动剥离。

七、总结

FileEditTool 是 Claude Code 工具链中最能体现工程严谨性的组件之一。它的设计哲学可以概括为以下几点：

1. 可预测性优先：使用字符串匹配而非正则表达式，减少意外行为
2. 安全至上：多层验证（时间戳、内容比对、权限检查、UNC 路径拦截）确保编辑不会破坏文件
3. 用户体验为核心：智能引号保留、上下文 Diff、大文件优化、友好的错误提示
4. 生态集成：与 LSP、Git、VSCode MCP 深度联动，成为开发者工作流的无缝一环
5. 防御性编程：Diff 超时、文件大小限制、Windows 时间戳误报处理

从 types.ts 中严谨的 Zod Schema，到 utils.ts 中对弯引号的细致处理，再到 FileEditToolDiff.tsx 中复杂的异步 Diff 加载，每一个模块都在回答同一个问题：如何让 AI 安全、可靠、优雅地修改人类代码。

FileEditTool 的实现证明，AI Agent 的工具设计不仅仅是"封装一个函数调用"，而是需要在语义理解、工程安全、交互设计和性能优化之间找到精妙的平衡。