// EditInput = 模型调用 edit_file 时需要传入的参数。
// 这个工具只适合“小范围精确替换”，不适合整文件重写。
type EditInput = {
  path: string;        // 要编辑的文件路径，必须解析到 workspace 内。
  oldText: string;     // 当前文件里必须精确存在的旧文本，相当于编辑锚点。
  newText: string;     // 要替换成的新文本。
  replaceAll?: boolean;// 是否替换所有命中。默认 false，避免误改多个位置。
};

// editFile = 精确字符串替换版编辑工具。
// 职责：校验路径 -> 读取文件 -> 校验 oldText -> 生成 diff -> 请求批准 -> 写入。
export async function editFile(input: EditInput, ctx: ToolContext): Promise<ToolResult> {
  // 把用户/模型给的相对路径解析成绝对路径，并限制在工作区内。
  // 这一步防止 ../../ 逃逸到 workspace 外。
  const abs = resolveWorkspacePath(ctx.cwd, input.path);

  // 读取当前文件内容。注意真实系统还要检测编码、BOM、二进制文件。
  const original = await readFile(abs, "utf8");

  // 统计 oldText 出现次数。编辑工具的第一条安全线就是“锚点必须明确”。
  const count = countOccurrences(original, input.oldText);

  // 找不到 oldText，说明模型上下文过期或路径错了，必须拒绝。
  if (count === 0) {
    throw new AgentError("TOOL_INPUT_INVALID", "oldText not found.", {
      path: input.path
    });
  }

  // oldText 出现多次时默认拒绝，因为模型可能只想改其中一处。
  // 除非模型显式传 replaceAll=true，才允许全部替换。
  if (count > 1 && !input.replaceAll) {
    throw new AgentError("TOOL_INPUT_INVALID", "oldText appears multiple times.", {
      path: input.path,
      count
    });
  }

  // 在内存里生成新内容，还没有落盘。
  const updated = input.replaceAll
    ? original.split(input.oldText).join(input.newText)
    : original.replace(input.oldText, input.newText);

  // diff 必须由程序根据 old/new 生成，不能让模型自己描述“我改了什么”。
  const diff = createUnifiedDiff(original, updated, input.path);

  // 写入前让用户/权限系统看到真实 diff。
  await requireWriteApproval({
    path: input.path,
    diff
  });

  // 最后才写文件。真实系统建议用 atomic write，而不是普通 writeFile。
  await writeFile(abs, updated, "utf8");

  // 工具返回 diff 和替换次数，模型下一步可以据此决定是否跑测试。
  return {
    summary: `Edited ${input.path}`,
    content: diff,
    metadata: {
      replacements: input.replaceAll ? count : 1
    }
  };
}

content.replace("config", "settings")

--- a/src/config.ts
+++ b/src/config.ts
 export const config = {
-  model: "sonnet",
+  model: "opus",
 };

// createUnifiedDiff = 把修改前/后的文本转换成统一 diff。
// 这里是教学版：真实项目建议用 diff 库处理复杂行变更。
function createUnifiedDiff(oldText: string, newText: string, path: string) {
  // 按行比较。这里先假设输入已经处理好 CRLF/LF。
  const oldLines = oldText.split("\n");
  const newLines = newText.split("\n");

  return [
    // diff 头：a/ 表示旧文件，b/ 表示新文件。
    `--- a/${path}`,
    `+++ b/${path}`,
    // simpleLineDiff 负责产出以 +、-、空格开头的变更行。
    ...simpleLineDiff(oldLines, newLines)
  ].join("\n");
}

// verifyEdit = 写入后的最小回读校验。
// 它不能证明语义正确，但能证明文件确实写进去了。
async function verifyEdit(abs: string, expected: string) {
  // 重新从磁盘读取，而不是相信内存里的 updated。
  const after = await readFile(abs, "utf8");

  // 如果新内容没出现，说明写入失败、写错文件或被其他进程覆盖。
  if (!after.includes(expected)) {
    throw new AgentError("TOOL_EXECUTION_FAILED", "Edit verification failed.");
  }
}

// detectLineEnding = 判断原文件主要使用哪种换行。
// Windows 项目常见 CRLF，Unix/macOS 项目常见 LF。
function detectLineEnding(text: string) {
  return text.includes("\r\n") ? "\r\n" : "\n";
}

// preserveLineEnding = 把更新后的文本换行统一回原文件风格。
// 目的：避免因为一次小修改导致全文件换行都变了，diff 爆炸。
function preserveLineEnding(original: string, updated: string) {
  const ending = detectLineEnding(original);
  return updated.replace(/\r?\n/g, ending);
}

const updatedWithOriginalEnding = preserveLineEnding(original, updated);

// PatchInput = 更高级的补丁输入。
// 它不是简单 oldText/newText，而是多个 hunk 组成的结构化 diff。
type PatchInput = {
  path: string; // 要应用 patch 的文件。
  hunks: Array<{
    oldStart: number;   // patch 认为旧文件从第几行开始匹配。
    oldLines: string[]; // 需要在旧文件中找到的上下文/删除行。
    newLines: string[]; // 应用后要变成的新行。
  }>;
};

Patch failed at hunk 2.
Expected context:
...
Actual nearby content:
...
Please re-read the file before generating a new patch.

// EditAudit = 编辑审计记录。
// 真实 Agent CLI 应该能回答：谁在什么时候改了哪个文件、改前改后是什么版本。
type EditAudit = {
  sessionId: string;                         // 哪个会话发起的编辑。
  path: string;                              // 被修改的文件。
  editType: "replace" | "write" | "patch";   // 编辑方式：精确替换、整文件写入、patch。
  oldHash: string;                           // 修改前文件 hash。
  newHash: string;                           // 修改后文件 hash。
  diff: string;                              // 真实 diff，用于审查和回放。
  approvedByUser: boolean;                   // 是否经过用户/策略批准。
  time: string;                              // 发生时间。
};

Use edit_file for small, precise replacements.
oldText must match the current file exactly.
If oldText is not unique, read the file again and include more surrounding context.
Do not use write_file for modifying existing large files unless replacing the whole file is intended.

// LoadedFile = Agent 读到的文件快照。
// 重点是 hash：后续写入前要确认磁盘文件还是这个版本。
type LoadedFile = {
  path: string;                                // 文件路径。
  text: string;                                // 读取到的完整文本。
  hash: string;                                // 读取时的内容 hash，用作乐观锁。
  lineEnding: "\n" | "\r\n";                   // 原始换行风格。
  encoding: "utf8" | "utf8-bom" | "unknown";   // 原始编码信息，写回时要尽量保持。
};

// EditPlan = 尚未落盘的编辑计划。
// baseHash 表示“这个计划基于哪个文件版本生成”。
type EditPlan = {
  path: string;                    // 要修改的文件。
  baseHash: string;                // 生成计划时文件的 hash。
  operations: EditOperation[];     // 一个或多个编辑操作，例如 replace、insert、delete。
};

// assertNotStale = 写入前的乐观锁检查。
// 如果用户或另一个工具在中途改了文件，就拒绝继续写。
async function assertNotStale(plan: EditPlan, abs: string) {
  // 写入前重新读当前磁盘内容。
  const current = await readFile(abs, "utf8");

  // 计算当前版本 hash。
  const currentHash = sha256(current);

  // 如果当前 hash 和计划里的 baseHash 不同，说明上下文过期。
  if (currentHash !== plan.baseHash) {
    throw new AgentError("FILE_STALE", "File changed after it was read.", {
      path: plan.path,
      expectedHash: plan.baseHash,
      actualHash: currentHash
    });
  }
}

表里几个词展开说一下:mtime 指文件的最后修改时间;
UTF-8 BOM 是文件开头可选的三个标记字节(EF BB BF,Windows 记事本经常写入),读写时把它弄丢,有些工具打开文件就会出问题;
generated file guard 指对自动生成的文件(编译产物、lock 文件这类)加保护,它们本来就不该手改;
AST 是抽象语法树,把代码解析成结构之后才能判断改的是不是语义上正确的位置;

// atomicWriteText = 原子写入教学版。
// 思路：先写临时文件，再 rename 覆盖目标文件，降低半写入风险。
async function atomicWriteText(abs: string, text: string) {
  // 临时文件放在同目录，避免跨磁盘 rename 失败。
  const dir = dirname(abs);

  // 带 pid 是为了减少多个进程同时写临时文件时重名。
  const tmp = join(dir, `.${basename(abs)}.${process.pid}.tmp`);

  // 先把完整内容写到临时文件。
  await writeFile(tmp, text, "utf8");

  // rename 在同一文件系统内通常是原子替换。
  await rename(tmp, abs);
}

// WriteFailureKind = 写入失败分类。
// 分类越具体，模型越容易知道下一步是重试、重读，还是请求用户处理权限。
type WriteFailureKind =
  | "permission_denied" // 没有写权限。
  | "file_locked"      // 文件被编辑器、杀毒软件或其他进程占用。
  | "path_not_found"   // 目录或文件不存在。
  | "disk_full"        // 磁盘空间不足。
  | "stale_file"       // 文件版本变了，不能基于旧上下文写。
  | "unknown";         // 未分类错误，应该保留原始错误信息。

// Patch = 一个完整补丁，可能涉及多个文件。
type Patch = {
  files: FilePatch[]; // 每个 FilePatch 对应一个文件的增删改。
};

// FilePatch = 单个文件的补丁。
type FilePatch = {
  oldPath: string; // 修改前路径。新增文件时可能是 /dev/null。
  newPath: string; // 修改后路径。删除文件时可能是 /dev/null。
  hunks: Hunk[];   // 一个文件里可能有多处不连续修改。
  kind: "add" | "delete" | "modify" | "rename"; // 文件级操作类型。
};

// Hunk = patch 中一段连续的修改区域。
type Hunk = {
  oldStart: number; // 旧文件中这段从第几行开始。
  oldCount: number; // 旧文件中这段覆盖多少行。
  newStart: number; // 新文件中这段从第几行开始。
  newCount: number; // 新文件中这段覆盖多少行。
  lines: PatchLine[]; // 具体每一行是上下文、删除还是新增。
};

// PatchLine = hunk 内的行。
type PatchLine =
  | { kind: "context"; text: string } // 未改变的上下文行，用来定位。
  | { kind: "remove"; text: string }  // 旧文件中要删除的行。
  | { kind: "add"; text: string };    // 新文件中要新增的行。

// ApplyResult = patch 应用结果。
// 成功时返回更新后的文本；失败时返回失败 hunk 和附近上下文。
type ApplyResult =
  | {
      ok: true;             // patch 应用成功。
      updatedText: string;  // 应用 patch 后的新文件内容。
      appliedHunks: number; // 成功应用了几个 hunk。
      warnings: string[];   // 非致命提示，例如行号发生漂移。
    }
  | {
      ok: false;            // patch 应用失败。
      failedHunkIndex: number; // 第几个 hunk 失败。
      reason: "context_not_found" | "overlap" | "malformed_patch"; // 失败原因。
      expected: string;     // patch 期望找到的上下文。
      nearby: string;       // 当前文件中相近位置的内容，帮助模型重读和修正。
    };

// locateHunk = 在当前文件里找到某个 hunk 应该应用的位置。
// 返回值是 0-based 行号；找不到或多义时应该返回 null/失败。
function locateHunk(lines: string[], hunk: Hunk): number | null {
  // add 行是新内容，不应该参与“在旧文件里定位”。
  // context/remove 才是旧文件中应该存在的内容。
  const expected = hunk.lines
    .filter(line => line.kind !== "add")
    .map(line => line.text);

  // patch 里的 oldStart 是 1-based，这里转成数组下标 0-based。
  const hinted = hunk.oldStart - 1;

  // 先在 oldStart 附近搜索，允许上下文有少量行号漂移。
  const window = range(Math.max(0, hinted - 20), Math.min(lines.length, hinted + 20));

  // 如果附近能唯一匹配，直接使用。
  const local = findUniqueMatch(lines, expected, window);
  if (local !== null) return local;

  // 附近找不到，再全文件搜索；如果多处匹配，findUniqueMatch 应该拒绝。
  const global = findUniqueMatch(lines, expected, range(0, lines.length));
  return global;
}

// scoreEditRisk = 根据变更规模和敏感度给编辑打风险分。
// 分数越高，越应该要求用户明确确认，甚至禁止自动执行。
function scoreEditRisk(change: PlannedChange): number {
  let risk = 0;

  // 一次改太多文件，说明影响面变大。
  if (change.files.length > 3) risk += 2;

  // 改动行数太多，diff 审查成本高，也更容易误伤。
  if (change.totalChangedLines > 80) risk += 2;

  // 命中密钥、配置、锁文件等敏感路径时提高风险。
  if (change.paths.some(isSensitivePath)) risk += 3;

  // workspace 外路径基本应该直接拒绝，这里给极高分。
  if (change.paths.some(isOutsideWorkspace)) risk += 10;

  // 删除操作比普通替换危险。
  if (change.kind === "delete") risk += 3;

  return risk;
}

// EditToolResult = 编辑工具返回给 QueryEngine/模型的事实。
// 它应该足够详细，让模型知道下一步该不该跑测试、该不该继续改。
type EditToolResult = {
  summary: string;        // 一句话摘要，例如 Edited src/config.ts。
  diff: string;           // 真实 diff。
  changedFiles: string[]; // 本次改动涉及哪些文件。
  oldHash: string;        // 修改前版本。
  newHash: string;        // 修改后版本。
  verification: {
    readBack: boolean;                         // 是否写后回读。
    formatter?: "passed" | "failed" | "skipped"; // 是否跑了 formatter。
    tests?: "passed" | "failed" | "skipped";     // 是否跑了测试。
  };
};

// 这个测试验证：文件被别人改过后，旧编辑计划不能继续写入。
it("rejects stale file before writing", async () => {
  // 先读取文件，生成一个基于当前 hash 的编辑计划。
  const loaded = await loadFile("config.ts");
  const plan = buildReplacePlan(loaded, "sonnet", "opus");

  // 模拟用户或其他进程在中途修改了同一个文件。
  await writeFile("config.ts", "user changed it", "utf8");

  // 应用旧计划必须失败，并且错误码应该明确是 FILE_STALE。
  await expect(applyEditPlan(plan)).rejects.toMatchObject({
    code: "FILE_STALE"
  });
});