file edit

FileEditTool 是 Claude Code 中最核心的工具之一，实现了基于 search-and-replace 的文件编辑机制。

设计理念

为什么不用 diff/patch？

传统的 diff/patch 方式存在问题：

• AI 难以生成正确的 diff 格式

• 行号容易过时

• 对空白字符敏感

search-and-replace 更适合 AI：

• 语义化的编辑描述

• 不依赖行号

• 更容易理解和调试

核心实现

输入 Schema

const FileEditInputSchema = z.object({
  path: z.string(),
  oldStr: z.string(),
  newStr: z.string(),
}).refine(
  data => data.oldStr !== data.newStr,
  { message: 'oldStr and newStr must be different' }
);

执行流程

async execute(input: FileEditInput, context: ToolContext) {
  // 1. 读取文件
  const content = await fs.readFile(input.path, 'utf-8');
  
  // 2. 引号归一化
  const normalizedOld = normalizeQuotes(input.oldStr);
  const normalizedContent = normalizeQuotes(content);
  
  // 3. 查找匹配
  const occurrences = countOccurrences(normalizedContent, normalizedOld);
  
  if (occurrences === 0) {
    return { success: false, error: 'String not found in file' };
  }
  
  if (occurrences > 1) {
    return {
      success: false,
      error: `Found ${occurrences} matches. Please provide more context to make oldStr unique.`
    };
  }
  
  // 4. 执行替换
  const newContent = normalizedContent.replace(normalizedOld, input.newStr);
  
  // 5. 写入文件
  await fs.writeFile(input.path, newContent, 'utf-8');
  
  // 6. 通知 LSP
  await notifyFileChange(input.path);
  
  return {
    success: true,
    output: `Successfully edited ${input.path}`,
  };
}

关键特性

1. 引号归一化

处理不同类型的引号：

function normalizeQuotes(text: string): string {
  return text
    .replace(/['']/g, "'")   // 智能单引号 → 普通单引号
    .replace(/[""]/g, '"')   // 智能双引号 → 普通双引号
    .replace(/…/g, '...');   // 省略号归一化
}

2. Staleness Check

检测文件是否在编辑期间被修改：

async function checkStaleness(path: string, originalContent: string) {
  const currentContent = await fs.readFile(path, 'utf-8');
  
  if (currentContent !== originalContent) {
    throw new Error(
      'File has been modified since it was read. Please re-read the file.'
    );
  }
}

3. 唯一性验证

确保 oldStr 在文件中唯一：

function countOccurrences(content: string, search: string): number {
  let count = 0;
  let pos = 0;
  
  while ((pos = content.indexOf(search, pos)) !== -1) {
    count++;
    pos += search.length;
  }
  
  return count;
}

4. LSP 通知

编辑后通知语言服务器：

async function notifyFileChange(path: string): Promise<void> {
  // 发送 didChange 通知
  await lspClient.sendNotification('textDocument/didChange', {
    textDocument: { uri: `file://${path}` },
    contentChanges: [{ text: newContent }],
  });
}

使用示例

简单替换

// 修改函数名
await fileEdit.execute({
  path: 'src/utils.ts',
  oldStr: 'function oldName() {',
  newStr: 'function newName() {',
}, context);

多行替换

// 修改函数实现
await fileEdit.execute({
  path: 'src/calculator.ts',
  oldStr: `function add(a, b) {
  return a + b;
}`,
  newStr: `function add(a, b) {
  // 添加类型检查
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('Arguments must be numbers');
  }
  return a + b;
}`,
}, context);

错误处理

常见错误

1

String not found

• 原因：oldStr 不存在于文件中

• 解决：检查拼写、空白字符、引号类型

2

Multiple matches

• 原因：oldStr 在文件中出现多次

• 解决：增加上下文，使 oldStr 唯一

3

File modified

• 原因：文件在读取后被修改

• 解决：重新读取文件

4

Permission denied

• 原因：没有写入权限

• 解决：检查文件权限或用户确认

错误恢复

try {
  await fileEdit.execute(input, context);
} catch (error) {
  if (error.code === 'MULTIPLE_MATCHES') {
    // 提示 AI 增加上下文
    return {
      success: false,
      error: 'Multiple matches found. Please include more surrounding context in oldStr.',
    };
  } else if (error.code === 'STALE_CONTENT') {
    // 提示 AI 重新读取
    return {
      success: false,
      error: 'File has been modified. Please re-read the file and try again.',
    };
  }
  throw error;
}

性能优化

1

增量编辑

对于大文件，只读取和写入必要的部分：

// 使用 line range 优化
const lines = content.split('\n');
const startLine = findLineNumber(content, oldStr);
const endLine = startLine + oldStr.split('\n').length;

// 只处理相关行
const relevantLines = lines.slice(startLine, endLine);

2

批量编辑

多个编辑操作可以批量执行：

async function batchEdit(edits: FileEdit[]): Promise<void> {
  // 按文件分组
  const byFile = groupBy(edits, e => e.path);
  
  // 每个文件只读写一次
  for (const [path, fileEdits] of Object.entries(byFile)) {
    let content = await fs.readFile(path, 'utf-8');
    
    for (const edit of fileEdits) {
      content = content.replace(edit.oldStr, edit.newStr);
    }
    
    await fs.writeFile(path, content);
  }
}

最佳实践

1

提供足够的上下文

// ❌ 上下文不足
oldStr: 'return result;'

// ✅ 包含周围代码
oldStr: `function calculate(x) {
  const result = x * 2;
  return result;
}`

2

保持空白字符一致

// ❌ 空白字符不匹配
oldStr: 'function foo() {'  // 2 个空格
// 文件中实际是 4 个空格

// ✅ 匹配文件的缩进
oldStr: 'function foo() {'  // 4 个空格

3

处理特殊字符

// 转义正则特殊字符
const escaped = oldStr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

下一步

• 了解 BashTool 的实现

• 探索 其他核心工具

• 查看 权限系统 如何控制文件编辑