@epoch-agent/plugin-file 0.1.0

package/LICENSE

@@ -0,0 +1,219 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+--------------------------------------------------------------------------------
+
+epoch-agent
+Copyright 2024-2026 bowen
+
+Portions of this software are derived from the Gemini CLI
+(https://github.com/google-gemini/gemini-cli), Copyright 2025 Google LLC,
+licensed under the Apache License, Version 2.0. Those files have been modified;
+each one retains its original copyright notice and SPDX-License-Identifier
+header. See the NOTICE file in the project source repository for the complete
+list of derived files.
+
+This software also quotes, with attribution, two lines of prose from OpenAI
+Codex (https://github.com/openai/codex), Copyright 2025 OpenAI, licensed under
+the Apache License, Version 2.0. No source file is a derived work of Codex.
+See the NOTICE file for details.

package/README.md

@@ -0,0 +1,65 @@
+# @epoch-agent/plugin-file
+
+文件工具插件。**8 个工具**。
+
+- ✅ **做**：读 / 写 / 精确编辑 / V4A 多文件补丁 / 搜索 / 列目录
+- ❌ **不做**：git 操作、跨机同步、任何引擎逻辑
+- **依赖**：`diff`（算 diff）。[protocol](../../protocol) 和 [infra](../../infra) 是 peer
+
+## 工具
+
+只读五个：`file_read` `file_multi_read` `file_search` `file_list` `file_diff_preview`；
+破坏性三个：`file_write` `file_patch` `file_multi_patch`。
+
+**每个工具干什么、分页与 `output_mode` 那些边界在
+[docs/TOOLS.md](../../../docs/TOOLS.md#文件)** —— 那份是工具清单的唯一真源，
+这里只写这个包自己的实现取舍。
+
+`file_search` 用 **ripgrep**，但**不要求用户自己装**：`rg` 从哪来由 infra 的
+[`resolveRipgrep()`](../../infra/src/ripgrep.ts) 三级决定 —— 系统 PATH 上有就用系统的，
+没有就用随包带的 vendor 二进制，两个都没有才退回「工具在、一调才报错 + 给安装提示」
+的老行为（启动诊断一条 warn，其余七个工具不受影响）。
+
+本插件**不再导出** `probeRipgrep()` / `RIPGREP_INSTALL_HINT`，它们搬去 infra 了：
+`file_list` 和将来的 `@` 文件补全也要用同一份解析，而 plugin 之间不许互相依赖。
+这里只管**参数怎么拼**和**输出怎么收**。
+
+只读的四个 + `file_diff_preview` 标了 `supportsParallel: true`，引擎可以并发调。
+
+## 处理的几类脏输入
+
+- **二进制**：扩展名黑名单拦截（`.png` / `.exe` / `.zip` 等），不把乱码喂给模型
+- **BOM**：剥掉 Windows 编辑器留的 UTF-8 BOM，否则第一行的 patch 匹配永远不中
+- **行尾**：CRLF ↔ LF 归一，patch 匹配不受平台影响
+- **路径**：`~` 和 `~user` 展开
+- **工作区边界**：`resolveSafePath` 防路径穿越——resolve 之后用 `relative` 判，
+  不是 `startsWith`。判定本身是 infra 的
+  [`isInWorkspace()`](../../infra/src/workspace.ts)（全仓唯一一份，权限层和
+  plugin-terminal 共用），这里只管 `~` 展开和抛 `PathEscapeError`。
+  `ctx.extraRoots`（`epoch --add-dir`）一并透传：落在额外根里的**绝对路径**
+  不算越界，但**相对路径仍然只按 `ctx.workDir` 解析**——否则 `src/a.ts` 会在每个
+  根里各找一遍，同一个相对路径有多个答案，而模型无从知道命中的是哪一个
+- **读类工具多认一格：本会话的 artifact 目录**（方案 47）。`file_read` /
+  `file_search` / `file_list` / `file_multi_read` 走的是 `resolveReadablePath`，
+  它在上面那套之外再认 `artifactsDir(ctx.sessionId)`。理由是大输出落盘之后
+  取回提示会告诉模型「用 `file_search` 在这个路径里搜」，而那个路径在工作区外——
+  不放开这一格，那句提示就是一句**必定失败**的指令。
+  口子收窄到三条：**只放开读**（`file_write` / `file_patch` 仍走 `resolveSafePath`，
+  模型没有理由改写「命令当时输出了什么」这份证据）、**只放开本会话那一个子目录**
+  （不是 `~/.epoch/artifacts`，更不是 `~/.epoch`——后者等于把 `.env` 里的 API key 和
+  `sessions.db` 一起交出去）、**`sessionId` 由引擎给且 `artifactsDir()` 内部再洗一次**。
+  这三条各有一条否定用例钉着，见 `__tests__/artifact-readable.test.ts`
+
+## `file_diff_preview` 的 operation 是故意填错的
+
+它的真实语义是只读（只算 diff 不落盘），`annotations` 照实写。但 `operation` 仍填
+`file_write`：老白名单把它归在 `FILE_WRITE_TOOLS` 里，只改一边会让 `recordApproval`
+那条路径与这里分叉。往严的方向偏，代价只是多一次确认。
+
+## 开发
+
+```bash
+pnpm --filter @epoch-agent/plugin-file test
+```
+
+`path-boundary.test.ts` 记的是具体的穿越手法，改 `resolveSafePath` 之前先读它。

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { EpochPlugin } from '@epoch-agent/protocol';
+
+/**
+ * @epoch-agent/plugin-file — 文件读写、搜索、精确编辑
+ *
+ * 目录结构：
+ *   src/
+ *   ├── utils.ts              # 共享工具函数
+ *   ├── tools/
+ *   │   ├── file-read.ts      # 分页读取，带行号
+ *   │   ├── file-multi-read.ts# 批量读取
+ *   │   ├── file-search.ts    # ripgrep 搜索
+ *   │   ├── file-write.ts     # 安全写入（备份+校验）
+ *   │   ├── file-patch.ts     # 精确编辑（apply_patch）
+ *   │   └── file-list.ts      # 目录列表
+ *   └── index.ts              # 插件定义入口
+ *
+ * 每个工具都同时声明三件事，缺一件权限系统就得靠猜：
+ *   - `annotations`：MCP 规范那套风险 hint，给透传 / 展示 / 推断用
+ *   - `operation`：权限类别，直接决定审批走不走。填了就不依赖推断
+ *   - `describeTarget`：这次操作的对象，用作审批缓存 key。不填就只能从
+ *     command/path/target/filePath/paths 五个候选参数名里猜
+ * 消费方见 core 的 permission/operation-type.ts 和 agent/tool-executor.ts。
+ *
+ * `operation` 的取值必须与 operation-type.ts 的工具名白名单一致 ——
+ * `recordApproval` 只拿到工具名、走的是白名单那条路，两边分叉就等于
+ * 「批准了也命不中缓存」。core 的 operation-type.test.ts 有一致性用例守着。
+ */
+
+declare const filePlugin: EpochPlugin;
+
+export { filePlugin };

package/dist/index.js

@@ -0,0 +1,960 @@
+// src/tools/file-multi-patch.ts
+import { randomUUID } from "crypto";
+import {
+  accessSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+import { structuredPatch } from "diff";
+import { isInWorkspace } from "@epoch-agent/infra";
+function parseV4APatch(patch, workDir) {
+  const hunks = [];
+  const blocks = patch.split(/\*\*\* Begin Patch\b/).filter((b) => b.trim());
+  for (const block of blocks) {
+    const endIdx = block.indexOf("*** End Patch");
+    if (endIdx === -1) continue;
+    const body = block.slice(0, endIdx);
+    const fileMatch = body.match(/\*\*\* Update File:\s*(.+)/);
+    if (!fileMatch) continue;
+    const filePath = fileMatch[1]?.trim() ?? "";
+    const absPath = isAbsolute(filePath) ? filePath : resolve(workDir, filePath);
+    const fileBody = body.slice(body.indexOf(fileMatch[0]) + fileMatch[0].length);
+    const hasAddLines = /^\+/m.test(fileBody);
+    const hasDelLines = /^-/m.test(fileBody);
+    const contextLines = fileBody.split("\n").filter((l) => !l.startsWith("@@") && !l.startsWith("+") && !l.startsWith("-"));
+    if (hasAddLines && !hasDelLines) {
+      const content = fileBody.split("\n").filter((l) => l.startsWith("+")).map((l) => l.slice(1).replace(/^ +/, "")).join("\n");
+      hunks.push({ type: "add", filePath: absPath, content });
+    } else if (hasDelLines && !hasAddLines && contextLines.join("").trim() === "") {
+      hunks.push({ type: "delete", filePath: absPath });
+    } else {
+      const addLines = fileBody.split("\n").filter((l) => l.startsWith("+")).map((l) => l.slice(1).replace(/^ +/, ""));
+      const delLines = fileBody.split("\n").filter((l) => l.startsWith("-")).map((l) => l.slice(1).replace(/^ +/, ""));
+      hunks.push({
+        type: "update",
+        filePath: absPath,
+        oldString: delLines.join("\n"),
+        newString: addLines.join("\n")
+      });
+    }
+  }
+  return hunks;
+}
+function applyPatch(hunks, _workDir) {
+  const changes = [];
+  let exact = true;
+  for (const hunk of hunks) {
+    try {
+      switch (hunk.type) {
+        case "add": {
+          if (hunk.content === void 0) continue;
+          try {
+            accessSync(hunk.filePath);
+            changes.push({ path: hunk.filePath, type: "added", newContent: hunk.content });
+            continue;
+          } catch {
+          }
+          atomicWrite(hunk.filePath, hunk.content);
+          changes.push({ path: hunk.filePath, type: "added", newContent: hunk.content });
+          break;
+        }
+        case "delete": {
+          try {
+            const oldContent = readFileSync(hunk.filePath, "utf-8");
+            atomicDelete(hunk.filePath);
+            changes.push({ path: hunk.filePath, type: "deleted", oldContent });
+          } catch {
+            exact = false;
+            changes.push({ path: hunk.filePath, type: "deleted" });
+          }
+          break;
+        }
+        case "update": {
+          if (hunk.oldString === void 0 || hunk.newString === void 0) continue;
+          const oldContent = readFileSync(hunk.filePath, "utf-8");
+          if (!oldContent.includes(hunk.oldString.trim())) {
+            exact = false;
+          }
+          const newContent = oldContent.replace(hunk.oldString, hunk.newString);
+          atomicWrite(hunk.filePath, newContent);
+          const diff = generateDiff(hunk.filePath, oldContent, newContent);
+          changes.push({
+            path: hunk.filePath,
+            type: "modified",
+            oldContent,
+            newContent,
+            unifiedDiff: diff
+          });
+          break;
+        }
+      }
+    } catch {
+      exact = false;
+      changes.push({ path: hunk.filePath, type: "modified" });
+    }
+  }
+  const added = changes.filter((c) => c.type === "added").length;
+  const modified = changes.filter((c) => c.type === "modified").length;
+  const deleted = changes.filter((c) => c.type === "deleted").length;
+  const summary = [
+    `\u5DF2\u4FEE\u6539 ${changes.length} \u4E2A\u6587\u4EF6: ${added} \u65B0\u589E, ${modified} \u4FEE\u6539, ${deleted} \u5220\u9664`,
+    exact ? "(\u6240\u6709\u53D8\u66F4\u7CBE\u786E\u5E94\u7528)" : "(\u90E8\u5206\u53D8\u66F4\u9700\u6A21\u7CCA\u5339\u914D)"
+  ].join(" ");
+  return { success: changes.length > 0, changes, exact, summary };
+}
+var DIFF_CONTEXT_LINES = 3;
+function generateDiff(filePath, oldContent, newContent) {
+  const patch = structuredPatch(filePath, filePath, oldContent, newContent, void 0, void 0, {
+    context: DIFF_CONTEXT_LINES
+  });
+  if (patch.hunks.length === 0) return "";
+  const lines = [`--- ${filePath}`, `+++ ${filePath}`];
+  for (const hunk of patch.hunks) {
+    lines.push(
+      `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`,
+      ...hunk.lines
+    );
+  }
+  return lines.join("\n");
+}
+function atomicWrite(filePath, content) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.epoch-atomic-${randomUUID().slice(0, 8)}.tmp`);
+  writeFileSync(tmp, content, "utf-8");
+  renameSync(tmp, filePath);
+}
+function atomicDelete(filePath) {
+  const backupPath = `${filePath}.epoch-backup-${randomUUID().slice(0, 8)}`;
+  try {
+    renameSync(filePath, backupPath);
+  } catch {
+    try {
+      unlinkSync(filePath);
+    } catch {
+    }
+  }
+}
+async function execMultiPatch(args, ctx) {
+  const patch = String(args["patch"] || "");
+  if (!patch.trim())
+    return {
+      success: false,
+      output: "",
+      error: { code: 4001, message: "\u8865\u4E01\u5185\u5BB9\u4E0D\u80FD\u4E3A\u7A7A" },
+      duration: 0
+    };
+  const hunks = parseV4APatch(patch, ctx.workDir);
+  if (hunks.length === 0)
+    return {
+      success: false,
+      output: "",
+      error: { code: 4002, message: "\u65E0\u6CD5\u89E3\u6790 V4A \u8865\u4E01\u683C\u5F0F" },
+      duration: 0
+    };
+  for (const h of hunks) {
+    if (!isInWorkspace(h.filePath, ctx.workDir, ctx.extraRoots)) {
+      return {
+        success: false,
+        output: "",
+        error: {
+          code: 4003,
+          message: `\u8DEF\u5F84\u8D8A\u754C\u62D2\u7EDD: ${h.filePath} \u4E0D\u5728\u5DE5\u4F5C\u533A ${ctx.workDir} \u5185`
+        },
+        duration: 0
+      };
+    }
+  }
+  const result = applyPatch(hunks, ctx.workDir);
+  return {
+    success: result.success,
+    output: result.summary + "\n\n" + result.changes.map(
+      (c) => c.unifiedDiff ? `=== ${c.path} ===
+${c.unifiedDiff}` : `${c.type}: ${c.path}`
+    ).join("\n\n"),
+    duration: 0
+  };
+}
+
+// src/tools/file-diff-preview.ts
+async function execDiffPreview(args, ctx) {
+  const patch = String(args["patch"] || "");
+  if (!patch.trim())
+    return {
+      success: false,
+      output: "",
+      error: { code: 4101, message: "\u8865\u4E01\u5185\u5BB9\u4E0D\u80FD\u4E3A\u7A7A" },
+      duration: 0
+    };
+  const hunks = parseV4APatch(patch, ctx.workDir);
+  if (hunks.length === 0)
+    return {
+      success: false,
+      output: "",
+      error: { code: 4102, message: "\u65E0\u6CD5\u89E3\u6790 V4A \u8865\u4E01\u683C\u5F0F" },
+      duration: 0
+    };
+  const summary = buildDiffSummary(hunks, ctx.workDir);
+  return {
+    success: true,
+    output: summary,
+    duration: 0
+  };
+}
+function buildDiffSummary(hunks, workDir) {
+  const lines = [];
+  const addCount = hunks.filter((h) => h.type === "add").length;
+  const updateCount = hunks.filter((h) => h.type === "update").length;
+  const deleteCount = hunks.filter((h) => h.type === "delete").length;
+  const counts = [];
+  if (addCount) counts.push(`${addCount} \u65B0\u589E`);
+  if (updateCount) counts.push(`${updateCount} \u4FEE\u6539`);
+  if (deleteCount) counts.push(`${deleteCount} \u5220\u9664`);
+  lines.push(`\u{1F4DD} \u8865\u4E01\u9884\u89C8 \u2014 ${hunks.length} \u4E2A\u6587\u4EF6\u5C06\u88AB\u4FEE\u6539 (${counts.join(", ")})`);
+  lines.push("");
+  for (const hunk of hunks) {
+    const icon = hunk.type === "add" ? "\u{1F4C4} ADD" : hunk.type === "delete" ? "\u{1F5D1}\uFE0F DELETE" : "\u270F\uFE0F UPDATE";
+    const short = hunk.filePath.replace(workDir + "/", "");
+    lines.push(`${icon}   ${short}`);
+    if (hunk.type === "add" && hunk.content) {
+      for (const l of hunk.content.split("\n").slice(0, 10)) {
+        lines.push(`  + ${l}`);
+      }
+      if (hunk.content.split("\n").length > 10)
+        lines.push(`  ... (${hunk.content.split("\n").length - 10} more lines)`);
+    } else if (hunk.type === "delete" && hunk.oldString) {
+      for (const l of hunk.oldString.split("\n").slice(0, 5)) {
+        lines.push(`  - ${l}`);
+      }
+    } else if (hunk.type === "update") {
+      if (hunk.oldString) {
+        for (const l of hunk.oldString.split("\n").slice(0, 5)) {
+          lines.push(`  - ${l}`);
+        }
+      }
+      if (hunk.newString) {
+        for (const l of hunk.newString.split("\n").slice(0, 5)) {
+          lines.push(`  + ${l}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("\u786E\u8BA4\u65E0\u8BEF\u540E\uFF0C\u4F7F\u7528 file_multi_patch \u5DE5\u5177\u5E94\u7528\u4EE5\u4E0A\u53D8\u66F4\u3002");
+  return lines.join("\n");
+}
+
+// src/tools/file-list.ts
+import { readdirSync, statSync } from "fs";
+import { join as join2 } from "path";
+
+// src/utils.ts
+import { homedir } from "os";
+import { resolve as resolve2 } from "path";
+import { artifactsDir, isInWorkspace as isInWorkspace2 } from "@epoch-agent/infra";
+var MAX_OUTPUT_BYTES = 5e4;
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".bmp",
+  ".ico",
+  ".svg",
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".bz2",
+  ".7z",
+  ".rar",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".o",
+  ".a",
+  ".pyc",
+  ".pyo",
+  ".class",
+  ".jar",
+  ".mp3",
+  ".mp4",
+  ".avi",
+  ".mov",
+  ".wav",
+  ".flac",
+  ".ttf",
+  ".otf",
+  ".woff",
+  ".woff2",
+  ".db",
+  ".sqlite",
+  ".sqlite3"
+]);
+function expandPath(filePath) {
+  if (filePath.startsWith("~")) {
+    return filePath.replace(/^~(?=$|[/\\])/, homedir());
+  }
+  return filePath;
+}
+var PathEscapeError = class extends Error {
+  constructor(attempted, workDir) {
+    super(`\u8DEF\u5F84\u8D8A\u754C\uFF1A${attempted} \u4E0D\u5728\u5DE5\u4F5C\u533A ${workDir} \u5185`);
+    this.attempted = attempted;
+    this.workDir = workDir;
+    this.name = "PathEscapeError";
+  }
+  attempted;
+  workDir;
+};
+function resolveSafePath(filePath, workDir, extraRoots = []) {
+  const expanded = expandPath(filePath);
+  const abs = resolve2(workDir, expanded);
+  if (!isInWorkspace2(abs, workDir, extraRoots)) {
+    throw new PathEscapeError(filePath, resolve2(workDir));
+  }
+  return abs;
+}
+function resolveReadablePath(filePath, workDir, extraRoots = [], sessionId, homeDir) {
+  if (!sessionId) return resolveSafePath(filePath, workDir, extraRoots);
+  return resolveSafePath(filePath, workDir, [...extraRoots, artifactsDir(sessionId, homeDir)]);
+}
+function isBinaryFile(filePath) {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}
+function stripBom(content) {
+  if (content.charCodeAt(0) === 65279) {
+    return { text: content.slice(1), hadBom: true };
+  }
+  return { text: content, hadBom: false };
+}
+function detectLineEnding(content) {
+  const hasCRLF = content.includes("\r\n");
+  const hasLFOnly = content.includes("\n") && !hasCRLF;
+  if (hasCRLF && !hasLFOnly) return "crlf";
+  if (hasLFOnly && !hasCRLF) return "lf";
+  if (hasCRLF && content.replace(/\r\n/g, "").includes("\n")) return "mixed";
+  return "lf";
+}
+function normalizeLineEndings(content, target) {
+  if (target === "lf") return content.replace(/\r\n/g, "\n");
+  return content.replace(/(?<!\r)\n/g, "\r\n");
+}
+function paginateContent(content, offset = 1, limit = 500) {
+  const lines = content.split("\n");
+  const totalLines = lines.length;
+  if (offset > totalLines) return { content: "", totalLines };
+  const end = Math.min(offset + limit - 1, totalLines);
+  const sliced = lines.slice(offset - 1, end).join("\n");
+  const result = {
+    content: sliced,
+    totalLines
+  };
+  if (end < totalLines) result.nextOffset = end + 1;
+  return result;
+}
+function truncateOutput(text) {
+  if (text.length > MAX_OUTPUT_BYTES) {
+    return text.slice(0, MAX_OUTPUT_BYTES) + `
+[\u8F93\u51FA\u5DF2\u622A\u65AD\uFF0C\u5171 ${text.length} \u5B57\u8282\uFF0C\u663E\u793A\u524D ${MAX_OUTPUT_BYTES} \u5B57\u8282]`;
+  }
+  return text;
+}
+function formatWithLineNumbers(content, startLine) {
+  return content.split("\n").map((line, i) => String(startLine + i).padStart(4, " ") + "|" + line).join("\n");
+}
+
+// src/tools/file-list.ts
+function formatEntry(entry) {
+  const size = entry.type === "directory" ? "-" : entry.size.toLocaleString("en-US");
+  const name = entry.type === "directory" ? `${entry.name}/` : entry.name;
+  return `${entry.type.padEnd(4)} ${size.padStart(12)}  ${name}`;
+}
+function collect(dir) {
+  const entries = [];
+  for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+    const type = dirent.isDirectory() ? "directory" : "file";
+    let size = 0;
+    if (type === "file") {
+      try {
+        size = statSync(join2(dir, dirent.name)).size;
+      } catch {
+        size = 0;
+      }
+    }
+    entries.push({ name: dirent.name, type, size });
+  }
+  entries.sort(
+    (a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === "directory" ? -1 : 1
+  );
+  return entries;
+}
+function execList(args, ctx) {
+  const path = String(args["path"] ?? ".");
+  let resolved;
+  try {
+    resolved = resolveReadablePath(path, ctx.workDir, ctx.extraRoots, ctx.sessionId, ctx.homeDir);
+  } catch (err) {
+    return Promise.resolve({
+      success: false,
+      output: "",
+      error: { code: 2006, message: err instanceof Error ? err.message : String(err) },
+      duration: 0
+    });
+  }
+  try {
+    const entries = collect(resolved);
+    const body = entries.length === 0 ? "(\u7A7A\u76EE\u5F55)" : entries.map(formatEntry).join("\n");
+    return Promise.resolve({
+      success: true,
+      output: truncateOutput(`${resolved}
+${body}
+\u5171 ${entries.length} \u9879`),
+      duration: 0
+    });
+  } catch (err) {
+    const code = err.code;
+    const message = err instanceof Error ? err.message : String(err);
+    return Promise.resolve({
+      success: false,
+      output: "",
+      error: {
+        code: 2005,
+        message,
+        ...code === "ENOTDIR" ? { suggestion: "\u76EE\u6807\u662F\u6587\u4EF6\uFF0C\u8BFB\u5185\u5BB9\u8BF7\u7528 file_read" } : {}
+      },
+      duration: 0
+    });
+  }
+}
+
+// src/tools/file-multi-read.ts
+import { readFile } from "fs/promises";
+async function execMultiRead(args, ctx) {
+  const paths = args["paths"];
+  if (!paths?.length) {
+    return {
+      success: false,
+      output: "",
+      error: { code: 2004, message: "\u53C2\u6570 paths \u4E0D\u80FD\u4E3A\u7A7A" },
+      duration: 0
+    };
+  }
+  const results = [];
+  for (const p of paths.slice(0, 10)) {
+    try {
+      const resolved = resolveReadablePath(
+        p,
+        ctx.workDir,
+        ctx.extraRoots,
+        ctx.sessionId,
+        ctx.homeDir
+      );
+      const content = await readFile(resolved, "utf-8");
+      const output = formatWithLineNumbers(content, 0);
+      results.push(`--- ${p} ---
+${truncateOutput(output)}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      results.push(`--- ${p} ---
+[\u8BFB\u53D6\u5931\u8D25: ${message}]`);
+    }
+  }
+  return { success: true, output: results.join("\n\n"), duration: 0 };
+}
+
+// src/tools/file-patch.ts
+import { readFile as readFile2, writeFile } from "fs/promises";
+import { basename } from "path";
+async function execPatch(args, ctx) {
+  const path = String(args["path"] ?? "");
+  const oldString = String(args["old_string"] ?? "");
+  const newString = String(args["new_string"] ?? "");
+  const replaceAll = Boolean(args["replace_all"]);
+  if (!path || !oldString) {
+    return {
+      success: false,
+      output: "",
+      error: { code: 2004, message: "\u53C2\u6570 path \u548C old_string \u4E0D\u80FD\u4E3A\u7A7A" },
+      duration: 0
+    };
+  }
+  const startTime = Date.now();
+  try {
+    const resolved = resolveSafePath(path, ctx.workDir, ctx.extraRoots);
+    const rawContent = await readFile2(resolved, "utf-8");
+    const lineEnding = detectLineEnding(rawContent);
+    const content = normalizeLineEndings(rawContent, "lf");
+    const normalizedOld = normalizeLineEndings(oldString, "lf");
+    const normalizedNew = normalizeLineEndings(newString, lineEnding === "crlf" ? "crlf" : "lf");
+    const indices = findAllMatches(content, normalizedOld);
+    if (indices.length === 0) {
+      const fuzzy = fuzzyMatch(content, normalizedOld);
+      if (fuzzy) {
+        const newContent2 = content.slice(0, fuzzy.start) + normalizedNew + content.slice(fuzzy.end);
+        await writeFile(resolved, newContent2, "utf-8");
+        return {
+          success: true,
+          output: `\u2705 \u6A21\u7CCA\u5339\u914D\u6210\u529F\uFF0C\u5DF2\u4FEE\u6539 ${basename(resolved)}`,
+          duration: Date.now() - startTime
+        };
+      }
+      return {
+        success: false,
+        output: "",
+        error: {
+          code: 2004,
+          message: `old_string \u672A\u5728\u6587\u4EF6\u4E2D\u627E\u5230\u3002\u5C1D\u8BD5\u4E86 9 \u79CD\u6A21\u7CCA\u5339\u914D\u7B56\u7565\u5747\u5931\u8D25\u3002`,
+          suggestion: "\u8BF7\u7528 file_read \u786E\u8BA4\u5F53\u524D\u6587\u4EF6\u5185\u5BB9\uFF0C\u786E\u4FDD old_string \u51C6\u786E"
+        },
+        duration: Date.now() - startTime
+      };
+    }
+    if (indices.length > 1 && !replaceAll) {
+      return {
+        success: false,
+        output: `\u5339\u914D\u5230 ${indices.length} \u5904\uFF0C\u8BF7\u4F7F\u7528 replace_all=true \u6216\u63D0\u4F9B\u66F4\u7CBE\u786E\u7684\u4E0A\u4E0B\u6587`,
+        error: {
+          code: 2004,
+          message: `\u5339\u914D\u5230 ${indices.length} \u5904\uFF0C\u9700\u660E\u786E\u6307\u5B9A`,
+          suggestion: "\u5C06 replace_all \u8BBE\u4E3A true \u6216\u589E\u52A0\u66F4\u591A\u4E0A\u4E0B\u6587\u8BA9\u5339\u914D\u552F\u4E00"
+        },
+        duration: Date.now() - startTime
+      };
+    }
+    let newContent = content;
+    for (let i = indices.length - 1; i >= 0; i--) {
+      const idx = indices[i];
+      if (idx === void 0) continue;
+      newContent = newContent.slice(0, idx) + normalizedNew + newContent.slice(idx + normalizedOld.length);
+    }
+    await writeFile(resolved, newContent, "utf-8");
+    return {
+      success: true,
+      output: `\u2705 \u5DF2\u4FEE\u6539 ${basename(resolved)}\uFF08${indices.length} \u5904\u66FF\u6362\uFF09`,
+      duration: Date.now() - startTime
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      output: "",
+      error: { code: 2005, message },
+      duration: Date.now() - startTime
+    };
+  }
+}
+function findAllMatches(content, old) {
+  const indices = [];
+  let pos = 0;
+  while ((pos = content.indexOf(old, pos)) !== -1) {
+    indices.push(pos);
+    pos += old.length;
+  }
+  return indices;
+}
+function fuzzyMatch(content, old) {
+  const strategies = [
+    () => simpleMatch(content, old.trim()),
+    () => simpleMatch(content.replace(/\r\n/g, "\n"), old.replace(/\r\n/g, "\n")),
+    () => simpleMatch(content, old.replace(/\t/g, "  ")),
+    () => lineTrimMatch(content, old),
+    () => simpleMatch(content.replace(/\s+/g, " "), old.replace(/\s+/g, " "))
+  ];
+  for (const fn of strategies) {
+    try {
+      const r = fn();
+      if (r) return r;
+    } catch {
+    }
+  }
+  return null;
+}
+function simpleMatch(content, old) {
+  const idx = content.indexOf(old);
+  return idx === -1 ? null : { start: idx, end: idx + old.length };
+}
+function lineTrimMatch(content, old) {
+  const cl = content.split("\n").map((l) => l.trim());
+  const ol = old.split("\n").map((l) => l.trim());
+  for (let i = 0; i <= cl.length - ol.length; i++) {
+    if (ol.every((line, j) => cl[i + j] === line)) {
+      return { start: content.indexOf(ol[0] ?? ""), end: content.length };
+    }
+  }
+  return null;
+}
+
+// src/tools/file-read.ts
+import { readFile as readFile3 } from "fs/promises";
+async function execRead(args, ctx) {
+  const path = String(args["path"] ?? "");
+  const offset = Number(args["offset"] ?? 1);
+  const limit = Number(args["limit"] ?? 500);
+  if (!path) {
+    return {
+      success: false,
+      output: "",
+      error: { code: 2004, message: "\u53C2\u6570 path \u4E0D\u80FD\u4E3A\u7A7A" },
+      duration: 0
+    };
+  }
+  try {
+    const resolved = resolveReadablePath(
+      path,
+      ctx.workDir,
+      ctx.extraRoots,
+      ctx.sessionId,
+      ctx.homeDir
+    );
+    if (isBinaryFile(resolved)) {
+      return { success: true, output: `[\u4E8C\u8FDB\u5236\u6587\u4EF6\uFF0C\u65E0\u6CD5\u8BFB\u53D6: ${path}]`, duration: 0 };
+    }
+    const raw = await readFile3(resolved, "utf-8");
+    const { text: content, hadBom } = stripBom(raw);
+    const result = paginateContent(content, offset, limit);
+    let output = formatWithLineNumbers(result.content, offset);
+    output = output || "(\u6587\u4EF6\u4E3A\u7A7A)";
+    if (result.nextOffset) {
+      output += `
+
+[\u7B2C ${result.nextOffset - 1} \u884C / \u5171 ${result.totalLines} \u884C\uFF0C\u4F7F\u7528 offset=${result.nextOffset} \u4E0B\u4E00\u9875]`;
+    }
+    if (hadBom) {
+      output = `[\u68C0\u6D4B\u5230 UTF-8 BOM\uFF0C\u5DF2\u81EA\u52A8\u5265\u79BB]
+${output}`;
+    }
+    return { success: true, output, duration: 0 };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, output: "", error: { code: 2001, message }, duration: 0 };
+  }
+}
+
+// src/tools/file-search.ts
+import { spawn } from "child_process";
+import { resolveRipgrep, RIPGREP_INSTALL_HINT, WINDOWS_HIDE_FLAGS } from "@epoch-agent/infra";
+function execSearch(args, ctx) {
+  return new Promise((resolve4) => {
+    const pattern = String(args["pattern"] ?? "");
+    const searchPath = String(args["path"] ?? ".");
+    const include = String(args["include"] ?? "");
+    const limit = Number(args["limit"] ?? 50);
+    const outputMode = args["output_mode"] || "content";
+    if (!pattern) {
+      resolve4({
+        success: false,
+        output: "",
+        error: { code: 2004, message: "\u53C2\u6570 pattern \u4E0D\u80FD\u4E3A\u7A7A" },
+        duration: 0
+      });
+      return;
+    }
+    let resolvedDir;
+    try {
+      resolvedDir = resolveReadablePath(
+        searchPath,
+        ctx.workDir,
+        ctx.extraRoots,
+        ctx.sessionId,
+        ctx.homeDir
+      );
+    } catch (err) {
+      resolve4({
+        success: false,
+        output: "",
+        error: { code: 2006, message: err instanceof Error ? err.message : String(err) },
+        duration: 0
+      });
+      return;
+    }
+    const rgArgs = [
+      "--line-number",
+      "--no-heading",
+      "--color",
+      "never",
+      "-m",
+      String(limit),
+      pattern,
+      resolvedDir
+    ];
+    if (include) rgArgs.splice(0, 0, "--glob", include);
+    if (outputMode === "files_only") rgArgs.splice(0, 0, "-l");
+    if (outputMode === "count") rgArgs.splice(0, 0, "-c");
+    const child = spawn(resolveRipgrep().command, rgArgs, {
+      timeout: 3e4,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...WINDOWS_HIDE_FLAGS
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => {
+      if (code === 0 || code === 1) {
+        resolve4({ success: true, output: truncateOutput(stdout) || "(\u65E0\u5339\u914D)", duration: 0 });
+      } else {
+        resolve4({
+          success: false,
+          output: "",
+          error: { code: 2005, message: stderr || `rg \u6267\u884C\u5931\u8D25 (exit ${code})` },
+          duration: 0
+        });
+      }
+    });
+    child.on("error", (err) => {
+      const notFound = err.code === "ENOENT";
+      resolve4({
+        success: false,
+        output: "",
+        error: {
+          code: 2005,
+          message: `ripgrep \u672A\u5B89\u88C5\u6216\u4E0D\u53EF\u7528: ${err.message}`,
+          ...notFound ? { suggestion: `\u5B89\u88C5 ripgrep \u540E\u91CD\u8BD5\uFF1A${RIPGREP_INSTALL_HINT}` } : {}
+        },
+        duration: 0
+      });
+    });
+  });
+}
+
+// src/tools/file-write.ts
+import { mkdir, readFile as readFile4, rename, stat, unlink, writeFile as writeFile2 } from "fs/promises";
+import { basename as basename2, resolve as resolve3 } from "path";
+async function execWrite(args, ctx) {
+  const path = String(args["path"] ?? "");
+  const content = String(args["content"] ?? "");
+  if (!path) {
+    return {
+      success: false,
+      output: "",
+      error: { code: 2004, message: "\u53C2\u6570 path \u4E0D\u80FD\u4E3A\u7A7A" },
+      duration: 0
+    };
+  }
+  const startTime = Date.now();
+  try {
+    const resolved = resolveSafePath(path, ctx.workDir, ctx.extraRoots);
+    let existed = false;
+    try {
+      await stat(resolved);
+      existed = true;
+      await rename(resolved, `${resolved}.bak`);
+    } catch {
+    }
+    await mkdir(resolve3(resolved, ".."), { recursive: true });
+    await writeFile2(resolved, content, "utf-8");
+    const written = await readFile4(resolved, "utf-8");
+    if (written !== content) {
+      await rename(`${resolved}.bak`, resolved);
+      throw new Error("\u6587\u4EF6\u5199\u5165\u6821\u9A8C\u5931\u8D25\uFF0C\u5DF2\u4ECE\u5907\u4EFD\u6062\u590D");
+    }
+    try {
+      await unlink(`${resolved}.bak`);
+    } catch {
+    }
+    return {
+      success: true,
+      output: existed ? `\u2705 \u5DF2\u66F4\u65B0 ${basename2(resolved)} (${content.length} \u5B57\u8282)` : `\u2705 \u5DF2\u521B\u5EFA ${basename2(resolved)} (${content.length} \u5B57\u8282)`,
+      duration: Date.now() - startTime
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      output: "",
+      error: { code: 2005, message },
+      duration: Date.now() - startTime
+    };
+  }
+}
+
+// src/index.ts
+var READ_ONLY = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+var DESTRUCTIVE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+function pathTarget(args) {
+  return String(args["path"] ?? "");
+}
+function dirTarget(args) {
+  return String(args["path"] ?? ".");
+}
+function patchTarget(args) {
+  const patch = String(args["patch"] ?? "");
+  const files = [...patch.matchAll(/^\*\*\* (?:Update|Add|Delete) File:\s*(.+)$/gm)].map(
+    (m) => (m[1] ?? "").trim()
+  );
+  return files.length > 0 ? files.join(",") : "";
+}
+var filePlugin = {
+  name: "@epoch-agent/plugin-file",
+  version: "0.0.0",
+  description: "\u6587\u4EF6\u8BFB\u5199\u3001\u641C\u7D22\u3001\u7CBE\u786E\u7F16\u8F91",
+  tools: [
+    {
+      name: "file_read",
+      description: "\u5206\u9875\u8BFB\u53D6\u6587\u4EF6\u5185\u5BB9\uFF0C\u5E26\u884C\u53F7\u3002\u9ED8\u8BA4\u4E00\u6B21\u8BFB 500 \u884C\uFF0C\u8D85\u8FC7\u7528 offset \u7FFB\u9875\u3002",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84\uFF08\u76F8\u5BF9\u5DE5\u4F5C\u76EE\u5F55\u6216\u7EDD\u5BF9\u8DEF\u5F84\uFF09" },
+          offset: { type: "number", description: "\u4ECE\u7B2C\u51E0\u884C\u5F00\u59CB\u8BFB\uFF08\u9ED8\u8BA4 1\uFF09" },
+          limit: { type: "number", description: "\u8BFB\u591A\u5C11\u884C\uFF08\u9ED8\u8BA4 500\uFF0C\u6700\u5927 2000\uFF09" }
+        },
+        required: ["path"]
+      },
+      supportsParallel: true,
+      annotations: READ_ONLY,
+      operation: "file_read",
+      describeTarget: pathTarget,
+      execute: execRead
+    },
+    {
+      name: "file_multi_read",
+      description: "\u4E00\u6B21\u8BFB\u53D6\u591A\u4E2A\u6587\u4EF6\uFF0C\u9002\u5408\u4E86\u89E3\u9879\u76EE\u7ED3\u6784\u3002\u6700\u591A\u540C\u65F6\u8BFB 10 \u4E2A\u3002",
+      parameters: {
+        type: "object",
+        properties: {
+          paths: { type: "array", items: { type: "string" }, description: "\u6587\u4EF6\u8DEF\u5F84\u5217\u8868" }
+        },
+        required: ["paths"]
+      },
+      supportsParallel: true,
+      annotations: READ_ONLY,
+      operation: "file_read",
+      describeTarget: (args) => {
+        const paths = args["paths"];
+        return Array.isArray(paths) ? paths.map(String).join(",") : String(paths ?? "");
+      },
+      execute: execMultiRead
+    },
+    {
+      name: "file_search",
+      description: "\u7528 ripgrep \u641C\u7D22\u6587\u4EF6\u5185\u5BB9\uFF08\u6B63\u5219\uFF09\u3002\u652F\u6301\u6307\u5B9A\u76EE\u5F55\u3001\u6587\u4EF6\u7C7B\u578B\u3001\u8F93\u51FA\u6A21\u5F0F\u3002",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "\u641C\u7D22\u6A21\u5F0F\uFF08\u6B63\u5219\uFF09" },
+          path: { type: "string", description: "\u641C\u7D22\u76EE\u5F55\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09" },
+          include: { type: "string", description: '\u6587\u4EF6\u7C7B\u578B\u8FC7\u6EE4\uFF0C\u5982 "*.ts"' },
+          limit: { type: "number", description: "\u6700\u591A\u8FD4\u56DE\u6761\u6570\uFF08\u9ED8\u8BA4 50\uFF09" },
+          output_mode: {
+            type: "string",
+            enum: ["content", "files_only", "count"],
+            description: "\u8F93\u51FA\u6A21\u5F0F"
+          }
+        },
+        required: ["pattern"]
+      },
+      supportsParallel: true,
+      annotations: READ_ONLY,
+      operation: "file_read",
+      // 搜索的对象是目录，不是 pattern
+      describeTarget: dirTarget,
+      execute: execSearch
+    },
+    {
+      name: "file_write",
+      description: "\u521B\u5EFA\u6216\u8986\u76D6\u6587\u4EF6\u3002\u5199\u5165\u524D\u81EA\u52A8\u5907\u4EFD\uFF0C\u5199\u5165\u540E\u6821\u9A8C\u5B8C\u6574\u6027\uFF0C\u5931\u8D25\u5219\u4ECE\u5907\u4EFD\u6062\u590D\u3002",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84" },
+          content: { type: "string", description: "\u6587\u4EF6\u5B8C\u6574\u5185\u5BB9" }
+        },
+        required: ["path", "content"]
+      },
+      supportsParallel: false,
+      annotations: DESTRUCTIVE,
+      operation: "file_write",
+      describeTarget: pathTarget,
+      execute: execWrite
+    },
+    {
+      name: "file_patch",
+      description: "\u7CBE\u786E\u7F16\u8F91\u6587\u4EF6\uFF1A\u53EA\u6539\u6307\u5B9A\u5185\u5BB9\uFF0C\u4E0D\u91CD\u5199\u6574\u4E2A\u6587\u4EF6\u3002\u6BD4 file_write \u66F4\u5B89\u5168\u3002",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84" },
+          old_string: { type: "string", description: "\u8981\u66FF\u6362\u7684\u539F\u59CB\u6587\u672C\uFF08\u591A\u7528\u51E0\u884C\u4E0A\u4E0B\u6587\u786E\u4FDD\u552F\u4E00\uFF09" },
+          new_string: { type: "string", description: "\u66FF\u6362\u540E\u7684\u6587\u672C" },
+          replace_all: { type: "boolean", description: "\u662F\u5426\u66FF\u6362\u6240\u6709\u5339\u914D\u5904\uFF08\u9ED8\u8BA4 false\uFF09" }
+        },
+        required: ["path", "old_string", "new_string"]
+      },
+      supportsParallel: false,
+      annotations: DESTRUCTIVE,
+      operation: "file_write",
+      describeTarget: pathTarget,
+      execute: execPatch
+    },
+    {
+      name: "file_list",
+      description: "\u5217\u51FA\u76EE\u5F55\u5185\u5BB9\u3002",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string", description: "\u76EE\u5F55\u8DEF\u5F84\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09" } }
+      },
+      supportsParallel: true,
+      annotations: READ_ONLY,
+      operation: "file_read",
+      describeTarget: dirTarget,
+      execute: execList
+    },
+    {
+      name: "file_diff_preview",
+      description: "\u9884\u89C8 V4A \u8865\u4E01\u2014\u2014\u4E0D\u4FEE\u6539\u6587\u4EF6\uFF0C\u4EC5\u5C55\u793A\u53D8\u66F4\u6458\u8981\u3002\u5148\u9884\u89C8\u786E\u8BA4\uFF0C\u518D\u7528 file_multi_patch \u5E94\u7528\u3002\u683C\u5F0F\u540C file_multi_patch\u3002",
+      parameters: {
+        type: "object",
+        properties: { patch: { type: "string", description: "V4A \u683C\u5F0F\u7684\u591A\u6587\u4EF6\u8865\u4E01\u5185\u5BB9" } },
+        required: ["patch"]
+      },
+      // 真实语义是只读（只算 diff 不落盘），annotations 照实写。
+      // 但 operation 仍填 file_write：老白名单把它归在 FILE_WRITE_TOOLS 里，
+      // 只改一边会让 recordApproval 那条路径与这里分叉。往严的方向偏，
+      // 代价只是多一次确认；纠正白名单本身是方案 06 的地盘。
+      annotations: READ_ONLY,
+      operation: "file_write",
+      describeTarget: patchTarget,
+      execute: execDiffPreview
+    },
+    {
+      name: "file_multi_patch",
+      description: "V4A \u591A\u6587\u4EF6\u8865\u4E01\u2014\u2014\u4E00\u6B21\u4FEE\u6539\u591A\u4E2A\u6587\u4EF6\u3002\u683C\u5F0F\uFF1A*** Begin Patch / *** Update File: / @@ / -\u65E7\u884C +\u65B0\u884C / *** End Patch\u3002\u652F\u6301\u6279\u91CF\u589E\u5220\u6539\u3002",
+      parameters: {
+        type: "object",
+        properties: { patch: { type: "string", description: "V4A \u683C\u5F0F\u7684\u591A\u6587\u4EF6\u8865\u4E01\u5185\u5BB9" } },
+        required: ["patch"]
+      },
+      annotations: DESTRUCTIVE,
+      operation: "file_write",
+      describeTarget: patchTarget,
+      execute: execMultiPatch
+    }
+  ]
+};
+export {
+  filePlugin
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@epoch-agent/plugin-file",
+  "version": "0.1.0",
+  "private": false,
+  "description": "epoch-agent 文件系统操作插件",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ddbor/epoch-agent.git"
+  },
+  "license": "Apache-2.0",
+  "author": "epoch-agent",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "diff": "^9.0.0",
+    "@epoch-agent/infra": "0.1.0",
+    "@epoch-agent/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "tsup": "^8.3.6",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}