ysagc-agent 0.1.0

package/src/methods/fs.js

@@ -0,0 +1,674 @@
+/**
+ * fs.* RPC 方法（T-M1-03/04/06/07/12）
+ * - fs.list / fs.stat / fs.read / fs.write / fs.mkdir / fs.rename / fs.copy / fs.rm
+ * - fs.trash.*（回收站） / fs.search（ripgrep 优先，内置降级） / fs.addRoot 由 project.* 提供
+ * - 文件监听（chokidar）→ event.fs.changed
+ * - 写操作幂等（requestId 去重 5 分钟）
+ * 编码：jschardet + iconv-lite；原子写 tmp+rename；快照冲突检测；.git 内部拒绝
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { RpcError } = require('../rpc');
+const logger = require('../logger');
+
+let jschardet = null;
+let iconv = null;
+let chokidar = null;
+try { jschardet = require('jschardet'); } catch { /* optional */ }
+try { iconv = require('iconv-lite'); } catch { /* optional */ }
+try { chokidar = require('chokidar'); } catch { /* optional */ }
+
+const MAX_EDIT_SIZE = 2 * 1024 * 1024; // >2MB 只读预览
+const MAX_PREVIEW_SIZE = 20 * 1024 * 1024; // >20MB 仅下载
+const TRASH_DIR_NAME = '.ws-trash';
+const TRASH_RETENTION_MS = 7 * 24 * 3600 * 1000;
+const TRASH_MAX_TOTAL = 2 * 1024 * 1024 * 1024; // 2GB
+const HIDDEN_PATTERNS = [/^\.git$/, /^\.ws-trash$/, /^node_modules$/, /^dist$/, /^build$/, /^\.idea$/, /^\.vscode$/];
+const SENSITIVE_PATTERNS = [/^\.env(\..*)?$/, /\.pem$/i, /\.key$/i, /^id_rsa/i, /^credentials/i, /secret/i, /token/i, /password/i, /\.p12$/i, /\.pfx$/i];
+const SEARCH_MAX_RESULTS = 500;
+const WRITE_IDEMPOTENT_MS = 5 * 60 * 1000;
+
+function createFsMethods(ctxRef) {
+  const sandbox = () => ctxRef().sandbox;
+  const cfg = () => ctxRef().config;
+  /** @type {Map<string, {at:number, result:any}>} 写操作幂等缓存 */
+  const idempotentCache = new Map();
+  const watchers = new Map(); // root -> chokidar watcher
+
+  // ---------------- 工具 ----------------
+
+  function normSep(p) {
+    return String(p).replace(/\\/g, '/');
+  }
+
+  function snapshotOf(absPath, size) {
+    try {
+      const stat = fs.statSync(absPath);
+      const mtimeMs = stat.mtimeMs;
+      const fileSize = size !== undefined ? size : stat.size;
+      let hash;
+      if (fileSize <= 1024 * 1024) {
+        hash = crypto.createHash('md5').update(fs.readFileSync(absPath)).digest('hex');
+      } else {
+        // >1MB 取头尾 64KB + size 组合
+        const fd = fs.openSync(absPath, 'r');
+        const head = Buffer.alloc(64 * 1024);
+        const tail = Buffer.alloc(64 * 1024);
+        fs.readSync(fd, head, 0, head.length, 0);
+        fs.readSync(fd, tail, 0, tail.length, fileSize - tail.length);
+        fs.closeSync(fd);
+        const h = crypto.createHash('md5');
+        h.update(head);
+        h.update(tail);
+        h.update(String(fileSize));
+        hash = h.digest('hex');
+      }
+      return { path: normSep(absPath), mtimeMs, size: fileSize, hash };
+    } catch {
+      return null;
+    }
+  }
+
+  function isSensitive(name) {
+    return SENSITIVE_PATTERNS.some((re) => re.test(name));
+  }
+
+  function isHiddenDir(name) {
+    return HIDDEN_PATTERNS.some((re) => re.test(name));
+  }
+
+  function isStrictUtf8(buf) {
+    try {
+      new TextDecoder('utf-8', { fatal: true }).decode(buf);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function detectEncoding(buf) {
+    // UTF-16 BOM
+    if (buf.length >= 2) {
+      if (buf[0] === 0xff && buf[1] === 0xfe) return { encoding: 'utf-16le', confident: true };
+      if (buf[0] === 0xfe && buf[1] === 0xff) return { encoding: 'utf-16be', confident: true };
+    }
+    // UTF-8 BOM
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) return { encoding: 'utf-8', confident: true };
+    // 严格 UTF-8 校验：合法即 UTF-8（中文 GBK 字节流一般不是合法 UTF-8）
+    if (isStrictUtf8(buf)) return { encoding: 'utf-8', confident: true };
+    // 非法 UTF-8 → jschardet 辅助判断，低置信/误判 utf-8 时回退 GBK（中文用户最常见场景）
+    if (jschardet) {
+      const det = jschardet.detect(buf.subarray(0, Math.min(buf.length, 64 * 1024)));
+      if (det && det.encoding && !/^(utf-8|ascii)$/i.test(det.encoding) && det.confidence >= 0.5) {
+        return { encoding: det.encoding, confident: det.confidence > 0.7 };
+      }
+    }
+    return { encoding: 'gbk', confident: false };
+  }
+
+  function decodeBuffer(buf, encoding) {
+    const enc = String(encoding || 'utf-8').toLowerCase();
+    if (enc === 'gbk' || enc === 'gb2312' || enc === 'gb18030') {
+      if (iconv) return iconv.decode(buf, 'gbk');
+      return buf.toString('latin1');
+    }
+    if (enc === 'big5' || enc === 'shift_jis' || enc === 'euc-kr') {
+      if (iconv) return iconv.decode(buf, enc);
+      return buf.toString('latin1');
+    }
+    if (enc === 'utf-16le' || enc === 'utf-16be') {
+      if (iconv) return iconv.decode(buf, enc);
+      return buf.toString('utf8');
+    }
+    return buf.toString('utf8');
+  }
+
+  function encodeContent(content, encoding, eol) {
+    const enc = String(encoding || 'utf-8').toLowerCase();
+    let text = String(content);
+    // EOL 保持：写入时按文件原 EOL 归一
+    if (eol === 'CRLF') {
+      text = text.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
+    } else {
+      text = text.replace(/\r\n/g, '\n');
+    }
+    if (enc === 'gbk' || enc === 'gb2312' || enc === 'gb18030') {
+      return iconv ? iconv.encode(text, 'gbk') : Buffer.from(text, 'latin1');
+    }
+    if (enc === 'utf-16le') return iconv ? iconv.encode(text, 'utf-16le') : Buffer.from(text, 'utf8');
+    if (enc === 'big5' || enc === 'shift_jis' || enc === 'euc-kr') {
+      return iconv ? iconv.encode(text, enc) : Buffer.from(text, 'utf8');
+    }
+    return Buffer.from(text, 'utf8');
+  }
+
+  function detectEol(text) {
+    const crlf = (text.match(/\r\n/g) || []).length;
+    const lf = (text.match(/(?<!\r)\n/g) || []).length;
+    return crlf > lf ? 'CRLF' : 'LF';
+  }
+
+  function isBinary(buf) {
+    const head = buf.subarray(0, Math.min(buf.length, 8192));
+    for (let i = 0; i < head.length; i++) {
+      if (head[i] === 0) return true;
+    }
+    return false;
+  }
+
+  function atomicWrite(absPath, buf) {
+    const tmp = path.join(path.dirname(absPath), `.${path.basename(absPath)}.tmp-${crypto.randomBytes(4).toString('hex')}`);
+    fs.writeFileSync(tmp, buf);
+    fs.renameSync(tmp, absPath); // 同目录 rename 原子替换
+  }
+
+  // 写操作幂等包装
+  async function withIdempotent(requestId, fn) {
+    if (requestId) {
+      const hit = idempotentCache.get(requestId);
+      if (hit && Date.now() - hit.at < WRITE_IDEMPOTENT_MS) return hit.result;
+    }
+    const result = await fn();
+    if (requestId) {
+      idempotentCache.set(requestId, { at: Date.now(), result });
+      if (idempotentCache.size > 500) {
+        const oldest = [...idempotentCache.entries()].sort((a, b) => a[1].at - b[1].at)[0];
+        if (oldest) idempotentCache.delete(oldest[0]);
+      }
+    }
+    return result;
+  }
+
+  // ---------------- 回收站 ----------------
+
+  function trashRootFor(root) {
+    return path.join(root, TRASH_DIR_NAME);
+  }
+
+  function ensureTrashDir(root) {
+    const dir = trashRootFor(root);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  function trashManifestPath(root) {
+    return path.join(trashRootFor(root), 'manifest.json');
+  }
+
+  function readManifest(root) {
+    try {
+      return JSON.parse(fs.readFileSync(trashManifestPath(root), 'utf8'));
+    } catch {
+      return { items: [] };
+    }
+  }
+
+  function writeManifest(root, manifest) {
+    try {
+      ensureTrashDir(root);
+      fs.writeFileSync(trashManifestPath(root), JSON.stringify(manifest, null, 2));
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function moveToTrash(root, absPath) {
+    const manifest = readManifest(root);
+    const id = `${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
+    const trashDir = ensureTrashDir(root);
+    const dest = path.join(trashDir, id);
+    fs.renameSync(absPath, dest);
+    const item = {
+      id,
+      originalPath: normSep(absPath),
+      name: path.basename(absPath),
+      isDir: fs.statSync(dest).isDirectory(),
+      size: fs.statSync(dest).size,
+      deletedAt: Date.now(),
+    };
+    manifest.items.unshift(item);
+    writeManifest(root, manifest);
+    // 清理超期（7 天）与超总量（2GB）
+    cleanupTrash(root, manifest);
+    return item;
+  }
+
+  function cleanupTrash(root, manifest) {
+    const now = Date.now();
+    let total = 0;
+    const keep = [];
+    for (const item of manifest.items) {
+      const p = path.join(trashRootFor(root), item.id);
+      let exists = false;
+      try {
+        exists = fs.existsSync(p);
+      } catch {
+        exists = false;
+      }
+      if (!exists || now - item.deletedAt > TRASH_RETENTION_MS) {
+        try { if (exists) fs.rmSync(p, { recursive: true, force: true }); } catch { /* ignore */ }
+        continue;
+      }
+      if (total + item.size > TRASH_MAX_TOTAL) {
+        try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* ignore */ }
+        continue;
+      }
+      total += item.size;
+      keep.push(item);
+    }
+    if (keep.length !== manifest.items.length) {
+      manifest.items = keep;
+      writeManifest(root, manifest);
+    }
+  }
+
+  // ---------------- 文件监听（T-M1-07） ----------------
+
+  function ensureWatcher(root) {
+    if (!chokidar) return;
+    if (watchers.has(root)) return watchers.get(root);
+    let queue = [];
+    let flushTimer = null;
+    const emit = () => {
+      if (!queue.length) return;
+      const batch = queue.slice();
+      queue = [];
+      try {
+        const br = ctxRef().broadcast;
+        if (br) br({ jsonrpc: '2.0', method: 'event.fs.changed', params: { root: normSep(root), events: batch } });
+      } catch {
+        /* ignore */
+      }
+    };
+    const w = chokidar.watch(root, {
+      ignored: (p) => {
+        const rel = path.relative(root, p);
+        return rel.split(path.sep).some((seg) => isHiddenDir(seg)) || rel.includes('/.ws-trash/') || rel.startsWith(TRASH_DIR_NAME);
+      },
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+    });
+    w.on('all', (event, p) => {
+      if (event === 'raw') return;
+      const rel = normSep(path.relative(root, p));
+      if (!rel) return;
+      queue.push({ type: event, path: rel });
+      if (flushTimer) clearTimeout(flushTimer);
+      flushTimer = setTimeout(() => emit(), 300);
+    });
+    w.on('error', (e) => logger.warn(`[fs] 监听错误: ${e.message}`));
+    watchers.set(root, w);
+    return w;
+  }
+
+  // ---------------- 内置搜索（ripgrep 缺失降级） ----------------
+
+  function builtinSearch(root, query, opts) {
+    const results = [];
+    const regex = opts.regex ? safeRegex(query, opts.caseSensitive) : null;
+    const walk = (dir, rel) => {
+      if (results.length >= SEARCH_MAX_RESULTS) return;
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        if (results.length >= SEARCH_MAX_RESULTS) return;
+        const abs = path.join(dir, e.name);
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) {
+          if (isHiddenDir(e.name)) continue;
+          walk(abs, r);
+        } else if (e.isFile()) {
+          const size = fs.statSync(abs).size;
+          if (size > MAX_EDIT_SIZE) continue; // 超大文件不搜
+          let content;
+          try {
+            const buf = fs.readFileSync(abs);
+            content = decodeBuffer(buf, detectEncoding(buf).encoding);
+          } catch {
+            continue;
+          }
+          const lines = content.split(/\r?\n/);
+          for (let i = 0; i < lines.length; i++) {
+            let hit = false;
+            if (regex) hit = regex.test(lines[i]);
+            else {
+              const hay = opts.caseSensitive ? lines[i] : lines[i].toLowerCase();
+              const needle = opts.caseSensitive ? query : query.toLowerCase();
+              hit = hay.includes(needle);
+            }
+            if (hit) {
+              results.push({ path: normSep(r), line: i + 1, text: lines[i].slice(0, 500) });
+              if (results.length >= SEARCH_MAX_RESULTS) break;
+            }
+          }
+        }
+      }
+    };
+    walk(root, '');
+    return results;
+  }
+
+  function safeRegex(pattern, caseSensitive) {
+    try {
+      return new RegExp(pattern, caseSensitive ? '' : 'i');
+    } catch {
+      return null;
+    }
+  }
+
+  function rgSearch(root, query, opts) {
+    return new Promise((resolve) => {
+      const args = ['--no-heading', '--line-number', '--max-count', String(SEARCH_MAX_RESULTS), '--max-columns', '500'];
+      if (!opts.caseSensitive) args.push('-i');
+      if (opts.regex) args.push('-e', query);
+      else args.push('-F', query);
+      args.push(root);
+      let child;
+      try {
+        const { execFile } = require('child_process');
+        child = execFile('rg', args, { timeout: 10000, maxBuffer: 10 * 1024 * 1024, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }, (err, stdout) => {
+          if (err && !stdout) return resolve(null);
+          const results = [];
+          for (const line of String(stdout).split(/\r?\n/)) {
+            if (!line) continue;
+            const m = line.match(/^(.+?):(\d+):(.*)$/);
+            if (m) results.push({ path: normSep(m[1]), line: Number(m[2]), text: m[3].slice(0, 500) });
+            if (results.length >= SEARCH_MAX_RESULTS) break;
+          }
+          resolve(results);
+        });
+        child.on('error', () => resolve(null));
+      } catch {
+        // spawn 被环境禁止/异常（如沙箱、rg 缺失）→ 降级内置搜索
+        resolve(null);
+      }
+    });
+  }
+
+  // ---------------- RPC 注册 ----------------
+
+  function register(reg) {
+    // ---- requestId 结果查询（T-M1-12）----
+    // 断线重连后，前端对"结果未知"的写操作查询是否已执行，防重复写入/重复扣费
+    reg('fs.requestStatus', async (params = {}) => {
+      const requestId = String(params.requestId || '');
+      if (!requestId) throw new RpcError('E_VALIDATION', '缺少 requestId');
+      const hit = idempotentCache.get(requestId);
+      if (!hit) return { known: false };
+      return { known: true, result: hit.result, at: hit.at };
+    });
+
+    // ---- 列表 ----
+    reg('fs.list', async (params = {}, ctx) => {
+      const r = sandbox().resolve(params.path, params.base);
+      const depth = Math.max(1, Math.min(Number(params.depth) || 1, 5));
+      const showHidden = !!params.showHidden;
+      const entries = [];
+      let dirs;
+      try {
+        dirs = fs.readdirSync(r.abs, { withFileTypes: true });
+      } catch (e) {
+        throw new RpcError('E_PATH_NOT_FOUND', `目录不存在或无法读取: ${e.message}`);
+      }
+      dirs.sort((a, b) => (a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1));
+      for (const e of dirs) {
+        const name = e.name;
+        if (e.isDirectory() && isHiddenDir(name) && !showHidden) continue;
+        const abs = path.join(r.abs, name);
+        const entry = {
+          name,
+          relPath: normSep(path.join(r.rel, name)),
+          type: e.isDirectory() ? 'dir' : 'file',
+          hidden: isHiddenDir(name),
+          sensitive: !e.isDirectory() && isSensitive(name),
+        };
+        try {
+          const st = fs.statSync(abs);
+          entry.size = st.size;
+          entry.mtimeMs = st.mtimeMs;
+          if (e.isDirectory() && depth > 1) {
+            entry.children = listDir(abs, depth - 1, showHidden, path.join(r.rel, name));
+          }
+        } catch {
+          entry.size = 0;
+          entry.mtimeMs = 0;
+        }
+        entries.push(entry);
+      }
+      return { root: r.root, rel: r.rel, entries };
+    });
+
+    // ---- stat ----
+    reg('fs.stat', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      const st = fs.statSync(r.abs);
+      return {
+        name: path.basename(r.abs),
+        relPath: normSep(r.rel),
+        type: st.isDirectory() ? 'dir' : 'file',
+        size: st.size,
+        mtimeMs: st.mtimeMs,
+        snapshot: st.isFile() ? snapshotOf(r.abs, st.size) : null,
+        sensitive: !st.isDirectory() && isSensitive(path.basename(r.abs)),
+      };
+    });
+
+    // ---- 读 ----
+    reg('fs.read', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      const st = fs.statSync(r.abs);
+      if (st.isDirectory()) throw new RpcError('E_PATH_NOT_DIR', '不能以读文件方式打开文件夹');
+      if (st.size > MAX_PREVIEW_SIZE) {
+        return { content: '', size: st.size, tooLarge: true, reason: 'EXCEED_20MB', message: '文件超过 20MB，仅支持下载' };
+      }
+      const buf = fs.readFileSync(r.abs);
+      if (isBinary(buf)) {
+        throw new RpcError('E_BINARY_FILE', '二进制文件无法编辑，仅支持下载');
+      }
+      const det = detectEncoding(buf);
+      const content = decodeBuffer(buf, det.encoding);
+      const snapshot = snapshotOf(r.abs, st.size);
+      if (st.size > MAX_EDIT_SIZE) {
+        // >2MB：只读预览（前 512KB）
+        return {
+          content: content.slice(0, 512 * 1024),
+          encoding: det.encoding,
+          eol: detectEol(content),
+          size: st.size,
+          truncated: true,
+          readOnly: true,
+          reason: 'EXCEED_2MB',
+          snapshot,
+        };
+      }
+      return { content, encoding: det.encoding, eol: detectEol(content), size: st.size, truncated: false, snapshot };
+    });
+
+    // ---- 写（带快照冲突检测 + 原子写 + requestId 幂等）----
+    reg('fs.write', async (params = {}, ctx) => {
+      const requestId = params.requestId;
+      return withIdempotent(requestId, async () => {
+        const r = sandbox().resolve(params.path, params.base);
+        const content = String(params.content ?? '');
+        // 冲突检测：携带快照时比对
+        if (params.snapshot) {
+          const cur = snapshotOf(r.abs, undefined);
+          const snap = params.snapshot;
+          const mismatch = !cur || cur.mtimeMs !== snap.mtimeMs || cur.size !== snap.size || cur.hash !== snap.hash;
+          if (mismatch) {
+            const err = new RpcError('E_FILE_CHANGED', '文件已在磁盘上被外部修改');
+            err.data = { remote: cur };
+            throw err;
+          }
+        }
+        const encoding = params.encoding || 'utf-8';
+        const eol = params.eol || 'LF';
+        const buf = encodeContent(content, encoding, eol);
+        try {
+          atomicWrite(r.abs, buf);
+        } catch (e) {
+          if ((e && e.code === 'EBUSY') || (e && e.code === 'EPERM')) throw new RpcError('E_FILE_LOCKED', `文件被占用: ${e.message}`);
+          if (e && e.code === 'ENOSPC') throw new RpcError('E_DISK_FULL', '磁盘空间不足');
+          throw e;
+        }
+        const snap = snapshotOf(r.abs, buf.length);
+        return { ok: true, snapshot: snap, size: buf.length };
+      });
+    });
+
+    // ---- 新建目录/文件 ----
+    reg('fs.mkdir', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      if (fs.existsSync(r.abs)) throw new RpcError('E_PATH_EXISTS', '同名文件/文件夹已存在');
+      fs.mkdirSync(r.abs, { recursive: true });
+      return { ok: true, relPath: normSep(r.rel) };
+    });
+
+    reg('fs.createFile', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      if (fs.existsSync(r.abs)) throw new RpcError('E_PATH_EXISTS', '同名文件已存在');
+      fs.writeFileSync(r.abs, '');
+      return { ok: true, relPath: normSep(r.rel) };
+    });
+
+    // ---- 重命名/移动 ----
+    reg('fs.rename', async (params = {}) => {
+      const requestId = params.requestId;
+      return withIdempotent(requestId, async () => {
+        const from = sandbox().resolve(params.path, params.base);
+        const to = sandbox().resolve(params.newPath, params.base);
+        if (from.root !== to.root) throw new RpcError('E_PATH_ESCAPE', '不能移动到项目目录之外');
+        if (fs.existsSync(to.abs)) throw new RpcError('E_PATH_EXISTS', '目标位置已存在同名文件/文件夹');
+        fs.renameSync(from.abs, to.abs);
+        return { ok: true };
+      });
+    });
+
+    // ---- 复制 ----
+    reg('fs.copy', async (params = {}) => {
+      const from = sandbox().resolve(params.path, params.base);
+      const to = sandbox().resolve(params.destPath, params.base);
+      if (from.root !== to.root) throw new RpcError('E_PATH_ESCAPE', '不能复制到项目目录之外');
+      if (fs.existsSync(to.abs)) throw new RpcError('E_PATH_EXISTS', '目标位置已存在同名文件/文件夹');
+      fs.cpSync(from.abs, to.abs, { recursive: true });
+      return { ok: true };
+    });
+
+    // ---- 删除（进回收站）----
+    reg('fs.rm', async (params = {}, ctx) => {
+      const requestId = params.requestId;
+      return withIdempotent(requestId, async () => {
+        const r = sandbox().resolve(params.path, params.base);
+        if (r.rel === '' || r.rel === '.') throw new RpcError('E_VALIDATION', '不能删除项目根目录');
+        if (cfg().trashEnabled) {
+          const item = moveToTrash(r.root, r.abs);
+          return { ok: true, trashed: true, trashId: item.id };
+        }
+        fs.rmSync(r.abs, { recursive: true, force: true });
+        return { ok: true, trashed: false };
+      });
+    });
+
+    // ---- 回收站 ----
+    reg('fs.trash.list', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      return { items: readManifest(r.root).items };
+    });
+
+    reg('fs.trash.restore', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      const manifest = readManifest(r.root);
+      const item = manifest.items.find((i) => i.id === params.trashId);
+      if (!item) throw new RpcError('E_PATH_NOT_FOUND', '回收站条目不存在');
+      const src = path.join(trashRootFor(r.root), item.id);
+      const originalAbs = item.originalPath.replace(/\//g, path.sep);
+      // 恢复目标必须在项目内
+      const restored = sandbox().resolve(originalAbs, r.root);
+      if (fs.existsSync(restored.abs)) throw new RpcError('E_PATH_EXISTS', '原位置已存在同名文件，请先处理');
+      fs.renameSync(src, restored.abs);
+      manifest.items = manifest.items.filter((i) => i.id !== item.id);
+      writeManifest(r.root, manifest);
+      return { ok: true };
+    });
+
+    reg('fs.trash.empty', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      const manifest = readManifest(r.root);
+      for (const item of manifest.items) {
+        try {
+          fs.rmSync(path.join(trashRootFor(r.root), item.id), { recursive: true, force: true });
+        } catch {
+          /* ignore */
+        }
+      }
+      manifest.items = [];
+      writeManifest(r.root, manifest);
+      return { ok: true };
+    });
+
+    // ---- 搜索 ----
+    reg('fs.search', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      const query = String(params.query || '').trim();
+      if (!query) throw new RpcError('E_VALIDATION', '搜索关键词为空');
+      const opts = {
+        caseSensitive: !!params.caseSensitive,
+        regex: !!params.regex,
+      };
+      let results = await rgSearch(r.abs, query, opts);
+      if (results === null) results = builtinSearch(r.abs, query, opts);
+      const truncated = results.length >= SEARCH_MAX_RESULTS;
+      return { results: results.slice(0, SEARCH_MAX_RESULTS), truncated };
+    });
+
+    // ---- 监听 ----
+    reg('fs.watch', async (params = {}) => {
+      const r = sandbox().resolve(params.path, params.base);
+      ensureWatcher(r.root);
+      return { ok: true, root: normSep(r.root) };
+    });
+  }
+
+  function listDir(absDir, depth, showHidden, relBase) {
+    const out = [];
+    let dirs;
+    try {
+      dirs = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return out;
+    }
+    for (const e of dirs) {
+      if (e.isDirectory() && isHiddenDir(e.name) && !showHidden) continue;
+      const abs = path.join(absDir, e.name);
+      const entry = {
+        name: e.name,
+        relPath: normSep(path.join(relBase, e.name)),
+        type: e.isDirectory() ? 'dir' : 'file',
+        hidden: e.isDirectory() && isHiddenDir(e.name),
+        sensitive: !e.isDirectory() && isSensitive(e.name),
+      };
+      try {
+        const st = fs.statSync(abs);
+        entry.size = st.size;
+        entry.mtimeMs = st.mtimeMs;
+        if (e.isDirectory() && depth > 1) entry.children = listDir(abs, depth - 1, showHidden, path.join(relBase, e.name));
+      } catch {
+        entry.size = 0;
+        entry.mtimeMs = 0;
+      }
+      out.push(entry);
+    }
+    return out;
+  }
+
+  return { register };
+}
+
+module.exports = { createFsMethods };