minimal-agent 0.10.0 → 0.12.0

package/src/tools/edit/edit.ts

@@ -0,0 +1,349 @@
+/**
+ * ============================================================
+ *  src/tools/edit.ts —— Edit 工具（精确字符串替换）
+ * ------------------------------------------------------------
+ *  对应 kakadeai 主仓库的 FileEditTool。
+ *  prompt 文本和 Zod schema 与 kakadeai 一致。
+ *
+ *  v0.2 增强：
+ *    - 路径安全校验（null byte / UNC 路径）
+ *    - 文件大小上限（1GB）
+ *    - old_string 找不到时提供模糊匹配提示（最常见模型错误）
+ * ============================================================
+ */
+
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import {
+  resolveToolPath,
+  findActualString,
+  preserveQuoteStyle,
+  detectLineEndingsForString,
+  applyLineEnding,
+  countOccurrences,
+  splitReplaceAll,
+  tryAutoSnapshot,
+  atomicWriteFile,
+  encodeTextFile,
+  readTextFile,
+} from '../shared/fileUtils.js';
+import { filePathField } from '../shared/schemas.js';
+import { assertFresh, hashFileBytes, recordRead, wasTruncated, type FileReadState } from '../shared/fileState.js';
+import { fileActivityMetadata } from '../shared/fileActivity.js';
+import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
+
+/** 编辑文件大小上限：1GB。防止模型试图 Edit 超大文件撑爆内存。 */
+const MAX_EDIT_FILE_SIZE_BYTES = 1024 * 1024 * 1024;
+
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+  file_path: filePathField('编辑'),
+  old_string: z
+    .string()
+    .describe(
+      '要替换的原文本（必须在文件中唯一，除非 replace_all=true）；为空字符串且文件不存在时创建新文件',
+    ),
+  new_string: z.string().describe('替换为的新文本（与 old_string 必须不同）'),
+  replace_all: z
+    .boolean()
+    .optional()
+    .describe('是否替换所有出现位置（默认 false）'),
+});
+type EditInput = z.infer<typeof inputSchema>;
+
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 3. Description（搬自 kakadeai/tools/FileEditTool/prompt.ts） ----------------
+const description = `Performs exact string replacements in files.
+
+Usage:
+- You MUST use your \`Read\` tool to read the current content of the file BEFORE calling Edit.
+  Memory is unreliable — if you think you "remember" how the code looks, you are probably wrong.
+  Re-read the relevant sections (function, module, or area you plan to change) every time.
+- To create a new file, pass an empty \`old_string\` and the desired contents as \`new_string\`. When creating a new file (path does not yet exist), you may call Edit directly — no prior Read is needed.
+- If the file already exists and you pass an empty \`old_string\`, the edit is rejected with a clear error. To replace the entire content of an existing file, use the Write tool instead.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.
+- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+- Preserve exact indentation (tabs/spaces).`;
+
+// ---------------- 4. call() ----------------
+async function call(input: EditInput, state?: FileReadState, cwd?: string): Promise<ToolResult> {
+  const { old_string, new_string } = input;
+  const replaceAll = input.replace_all ?? false;
+
+  // 5a. 路径规范化 + 安全校验（含 null byte / UNC / 设备文件拦截 / ~ 展开）
+  const pathResult = resolveToolPath(input.file_path, cwd);
+  if (!pathResult.ok) return pathResult;
+  const filePath = pathResult.resolvedPath;
+
+  // 5a-bis. Pre-read guard：文件已存在则必须先 Read（创建新文件场景下 assertFresh 返回 ok:true）
+  // 拦截路径自动注入 snippet：让模型在同一轮 tool result 里看到当前内容，无需多绕一次 Read。
+  // 安全语义保留：模型必须显式重发 Edit 才会落盘；snippet 只是给模型看的，不静默放行。
+  const freshness = await assertFresh(filePath, {}, state);
+  if (!freshness.ok) {
+    const snap = await tryAutoSnapshot(filePath);
+    if (snap.ok) {
+      // 关键：truncated=true 时 wasTruncated 会守住 Write 路径，防止基于残缺 snippet 重写整文件
+      recordRead(filePath, { truncated: snap.truncated, partial: snap.truncated }, state);
+      const tail = snap.truncated
+        ? `\n\n⚠️ 仅注入了前 200 行（文件共 ${snap.totalLines} 行 / 上限 32KB）。若要改的位置在范围外，请显式 Read offset=X limit=Y 后再 Edit。`
+        : '';
+      return {
+        ok: false,
+        error:
+          freshness.error +
+          `\n\n以下是当前文件${snap.truncated ? '前 200 行' : '全部'}内容（带行号），请基于此重新构造 old_string 后立即重试 Edit，不要再单独调 Read：\n\n${snap.snippet}` +
+          tail,
+      };
+    }
+    const why =
+      snap.reason === 'too-large'
+        ? `文件 ${((snap.sizeBytes ?? 0) / 1024).toFixed(1)} KB 超过 32KB 自动注入上限`
+        : snap.reason === 'binary'
+          ? '文件命中二进制扩展名黑名单'
+          : '文件读取失败';
+    return {
+      ok: false,
+      error: `${freshness.error}\n\n（${why}，未注入内容快照，请用 Read 工具显式读取后再 Edit）`,
+    };
+  }
+
+  if (old_string === new_string) {
+    return { ok: false, error: 'old_string 与 new_string 完全相同，没有可改的内容。' };
+  }
+
+  // 5b. 创建新文件路径：old_string === '' 且文件不存在
+  if (old_string === '' && !existsSync(filePath)) {
+    try {
+      await atomicWriteFile(filePath, new_string);
+      recordRead(filePath, { contentHash: hashFileBytes(encodeTextFile(new_string, 'utf8')) }, state);
+      emitFileMutation(filePath);
+      const patch = buildPatchSummary('', new_string, input.file_path);
+      return {
+        ok: true,
+        content: `已创建新文件：${filePath}（${new_string.length} 字符）\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+        metadata: await fileActivityMetadata(filePath, 'created', 'not_run', 'support', cwd, patch),
+      };
+    } catch (e) {
+      return { ok: false, error: `创建文件失败：${(e as Error).message}` };
+    }
+  }
+
+  // 5c. 既有文件：读 → 改 → 写
+  if (!existsSync(filePath)) {
+    return {
+      ok: false,
+      error: `文件不存在：${filePath}\n（要创建新文件，请把 old_string 设为空字符串）`,
+    };
+  }
+
+  let original: string;
+  let sourceEncoding: Awaited<ReturnType<typeof readTextFile>>['encoding'];
+  try {
+    const snapshot = await readTextFile(filePath);
+    original = snapshot.content;
+    sourceEncoding = snapshot.encoding;
+  } catch (e) {
+    return { ok: false, error: `读取失败：${(e as Error).message}` };
+  }
+
+  // 5d-1. 记录原文件行尾符风格（写入时保持一致）
+  const originalLineEnding = detectLineEndingsForString(original);
+
+  // 5d. 文件大小上限检查
+  const fileSize = Buffer.byteLength(original, 'utf8');
+  if (fileSize > MAX_EDIT_FILE_SIZE_BYTES) {
+    return {
+      ok: false,
+      error: `文件过大（${fileSize} 字节 > ${MAX_EDIT_FILE_SIZE_BYTES} 字节 ≈ 1GB）。Edit 不适合操作超大文件，请用 Write 工具。`,
+    };
+  }
+
+  // 唯性检查
+  if (old_string === '') {
+    return {
+      ok: false,
+      error: 'old_string 为空但文件已存在 —— 这通常是错误的。要替换全文请用 Write 工具。',
+    };
+  }
+
+  // 5e. 引号风格归一化：处理模型输出的直引号 vs 文件中的弯引号差异
+  let searchTarget = old_string;
+  let processedNewString = new_string;
+  const actualOld = findActualString(original, old_string);
+  if (actualOld !== null && actualOld !== old_string) {
+    searchTarget = actualOld;
+    processedNewString = preserveQuoteStyle(old_string, actualOld, new_string);
+  }
+
+  // splitCount = 出现次数
+  const occurrences = countOccurrences(original, searchTarget);
+  const truncHint = wasTruncated(filePath, state)
+    ? `\n\n⚠️ 上次 Read 该文件时被截断了（只看到部分内容）。当前 old_string 可能在截断范围外。请用更小的 limit + offset 精确读取目标行号附近后再 Edit。`
+    : '';
+  if (occurrences === 0) {
+    // 模糊匹配提示：找找有没有"接近"的内容
+    const hint = findFuzzyMatchHint(original, searchTarget);
+    const extraMsg = hint ? `\n\n💡 提示：${hint}` : '';
+    return {
+      ok: false,
+      error: `在 ${filePath} 中找不到 old_string。请先用 Read 工具核对内容（注意空格/缩进/换行）。${extraMsg}${truncHint}`,
+    };
+  }
+  if (occurrences > 1 && !replaceAll) {
+    return {
+      ok: false,
+      error: `old_string 在文件中出现了 ${occurrences} 次，不唯一。\n请扩大 old_string 包含更多上下文，或显式传 replace_all=true。${truncHint}`,
+    };
+  }
+
+  const replaced = replaceAll
+    ? splitReplaceAll(original, searchTarget, processedNewString)
+    : original.replace(searchTarget, processedNewString); // 只替换第一处（已确认 occurrences === 1）
+
+  // 5f. 保持原文件行尾符风格
+  const normalizedReplaced = applyLineEnding(replaced, originalLineEnding);
+
+  try {
+    await atomicWriteFile(filePath, normalizedReplaced, sourceEncoding);
+    recordRead(filePath, {
+      contentHash: hashFileBytes(encodeTextFile(normalizedReplaced, sourceEncoding)),
+    }, state);
+    emitFileMutation(filePath);
+  } catch (e) {
+    return { ok: false, error: `写入失败：${(e as Error).message}` };
+  }
+
+  // 输出：报告改了几处 + 行变化
+  const linesBefore = original.split('\n').length;
+  const linesAfter = replaced.split('\n').length;
+  const patch = buildPatchSummary(original, normalizedReplaced, input.file_path);
+  return {
+    ok: true,
+    content:
+      `已编辑 ${filePath}\n` +
+      `替换次数：${replaceAll ? occurrences : 1}\n` +
+      `行数：${linesBefore} → ${linesAfter}\n` + (patch.unifiedDiff ?? '[diff omitted: too large]'),
+    metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
+  };
+}
+
+// ---------------- 5. 模糊匹配提示 ----------------
+
+/**
+ * 当 old_string 精确匹配失败时，尝试在文件内容中找到相似行。
+ * 常见场景：模型传入的 old_string 缩进差一个 tab、末尾多一个空格等。
+ *
+ * 策略：
+ *   1. 按 \n 分割成行
+ *   2. 对每行计算与 old_string 的字符重叠率（最长公共子序列长度 / max(len)）
+ *   3. 返回重叠率最高的前 N 行作为提示
+ */
+function findFuzzyMatchHint(fileContent: string, target: string): string | null {
+  const MIN_OVERLAP_RATIO = 0.5; // 至少 50% 字符重叠才认为"接近"
+  const MAX_HINTS = 3; // 最多提示 3 个候选
+
+  const targetTrimmed = target.trim();
+  if (targetTrimmed.length < 5) return null; // 太短的 target 不做模糊匹配
+
+  const lines = fileContent.split('\n');
+
+  type Candidate = { lineNum: number; text: string; ratio: number };
+  const candidates: Candidate[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trim();
+
+    // 跳过空行和太短的行
+    if (trimmedLine.length < 5) continue;
+
+    const ratio = lcsRatio(targetTrimmed, trimmedLine);
+    if (ratio >= MIN_OVERLAP_RATIO) {
+      candidates.push({ lineNum: i + 1, text: trimmedLine, ratio });
+    }
+  }
+
+  // 也检查跨行情况：如果 target 包含换行，尝试匹配连续多行
+  if (target.includes('\n') && candidates.length < MAX_HINTS) {
+    const targetLines = target.split('\n').filter((l) => l.trim().length > 0);
+    if (targetLines.length >= 2) {
+      for (let start = 0; start <= lines.length - targetLines.length; start++) {
+        const window = lines.slice(start, start + targetLines.length).map((l) => l.trim()).join('\n');
+        const ratio = lcsRatio(target.trim(), window);
+        if (ratio >= MIN_OVERLAP_RATIO) {
+          candidates.push({ lineNum: start + 1, text: window.slice(0, 80) + (window.length > 80 ? '...' : ''), ratio });
+        }
+      }
+    }
+  }
+
+  if (candidates.length === 0) return null;
+
+  // 按重叠率降序排列，取前 N 个
+  candidates.sort((a, b) => b.ratio - a.ratio);
+  const top = candidates.slice(0, MAX_HINTS);
+
+  const hints = top.map(
+    (c) =>
+      `第 ${c.lineNum} 行附近有相似内容（相似度 ${(c.ratio * 100).toFixed(0)}%）:\n      "${c.text.slice(0, 100)}${c.text.length > 100 ? '…' : ''}"`,
+  );
+
+  return `可能你想要修改以下位置之一？\n  ${hints.join('\n  ')}`;
+}
+
+/**
+ * 计算两个字符串的最长公共子序列（LCS）长度比。
+ * 使用动态规划，时间复杂度 O(m*n)，但对短字符串足够快。
+ * 返回值范围 [0, 1]，1 表示完全相同。
+ */
+function lcsRatio(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+
+  // 对太长的字符串截断处理（防止性能问题）
+  const MAX_LEN = 500;
+  const aa = m > MAX_LEN ? a.slice(0, MAX_LEN) : a;
+  const bb = n > MAX_LEN ? b.slice(0, MAX_LEN) : b;
+  const mm = aa.length;
+  const nn = bb.length;
+
+  // 用一维 DP 优化空间
+  const dp: number[] = new Array(nn + 1).fill(0);
+
+  for (let i = 1; i <= mm; i++) {
+    let prev = 0;
+    for (let j = 1; j <= nn; j++) {
+      const temp = dp[j];
+      if (aa[i - 1] === bb[j - 1]) {
+        dp[j] = prev + 1;
+      } else {
+        dp[j] = Math.max(dp[j], dp[j - 1]);
+      }
+      prev = temp;
+    }
+  }
+
+  return dp[nn] / Math.max(mm, nn);
+}
+
+// ---------------- 6. 导出 ----------------
+export const editTool: Tool<EditInput> = {
+  name: 'Edit',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'block',
+  call: (input) => call(input),
+  callWithContext: (input, _signal, context: ToolCallContext) => call(input, context.sessionState?.fileReads, context.cwd),
+};

package/src/tools/edit/multi-edit.js

@@ -13,14 +13,16 @@
  *    4. 不支持 "old_string='' 创建文件"（那是 Edit 的单文件场景，多 edit 无意义）
  * ============================================================
  */
-import { readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { z } from 'zod';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
-import { resolveToolPath, detectFileLineEndings, applyLineEnding, findActualString, preserveQuoteStyle, countOccurrences, splitReplaceAll, tryAutoSnapshot, } from '../shared/fileUtils.js';
+import { resolveToolPath, detectLineEndingsForString, applyLineEnding, findActualString, preserveQuoteStyle, countOccurrences, splitReplaceAll, tryAutoSnapshot, atomicWriteFile, encodeTextFile, readTextFile, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
-import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
+import { assertFresh, hashFileBytes, recordRead, wasTruncated } from '../shared/fileState.js';
+import { fileActivityMetadata } from '../shared/fileActivity.js';
+import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 // ---------------- 1. Zod 输入 schema ----------------
 const editItemSchema = z.object({
     old_string: z.string().min(1).describe('要替换的原文本（不允许为空 —— 创建新文件请用 Edit 工具）'),
@@ -52,18 +54,18 @@ Usage:
 - Empty \`old_string\` is NOT allowed in MultiEdit. To create a new file, use the \`Edit\` tool with a single empty-old_string call.
 - Preserve exact indentation (tabs/spaces).`;
 // ---------------- 4. call() ----------------
-async function call(input) {
+async function call(input, state, cwd) {
     // 4a. 路径规范化 + 安全校验
-    const pathResult = resolveToolPath(input.file_path);
+    const pathResult = resolveToolPath(input.file_path, cwd);
     if (!pathResult.ok)
         return pathResult;
     const filePath = pathResult.resolvedPath;
     // 4b. Pre-read guard —— 入口处一次性检查 + 注入 snippet（循环内多个 edit 不重复注入）
-    const freshness = assertFresh(filePath);
+    const freshness = await assertFresh(filePath, {}, state);
     if (!freshness.ok) {
         const snap = await tryAutoSnapshot(filePath);
         if (snap.ok) {
-            recordRead(filePath, { truncated: snap.truncated });
+            recordRead(filePath, { truncated: snap.truncated, partial: snap.truncated }, state);
             const tail = snap.truncated
                 ? `\n\n⚠️ 仅注入了前 200 行（文件共 ${snap.totalLines} 行 / 上限 32KB）。若要改的位置在范围外，请显式 Read offset=X limit=Y 后再 MultiEdit。`
                 : '';
@@ -106,15 +108,18 @@ async function call(input) {
     }
     // 4e. 读原文
     let originalContent;
+    let sourceEncoding;
     try {
-        originalContent = await readFile(filePath, 'utf8');
+        const snapshot = await readTextFile(filePath);
+        originalContent = snapshot.content;
+        sourceEncoding = snapshot.encoding;
     }
     catch (e) {
         return { ok: false, error: `读取失败：${e.message}` };
     }
     // 4f. 在内存中顺序应用所有 edit（任一失败立即返回，磁盘不动）
     let currentContent = originalContent;
-    const truncHint = wasTruncated(filePath)
+    const truncHint = wasTruncated(filePath, state)
         ? `\n\n⚠️ 上次 Read 该文件时被截断了（只看到部分内容）。当前 old_string 可能在截断范围外。请用更小的 limit + offset 精确读取目标行号附近后再 MultiEdit。`
         : '';
     for (let i = 0; i < edits.length; i++) {
@@ -152,18 +157,23 @@ async function call(input) {
             : currentContent.replace(searchTarget, processedNewString);
     }
     // 4g. 全部成功 → 保持原文件行尾符风格，写盘
-    const lineEnding = await detectFileLineEndings(filePath);
+    const lineEnding = detectLineEndingsForString(originalContent);
     const finalContent = applyLineEnding(currentContent, lineEnding);
     try {
-        await writeFile(filePath, finalContent, 'utf8');
-        recordRead(filePath);
+        await atomicWriteFile(filePath, finalContent, sourceEncoding);
+        recordRead(filePath, {
+            contentHash: hashFileBytes(encodeTextFile(finalContent, sourceEncoding)),
+        }, state);
+        emitFileMutation(filePath);
     }
     catch (e) {
         return { ok: false, error: `写入失败：${e.message}` };
     }
+    const patch = buildPatchSummary(originalContent, finalContent, input.file_path);
     return {
         ok: true,
-        content: `已对 ${filePath} 应用 ${edits.length} 处修改`,
+        content: `已对 ${filePath} 应用 ${edits.length} 处修改\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+        metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
     };
 }
 // ---------------- 5. 导出 ----------------
@@ -176,5 +186,6 @@ export const multiEditTool = {
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'block',
-    call,
+    call: (input) => call(input),
+    callWithContext: (input, _signal, context) => call(input, context.sessionState?.fileReads, context.cwd),
 };

package/src/tools/edit/multi-edit.ts

@@ -0,0 +1,223 @@
+/**
+ * ============================================================
+ *  src/tools/edit/multi-edit.ts —— MultiEdit 工具（原子化多处替换）
+ * ------------------------------------------------------------
+ *  对应 kakadeai 主仓库的 FileEditTool.getPatchForEdits 设计思路，
+ *  但比上游更严格：**all-or-nothing**。
+ *
+ *  与 Edit 的关键差异：
+ *    1. 一次处理多条 edit，按顺序在内存中应用，全部成功才写盘
+ *    2. 任何一条匹配失败 / 多义匹配 → 全部回退（磁盘不动一字）
+ *    3. 依赖检测：edits[i].old_string 若是 edits[j<i].new_string 的子串，
+ *       会命中前序产物，直接拒绝（要求调用方重排序或合并）
+ *    4. 不支持 "old_string='' 创建文件"（那是 Edit 的单文件场景，多 edit 无意义）
+ * ============================================================
+ */
+
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import {
+  resolveToolPath,
+  detectLineEndingsForString,
+  applyLineEnding,
+  findActualString,
+  preserveQuoteStyle,
+  countOccurrences,
+  splitReplaceAll,
+  tryAutoSnapshot,
+  atomicWriteFile,
+  encodeTextFile,
+  readTextFile,
+} from '../shared/fileUtils.js';
+import { filePathField } from '../shared/schemas.js';
+import { assertFresh, hashFileBytes, recordRead, wasTruncated, type FileReadState } from '../shared/fileState.js';
+import { fileActivityMetadata } from '../shared/fileActivity.js';
+import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
+
+// ---------------- 1. Zod 输入 schema ----------------
+const editItemSchema = z.object({
+  old_string: z.string().min(1).describe('要替换的原文本（不允许为空 —— 创建新文件请用 Edit 工具）'),
+  new_string: z.string().describe('替换为的新文本'),
+  replace_all: z
+    .boolean()
+    .optional()
+    .describe('是否替换所有出现位置（默认 false，要求 old_string 在当前内容中唯一）'),
+});
+
+const inputSchema = z.object({
+  file_path: filePathField('编辑'),
+  edits: z
+    .array(editItemSchema)
+    .min(1)
+    .max(50)
+    .describe('按顺序应用的 edit 列表（1-50 条），原子化执行：全部成功才落盘'),
+});
+type MultiEditInput = z.infer<typeof inputSchema>;
+
+// ---------------- 2. JSON Schema ----------------
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 3. Description ----------------
+const description = `Performs multiple exact string replacements in a single file, applied atomically (all-or-nothing).
+
+Usage:
+- You MUST use your \`Read\` tool to read the current content of the file BEFORE calling MultiEdit.
+- Provide a list of \`edits\`, each with \`old_string\`, \`new_string\`, and optional \`replace_all\`.
+- All edits are applied sequentially in memory; if ANY edit fails (string not found, ambiguous match, or dependency conflict), the file on disk is UNTOUCHED.
+- Order matters: later edits operate on the result of earlier edits. If a later edit's \`old_string\` is a substring of an earlier edit's \`new_string\`, MultiEdit refuses (reorder or merge instead).
+- Each \`old_string\` must be unique in the current content (after prior edits) unless \`replace_all=true\`.
+- Empty \`old_string\` is NOT allowed in MultiEdit. To create a new file, use the \`Edit\` tool with a single empty-old_string call.
+- Preserve exact indentation (tabs/spaces).`;
+
+// ---------------- 4. call() ----------------
+async function call(input: MultiEditInput, state?: FileReadState, cwd?: string): Promise<ToolResult> {
+  // 4a. 路径规范化 + 安全校验
+  const pathResult = resolveToolPath(input.file_path, cwd);
+  if (!pathResult.ok) return pathResult;
+  const filePath = pathResult.resolvedPath;
+
+  // 4b. Pre-read guard —— 入口处一次性检查 + 注入 snippet（循环内多个 edit 不重复注入）
+  const freshness = await assertFresh(filePath, {}, state);
+  if (!freshness.ok) {
+    const snap = await tryAutoSnapshot(filePath);
+    if (snap.ok) {
+      recordRead(filePath, { truncated: snap.truncated, partial: snap.truncated }, state);
+      const tail = snap.truncated
+        ? `\n\n⚠️ 仅注入了前 200 行（文件共 ${snap.totalLines} 行 / 上限 32KB）。若要改的位置在范围外，请显式 Read offset=X limit=Y 后再 MultiEdit。`
+        : '';
+      return {
+        ok: false,
+        error:
+          freshness.error +
+          `\n\n以下是当前文件${snap.truncated ? '前 200 行' : '全部'}内容（带行号），请基于此重新构造各 edit 的 old_string 后立即重试 MultiEdit，不要再单独调 Read：\n\n${snap.snippet}` +
+          tail,
+      };
+    }
+    const why =
+      snap.reason === 'too-large'
+        ? `文件 ${((snap.sizeBytes ?? 0) / 1024).toFixed(1)} KB 超过 32KB 自动注入上限`
+        : snap.reason === 'binary'
+          ? '文件命中二进制扩展名黑名单'
+          : '文件读取失败';
+    return {
+      ok: false,
+      error: `${freshness.error}\n\n（${why}，未注入内容快照，请用 Read 工具显式读取后再 MultiEdit）`,
+    };
+  }
+
+  // 4c. 文件必须存在（MultiEdit 不做"创建新文件"语义）
+  if (!existsSync(filePath)) {
+    return {
+      ok: false,
+      error: `文件不存在：${filePath}\n（MultiEdit 不支持创建新文件，请改用 Edit 工具）`,
+    };
+  }
+
+  // 4d. 依赖检测：edits[i].old_string 若是 edits[j<i].new_string 的子串，
+  //     后续 edit 会命中前序产物，直接拒绝。
+  const edits = input.edits;
+  for (let i = 0; i < edits.length; i++) {
+    for (let j = 0; j < i; j++) {
+      if (edits[j]!.new_string.includes(edits[i]!.old_string)) {
+        return {
+          ok: false,
+          error: `edits[${i}].old_string 是 edits[${j}].new_string 的子串，会导致后续 edit 命中前序产物，请重新排序或合并`,
+        };
+      }
+    }
+  }
+
+  // 4e. 读原文
+  let originalContent: string;
+  let sourceEncoding: Awaited<ReturnType<typeof readTextFile>>['encoding'];
+  try {
+    const snapshot = await readTextFile(filePath);
+    originalContent = snapshot.content;
+    sourceEncoding = snapshot.encoding;
+  } catch (e) {
+    return { ok: false, error: `读取失败：${(e as Error).message}` };
+  }
+
+  // 4f. 在内存中顺序应用所有 edit（任一失败立即返回，磁盘不动）
+  let currentContent = originalContent;
+  const truncHint = wasTruncated(filePath, state)
+    ? `\n\n⚠️ 上次 Read 该文件时被截断了（只看到部分内容）。当前 old_string 可能在截断范围外。请用更小的 limit + offset 精确读取目标行号附近后再 MultiEdit。`
+    : '';
+  for (let i = 0; i < edits.length; i++) {
+    const edit = edits[i]!;
+    const replaceAll = edit.replace_all ?? false;
+
+    // 引号风格归一化
+    let searchTarget = edit.old_string;
+    let processedNewString = edit.new_string;
+    const actualOld = findActualString(currentContent, edit.old_string);
+    if (actualOld === null) {
+      return {
+        ok: false,
+        error: `edits[${i}] 未匹配到 old_string（在已应用前序 ${i} 处修改后的内容中找不到）。请先用 Read 工具核对当前内容（注意空格/缩进/换行），并检查 edit 顺序。${truncHint}`,
+      };
+    }
+    if (actualOld !== edit.old_string) {
+      searchTarget = actualOld;
+      processedNewString = preserveQuoteStyle(edit.old_string, actualOld, edit.new_string);
+    }
+
+    const occurrences = countOccurrences(currentContent, searchTarget);
+    if (occurrences === 0) {
+      return {
+        ok: false,
+        error: `edits[${i}] 未匹配到 old_string（已应用前序 ${i} 处修改后内容中出现 0 次）。${truncHint}`,
+      };
+    }
+    if (occurrences > 1 && !replaceAll) {
+      return {
+        ok: false,
+        error: `edits[${i}].old_string 在当前内容中出现 ${occurrences} 次，不唯一。请扩大 old_string 包含更多上下文，或显式传 replace_all=true。${truncHint}`,
+      };
+    }
+
+    currentContent = replaceAll
+      ? splitReplaceAll(currentContent, searchTarget, processedNewString)
+      : currentContent.replace(searchTarget, processedNewString);
+  }
+
+  // 4g. 全部成功 → 保持原文件行尾符风格，写盘
+  const lineEnding = detectLineEndingsForString(originalContent);
+  const finalContent = applyLineEnding(currentContent, lineEnding);
+
+  try {
+    await atomicWriteFile(filePath, finalContent, sourceEncoding);
+    recordRead(filePath, {
+      contentHash: hashFileBytes(encodeTextFile(finalContent, sourceEncoding)),
+    }, state);
+    emitFileMutation(filePath);
+  } catch (e) {
+    return { ok: false, error: `写入失败：${(e as Error).message}` };
+  }
+
+  const patch = buildPatchSummary(originalContent, finalContent, input.file_path);
+  return {
+    ok: true,
+    content: `已对 ${filePath} 应用 ${edits.length} 处修改\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+    metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
+  };
+}
+
+// ---------------- 5. 导出 ----------------
+export const multiEditTool: Tool<MultiEditInput> = {
+  name: 'MultiEdit',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'block',
+  call: (input) => call(input),
+  callWithContext: (input, _signal, context: ToolCallContext) => call(input, context.sessionState?.fileReads, context.cwd),
+};