Edit 工具

Edit 工具用于基于行号编辑文件内容。

概述

Edit 工具允许 AI 助手通过行号精确编辑文件。它支持：

  • 删除指定行
  • 替换行内容
  • 插入新行
  • 多行编辑

定义位置

  • packages/opencode/src/tool/edit.ts
  • packages/opencode/src/tool/edit.txt

参数说明

参数名类型必填说明
filePathstring是要编辑的文件路径
editsEditItem[]是编辑操作数组

EditItem 类型

字段名类型必填说明
oldStrstring是要查找的旧字符串
newStrstring是替换的新字符串

TypeScript 类型定义

export type EditInput = {
  filePath: string
  edits: {
    oldStr: string
    newStr: string
  }[]
}

export type EditOutput = {
  title: string
  output: string
  metadata: {
    summary: FileSummary
  }
}

工作流程

1. 读取文件

const file = Bun.file(filepath)
const content = await file.text()

2. 应用编辑

let result = content
for (const edit of params.edits) {
  if (!result.includes(edit.oldStr)) {
    throw new Error(`String not found in file: ${edit.oldStr}`)
  }
  result = result.replace(edit.oldStr, edit.newStr)
}

3. 写回文件

await Bun.write(filepath, result)
FileTime.write(ctx.sessionID, filepath)
LSP.touchFile(filepath, true)

典型使用场景

场景 1：替换单行

await EditTool.execute(
  {
    filePath: "src/config.ts",
    edits: [
      {
        oldStr: "  debug: false",
        newStr: "  debug: true",
      },
    ],
  },
  ctx,
)

场景 2：多次替换

await EditTool.execute(
  {
    filePath: "src/app.ts",
    edits: [
      {
        oldStr: "const API_URL = 'http://localhost:3000'",
        newStr: "const API_URL = process.env.API_URL || 'http://localhost:3000'",
      },
      {
        oldStr: "  timeout: 5000,",
        newStr: "  timeout: 10000,",
      },
    ],
  },
  ctx,
)

场景 3：删除内容

await EditTool.execute(
  {
    filePath: "src/README.md",
    edits: [
      {
        oldStr: "TODO: Add more features",
        newStr: "", // 删除该行
      },
    ],
  },
  ctx,
)

错误处理

字符串未找到

Error: String not found in file: old string

解决：

  • 检查文件内容是否正确
  • 确认要替换的字符串存在
  • 考虑使用 Read 工具先查看文件内容

文件不存在

Error: ENOENT: no such file or directory, edit 'path/to/file'

解决：

  • 确认文件路径正确
  • 使用 Write 工具创建新文件

限制和注意事项

替换逻辑

  • 使用简单的字符串替换
  • 所有匹配项都会被替换
  • 不支持正则表达式

编辑顺序

  • 编辑操作按顺序应用
  • 前面的编辑会影响后面的编辑

文件大小限制

  • 大文件编辑可能触发输出截断
  • 建议对大文件使用分批编辑

权限要求

权限类型说明
edit编辑文件的权限
write写入文件的权限（Edit 会调用）

最佳实践

1. 使用唯一的字符串

// ✅ 好：匹配唯一的内容
await EditTool.execute(
  {
    filePath: "src/config.ts",
    edits: [
      {
        oldStr: "export const API_KEY = 'dev-key'",
        newStr: "export const API_KEY = 'prod-key'",
      },
    ],
  },
  ctx,
)

// ❌ 差：可能匹配多个地方
await EditTool.execute(
  {
    filePath: "src/config.ts",
    edits: [
      {
        oldStr: "  debug: false",
        newStr: "  debug: true",
      },
    ],
  },
  ctx,
)

2. 一次性完成相关编辑

// ✅ 好：一次调用完成多个相关编辑
await EditTool.execute(
  {
    filePath: "src/app.ts",
    edits: [
      { oldStr: "  debug: false", newStr: "  debug: true" },
      { oldStr: "  logging: false", newStr: "  logging: true" },
      { oldStr: "  featureX: false", newStr: "  featureX: true" },
    ],
  },
  ctx,
)

// ❌ 差：多次调用
await EditTool.execute(
  {
    filePath: "src/app.ts",
    edits: [{ oldStr: "  debug: false", newStr: "  debug: true" }],
  },
  ctx,
)
await EditTool.execute(
  {
    filePath: "src/app.ts",
    edits: [{ oldStr: "  logging: false", newStr: "  logging: true" }],
  },
  ctx,
)

3. 验证编辑结果

const result = await EditTool.execute(
  {
    filePath: "src/config.ts",
    edits: [{ oldStr: "...", newStr: "..." }],
  },
  ctx,
)

// 检查返回内容
console.log(result.metadata.summary)

相关文档

变更历史

版本变更内容日期
v1初始 Edit 工具-