@zqagent/core 0.2.16 → 0.3.6

package/dist/tools/files.cjs

@@ -85,25 +85,24 @@ function resolveWithinRoot(workspace, target) {
 
 // src/tools/files.ts
 var DEFAULT_MAX_LINES = 2e3;
+var MULTI_READ_MAX_TOTAL_LINES = 1500;
 var MAX_LINE_CHARS = 500;
-function makeReadFile(workspace) {
+function makeReadFile(workspace, guard) {
   const root = path2.resolve(workspace);
-  return function read_file(args) {
-    const filePath = String(args.path ?? "");
-    const startLine = Math.max(1, Number(args.start_line ?? 1));
-    const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);
+  function readOne(filePath, startLine, maxLines) {
     const resolved = resolveWithinRoot(root, filePath);
     if (!resolved) {
-      return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
+      return { path: filePath, error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
     }
     const target = resolved.real;
     if (!fs2.existsSync(target) || !fs2.statSync(target).isFile()) {
-      return { error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
+      return { path: filePath, error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
     }
     const selected = [];
     let total = 0;
     try {
       const content = fs2.readFileSync(target, "utf-8");
+      guard?.noteRead(target, content);
       const lines = content.split("\n");
       total = lines.length;
       for (let i = startLine - 1; i < Math.min(startLine - 1 + maxLines, lines.length); i++) {
@@ -111,10 +110,10 @@ function makeReadFile(workspace) {
         if (text.length > MAX_LINE_CHARS) {
           text = text.slice(0, MAX_LINE_CHARS) + "\u2026 (line truncated)";
         }
-        selected.push(`${String(i + 1).padStart(6)}	${text}`);
+        selected.push(`${i + 1}|${text}`);
       }
     } catch (exc) {
-      return { error: `\u8BFB\u53D6\u5931\u8D25: ${String(exc)}` };
+      return { path: filePath, error: `\u8BFB\u53D6\u5931\u8D25: ${String(exc)}` };
     }
     const end = startLine + selected.length - 1;
     const result = {
@@ -128,9 +127,35 @@ function makeReadFile(workspace) {
       result.note = `\u663E\u793A\u7B2C ${startLine}-${end} \u884C\uFF0C\u5171 ${total} \u884C\uFF1B\u8C03\u7528 read_file(start_line=${end + 1}) \u7EE7\u7EED\u9605\u8BFB`;
     }
     return result;
+  }
+  return function read_file(args) {
+    const startLine = Math.max(1, Number(args.start_line ?? 1));
+    const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);
+    const paths = Array.isArray(args.paths) ? args.paths.map((p) => String(p ?? "")).filter(Boolean) : [];
+    if (paths.length > 0) {
+      const files = [];
+      let remainingLines = MULTI_READ_MAX_TOTAL_LINES;
+      for (const filePath2 of paths) {
+        const perFile = Math.min(maxLines, Math.max(1, remainingLines));
+        const one = readOne(filePath2, startLine, perFile);
+        files.push(one);
+        if (!one.error) remainingLines -= one.content.split("\n").length;
+        if (remainingLines <= 0) break;
+      }
+      return {
+        files,
+        count: files.length,
+        ...files.length < paths.length ? { note: `\u5DF2\u8FBE\u5230\u5355\u6B21\u591A\u6587\u4EF6\u8BFB\u53D6\u4E0A\u9650\uFF08\u5171 ${MULTI_READ_MAX_TOTAL_LINES} \u884C\uFF09\uFF0C\u5176\u4F59\u8DEF\u5F84\u672A\u8BFB\u53D6` } : {}
+      };
+    }
+    const filePath = String(args.path ?? "");
+    if (!filePath) {
+      return { error: "\u7F3A\u5C11 path\uFF08\u6216 paths\uFF09\u53C2\u6570" };
+    }
+    return readOne(filePath, startLine, maxLines);
   };
 }
-function makeWriteFile(workspace) {
+function makeWriteFile(workspace, guard) {
   const root = path2.resolve(workspace);
   return function write_file(args) {
     const filePath = String(args.path ?? "");
@@ -147,9 +172,12 @@ function makeWriteFile(workspace) {
     if (fs2.existsSync(target) && !overwrite) {
       return { error: "\u6587\u4EF6\u5DF2\u5B58\u5728 (overwrite=false)" };
     }
+    const conflict = guard?.checkWrite(target, filePath);
+    if (conflict) return { error: conflict.message };
     try {
       fs2.mkdirSync(path2.dirname(target), { recursive: true });
       fs2.writeFileSync(target, content, "utf-8");
+      guard?.noteWrite(target, content);
     } catch (exc) {
       return { error: `\u5199\u5165\u5931\u8D25: ${String(exc)}` };
     }
@@ -183,7 +211,7 @@ function makeListFiles(workspace) {
     }
   };
 }
-function makeReplaceInFile(workspace) {
+function makeReplaceInFile(workspace, guard) {
   const root = path2.resolve(workspace);
   return function replace_in_file(args) {
     const filePath = String(args.path ?? "");
@@ -197,6 +225,8 @@ function makeReplaceInFile(workspace) {
     if (!fs2.existsSync(target) || !fs2.statSync(target).isFile()) {
       return { error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
     }
+    const conflict = guard?.checkWrite(target, filePath);
+    if (conflict) return { error: conflict.message };
     try {
       const content = fs2.readFileSync(target, "utf-8");
       const count = content.split(oldStr).length - 1;
@@ -205,6 +235,7 @@ function makeReplaceInFile(workspace) {
       }
       const updated = content.replaceAll(oldStr, newStr);
       fs2.writeFileSync(target, updated, "utf-8");
+      guard?.noteWrite(target, updated);
       return {
         path: path2.relative(resolved.root, target),
         replacements: count,
@@ -216,8 +247,8 @@ function makeReplaceInFile(workspace) {
     }
   };
 }
-function registerReadOnlyFileTools(registry, workspace) {
-  const readFile = makeReadFile(workspace);
+function registerReadOnlyFileTools(registry, workspace, guard) {
+  const readFile = makeReadFile(workspace, guard);
   registry.register(
     (args) => readFile(args),
     { category: "filesystem", riskLevel: "low", capabilities: ["read_file"], requiresApproval: false },
@@ -225,15 +256,19 @@ function registerReadOnlyFileTools(registry, workspace) {
       type: "function",
       function: {
         name: "read_file",
-        description: "\u8BFB\u53D6\u6587\u672C\u6587\u4EF6\uFF0C\u8FD4\u56DE\u5E26\u884C\u53F7\u7684\u5185\u5BB9 (\u683C\u5F0F: '  12\\\\ttext')\uFF0C\u4EE5\u4FBF\u5F15\u7528\u4E3A path:line\u3002\u5927\u6587\u4EF6\u7A97\u53E3\u5316\uFF1A\u4F20\u9012 start_line \u4ECE\u4E0A\u4E00\u6B21\u8BFB\u53D6\u7684\u4F4D\u7F6E\u7EE7\u7EED\u3002\u53EA\u8BFB\u3002",
+        description: "\u8BFB\u53D6\u6587\u672C\u6587\u4EF6\uFF0C\u8FD4\u56DE\u5E26\u884C\u53F7\u7684\u5185\u5BB9 (\u683C\u5F0F: '12|text')\uFF0C\u4EE5\u4FBF\u5F15\u7528\u4E3A path:line\u3002path \u4E0E paths \u81F3\u5C11\u4F20\u4E00\u4E2A\u3002\u5927\u6587\u4EF6\u7A97\u53E3\u5316\uFF1A\u4F20\u9012 start_line \u4ECE\u4E0A\u4E00\u6B21\u8BFB\u53D6\u7684\u4F4D\u7F6E\u7EE7\u7EED\u3002\u9700\u8981\u540C\u65F6\u67E5\u770B\u591A\u4E2A\u6587\u4EF6/\u533A\u95F4\u65F6\u7528 paths \u4E00\u6B21\u8BFB\u53D6\uFF0C\u51CF\u5C11\u5F80\u8FD4\u3002\u53EA\u8BFB\u3002",
         parameters: {
           type: "object",
           properties: {
             path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84 (\u76F8\u5BF9\u4E8E\u5DE5\u4F5C\u533A)" },
+            paths: {
+              type: "array",
+              items: { type: "string" },
+              description: "\u4E00\u6B21\u8BFB\u53D6\u591A\u4E2A\u6587\u4EF6 (\u4E0E path \u4E8C\u9009\u4E00)\uFF1B\u591A\u4E2A\u5019\u9009\u6587\u4EF6\u5E94\u4E00\u6B21\u8BFB\u5B8C\uFF0C\u4E0D\u8981\u9010\u4E2A\u53D1\u8BF7\u6C42"
+            },
             start_line: { type: "integer", description: "\u8D77\u59CB\u884C\u53F7 (\u4ECE1\u5F00\u59CB\uFF0C\u9ED8\u8BA41)" },
-            max_lines: { type: "integer", description: `\u6700\u5927\u884C\u6570 (\u9ED8\u8BA4 ${DEFAULT_MAX_LINES})` }
-          },
-          required: ["path"]
+            max_lines: { type: "integer", description: `\u6700\u5927\u884C\u6570 (\u9ED8\u8BA4 ${DEFAULT_MAX_LINES}\uFF0C\u591A\u6587\u4EF6\u5408\u8BA1\u4E0A\u9650 ${MULTI_READ_MAX_TOTAL_LINES})` }
+          }
         }
       }
     }
@@ -258,9 +293,9 @@ function registerReadOnlyFileTools(registry, workspace) {
     }
   );
 }
-function registerFileTools(registry, workspace) {
-  registerReadOnlyFileTools(registry, workspace);
-  const writeFile = makeWriteFile(workspace);
+function registerFileTools(registry, workspace, guard) {
+  registerReadOnlyFileTools(registry, workspace, guard);
+  const writeFile = makeWriteFile(workspace, guard);
   registry.register(
     (args) => writeFile(args),
     { category: "filesystem", riskLevel: "medium", capabilities: ["write_file"], requiresApproval: true },
@@ -281,7 +316,7 @@ function registerFileTools(registry, workspace) {
       }
     }
   );
-  const replaceFile = makeReplaceInFile(workspace);
+  const replaceFile = makeReplaceInFile(workspace, guard);
   registry.register(
     (args) => replaceFile(args),
     { category: "filesystem", riskLevel: "medium", capabilities: ["edit_file"], requiresApproval: true },

package/dist/tools/files.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tools/files.ts","../../src/tools/pathSafety.ts"],"sourcesContent":["/**\n * 文件系统工具\n *\n * 提供 read_file / write_file / list_files 三个文件工具的实现，\n * 并注册到 ToolRegistry。所有工具都做了路径范围检查（限制在\n * 工作区内，防止通过 ../ 逃逸）。实现为工厂函数（makeXxx），\n * 以便为每个引擎实例绑定各自的工作区根目录。\n */\nimport * as fs from \"fs\";\nimport * as path from \"path\";\nimport { ToolRegistry, RiskClass, type ToolMetadata } from \"./ToolRegistry.js\";\nimport { resolveWithinRoot } from \"./pathSafety.js\";\n\n/** read_file 默认最大读取行数 */\nconst DEFAULT_MAX_LINES = 2000;\n/** 单行最大字符数（超长行截断，防止输出爆炸） */\nconst MAX_LINE_CHARS = 500;\n\n/**\n * read_file — 行号标注版 (对齐 Python 版)\n *\n * 返回带行号的内容，格式 '  12\\ttext'，便于引用为 path:line；\n * 大文件通过 start_line / max_lines 窗口化阅读。\n */\nfunction makeReadFile(workspace: string) {\n  const root = path.resolve(workspace);\n\n  return function read_file(args: Record<string, unknown>) {\n    const filePath = String(args.path ?? \"\");\n    const startLine = Math.max(1, Number(args.start_line ?? 1));\n    const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);\n\n    // 路径范围检查 + 存在性/文件类型检查。\n    // 用解析后的真实路径做后续 fs 操作，避免校验后 symlink 组件被替换。\n    const resolved = resolveWithinRoot(root, filePath);\n    if (!resolved) {\n      return { error: \"路径在工作区之外\" };\n    }\n    const target = resolved.real;\n    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {\n      return { error: `不是文件: ${filePath}` };\n    }\n\n    // 按窗口截取行，超长行截断并标注\n    const selected: string[] = [];\n    let total = 0;\n    try {\n      const content = fs.readFileSync(target, \"utf-8\");\n      const lines = content.split(\"\\n\");\n      total = lines.length;\n      for (let i = startLine - 1; i < Math.min(startLine - 1 + maxLines, lines.length); i++) {\n        let text = lines[i];\n        if (text.length > MAX_LINE_CHARS) {\n          text = text.slice(0, MAX_LINE_CHARS) + \"… (line truncated)\";\n        }\n        selected.push(`${String(i + 1).padStart(6)}\\t${text}`);\n      }\n    } catch (exc) {\n      return { error: `读取失败: ${String(exc)}` };\n    }\n\n    const end = startLine + selected.length - 1;\n    const result: Record<string, unknown> = {\n      path: path.relative(resolved.root, target),\n      start_line: startLine,\n      end_line: end,\n      total_lines: total,\n      content: selected.join(\"\\n\"),\n    };\n    // 文件未读完时提示继续阅读的入口\n    if (end < total) {\n      result.note = `显示第 ${startLine}-${end} 行，共 ${total} 行；调用 read_file(start_line=${end + 1}) 继续阅读`;\n    }\n    return result;\n  };\n}\n\n/**\n * write_file — 路径范围检查 + UTF-8 写入\n *\n * 自动创建父目录；overwrite=false 时拒绝覆盖已存在文件。\n */\nfunction makeWriteFile(workspace: string) {\n  const root = path.resolve(workspace);\n\n  return function write_file(args: Record<string, unknown>) {\n    const filePath = String(args.path ?? \"\");\n    const content = String(args.content ?? \"\");\n    const overwrite = args.overwrite !== false;\n\n    // 路径范围 + 类型检查（不能写目录、默认不覆盖已有文件）\n    const resolved = resolveWithinRoot(root, filePath);\n    if (!resolved) {\n      return { error: \"路径在工作区之外\" };\n    }\n    const target = resolved.real;\n    if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {\n      return { error: \"路径是目录，不是文件\" };\n    }\n    if (fs.existsSync(target) && !overwrite) {\n      return { error: \"文件已存在 (overwrite=false)\" };\n    }\n\n    try {\n      fs.mkdirSync(path.dirname(target), { recursive: true });\n      fs.writeFileSync(target, content, \"utf-8\");\n    } catch (exc) {\n      return { error: `写入失败: ${String(exc)}` };\n    }\n\n    return path.relative(resolved.root, target);\n  };\n}\n\n/**\n * list_files — 列出目录内容\n *\n * 跳过隐藏文件（. 开头）及 node_modules / __pycache__ / dist 等\n * 无意义目录；目录项以 / 后缀标识；结果按名称排序。\n */\nfunction makeListFiles(workspace: string) {\n  const root = path.resolve(workspace);\n\n  return function list_files(args: Record<string, unknown>) {\n    const dirPath = String(args.path ?? \".\");\n    const maxResults = Math.min(Number(args.max_results ?? 100), 100);\n    const resolved = resolveWithinRoot(root, dirPath);\n    if (!resolved) return { error: \"路径在工作区之外\" };\n    const target = resolved.real;\n    if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {\n      return { error: `不是目录: ${dirPath}` };\n    }\n\n    try {\n      const entries = fs.readdirSync(target, { withFileTypes: true });\n      const results: string[] = [];\n      for (const e of entries) {\n        if (results.length >= maxResults) break;\n        if (e.name.startsWith(\".\")) continue;\n        if (e.name === \"node_modules\" || e.name === \"__pycache__\" || e.name === \"dist\") continue;\n        results.push(e.isDirectory() ? `${e.name}/` : e.name);\n      }\n      results.sort();\n      return { path: path.relative(resolved.root, target), entries: results.slice(0, maxResults) };\n    } catch (exc) {\n      return { error: `列出文件失败: ${String(exc)}` };\n    }\n  };\n}\n\n/** replace_in_file — 精确文本替换 (对齐 Python 版 aisuite) */\nfunction makeReplaceInFile(workspace: string) {\n  const root = path.resolve(workspace);\n\n  return function replace_in_file(args: Record<string, unknown>) {\n    const filePath = String(args.path ?? \"\");\n    const oldStr = String(args.old ?? \"\");\n    const newStr = String(args.new ?? \"\");\n    const expectedReplacements = Math.max(1, Number(args.expected_replacements ?? 1));\n\n    if (!oldStr) return { error: \"old 不能为空\" };\n\n    const resolved = resolveWithinRoot(root, filePath);\n    if (!resolved) return { error: \"路径在工作区之外\" };\n    const target = resolved.real;\n    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {\n      return { error: `不是文件: ${filePath}` };\n    }\n\n    try {\n      const content = fs.readFileSync(target, \"utf-8\");\n      const count = content.split(oldStr).length - 1;\n\n      if (count !== expectedReplacements) {\n        return { error: `期望 ${expectedReplacements} 处替换，实际找到 ${count} 处: ${filePath}` };\n      }\n\n      const updated = content.replaceAll(oldStr, newStr);\n      fs.writeFileSync(target, updated, \"utf-8\");\n      return {\n        path: path.relative(resolved.root, target),\n        replacements: count,\n        chars_before: content.length,\n        chars_after: updated.length,\n      };\n    } catch (exc) {\n      return { error: `替换失败: ${String(exc)}` };\n    }\n  };\n}\n\n/**\n * 注册只读文件工具（read_file / list_files）。\n *\n * 供 explore 子代理等「只读」场景使用，使声明的 schema 与实际能力一致。\n */\nexport function registerReadOnlyFileTools(registry: ToolRegistry, workspace: string): void {\n  const readFile = makeReadFile(workspace);\n  registry.register(\n    (args) => readFile(args),\n    { category: \"filesystem\", riskLevel: \"low\", capabilities: [\"read_file\"], requiresApproval: false },\n    {\n      type: \"function\",\n      function: {\n        name: \"read_file\",\n        description: \"读取文本文件，返回带行号的内容 (格式: '  12\\\\\\\\ttext')，以便引用为 path:line。大文件窗口化：传递 start_line 从上一次读取的位置继续。只读。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"文件路径 (相对于工作区)\" },\n            start_line: { type: \"integer\", description: \"起始行号 (从1开始，默认1)\" },\n            max_lines: { type: \"integer\", description: `最大行数 (默认 ${DEFAULT_MAX_LINES})` },\n          },\n          required: [\"path\"],\n        },\n      },\n    },\n  );\n\n  const listFiles = makeListFiles(workspace);\n  registry.register(\n    (args) => listFiles(args),\n    { category: \"filesystem\", riskLevel: \"low\", capabilities: [\"list_files\"], requiresApproval: false },\n    {\n      type: \"function\",\n      function: {\n        name: \"list_files\",\n        description: \"列出目录下的文件和子目录。跳过隐藏文件和 node_modules 等目录。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"目录路径 (相对于工作区，默认 '.')\" },\n            max_results: { type: \"integer\", description: \"最大结果数 (默认 100)\" },\n          },\n        },\n      },\n    },\n  );\n}\n\n/**\n * 注册文件工具到 ToolRegistry\n *\n * read_file / list_files 为低风险（无需审批）；write_file / replace_in_file\n * 为中风险且 requiresApproval=true（由权限引擎决定是否需要审批）。\n */\nexport function registerFileTools(registry: ToolRegistry, workspace: string): void {\n  registerReadOnlyFileTools(registry, workspace);\n\n  const writeFile = makeWriteFile(workspace);\n  registry.register(\n    (args) => writeFile(args),\n    { category: \"filesystem\", riskLevel: \"medium\", capabilities: [\"write_file\"], requiresApproval: true },\n    {\n      type: \"function\",\n      function: {\n        name: \"write_file\",\n        description: \"写入一个 UTF-8 文本文件。用于创建新文件或完全重写现有文件。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"文件路径 (相对于工作区)\" },\n            content: { type: \"string\", description: \"文件内容 (UTF-8)\" },\n            overwrite: { type: \"boolean\", description: \"是否覆盖已存在的文件 (默认 true)\" },\n          },\n          required: [\"path\", \"content\"],\n        },\n      },\n    },\n  );\n\n  const replaceFile = makeReplaceInFile(workspace);\n  registry.register(\n    (args) => replaceFile(args),\n    { category: \"filesystem\", riskLevel: \"medium\", capabilities: [\"edit_file\"], requiresApproval: true },\n    {\n      type: \"function\",\n      function: {\n        name: \"replace_in_file\",\n        description: \"在文件中精确替换一段文本。先按预期次数精确匹配 old 字符串，然后替换为 new。用于小范围精确编辑。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"文件路径 (相对于工作区)\" },\n            old: { type: \"string\", description: \"要被替换的精确文本\" },\n            new: { type: \"string\", description: \"替换后的新文本\" },\n            expected_replacements: { type: \"integer\", description: \"期望的替换次数 (默认 1)\" },\n          },\n          required: [\"path\", \"old\", \"new\"],\n        },\n      },\n    },\n  );\n}\n","/**\n * 路径安全辅助函数\n *\n * 判断目标路径是否真正位于工作区根目录之内。\n *\n * 仅做字符串比较（path.relative）无法防御符号链接逃逸：\n * 工作区内若存在指向外部的 symlink，`workspace/link/secret.txt`\n * 的字符串前缀合法，但实际读写发生在链接目标（工作区外）。\n *\n * 因此这里用 fs.realpathSync 解析符号链接后再与根目录的 realpath\n * 比较。目标尚不存在（如 write_file 新建文件）时，向上回溯到最近\n * 已存在的祖先目录解析，再拼回剩余路径段。\n *\n * 校验通过时把解析后的真实路径一并返回：调用方必须用它（而非原始\n * 相对路径）做实际 fs 操作，否则「校验后、操作前」路径组件被替换为\n * 指向外部的 symlink 仍会逃逸（TOCTOU）。\n */\nimport * as fs from \"fs\";\nimport * as path from \"path\";\n\n/**\n * 判断 `path.relative(root, target)` 的结果是否落在 root 之内。\n *\n * 逃逸必然恰好是 `..` 或以 `..` + 分隔符开头，不能用 `startsWith(\"..\")`：\n * 工作区里名为 `..foo` 的合法条目会被误判为逃逸而拒绝。\n * 跨盘符时（Windows）path.relative 返回绝对路径，一并拒绝。\n */\nfunction isInsideRelative(rel: string): boolean {\n  return (\n    !path.isAbsolute(rel) && rel !== \"..\" && !rel.startsWith(`..${path.sep}`)\n  );\n}\n\n/** 是否为文件系统根（\"/\"、\"C:\\\\\"） */\nfunction isFilesystemRoot(p: string): boolean {\n  return path.parse(p).root === p;\n}\n\n/** 校验通过的路径：root 为工作区根的真实路径，real 为目标的真实路径 */\nexport interface ResolvedPath {\n  root: string;\n  real: string;\n}\n\n/**\n * 校验 target（相对 workspace 的路径）是否位于 workspace 内，并返回\n * 解析符号链接后的真实路径；不在工作区内时返回 null。\n *\n * - 解析符号链接：路径中任何 symlink 组件都会先 realpath 再校验；\n *   broken symlink（存在但无法解析）一律拒绝。\n * - 目标不存在时（写新文件）：回溯到最近存在的祖先做 realpath，\n *   再拼接剩余段，仍能捕获祖先链中的 symlink 逃逸。\n * - 工作区根若就是文件系统根（`WORKSPACE=/`）：此时任何绝对路径都在\n *   其内，等同没有沙箱，直接判为越界。\n */\nexport function resolveWithinRoot(\n  workspace: string,\n  target: string,\n): ResolvedPath | null {\n  const abs = path.resolve(workspace, target);\n\n  let rootReal: string;\n  try {\n    rootReal = fs.realpathSync(workspace);\n  } catch {\n    // 根目录不存在（如权限引擎尚未初始化工作区）：\n    // 没有实际目录结构即无 symlink 逃逸面，退化为纯字符串路径比较。\n    const rootAbs = path.resolve(workspace);\n    if (!isInsideRelative(path.relative(rootAbs, abs))) return null;\n    return { root: rootAbs, real: abs };\n  }\n  if (isFilesystemRoot(rootReal)) return null;\n\n  let real: string;\n  try {\n    real = fs.realpathSync(abs);\n  } catch {\n    // abs 不存在：向上回溯找最近存在的祖先\n    let probe = abs;\n    const tail: string[] = [];\n    for (;;) {\n      // 组件存在（含 broken symlink）但 realpath 失败 → 无法解析，拒绝\n      const exists = fs.existsSync(probe) || fs.lstatSync(probe, { throwIfNoEntry: false }) !== undefined;\n      if (exists) {\n        try {\n          real = path.join(fs.realpathSync(probe), ...tail);\n          break;\n        } catch {\n          return null;\n        }\n      }\n      tail.unshift(path.basename(probe));\n      const parent = path.dirname(probe);\n      if (parent === probe) return null; // 已到文件系统根\n      probe = parent;\n    }\n  }\n\n  if (!isInsideRelative(path.relative(rootReal, real))) return null;\n  return { root: rootReal, real };\n}\n\n/**\n * 判断 target 是否安全地位于 workspace 内（不需要真实路径时用这个）。\n *\n * 注意：删除类操作不应据此改用 realpath 去 unlink —— 那会删掉符号链接\n * 指向的目标而非链接本身；这类操作请用 resolveEntryWithinRoot。\n */\nexport function isWithinRoot(workspace: string, target: string): boolean {\n  return resolveWithinRoot(workspace, target) !== null;\n}\n\n/**\n * 解析「目录项本身」的路径：父目录取 realpath，最后一段保持原样。\n *\n * 供 unlink / rename 等作用于条目自身的操作用：父目录不可被 symlink\n * 替换，而最后一段若是符号链接，被操作的是链接本身，不会被跟随。\n */\nexport function resolveEntryWithinRoot(\n  workspace: string,\n  target: string,\n): ResolvedPath | null {\n  const abs = path.resolve(workspace, target);\n  const parent = resolveWithinRoot(workspace, path.dirname(abs));\n  if (!parent) return null;\n  return { root: parent.root, real: path.join(parent.real, path.basename(abs)) };\n}\n"],"mappings":"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","names":["fs","path"]}
+{"version":3,"sources":["../../src/tools/files.ts","../../src/tools/pathSafety.ts"],"sourcesContent":["/**\n * 文件系统工具\n *\n * 提供 read_file / write_file / list_files 三个文件工具的实现，\n * 并注册到 ToolRegistry。所有工具都做了路径范围检查（限制在\n * 工作区内，防止通过 ../ 逃逸）。实现为工厂函数（makeXxx），\n * 以便为每个引擎实例绑定各自的工作区根目录。\n */\nimport * as fs from \"fs\";\nimport * as path from \"path\";\nimport { ToolRegistry, RiskClass, type ToolMetadata } from \"./ToolRegistry.js\";\nimport { resolveWithinRoot } from \"./pathSafety.js\";\nimport type { ConflictGuard } from \"./conflictGuard.js\";\n\n/** read_file 默认最大读取行数 */\nconst DEFAULT_MAX_LINES = 2000;\n/** 单次多文件读取的总行数上限（防止一次返回撑爆上下文） */\nconst MULTI_READ_MAX_TOTAL_LINES = 1500;\n/** 单行最大字符数（超长行截断，防止输出爆炸） */\nconst MAX_LINE_CHARS = 500;\n\n/**\n * read_file — 行号标注版 (对齐 Python 版)\n *\n * 返回带行号的内容，格式 '12|text'，便于引用为 path:line；\n * 大文件通过 start_line / max_lines 窗口化阅读。\n *\n * 行号用最短分隔（`12|`）而不是 `padStart(6) + \\t`：行号前缀实测占\n * read_file 输出的 12.7%，每次迭代都要重发，瘦身属于纯无损节省。\n *\n * 也支持 paths 一次读取多个文件/区间：每次工具往返都要重发全部上下文，\n * 合并读取能直接减少迭代次数。\n */\nfunction makeReadFile(workspace: string, guard?: ConflictGuard) {\n  const root = path.resolve(workspace);\n\n  /** 读取单个窗口，返回结果对象（不抛错，失败转为 error 字段） */\n  function readOne(\n    filePath: string,\n    startLine: number,\n    maxLines: number,\n  ): Record<string, unknown> {\n    // 路径范围检查 + 存在性/文件类型检查。\n    // 用解析后的真实路径做后续 fs 操作，避免校验后 symlink 组件被替换。\n    const resolved = resolveWithinRoot(root, filePath);\n    if (!resolved) {\n      return { path: filePath, error: \"路径在工作区之外\" };\n    }\n    const target = resolved.real;\n    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {\n      return { path: filePath, error: `不是文件: ${filePath}` };\n    }\n\n    // 按窗口截取行，超长行截断并标注\n    const selected: string[] = [];\n    let total = 0;\n    try {\n      const content = fs.readFileSync(target, \"utf-8\");\n      // 记录本会话读到的版本：后续写入若发现磁盘内容已变（别的会话改过），\n      // 会被 ConflictGuard 拦下，而不是静默覆盖\n      guard?.noteRead(target, content);\n      const lines = content.split(\"\\n\");\n      total = lines.length;\n      for (let i = startLine - 1; i < Math.min(startLine - 1 + maxLines, lines.length); i++) {\n        let text = lines[i];\n        if (text.length > MAX_LINE_CHARS) {\n          text = text.slice(0, MAX_LINE_CHARS) + \"… (line truncated)\";\n        }\n        selected.push(`${i + 1}|${text}`);\n      }\n    } catch (exc) {\n      return { path: filePath, error: `读取失败: ${String(exc)}` };\n    }\n\n    const end = startLine + selected.length - 1;\n    const result: Record<string, unknown> = {\n      path: path.relative(resolved.root, target),\n      start_line: startLine,\n      end_line: end,\n      total_lines: total,\n      content: selected.join(\"\\n\"),\n    };\n    // 文件未读完时提示继续阅读的入口\n    if (end < total) {\n      result.note = `显示第 ${startLine}-${end} 行，共 ${total} 行；调用 read_file(start_line=${end + 1}) 继续阅读`;\n    }\n    return result;\n  }\n\n  return function read_file(args: Record<string, unknown>) {\n    const startLine = Math.max(1, Number(args.start_line ?? 1));\n    const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);\n\n    // 多文件模式：一次读取多个文件，均受同一窗口参数约束\n    const paths = Array.isArray(args.paths)\n      ? args.paths.map((p) => String(p ?? \"\")).filter(Boolean)\n      : [];\n    if (paths.length > 0) {\n      const files: Record<string, unknown>[] = [];\n      let remainingLines = MULTI_READ_MAX_TOTAL_LINES;\n      for (const filePath of paths) {\n        const perFile = Math.min(maxLines, Math.max(1, remainingLines));\n        const one = readOne(filePath, startLine, perFile);\n        files.push(one);\n        // 出错的文件不占预算；成功读取的按实际窗口扣减\n        if (!one.error) remainingLines -= (one.content as string).split(\"\\n\").length;\n        if (remainingLines <= 0) break;\n      }\n      return {\n        files,\n        count: files.length,\n        ...(files.length < paths.length\n          ? { note: `已达到单次多文件读取上限（共 ${MULTI_READ_MAX_TOTAL_LINES} 行），其余路径未读取` }\n          : {}),\n      };\n    }\n\n    const filePath = String(args.path ?? \"\");\n    if (!filePath) {\n      return { error: \"缺少 path（或 paths）参数\" };\n    }\n    return readOne(filePath, startLine, maxLines);\n  };\n}\n\n/**\n * write_file — 路径范围检查 + UTF-8 写入\n *\n * 自动创建父目录；overwrite=false 时拒绝覆盖已存在文件。\n */\nfunction makeWriteFile(workspace: string, guard?: ConflictGuard) {\n  const root = path.resolve(workspace);\n\n  return function write_file(args: Record<string, unknown>) {\n    const filePath = String(args.path ?? \"\");\n    const content = String(args.content ?? \"\");\n    const overwrite = args.overwrite !== false;\n\n    // 路径范围 + 类型检查（不能写目录、默认不覆盖已有文件）\n    const resolved = resolveWithinRoot(root, filePath);\n    if (!resolved) {\n      return { error: \"路径在工作区之外\" };\n    }\n    const target = resolved.real;\n    if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {\n      return { error: \"路径是目录，不是文件\" };\n    }\n    if (fs.existsSync(target) && !overwrite) {\n      return { error: \"文件已存在 (overwrite=false)\" };\n    }\n    // 只有本会话读过该文件时才校验：读过之后又被别的会话改动 → 拒绝覆盖\n    const conflict = guard?.checkWrite(target, filePath);\n    if (conflict) return { error: conflict.message };\n\n    try {\n      fs.mkdirSync(path.dirname(target), { recursive: true });\n      fs.writeFileSync(target, content, \"utf-8\");\n      guard?.noteWrite(target, content);\n    } catch (exc) {\n      return { error: `写入失败: ${String(exc)}` };\n    }\n\n    return path.relative(resolved.root, target);\n  };\n}\n\n/**\n * list_files — 列出目录内容\n *\n * 跳过隐藏文件（. 开头）及 node_modules / __pycache__ / dist 等\n * 无意义目录；目录项以 / 后缀标识；结果按名称排序。\n */\nfunction makeListFiles(workspace: string) {\n  const root = path.resolve(workspace);\n\n  return function list_files(args: Record<string, unknown>) {\n    const dirPath = String(args.path ?? \".\");\n    const maxResults = Math.min(Number(args.max_results ?? 100), 100);\n    const resolved = resolveWithinRoot(root, dirPath);\n    if (!resolved) return { error: \"路径在工作区之外\" };\n    const target = resolved.real;\n    if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {\n      return { error: `不是目录: ${dirPath}` };\n    }\n\n    try {\n      const entries = fs.readdirSync(target, { withFileTypes: true });\n      const results: string[] = [];\n      for (const e of entries) {\n        if (results.length >= maxResults) break;\n        if (e.name.startsWith(\".\")) continue;\n        if (e.name === \"node_modules\" || e.name === \"__pycache__\" || e.name === \"dist\") continue;\n        results.push(e.isDirectory() ? `${e.name}/` : e.name);\n      }\n      results.sort();\n      return { path: path.relative(resolved.root, target), entries: results.slice(0, maxResults) };\n    } catch (exc) {\n      return { error: `列出文件失败: ${String(exc)}` };\n    }\n  };\n}\n\n/** replace_in_file — 精确文本替换 (对齐 Python 版 aisuite) */\nfunction makeReplaceInFile(workspace: string, guard?: ConflictGuard) {\n  const root = path.resolve(workspace);\n\n  return function replace_in_file(args: Record<string, unknown>) {\n    const filePath = String(args.path ?? \"\");\n    const oldStr = String(args.old ?? \"\");\n    const newStr = String(args.new ?? \"\");\n    const expectedReplacements = Math.max(1, Number(args.expected_replacements ?? 1));\n\n    if (!oldStr) return { error: \"old 不能为空\" };\n\n    const resolved = resolveWithinRoot(root, filePath);\n    if (!resolved) return { error: \"路径在工作区之外\" };\n    const target = resolved.real;\n    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {\n      return { error: `不是文件: ${filePath}` };\n    }\n    // 先看本会话读到的版本是否已过期（被别的会话改过）\n    const conflict = guard?.checkWrite(target, filePath);\n    if (conflict) return { error: conflict.message };\n\n    try {\n      const content = fs.readFileSync(target, \"utf-8\");\n      const count = content.split(oldStr).length - 1;\n\n      if (count !== expectedReplacements) {\n        return { error: `期望 ${expectedReplacements} 处替换，实际找到 ${count} 处: ${filePath}` };\n      }\n\n      const updated = content.replaceAll(oldStr, newStr);\n      fs.writeFileSync(target, updated, \"utf-8\");\n      guard?.noteWrite(target, updated);\n      return {\n        path: path.relative(resolved.root, target),\n        replacements: count,\n        chars_before: content.length,\n        chars_after: updated.length,\n      };\n    } catch (exc) {\n      return { error: `替换失败: ${String(exc)}` };\n    }\n  };\n}\n\n/**\n * 注册只读文件工具（read_file / list_files）。\n *\n * 供 explore 子代理等「只读」场景使用，使声明的 schema 与实际能力一致。\n */\nexport function registerReadOnlyFileTools(\n  registry: ToolRegistry,\n  workspace: string,\n  guard?: ConflictGuard,\n): void {\n  const readFile = makeReadFile(workspace, guard);\n  registry.register(\n    (args) => readFile(args),\n    { category: \"filesystem\", riskLevel: \"low\", capabilities: [\"read_file\"], requiresApproval: false },\n    {\n      type: \"function\",\n      function: {\n        name: \"read_file\",\n        description: \"读取文本文件，返回带行号的内容 (格式: '12|text')，以便引用为 path:line。path 与 paths 至少传一个。大文件窗口化：传递 start_line 从上一次读取的位置继续。需要同时查看多个文件/区间时用 paths 一次读取，减少往返。只读。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"文件路径 (相对于工作区)\" },\n            paths: {\n              type: \"array\",\n              items: { type: \"string\" },\n              description: \"一次读取多个文件 (与 path 二选一)；多个候选文件应一次读完，不要逐个发请求\",\n            },\n            start_line: { type: \"integer\", description: \"起始行号 (从1开始，默认1)\" },\n            max_lines: { type: \"integer\", description: `最大行数 (默认 ${DEFAULT_MAX_LINES}，多文件合计上限 ${MULTI_READ_MAX_TOTAL_LINES})` },\n          },\n        },\n      },\n    },\n  );\n\n  const listFiles = makeListFiles(workspace);\n  registry.register(\n    (args) => listFiles(args),\n    { category: \"filesystem\", riskLevel: \"low\", capabilities: [\"list_files\"], requiresApproval: false },\n    {\n      type: \"function\",\n      function: {\n        name: \"list_files\",\n        description: \"列出目录下的文件和子目录。跳过隐藏文件和 node_modules 等目录。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"目录路径 (相对于工作区，默认 '.')\" },\n            max_results: { type: \"integer\", description: \"最大结果数 (默认 100)\" },\n          },\n        },\n      },\n    },\n  );\n}\n\n/**\n * 注册文件工具到 ToolRegistry\n *\n * read_file / list_files 为低风险（无需审批）；write_file / replace_in_file\n * 为中风险且 requiresApproval=true（由权限引擎决定是否需要审批）。\n */\nexport function registerFileTools(\n  registry: ToolRegistry,\n  workspace: string,\n  guard?: ConflictGuard,\n): void {\n  registerReadOnlyFileTools(registry, workspace, guard);\n\n  const writeFile = makeWriteFile(workspace, guard);\n  registry.register(\n    (args) => writeFile(args),\n    { category: \"filesystem\", riskLevel: \"medium\", capabilities: [\"write_file\"], requiresApproval: true },\n    {\n      type: \"function\",\n      function: {\n        name: \"write_file\",\n        description: \"写入一个 UTF-8 文本文件。用于创建新文件或完全重写现有文件。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"文件路径 (相对于工作区)\" },\n            content: { type: \"string\", description: \"文件内容 (UTF-8)\" },\n            overwrite: { type: \"boolean\", description: \"是否覆盖已存在的文件 (默认 true)\" },\n          },\n          required: [\"path\", \"content\"],\n        },\n      },\n    },\n  );\n\n  const replaceFile = makeReplaceInFile(workspace, guard);\n  registry.register(\n    (args) => replaceFile(args),\n    { category: \"filesystem\", riskLevel: \"medium\", capabilities: [\"edit_file\"], requiresApproval: true },\n    {\n      type: \"function\",\n      function: {\n        name: \"replace_in_file\",\n        description: \"在文件中精确替换一段文本。先按预期次数精确匹配 old 字符串，然后替换为 new。用于小范围精确编辑。\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            path: { type: \"string\", description: \"文件路径 (相对于工作区)\" },\n            old: { type: \"string\", description: \"要被替换的精确文本\" },\n            new: { type: \"string\", description: \"替换后的新文本\" },\n            expected_replacements: { type: \"integer\", description: \"期望的替换次数 (默认 1)\" },\n          },\n          required: [\"path\", \"old\", \"new\"],\n        },\n      },\n    },\n  );\n}\n","/**\n * 路径安全辅助函数\n *\n * 判断目标路径是否真正位于工作区根目录之内。\n *\n * 仅做字符串比较（path.relative）无法防御符号链接逃逸：\n * 工作区内若存在指向外部的 symlink，`workspace/link/secret.txt`\n * 的字符串前缀合法，但实际读写发生在链接目标（工作区外）。\n *\n * 因此这里用 fs.realpathSync 解析符号链接后再与根目录的 realpath\n * 比较。目标尚不存在（如 write_file 新建文件）时，向上回溯到最近\n * 已存在的祖先目录解析，再拼回剩余路径段。\n *\n * 校验通过时把解析后的真实路径一并返回：调用方必须用它（而非原始\n * 相对路径）做实际 fs 操作，否则「校验后、操作前」路径组件被替换为\n * 指向外部的 symlink 仍会逃逸（TOCTOU）。\n */\nimport * as fs from \"fs\";\nimport * as path from \"path\";\n\n/**\n * 判断 `path.relative(root, target)` 的结果是否落在 root 之内。\n *\n * 逃逸必然恰好是 `..` 或以 `..` + 分隔符开头，不能用 `startsWith(\"..\")`：\n * 工作区里名为 `..foo` 的合法条目会被误判为逃逸而拒绝。\n * 跨盘符时（Windows）path.relative 返回绝对路径，一并拒绝。\n *\n * 导出供自行做 `path.relative` 校验的调用方复用（如目录浏览新建目录、\n * git 面板的 repo / path 参数），避免各处重复写 `startsWith(\"..\")`。\n */\nexport function isInsideRelative(rel: string): boolean {\n  return (\n    !path.isAbsolute(rel) && rel !== \"..\" && !rel.startsWith(`..${path.sep}`)\n  );\n}\n\n/** 是否为文件系统根（\"/\"、\"C:\\\\\"） */\nfunction isFilesystemRoot(p: string): boolean {\n  return path.parse(p).root === p;\n}\n\n/** 校验通过的路径：root 为工作区根的真实路径，real 为目标的真实路径 */\nexport interface ResolvedPath {\n  root: string;\n  real: string;\n}\n\n/**\n * 校验 target（相对 workspace 的路径）是否位于 workspace 内，并返回\n * 解析符号链接后的真实路径；不在工作区内时返回 null。\n *\n * - 解析符号链接：路径中任何 symlink 组件都会先 realpath 再校验；\n *   broken symlink（存在但无法解析）一律拒绝。\n * - 目标不存在时（写新文件）：回溯到最近存在的祖先做 realpath，\n *   再拼接剩余段，仍能捕获祖先链中的 symlink 逃逸。\n * - 工作区根若就是文件系统根（`WORKSPACE=/`）：此时任何绝对路径都在\n *   其内，等同没有沙箱，直接判为越界。\n */\nexport function resolveWithinRoot(\n  workspace: string,\n  target: string,\n): ResolvedPath | null {\n  const abs = path.resolve(workspace, target);\n\n  let rootReal: string;\n  try {\n    rootReal = fs.realpathSync(workspace);\n  } catch {\n    // 根目录不存在（如权限引擎尚未初始化工作区）：\n    // 没有实际目录结构即无 symlink 逃逸面，退化为纯字符串路径比较。\n    const rootAbs = path.resolve(workspace);\n    if (!isInsideRelative(path.relative(rootAbs, abs))) return null;\n    return { root: rootAbs, real: abs };\n  }\n  if (isFilesystemRoot(rootReal)) return null;\n\n  let real: string;\n  try {\n    real = fs.realpathSync(abs);\n  } catch {\n    // abs 不存在：向上回溯找最近存在的祖先\n    let probe = abs;\n    const tail: string[] = [];\n    for (;;) {\n      // 组件存在（含 broken symlink）但 realpath 失败 → 无法解析，拒绝\n      const exists = fs.existsSync(probe) || fs.lstatSync(probe, { throwIfNoEntry: false }) !== undefined;\n      if (exists) {\n        try {\n          real = path.join(fs.realpathSync(probe), ...tail);\n          break;\n        } catch {\n          return null;\n        }\n      }\n      tail.unshift(path.basename(probe));\n      const parent = path.dirname(probe);\n      if (parent === probe) return null; // 已到文件系统根\n      probe = parent;\n    }\n  }\n\n  if (!isInsideRelative(path.relative(rootReal, real))) return null;\n  return { root: rootReal, real };\n}\n\n/**\n * 判断 target 是否安全地位于 workspace 内（不需要真实路径时用这个）。\n *\n * 注意：删除类操作不应据此改用 realpath 去 unlink —— 那会删掉符号链接\n * 指向的目标而非链接本身；这类操作请用 resolveEntryWithinRoot。\n */\nexport function isWithinRoot(workspace: string, target: string): boolean {\n  return resolveWithinRoot(workspace, target) !== null;\n}\n\n/**\n * 解析「目录项本身」的路径：父目录取 realpath，最后一段保持原样。\n *\n * 供 unlink / rename 等作用于条目自身的操作用：父目录不可被 symlink\n * 替换，而最后一段若是符号链接，被操作的是链接本身，不会被跟随。\n */\nexport function resolveEntryWithinRoot(\n  workspace: string,\n  target: string,\n): ResolvedPath | null {\n  const abs = path.resolve(workspace, target);\n  const parent = resolveWithinRoot(workspace, path.dirname(abs));\n  if (!parent) return null;\n  return { root: parent.root, real: path.join(parent.real, path.basename(abs)) };\n}\n"],"mappings":"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","names":["fs","path","filePath"]}

package/dist/tools/files.d.cts

@@ -1,17 +1,20 @@
-import { T as ToolRegistry } from '../ToolRegistry-C3pTFiaJ.cjs';
+import { T as ToolRegistry } from '../ToolRegistry-DouDvn9E.cjs';
+import { C as ConflictGuard } from '../conflictGuard-BBOOIxxK.cjs';
+import '../types-BYyXWWPW.cjs';
+import '@zqagent/shared/model-capabilities';
 
 /**
  * 注册只读文件工具（read_file / list_files）。
  *
  * 供 explore 子代理等「只读」场景使用，使声明的 schema 与实际能力一致。
  */
-declare function registerReadOnlyFileTools(registry: ToolRegistry, workspace: string): void;
+declare function registerReadOnlyFileTools(registry: ToolRegistry, workspace: string, guard?: ConflictGuard): void;
 /**
  * 注册文件工具到 ToolRegistry
  *
  * read_file / list_files 为低风险（无需审批）；write_file / replace_in_file
  * 为中风险且 requiresApproval=true（由权限引擎决定是否需要审批）。
  */
-declare function registerFileTools(registry: ToolRegistry, workspace: string): void;
+declare function registerFileTools(registry: ToolRegistry, workspace: string, guard?: ConflictGuard): void;
 
 export { registerFileTools, registerReadOnlyFileTools };

package/dist/tools/files.d.ts

@@ -1,17 +1,20 @@
-import { T as ToolRegistry } from '../ToolRegistry-C3pTFiaJ.js';
+import { T as ToolRegistry } from '../ToolRegistry-Cy0fQxrb.js';
+import { C as ConflictGuard } from '../conflictGuard-BBOOIxxK.js';
+import '../types-BYyXWWPW.js';
+import '@zqagent/shared/model-capabilities';
 
 /**
  * 注册只读文件工具（read_file / list_files）。
  *
  * 供 explore 子代理等「只读」场景使用，使声明的 schema 与实际能力一致。
  */
-declare function registerReadOnlyFileTools(registry: ToolRegistry, workspace: string): void;
+declare function registerReadOnlyFileTools(registry: ToolRegistry, workspace: string, guard?: ConflictGuard): void;
 /**
  * 注册文件工具到 ToolRegistry
  *
  * read_file / list_files 为低风险（无需审批）；write_file / replace_in_file
  * 为中风险且 requiresApproval=true（由权限引擎决定是否需要审批）。
  */
-declare function registerFileTools(registry: ToolRegistry, workspace: string): void;
+declare function registerFileTools(registry: ToolRegistry, workspace: string, guard?: ConflictGuard): void;
 
 export { registerFileTools, registerReadOnlyFileTools };

package/dist/tools/files.js

@@ -50,25 +50,24 @@ function resolveWithinRoot(workspace, target) {
 
 // src/tools/files.ts
 var DEFAULT_MAX_LINES = 2e3;
+var MULTI_READ_MAX_TOTAL_LINES = 1500;
 var MAX_LINE_CHARS = 500;
-function makeReadFile(workspace) {
+function makeReadFile(workspace, guard) {
   const root = path2.resolve(workspace);
-  return function read_file(args) {
-    const filePath = String(args.path ?? "");
-    const startLine = Math.max(1, Number(args.start_line ?? 1));
-    const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);
+  function readOne(filePath, startLine, maxLines) {
     const resolved = resolveWithinRoot(root, filePath);
     if (!resolved) {
-      return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
+      return { path: filePath, error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
     }
     const target = resolved.real;
     if (!fs2.existsSync(target) || !fs2.statSync(target).isFile()) {
-      return { error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
+      return { path: filePath, error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
     }
     const selected = [];
     let total = 0;
     try {
       const content = fs2.readFileSync(target, "utf-8");
+      guard?.noteRead(target, content);
       const lines = content.split("\n");
       total = lines.length;
       for (let i = startLine - 1; i < Math.min(startLine - 1 + maxLines, lines.length); i++) {
@@ -76,10 +75,10 @@ function makeReadFile(workspace) {
         if (text.length > MAX_LINE_CHARS) {
           text = text.slice(0, MAX_LINE_CHARS) + "\u2026 (line truncated)";
         }
-        selected.push(`${String(i + 1).padStart(6)}	${text}`);
+        selected.push(`${i + 1}|${text}`);
       }
     } catch (exc) {
-      return { error: `\u8BFB\u53D6\u5931\u8D25: ${String(exc)}` };
+      return { path: filePath, error: `\u8BFB\u53D6\u5931\u8D25: ${String(exc)}` };
     }
     const end = startLine + selected.length - 1;
     const result = {
@@ -93,9 +92,35 @@ function makeReadFile(workspace) {
       result.note = `\u663E\u793A\u7B2C ${startLine}-${end} \u884C\uFF0C\u5171 ${total} \u884C\uFF1B\u8C03\u7528 read_file(start_line=${end + 1}) \u7EE7\u7EED\u9605\u8BFB`;
     }
     return result;
+  }
+  return function read_file(args) {
+    const startLine = Math.max(1, Number(args.start_line ?? 1));
+    const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);
+    const paths = Array.isArray(args.paths) ? args.paths.map((p) => String(p ?? "")).filter(Boolean) : [];
+    if (paths.length > 0) {
+      const files = [];
+      let remainingLines = MULTI_READ_MAX_TOTAL_LINES;
+      for (const filePath2 of paths) {
+        const perFile = Math.min(maxLines, Math.max(1, remainingLines));
+        const one = readOne(filePath2, startLine, perFile);
+        files.push(one);
+        if (!one.error) remainingLines -= one.content.split("\n").length;
+        if (remainingLines <= 0) break;
+      }
+      return {
+        files,
+        count: files.length,
+        ...files.length < paths.length ? { note: `\u5DF2\u8FBE\u5230\u5355\u6B21\u591A\u6587\u4EF6\u8BFB\u53D6\u4E0A\u9650\uFF08\u5171 ${MULTI_READ_MAX_TOTAL_LINES} \u884C\uFF09\uFF0C\u5176\u4F59\u8DEF\u5F84\u672A\u8BFB\u53D6` } : {}
+      };
+    }
+    const filePath = String(args.path ?? "");
+    if (!filePath) {
+      return { error: "\u7F3A\u5C11 path\uFF08\u6216 paths\uFF09\u53C2\u6570" };
+    }
+    return readOne(filePath, startLine, maxLines);
   };
 }
-function makeWriteFile(workspace) {
+function makeWriteFile(workspace, guard) {
   const root = path2.resolve(workspace);
   return function write_file(args) {
     const filePath = String(args.path ?? "");
@@ -112,9 +137,12 @@ function makeWriteFile(workspace) {
     if (fs2.existsSync(target) && !overwrite) {
       return { error: "\u6587\u4EF6\u5DF2\u5B58\u5728 (overwrite=false)" };
     }
+    const conflict = guard?.checkWrite(target, filePath);
+    if (conflict) return { error: conflict.message };
     try {
       fs2.mkdirSync(path2.dirname(target), { recursive: true });
       fs2.writeFileSync(target, content, "utf-8");
+      guard?.noteWrite(target, content);
     } catch (exc) {
       return { error: `\u5199\u5165\u5931\u8D25: ${String(exc)}` };
     }
@@ -148,7 +176,7 @@ function makeListFiles(workspace) {
     }
   };
 }
-function makeReplaceInFile(workspace) {
+function makeReplaceInFile(workspace, guard) {
   const root = path2.resolve(workspace);
   return function replace_in_file(args) {
     const filePath = String(args.path ?? "");
@@ -162,6 +190,8 @@ function makeReplaceInFile(workspace) {
     if (!fs2.existsSync(target) || !fs2.statSync(target).isFile()) {
       return { error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
     }
+    const conflict = guard?.checkWrite(target, filePath);
+    if (conflict) return { error: conflict.message };
     try {
       const content = fs2.readFileSync(target, "utf-8");
       const count = content.split(oldStr).length - 1;
@@ -170,6 +200,7 @@ function makeReplaceInFile(workspace) {
       }
       const updated = content.replaceAll(oldStr, newStr);
       fs2.writeFileSync(target, updated, "utf-8");
+      guard?.noteWrite(target, updated);
       return {
         path: path2.relative(resolved.root, target),
         replacements: count,
@@ -181,8 +212,8 @@ function makeReplaceInFile(workspace) {
     }
   };
 }
-function registerReadOnlyFileTools(registry, workspace) {
-  const readFile = makeReadFile(workspace);
+function registerReadOnlyFileTools(registry, workspace, guard) {
+  const readFile = makeReadFile(workspace, guard);
   registry.register(
     (args) => readFile(args),
     { category: "filesystem", riskLevel: "low", capabilities: ["read_file"], requiresApproval: false },
@@ -190,15 +221,19 @@ function registerReadOnlyFileTools(registry, workspace) {
       type: "function",
       function: {
         name: "read_file",
-        description: "\u8BFB\u53D6\u6587\u672C\u6587\u4EF6\uFF0C\u8FD4\u56DE\u5E26\u884C\u53F7\u7684\u5185\u5BB9 (\u683C\u5F0F: '  12\\\\ttext')\uFF0C\u4EE5\u4FBF\u5F15\u7528\u4E3A path:line\u3002\u5927\u6587\u4EF6\u7A97\u53E3\u5316\uFF1A\u4F20\u9012 start_line \u4ECE\u4E0A\u4E00\u6B21\u8BFB\u53D6\u7684\u4F4D\u7F6E\u7EE7\u7EED\u3002\u53EA\u8BFB\u3002",
+        description: "\u8BFB\u53D6\u6587\u672C\u6587\u4EF6\uFF0C\u8FD4\u56DE\u5E26\u884C\u53F7\u7684\u5185\u5BB9 (\u683C\u5F0F: '12|text')\uFF0C\u4EE5\u4FBF\u5F15\u7528\u4E3A path:line\u3002path \u4E0E paths \u81F3\u5C11\u4F20\u4E00\u4E2A\u3002\u5927\u6587\u4EF6\u7A97\u53E3\u5316\uFF1A\u4F20\u9012 start_line \u4ECE\u4E0A\u4E00\u6B21\u8BFB\u53D6\u7684\u4F4D\u7F6E\u7EE7\u7EED\u3002\u9700\u8981\u540C\u65F6\u67E5\u770B\u591A\u4E2A\u6587\u4EF6/\u533A\u95F4\u65F6\u7528 paths \u4E00\u6B21\u8BFB\u53D6\uFF0C\u51CF\u5C11\u5F80\u8FD4\u3002\u53EA\u8BFB\u3002",
         parameters: {
           type: "object",
           properties: {
             path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84 (\u76F8\u5BF9\u4E8E\u5DE5\u4F5C\u533A)" },
+            paths: {
+              type: "array",
+              items: { type: "string" },
+              description: "\u4E00\u6B21\u8BFB\u53D6\u591A\u4E2A\u6587\u4EF6 (\u4E0E path \u4E8C\u9009\u4E00)\uFF1B\u591A\u4E2A\u5019\u9009\u6587\u4EF6\u5E94\u4E00\u6B21\u8BFB\u5B8C\uFF0C\u4E0D\u8981\u9010\u4E2A\u53D1\u8BF7\u6C42"
+            },
             start_line: { type: "integer", description: "\u8D77\u59CB\u884C\u53F7 (\u4ECE1\u5F00\u59CB\uFF0C\u9ED8\u8BA41)" },
-            max_lines: { type: "integer", description: `\u6700\u5927\u884C\u6570 (\u9ED8\u8BA4 ${DEFAULT_MAX_LINES})` }
-          },
-          required: ["path"]
+            max_lines: { type: "integer", description: `\u6700\u5927\u884C\u6570 (\u9ED8\u8BA4 ${DEFAULT_MAX_LINES}\uFF0C\u591A\u6587\u4EF6\u5408\u8BA1\u4E0A\u9650 ${MULTI_READ_MAX_TOTAL_LINES})` }
+          }
         }
       }
     }
@@ -223,9 +258,9 @@ function registerReadOnlyFileTools(registry, workspace) {
     }
   );
 }
-function registerFileTools(registry, workspace) {
-  registerReadOnlyFileTools(registry, workspace);
-  const writeFile = makeWriteFile(workspace);
+function registerFileTools(registry, workspace, guard) {
+  registerReadOnlyFileTools(registry, workspace, guard);
+  const writeFile = makeWriteFile(workspace, guard);
   registry.register(
     (args) => writeFile(args),
     { category: "filesystem", riskLevel: "medium", capabilities: ["write_file"], requiresApproval: true },
@@ -246,7 +281,7 @@ function registerFileTools(registry, workspace) {
       }
     }
   );
-  const replaceFile = makeReplaceInFile(workspace);
+  const replaceFile = makeReplaceInFile(workspace, guard);
   registry.register(
     (args) => replaceFile(args),
     { category: "filesystem", riskLevel: "medium", capabilities: ["edit_file"], requiresApproval: true },