llm-api-gateway-cli 1.0.0

package/lib/tools.js

@@ -0,0 +1,927 @@
+/**
+ * 模式五 · 任务模式的工具集
+ *
+ * 安全边界：所有文件工具都只能作用于会话选定的工作目录之内。
+ *  1. 先用 path.resolve 做字符串层面的越界检查（挡住 ../../ 这类）；
+ *  2. 再用 realpath 复核，挡住「工作目录内的符号链接指向外部」这种绕过。
+ * 写入类工具需要用户批准，未批准时 executeTool 直接拒绝。
+ *
+ * 工具分三档（M3 扩展后）：
+ *  · 只读：list_dir / read_file / search_files / glob / grep —— 计划模式也能用；
+ *  · 写入：apply_patch / write_file —— 必须批准；
+ *  · 命令：bash —— 必须批准**且**由宿主显式开启（默认关闭），安全面从路径级升到命令级。
+ */
+
+import { existsSync, statSync, readdirSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { spawnSync, spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+// MCP 工具是**动态**来源（清单按密钥从网关取），见 lib/mcp.js 的模块说明
+import {
+  mcpToolSpecs,
+  isMcpTool,
+  describeMcpCall,
+  callMcpTool,
+  mcpPreview,
+  setMcpReserved,
+} from './mcp.js';
+
+const MAX_READ_BYTES = 200 * 1024;
+const MAX_WRITE_BYTES = 512 * 1024;
+const MAX_BROWSE_ENTRIES = 2000;
+const MAX_SEARCH_RESULTS = 60;
+const MAX_SEARCH_FILES = 4000;
+const MAX_SEARCH_FILE_BYTES = 512 * 1024;
+const MAX_GLOB_RESULTS = 200;
+const MAX_PREVIEW_CHARS = 8000;
+const BASH_TIMEOUT_MS = 30 * 1000;
+const MAX_BASH_OUTPUT = 20000;
+
+// 搜索时跳过的目录：这些要么是依赖、要么是版本库元数据，翻进去没有意义还很慢
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.svn', '.hg', '.idea', '.vscode', 'dist', 'build', 'out',
+  'target', 'coverage', '.next', '.nuxt', '.cache', '.venv', 'venv', '__pycache__', 'vendor',
+]);
+
+/* ---------- bash 开关：默认关闭 ---------- */
+
+let bashEnabled = false;
+
+/** 由宿主显式开启（CLI 的 --allow-bash / Web 侧同理）。默认关闭是刻意的：命令级权限不该默默打开 */
+export function setBashEnabled(v) {
+  bashEnabled = Boolean(v);
+}
+export const isBashEnabled = () => bashEnabled;
+
+export const TOOLS = [
+  {
+    type: 'function',
+    function: {
+      name: 'list_dir',
+      description: '列出工作目录内某个目录的文件与子目录。path 为相对工作目录的路径，省略表示工作目录根。',
+      parameters: {
+        type: 'object',
+        properties: { path: { type: 'string', description: '相对工作目录的目录路径，如 "src" 或 "."' } },
+        required: [],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'read_file',
+      description: '读取工作目录内一个文本文件的完整内容。只能读文本文件，大小上限 200KB。',
+      parameters: {
+        type: 'object',
+        properties: { path: { type: 'string', description: '相对工作目录的文件路径，如 "README.md"' } },
+        required: ['path'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_files',
+      description: '在工作目录内按关键字搜索文件内容（不区分大小写），返回 文件:行号: 内容。适合先定位再读取。',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '要搜索的关键字' },
+          path: { type: 'string', description: '相对工作目录的起始目录，省略为工作目录根' },
+        },
+        required: ['query'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'glob',
+      description:
+        '按文件名模式查找文件（不是搜内容）。支持 * / ** / ? 与 {a,b}，例如 "**/*.test.mjs"、"src/*.js"。' +
+        '不含 / 的模式会当成 "**/模式" 处理，所以 "*.md" 能匹配到任意层级。',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: '文件名模式，如 "**/*.mjs"' },
+          path: { type: 'string', description: '相对工作目录的起始目录，省略为工作目录根' },
+        },
+        required: ['pattern'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'grep',
+      description: '在工作目录内按**正则表达式**搜索文件内容，返回 文件:行号: 内容。比 search_files 更精确（它只做关键字包含）。',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: '正则表达式，如 "function\\s+\\w+\\("' },
+          path: { type: 'string', description: '相对工作目录的起始目录，省略为工作目录根' },
+          ignore_case: { type: 'boolean', description: '是否忽略大小写，默认 false' },
+        },
+        required: ['pattern'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'apply_patch',
+      description:
+        '对工作目录内**已存在**的文件做增量编辑：给出若干「查找 → 替换」片段，只改动匹配到的部分，' +
+        '不必重写整个文件。每处 find 必须能唯一匹配，否则整次修改都不会落盘。新建文件请用 write_file。执行前需要用户批准。',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '相对工作目录的文件路径（必须已存在）' },
+          edits: {
+            type: 'array',
+            description: '要应用的修改列表，按顺序执行',
+            items: {
+              type: 'object',
+              properties: {
+                find: { type: 'string', description: '要被替换的原文（必须唯一出现）' },
+                replace: { type: 'string', description: '替换成的新内容，可以是空串（表示删除）' },
+                all: { type: 'boolean', description: '允许 find 出现多次并全部替换，默认 false' },
+              },
+              required: ['find'],
+            },
+          },
+        },
+        required: ['path', 'edits'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'write_file',
+      description:
+        '把内容写入工作目录内的文件（存在则整体覆盖，不存在则新建，父目录会自动创建）。' +
+        '这是整体覆盖而非增量修改，务必先 read_file 拿到完整内容再写；只改几处请优先用 apply_patch。执行前需要用户批准。',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '相对工作目录的文件路径' },
+          content: { type: 'string', description: '要写入的完整文件内容' },
+        },
+        required: ['path', 'content'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'bash',
+      description:
+        '在工作目录内执行一条 shell 命令并返回输出。默认关闭，只有宿主显式开启后才可用；' +
+        '有超时与输出截断，每次执行都需要用户批准（自动模式下不再逐个确认）。' +
+        (process.platform === 'win32'
+          ? '本机是 Windows：命令经 cmd.exe 执行，只有 cmd 内建命令与 PATH 里的程序可用 —— '
+            + '不要用 tail / head / grep / sed / cat 这类 Unix 命令，'
+            + '需要截断或筛选请改用程序自带参数（如 pytest -q、--maxfail=1、node -e）。'
+          : '本机是类 Unix：命令经 /bin/sh 执行。'),
+      parameters: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: '要执行的命令' },
+          timeout_ms: { type: 'number', description: `超时毫秒数，默认 ${BASH_TIMEOUT_MS}` },
+        },
+        required: ['command'],
+      },
+    },
+  },
+];
+
+// 内置工具名登记给 MCP 层：远端工具与内置同名时必须让位（内置带工作目录沙箱语义）。
+// 放在这里而不是 mcp.js 里，是因为内置清单的**唯一出处**就是本文件的 TOOLS。
+setMcpReserved(TOOLS.map((t) => t.function.name));
+
+const WRITE_TOOLS = new Set(['write_file', 'apply_patch', 'bash']);
+/**
+ * **要人工批准**的工具：只有会改动本机文件的这三支。
+ *
+ * 这是**唯一**的审批闸门。远端 MCP 调用**不**走它——理由是一个真实的踩坑：
+ * 原先 MCP 也算「写入类」，于是非交互 `-p` 模式（默认拒绝写入）下**每一次 MCP 调用
+ * 都要 y/N**，实际表现是「所有地图/搜索工具全部被拒」，任务一行工具都跑不出来。
+ * 而想绕过就只能加 `--yes`，那又会把**任意文件写入**一起放开——用一个更大的权限
+ * 去换一个更小的功能，这个交换不成立。所以 MCP 改成直接执行（每次调用照样通过
+ * `tool_call` 事件打出来，用户看得见），审批闸门只留给真正改本机文件的工具。
+ */
+export const isFileWriteTool = (name) => WRITE_TOOLS.has(name);
+
+/**
+ * **计划模式下不给模型**的工具：本机写入 + 远端 MCP。
+ *
+ * 注意它和上面的 `isFileWriteTool` **不是一回事**，别合并：
+ * 「计划模式只做本地只读调研」是产品边界（MCP 会出网、有副作用、要花钱），
+ * 与「执行前要不要人工批准」无关。合成一个谓词的话，改任一边都会静默改掉另一边。
+ */
+export const isWriteTool = (name) => WRITE_TOOLS.has(name) || isMcpTool(name);
+
+/** 当前可用工具：bash 没开启时直接从清单里摘掉，模型就不会去试 */
+export function availableTools() {
+  const builtins = bashEnabled ? TOOLS : TOOLS.filter((t) => t.function.name !== 'bash');
+  // MCP 工具与内置常量合并。重名以内置为准：内置工具带沙箱语义，
+  // 不能被远端同名工具顶掉（mcpToolSpecs 的 reserved 参数就是为此传入）。
+  return [...builtins, ...mcpToolSpecs(new Set(TOOLS.map((t) => t.function.name)))];
+}
+
+/** 给 UI 用的一句话描述 */
+export function describeCall(name, args = {}) {
+  switch (name) {
+    case 'list_dir':
+      return `列出目录 ${args.path || '.'}`;
+    case 'read_file':
+      return `读取文件 ${args.path || '?'}`;
+    case 'search_files':
+      return `搜索 “${args.query || '?'}”${args.path ? ` @ ${args.path}` : ''}`;
+    case 'glob':
+      return `按模式查找 ${args.pattern || '?'}${args.path ? ` @ ${args.path}` : ''}`;
+    case 'grep':
+      return `正则搜索 ${args.pattern || '?'}${args.path ? ` @ ${args.path}` : ''}`;
+    case 'apply_patch': {
+      const n = Array.isArray(args.edits) ? args.edits.length : 0;
+      return `修改文件 ${args.path || '?'}（${n} 处）`;
+    }
+    case 'write_file':
+      return `写入文件 ${args.path || '?'}`;
+    case 'bash':
+      return `执行命令 ${String(args.command || '?').slice(0, 80)}`;
+    default:
+      // MCP 工具走专用文案（带服务器与参数摘要），未知名字保持原样
+      return isMcpTool(name) ? describeMcpCall(name, args) : `调用 ${name}`;
+  }
+}
+
+// ---------- 工作目录校验与沙箱 ----------
+
+export function checkWorkDir(dir) {
+  if (typeof dir !== 'string' || !dir.trim()) {
+    throw Object.assign(new Error('未指定工作目录'), { status: 400 });
+  }
+  const abs = path.resolve(dir.trim());
+  if (!existsSync(abs)) throw Object.assign(new Error(`工作目录不存在：${abs}`), { status: 400 });
+  if (!statSync(abs).isDirectory()) throw Object.assign(new Error(`工作目录不是目录：${abs}`), { status: 400 });
+  return abs;
+}
+
+function resolveInRoot(root, p) {
+  const raw = typeof p === 'string' && p.trim() ? p.trim() : '.';
+  const abs = path.resolve(root, raw);
+  const rel = path.relative(root, abs);
+  if (rel !== '' && (rel.startsWith('..') || path.isAbsolute(rel))) {
+    throw new Error(`路径越界：${raw} 不在工作目录内`);
+  }
+  return abs;
+}
+
+/** 符号链接复核：不存在的路径回退到最近的存在祖先，再 realpath 比对 */
+function assertNoEscape(root, abs) {
+  let realRoot;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    return; // 工作目录本身取不到 realpath 时，字符串检查已经生效，放过
+  }
+  let probe = abs;
+  while (!existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  let real;
+  try {
+    real = realpathSync(probe);
+  } catch {
+    return;
+  }
+  const rel = path.relative(realRoot, real);
+  if (rel !== '' && (rel.startsWith('..') || path.isAbsolute(rel))) {
+    throw new Error('路径越界：该路径经符号链接指向工作目录之外');
+  }
+}
+
+/**
+ * 在工作目录内安全写文件 —— 供**服务端自己决定内容**的写入复用同一套沙箱
+ * （`/api/init` 生成项目记忆文件）。模型发起的写入不走这里：那条路必须经过用户审批。
+ *
+ * 越界检查与工具走同一条（`resolveInRoot` + `assertNoEscape`），不做任何额外放行。
+ *
+ * @returns {{path:string, rel:string, bytes:number, overwrote:boolean}}
+ */
+export function writeInsideRoot(root, rel, text, { overwrite = false } = {}) {
+  const absRoot = checkWorkDir(root);
+  const abs = resolveInRoot(absRoot, rel);
+  assertNoEscape(absRoot, abs);
+  const existed = existsSync(abs);
+  if (existed && !overwrite) {
+    throw Object.assign(new Error(`文件已存在：${relTo(absRoot, abs)}（要覆盖请显式加 --force）`), { status: 409 });
+  }
+  const parent = path.dirname(abs);
+  if (!existsSync(parent)) {
+    throw Object.assign(new Error(`上级目录不存在：${relTo(absRoot, parent)}`), { status: 400 });
+  }
+  const payload = String(text ?? '');
+  writeFileSync(abs, payload, 'utf8');
+  return { path: abs, rel: relTo(absRoot, abs), bytes: Buffer.byteLength(payload, 'utf8'), overwrote: existed };
+}
+
+const relTo = (root, abs) => path.relative(root, abs).split(path.sep).join('/') || '.';
+
+function looksBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+const fmtSize = (n) => (n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`);
+
+/** 真实行数：末尾换行不算多出一行（"a\nb\n" 是 2 行，不是 3 行） */
+function countLines(text) {
+  if (!text) return 0;
+  const n = text.split('\n').length;
+  return text.endsWith('\n') ? n - 1 : n;
+}
+
+/* ---------- 增量编辑（apply_patch 的核心，纯函数，便于单测） ---------- */
+
+/**
+ * 按 edits 依次修改文本。任何一处 find 找不到或（未开 all 时）不唯一，就整体失败，
+ * 由调用方保证「不落盘」—— 宁可什么都不改，也不要改一半。
+ *
+ * @returns {{text:string, applied:number}}
+ */
+export function applyEdits(text, edits) {
+  if (!Array.isArray(edits) || !edits.length) throw new Error('edits 不能为空，至少要给一处修改');
+  let out = text;
+  let applied = 0;
+  for (let i = 0; i < edits.length; i++) {
+    const e = edits[i];
+    const find = typeof e?.find === 'string' ? e.find : typeof e?.old_string === 'string' ? e.old_string : null;
+    if (!find) throw new Error(`第 ${i + 1} 处修改缺少 find（要替换的原文）`);
+    const replace = typeof e?.replace === 'string' ? e.replace : typeof e?.new_string === 'string' ? e.new_string : '';
+    const all = e?.all === true;
+    const parts = out.split(find);
+    const hits = parts.length - 1;
+    if (hits === 0) throw new Error(`第 ${i + 1} 处修改：在工作目录的文件里找不到要替换的原文（find 片段不匹配，注意缩进与换行）`);
+    if (hits > 1 && !all) {
+      throw new Error(`第 ${i + 1} 处修改：find 片段出现了 ${hits} 次，不唯一 —— 请给出更长的上下文，或显式加 all: true 表示全部替换`);
+    }
+    // 未开 all 时上面已保证 hits === 1，两种情况都是「把匹配到的片段换成 replace」
+    out = parts.join(replace);
+    applied++;
+  }
+  return { text: out, applied };
+}
+
+/* ---------- 具体工具实现 ---------- */
+
+function toolListDir(root, p) {
+  const abs = resolveInRoot(root, p);
+  assertNoEscape(root, abs);
+  if (!existsSync(abs)) throw new Error(`目录不存在：${relTo(root, abs)}`);
+  if (!statSync(abs).isDirectory()) throw new Error(`${relTo(root, abs)} 不是目录，请用 read_file`);
+
+  const items = [];
+  for (const name of readdirSync(abs)) {
+    let st;
+    try {
+      st = statSync(path.join(abs, name));
+    } catch {
+      continue;
+    }
+    items.push({ name, dir: st.isDirectory(), size: st.isDirectory() ? 0 : st.size });
+  }
+  items.sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name, 'zh') : a.dir ? -1 : 1));
+
+  const shown = items.slice(0, 400);
+  const lines = shown.map((it) => (it.dir ? `${it.name}/` : `${it.name}  (${fmtSize(it.size)})`));
+  const more = items.length > shown.length ? `\n…（另有 ${items.length - shown.length} 项未显示）` : '';
+  return {
+    ok: true,
+    summary: `列出 ${relTo(root, abs)}：${items.length} 项`,
+    content: lines.length ? lines.join('\n') + more : '（空目录）',
+  };
+}
+
+function toolReadFile(root, p) {
+  const abs = resolveInRoot(root, p);
+  assertNoEscape(root, abs);
+  if (!existsSync(abs)) throw new Error(`文件不存在：${relTo(root, abs)}`);
+  const st = statSync(abs);
+  if (st.isDirectory()) throw new Error(`${relTo(root, abs)} 是目录，请用 list_dir`);
+  if (st.size > MAX_READ_BYTES) {
+    throw new Error(`文件过大（${fmtSize(st.size)}），超过 ${fmtSize(MAX_READ_BYTES)} 上限，无法整体读取`);
+  }
+  const buf = readFileSync(abs);
+  if (looksBinary(buf)) throw new Error(`${relTo(root, abs)} 看起来是二进制文件，已拒绝读取`);
+
+  // 只把文件原文交给模型（不带行号），避免模型把行号一起写回文件
+  const text = buf.toString('utf8');
+  return {
+    ok: true,
+    summary: `读取 ${relTo(root, abs)}：${countLines(text)} 行 / ${fmtSize(st.size)}`,
+    content: text,
+  };
+}
+
+function* walk(dir, root, budget) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (budget.files >= MAX_SEARCH_FILES) return;
+    const full = path.join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(name)) continue;
+      yield* walk(full, root, budget);
+    } else if (st.isFile()) {
+      budget.files++;
+      if (st.size > MAX_SEARCH_FILE_BYTES) continue;
+      yield { full, size: st.size };
+    }
+  }
+}
+
+function toolSearchFiles(root, query, p) {
+  const q = typeof query === 'string' ? query.trim() : '';
+  if (!q) throw new Error('query 不能为空');
+  const base = resolveInRoot(root, p);
+  assertNoEscape(root, base);
+  if (!existsSync(base)) throw new Error(`目录不存在：${relTo(root, base)}`);
+
+  const needle = q.toLowerCase();
+  const budget = { files: 0 };
+  const hits = [];
+  let scanned = 0;
+
+  for (const file of walk(base, root, budget)) {
+    let buf;
+    try {
+      buf = readFileSync(file.full);
+    } catch {
+      continue;
+    }
+    if (looksBinary(buf)) continue;
+    scanned++;
+    const text = buf.toString('utf8');
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].toLowerCase().includes(needle)) {
+        hits.push(`${relTo(root, file.full)}:${i + 1}: ${lines[i].trim().slice(0, 200)}`);
+        if (hits.length >= MAX_SEARCH_RESULTS) break;
+      }
+    }
+    if (hits.length >= MAX_SEARCH_RESULTS) break;
+  }
+
+  return {
+    ok: true,
+    summary: hits.length ? `搜索 “${q}”：命中 ${hits.length} 处于 ${scanned} 个文件` : `搜索 “${q}”：无命中（已扫描 ${scanned} 个文件）`,
+    content: hits.length
+      ? hits.join('\n') + (hits.length >= MAX_SEARCH_RESULTS ? `\n…（已达到 ${MAX_SEARCH_RESULTS} 条上限，请缩小范围）` : '')
+      : '无命中。可以换关键字，或用 list_dir 先看目录结构。',
+  };
+}
+
+/* ---------- glob ---------- */
+
+/** 把 glob 编译成正则：支持 *、**、?、{a,b}；不含斜杠的模式按 “**” 加 “/” 前缀处理 */
+export function globToRegExp(pattern) {
+  let s = String(pattern || '').replace(/\\/g, '/').trim();
+  if (!s) throw new Error('pattern 不能为空');
+  if (!s.includes('/')) s = `**/${s}`;
+  let re = '';
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === '*') {
+      if (s[i + 1] === '*') {
+        i++;
+        if (s[i + 1] === '/') {
+          i++;
+          re += '(?:[^/]+/)*'; // **/ 匹配任意层级（含零层）
+        } else {
+          re += '.*';
+        }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (c === '{') {
+      const close = s.indexOf('}', i);
+      if (close === -1) {
+        re += '\\{';
+      } else {
+        const alts = s
+          .slice(i + 1, close)
+          .split(',')
+          .map((x) => x.replace(/[.+^${}()|[\]\\]/g, '\\$&'));
+        re += `(?:${alts.join('|')})`;
+        i = close;
+      }
+    } else if ('.+^$()|[]\\'.includes(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function toolGlob(root, pattern, p) {
+  const re = globToRegExp(pattern);
+  const base = resolveInRoot(root, p);
+  assertNoEscape(root, base);
+  if (!existsSync(base)) throw new Error(`目录不存在：${relTo(root, base)}`);
+
+  const budget = { files: 0 };
+  const hits = [];
+  for (const file of walk(base, root, budget)) {
+    const rel = relTo(root, file.full);
+    if (re.test(rel)) {
+      hits.push(`${rel}  (${fmtSize(file.size)})`);
+      if (hits.length >= MAX_GLOB_RESULTS) break;
+    }
+  }
+  hits.sort();
+  return {
+    ok: true,
+    summary: hits.length ? `匹配 “${pattern}”：${hits.length} 个文件` : `匹配 “${pattern}”：没有文件命中`,
+    content: hits.length
+      ? hits.join('\n') + (hits.length >= MAX_GLOB_RESULTS ? `\n…（已达到 ${MAX_GLOB_RESULTS} 条上限，请缩小范围）` : '')
+      : '没有命中的文件。换个模式（如 **/*.js）或用 list_dir 先看目录结构。',
+  };
+}
+
+/* ---------- grep ---------- */
+
+function toolGrep(root, pattern, p, ignoreCase) {
+  const src = typeof pattern === 'string' ? pattern : '';
+  if (!src.trim()) throw new Error('pattern 不能为空');
+  let re;
+  try {
+    re = new RegExp(src, ignoreCase ? 'i' : '');
+  } catch (e) {
+    throw new Error(`正则表达式非法：${e?.message || e}`);
+  }
+  const base = resolveInRoot(root, p);
+  assertNoEscape(root, base);
+  if (!existsSync(base)) throw new Error(`目录不存在：${relTo(root, base)}`);
+
+  const budget = { files: 0 };
+  const hits = [];
+  let scanned = 0;
+  for (const file of walk(base, root, budget)) {
+    let buf;
+    try {
+      buf = readFileSync(file.full);
+    } catch {
+      continue;
+    }
+    if (looksBinary(buf)) continue;
+    scanned++;
+    const lines = buf.toString('utf8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      re.lastIndex = 0;
+      if (re.test(lines[i])) {
+        hits.push(`${relTo(root, file.full)}:${i + 1}: ${lines[i].trim().slice(0, 200)}`);
+        if (hits.length >= MAX_SEARCH_RESULTS) break;
+      }
+    }
+    if (hits.length >= MAX_SEARCH_RESULTS) break;
+  }
+  return {
+    ok: true,
+    summary: hits.length ? `正则 “${src}”：命中 ${hits.length} 处于 ${scanned} 个文件` : `正则 “${src}”：无命中（已扫描 ${scanned} 个文件）`,
+    content: hits.length
+      ? hits.join('\n') + (hits.length >= MAX_SEARCH_RESULTS ? `\n…（已达到 ${MAX_SEARCH_RESULTS} 条上限，请缩小范围）` : '')
+      : '无命中。可以放宽正则，或先用 glob 找到候选文件。',
+  };
+}
+
+/* ---------- 写入 ---------- */
+
+function toolWriteFile(root, p, content) {
+  if (typeof content !== 'string') throw new Error('content 必须是字符串');
+  if (Buffer.byteLength(content) > MAX_WRITE_BYTES) {
+    throw new Error(`内容过大（${fmtSize(Buffer.byteLength(content))}），超过 ${fmtSize(MAX_WRITE_BYTES)} 上限`);
+  }
+  const abs = resolveInRoot(root, p);
+  assertNoEscape(root, abs);
+  if (existsSync(abs) && statSync(abs).isDirectory()) throw new Error(`${relTo(root, abs)} 是目录，不能写入`);
+
+  const existed = existsSync(abs);
+  const before = existed ? readFileSync(abs, 'utf8') : '';
+  mkdirSync(path.dirname(abs), { recursive: true });
+  writeFileSync(abs, content, 'utf8');
+
+  let delta = '';
+  if (existed && before !== content) {
+    const b = countLines(before);
+    const a = countLines(content);
+    delta = `（${b} 行 → ${a} 行）`;
+  }
+  return {
+    ok: true,
+    summary: `${existed ? '已更新' : '已新建'} ${relTo(root, abs)} ${delta}`.trim(),
+    content: `写入成功：${relTo(root, abs)}，${Buffer.byteLength(content)} 字节。`,
+  };
+}
+
+/** 读文件原文用于计算预览（走同一套沙箱，不另开一条读路径） */
+function readTextInRoot(root, p) {
+  const abs = resolveInRoot(root, p);
+  assertNoEscape(root, abs);
+  if (!existsSync(abs)) return { abs, text: null };
+  const st = statSync(abs);
+  if (!st.isDirectory() && st.size <= MAX_READ_BYTES) {
+    const buf = readFileSync(abs);
+    if (!looksBinary(buf)) return { abs, text: buf.toString('utf8') };
+  }
+  return { abs, text: null };
+}
+
+function toolApplyPatch(root, p, edits) {
+  const { abs, text } = readTextInRoot(root, p);
+  if (text === null) throw new Error(`${relTo(root, abs)} 不存在或不可读 —— apply_patch 只能修改已存在的文本文件，新建请用 write_file`);
+  const { text: next, applied } = applyEdits(text, edits);
+  if (next === text) {
+    return { ok: true, summary: `${relTo(root, abs)} 无需改动（替换结果与原文一致）`, content: `未发生变化：${relTo(root, abs)}` };
+  }
+  if (Buffer.byteLength(next) > MAX_WRITE_BYTES) {
+    throw new Error(`修改后内容过大（${fmtSize(Buffer.byteLength(next))}），超过 ${fmtSize(MAX_WRITE_BYTES)} 上限`);
+  }
+  writeFileSync(abs, next, 'utf8');
+  const b = countLines(text);
+  const a = countLines(next);
+  return {
+    ok: true,
+    summary: `已修改 ${relTo(root, abs)}（${applied} 处，${b} 行 → ${a} 行）`,
+    content: `修改成功：${relTo(root, abs)}，应用 ${applied} 处替换，${Buffer.byteLength(next)} 字节。`,
+  };
+}
+
+/* ---------- bash ---------- */
+
+/**
+ * 杀掉整棵进程树。
+ * Windows 上 shell 只是个 cmd.exe 中转壳，真正的命令是它的子进程 —— 只杀壳子
+ * 会留下「已经报告被终止、其实还在跑」的孤儿（实测：超时 300ms 报「已终止」，
+ * 但那句 node 睡满 5 秒才退，期间还占着工作目录）。所以必须按树杀。
+ */
+function killTree(child) {
+  if (!child || !child.pid) return;
+  if (process.platform === 'win32') {
+    try {
+      spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      return;
+    } catch {
+      /* 落到下面的兜底 */
+    }
+  }
+  try {
+    child.kill('SIGKILL');
+  } catch {
+    /* 已经结束了 */
+  }
+}
+
+/**
+ * 跑一条 shell 命令，带超时与整树终止。
+ * 用异步 spawn 而不是 spawnSync：spawnSync 超时后我们手里已经没有活着的壳子了，
+ * 想按树杀也找不到父进程，只能干看着孤儿继续跑。
+ */
+function runShell(root, cmd, timeout) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, { cwd: root, shell: true, windowsHide: true });
+    } catch (e) {
+      resolve({ stdout: '', stderr: '', status: null, timedOut: false, error: e });
+      return;
+    }
+    const CAP = 4 * 1024 * 1024;
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+    }, timeout);
+
+    const onData = (buf, which) => {
+      const s = String(buf);
+      if (which === 'out') {
+        if (stdout.length < CAP) stdout += s;
+      } else if (stderr.length < CAP) {
+        stderr += s;
+      }
+    };
+    child.stdout?.on('data', (d) => onData(d, 'out'));
+    child.stderr?.on('data', (d) => onData(d, 'err'));
+
+    const finish = (code, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ stdout, stderr, status: code, timedOut, error: error || null });
+    };
+    child.on('error', (e) => finish(null, e));
+    child.on('close', (code) => finish(code, null));
+  });
+}
+
+async function toolBash(root, command, timeoutMs) {
+  if (!bashEnabled) throw new Error('bash 工具未启用（默认关闭，需宿主显式开启）');
+  const cmd = typeof command === 'string' ? command.trim() : '';
+  if (!cmd) throw new Error('command 不能为空');
+  const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, 120000) : BASH_TIMEOUT_MS;
+
+  const r = await runShell(root, cmd, timeout);
+  if (r.error) throw new Error(`命令执行失败：${r.error.message}`);
+  if (r.timedOut) throw new Error(`命令超时（超过 ${timeout} ms）已被终止`);
+  const parts = [];
+  if (r.stdout) parts.push(String(r.stdout));
+  if (r.stderr) parts.push(`[stderr]\n${String(r.stderr)}`);
+  let out = parts.join('\n').trim();
+  if (!out) out = '(无输出)';
+  if (out.length > MAX_BASH_OUTPUT) out = `${out.slice(0, MAX_BASH_OUTPUT)}\n…（输出已截断）`;
+  const code = r.status ?? 0;
+  return {
+    ok: code === 0,
+    summary: `命令退出码 ${code}：${cmd.slice(0, 60)}`,
+    content: `$ ${cmd}\n${out}`,
+  };
+}
+
+/**
+ * 执行一个工具调用。写入类工具必须显式 allowWrite 才放行。
+ * 返回 { ok, summary, content }；失败时抛错由调用方转成 tool 结果。
+ *
+ * `mcp`：MCP 工具要带上的上下文 `{ planNode, sessionId }`（本机工具用不到）。
+ * 由调用方（agent 的主循环）从**上一轮对话响应头**取到——见 mcp.js 的说明。
+ */
+export async function executeTool(name, args, root, { allowWrite = false, mcp = null } = {}) {
+  const a = args && typeof args === 'object' ? args : {};
+  // 只有**改本机文件**的工具需要批准；MCP 调用不走这道闸门（见 isFileWriteTool 的说明）
+  if (isFileWriteTool(name) && !allowWrite) throw new Error('写入操作未获用户批准，已拒绝执行');
+  // MCP 工具不在本机执行：转给网关，由它统一限流、写审计、转发第三方
+  if (isMcpTool(name)) return callMcpTool(name, a, mcp);
+  switch (name) {
+    case 'list_dir':
+      return toolListDir(root, a.path);
+    case 'read_file':
+      return toolReadFile(root, a.path);
+    case 'search_files':
+      return toolSearchFiles(root, a.query, a.path);
+    case 'glob':
+      return toolGlob(root, a.pattern, a.path);
+    case 'grep':
+      return toolGrep(root, a.pattern, a.path, a.ignore_case === true);
+    case 'apply_patch':
+      return toolApplyPatch(root, a.path, a.edits);
+    case 'write_file':
+      return toolWriteFile(root, a.path, a.content);
+    case 'bash':
+      return toolBash(root, a.command, a.timeout_ms);
+    default:
+      throw new Error(`未知工具：${name}`);
+  }
+}
+
+/**
+ * 写入批准弹窗需要的预览。
+ * `old` 是改动前的原文（截断），供审批界面渲染行级 diff —— 覆盖已有文件时，
+ * 只看新内容根本判断不出改了什么，这是审批闸门的关键一环。
+ */
+export function writePreview(root, args = {}) {
+  const name = args.__tool || 'write_file';
+
+  // MCP 工具没有本地文件可预览：给「服务器 · 工具 + 参数 JSON」，
+  // 让批准弹窗照样说明「这次要干什么」（复用既有面板，不改前端渲染）
+  if (isMcpTool(name)) return mcpPreview(name, args);
+
+  if (name === 'bash') {
+    const command = typeof args.command === 'string' ? args.command : '';
+    return { path: `$ ${command}`, exists: false, bytes: Buffer.byteLength(command), lines: 1, content: command, old: null, shell: true };
+  }
+
+  const isPatch = name === 'apply_patch';
+  let target = args.path || '?';
+  let exists = false;
+  let old = null;
+  let content = '';
+  let note = '';
+
+  if (isPatch) {
+    try {
+      const { abs, text } = readTextInRoot(root, args.path);
+      target = relTo(root, abs);
+      old = text;
+      exists = text !== null;
+      if (text === null) {
+        note = '（文件不存在或不可读，执行时会失败 —— 新建文件请用 write_file）';
+      } else {
+        try {
+          content = applyEdits(text, args.edits).text;
+        } catch (e) {
+          content = text;
+          note = `（无法应用修改：${e?.message || e}）`;
+        }
+      }
+    } catch (e) {
+      note = `（路径非法：${e?.message || e}）`;
+    }
+  } else {
+    content = typeof args.content === 'string' ? args.content : '';
+    try {
+      const { abs } = readTextInRoot(root, args.path);
+      exists = existsSync(abs) && !statSync(abs).isDirectory();
+      target = relTo(root, abs);
+      old = exists ? readTextInRoot(root, args.path).text : null;
+    } catch {
+      /* 路径非法就按原样展示，执行时会被沙箱拦下 */
+    }
+  }
+
+  const clip = (s) => (s && s.length > MAX_PREVIEW_CHARS ? `${s.slice(0, MAX_PREVIEW_CHARS)}\n…（预览截断）` : s);
+  return {
+    path: target,
+    exists,
+    bytes: Buffer.byteLength(content),
+    lines: countLines(content),
+    content: clip(content) || '',
+    old: clip(old),
+    patch: isPatch,
+    note,
+  };
+}
+
+// ---------- 目录浏览（给「选择工作目录」用，不受沙箱限制） ----------
+
+export function browseDir(absPath) {
+  const abs = path.resolve(String(absPath || ''));
+  if (!existsSync(abs)) throw Object.assign(new Error(`目录不存在：${abs}`), { status: 404 });
+  if (!statSync(abs).isDirectory()) throw Object.assign(new Error(`不是目录：${abs}`), { status: 400 });
+
+  const entries = [];
+  for (const name of readdirSync(abs)) {
+    let st;
+    try {
+      st = statSync(path.join(abs, name));
+    } catch {
+      continue; // 权限不足等，跳过
+    }
+    entries.push({ name, type: st.isDirectory() ? 'dir' : 'file', size: st.isDirectory() ? null : st.size });
+  }
+  entries.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name, 'zh') : a.type === 'dir' ? -1 : 1));
+
+  const parent = path.dirname(abs);
+  return {
+    path: abs,
+    parent: parent === abs ? null : parent,
+    entries: entries.slice(0, MAX_BROWSE_ENTRIES),
+    truncated: entries.length > MAX_BROWSE_ENTRIES,
+  };
+}
+
+/** 可用于起点选择的根目录：盘符 / 主目录 / 当前项目 */
+export function listRoots() {
+  const roots = [];
+  const add = (p, label) => {
+    try {
+      if (p && existsSync(p) && statSync(p).isDirectory()) roots.push({ path: p, label });
+    } catch {
+      /* 忽略无权限的盘符 */
+    }
+  };
+  add(process.cwd(), '当前项目目录');
+  add(os.homedir(), '用户主目录');
+  if (process.platform === 'win32') {
+    for (let c = 65; c <= 90; c++) {
+      const letter = String.fromCharCode(c);
+      add(`${letter}:\\`, `${letter}: 盘`);
+    }
+  } else {
+    for (const d of ['/', '/home', '/mnt', '/media', '/opt', '/srv', '/tmp']) add(d, d);
+  }
+  const seen = new Set();
+  return roots.filter((r) => (seen.has(r.path) ? false : (seen.add(r.path), true)));
+}