文件读写与代码修改

6. 用户输入到 agent 行动的整体链路

model read/edit/write tool-call
  -> SessionTools.resolve execute
  -> ReadTool/EditTool/WriteTool.execute
  -> path resolve + external directory check
  -> ctx.ask(read/edit)
  -> fs read/write
  -> format.file
  -> File.Event.Edited / FileWatcher.Event.Updated
  -> lsp.touchFile + diagnostics
  -> ToolResult output

7. 核心源码逐段讲解

ReadTool 权限

if (!path.isAbsolute(filepath)) {
  filepath = path.resolve(instance.directory, filepath)
}
yield* assertExternalDirectoryEffect(ctx, filepath, { kind: stat?.type === "Directory" ? "directory" : "file" })
yield* ctx.ask({ permission: "read", patterns: [path.relative(instance.worktree, filepath)], always: ["*"] })

路径：packages/opencode/src/tool/read.ts:200-232。

外部目录

if (containsPath(full, ins)) return
const glob = path.join(dir, "*").replaceAll("\\", "/")
yield* ctx.ask({ permission: "external_directory", patterns: [glob], always: [glob] })

路径：packages/opencode/src/tool/external-directory.ts:16-45。

EditTool diff + ask + write

diff = trimDiff(createTwoFilesPatch(filePath, filePath, contentOld, contentNew))
yield* ctx.ask({ permission: "edit", patterns: [path.relative(instance.worktree, filePath)], metadata: { filepath: filePath, diff } })
yield* afs.writeWithDirs(filePath, Bom.join(contentNew, desiredBom))
if (yield* format.file(filePath)) {
  contentNew = yield* Bom.syncFile(afs, filePath, desiredBom)
}

路径：packages/opencode/src/tool/edit.ts:88-160。

LSP 反馈

yield* lsp.touchFile(filePath, "document")
const diagnostics = yield* lsp.diagnostics()
const block = LSP.Diagnostic.report(filePath, diagnostics[normalizedFilePath] ?? [])
if (block) output += `\n\nLSP errors detected in this file, please fix:\n${block}`

路径：packages/opencode/src/tool/edit.ts:192-198。

WriteTool 项目诊断

WriteTool 写入后还会报告其他文件的 LSP errors。来源：packages/opencode/src/tool/write.ts:74-90。

8. 关键 TypeScript 语法复习

• Schema.Struct 定义工具参数。
• Effect.catchIf 恢复 stat not found。
• object literal metadata：{ filepath, diff }。
• template literal 拼 diagnostics。
• 平台分支处理 Windows 路径。

9-10. 架构思想与协作

• Policy enforcement：外部目录 + read/edit 权限。
• Domain Event：文件编辑后发布 File/FileWatcher 事件。
• Feedback Loop：LSP diagnostics 进入 tool output。
• Provider 不直接参与文件工具执行；它主要影响工具 schema 暴露。

11. mini agent 对应代码

async function editFile(args, ctx) {
  const filePath = resolveInsideProject(args.filePath, ctx.cwd)
  const oldContent = await fs.readFile(filePath, "utf8")
  const newContent = oldContent.replace(args.oldString, args.newString)
  const diff = makeDiff(oldContent, newContent)
  await ctx.ask({ permission: "edit", patterns: [relative(ctx.root, filePath)], metadata: { diff } })
  await fs.writeFile(filePath, newContent)
  return { output: await diagnostics(filePath) }
}