zipcalm 0.0.0-stage → 1.0.2

package/server/core/fs/search.js

@@ -0,0 +1,108 @@
+// 文件名搜索（docs/16 批次②的需求①）：只在**当前根内**按文件名做子串匹配
+//
+// 为什么不做全文索引：这是「找某个文件在哪」的诉求，不是内容检索；索引要持久化、要失效策略、
+// 要吃内存，对一个 NAS 文件管理器属于 YAGNI。这里用**有界遍历**：深度/结果数/耗时三重上限，
+// 超了就把 truncated 置真并返回已有结果 —— 宁可给部分结果，也不能让一次搜索把服务拖住。
+//
+// 安全：不跟随符号链接（越界链接一律不进入）；跳过黑名单目录（如 @eaDir，避免翻元数据目录）。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+/** 搜索边界（写死，不做成配置：这是"防止一次搜索拖垮服务"的保护，不是业务策略） */
+export const SEARCH_LIMITS = Object.freeze({
+  maxDepth: 6,
+  maxResults: 500,
+  timeoutMs: 3000,
+  /** 单目录最多读多少项，避免超大目录把一次 readdir 拖很久 */
+  maxEntriesPerDir: 5000,
+});
+
+/** 目录名是否属于"不搜"的（黑名单目录规则 + 点开头系统目录） */
+function isSkippedDir(name, layers) {
+  if (name.startsWith('.')) return true;
+  if (!Array.isArray(layers) || layers.length === 0) return false;
+  // 复用黑名单的目录名匹配（@eaDir 这类），但只对目录名，不误伤普通文件
+  return layers.some((layer) => (layer.patterns || []).some((pattern) => pattern === name));
+}
+
+/**
+ * 在 rootAbs 内按文件名子串搜索。
+ * @param {{rootAbs: string, userPath?: string}} ctx 当前根与搜索起点（用户路径，缺省根）
+ * @param {string} query 关键字（非空；大小写不敏感）
+ * @param {{limit?: number, layers?: Array}} [options]
+ * @returns {Promise<{items: Array, truncated: boolean, scannedDirs: number, elapsedMs: number}>}
+ */
+export async function searchFiles(ctx, query, options = {}) {
+  const keyword = String(query || '').trim().toLowerCase();
+  if (keyword.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'q 不能为空');
+  }
+  const limit = Math.min(SEARCH_LIMITS.maxResults, Math.max(1, Number(options.limit) || 100));
+  const rootAbs = ctx.rootAbs;
+  const startAbs = options.startAbs || rootAbs;
+  const startedAt = Date.now();
+  const items = [];
+  let scannedDirs = 0;
+  let truncated = false;
+
+  /** 时间预算耗尽就停（哪怕还没扫完） */
+  const budgetExceeded = () => Date.now() - startedAt > SEARCH_LIMITS.timeoutMs;
+
+  async function walk(dirAbs, depth) {
+    if (truncated || budgetExceeded() || items.length >= limit) {
+      truncated = true;
+      return;
+    }
+    scannedDirs += 1;
+    let dirents;
+    try {
+      dirents = await fsp.readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return; // 不可读的子树直接跳过（不打断整次搜索）
+    }
+    if (dirents.length > SEARCH_LIMITS.maxEntriesPerDir) {
+      dirents = dirents.slice(0, SEARCH_LIMITS.maxEntriesPerDir);
+      truncated = true;
+    }
+    for (const dirent of dirents) {
+      if (truncated || budgetExceeded() || items.length >= limit) {
+        truncated = true;
+        return;
+      }
+      if (dirent.isSymbolicLink()) continue; // 不跟随：越界链接不该被搜索"带进来"
+      const childAbs = path.join(dirAbs, dirent.name);
+      if (dirent.isDirectory()) {
+        // 目录也参与匹配（用户搜"照片在哪"时，目录名往往就是答案），但匹配后仍继续往下走
+        if (dirent.name.toLowerCase().includes(keyword)) {
+          items.push(await describeEntry(childAbs, rootAbs, 'dir'));
+        }
+        if (depth + 1 > SEARCH_LIMITS.maxDepth) continue;
+        if (isSkippedDir(dirent.name, options.layers)) continue;
+        await walk(childAbs, depth + 1);
+        continue;
+      }
+      if (!dirent.isFile()) continue;
+      if (!dirent.name.toLowerCase().includes(keyword)) continue;
+      items.push(await describeEntry(childAbs, rootAbs, 'file'));
+    }
+  }
+
+  await walk(startAbs, 0);
+  return { items, truncated, scannedDirs, elapsedMs: Date.now() - startedAt };
+}
+
+/** 单个命中项：只回传用户路径，**不带 absPath**（契约红线） */
+async function describeEntry(absPath, rootAbs, entryType) {
+  const stat = await fsp.lstat(absPath).catch(() => null);
+  const userPath = `/${path.relative(rootAbs, absPath).split(path.sep).join('/')}`;
+  return {
+    path: userPath,
+    name: path.basename(absPath),
+    type: entryType,
+    size: stat ? stat.size : 0,
+    mtime: stat ? Math.trunc(stat.mtimeMs) : 0,
+  };
+}

package/server/core/fs/stat.js

@@ -0,0 +1,110 @@
+// 单条目详情（M1：GET /api/v1/fs/stat）
+//
+// 与 list 共用同一套白名单（core/fs/safePath.js），因此不存在"list 安全、stat 漏了"的缺口。
+// 目录额外返回 childCount（只数一层，用于前端"进入前先看有多少项"）。
+//
+// 结构：基础字段 → 符号链接补充 → 目录补充，三步各一小函数；
+// statEntry 只负责串起来，不再把三类信息混在一个函数里。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError, toApiError } from '../../lib/errors.js';
+import { matchEntry } from '../compress/blacklist.js';
+import { ROOT_USER_PATH, resolveRequestPath } from './safePath.js';
+
+/** 入口类型判定（不跟随符号链接） */
+function entryType(stat) {
+  if (stat.isSymbolicLink()) return 'symlink';
+  if (stat.isDirectory()) return 'dir';
+  if (stat.isFile()) return 'file';
+  return 'other';
+}
+
+/** 基础字段（含可读性探测） */
+async function buildBaseEntry(userPath, realPath, stat) {
+  const type = entryType(stat);
+  let readable = true;
+  try {
+    await fs.access(realPath, fs.constants.R_OK);
+  } catch {
+    readable = false;
+  }
+  return {
+    name: userPath === ROOT_USER_PATH ? '/' : path.basename(userPath),
+    path: userPath,
+    type,
+    size: type === 'file' ? stat.size : 0,
+    mtime: Math.trunc(stat.mtimeMs),
+    readable,
+    extension: type === 'file' ? path.extname(userPath) : '',
+    enterable: type === 'dir',
+  };
+}
+
+/** 符号链接补充：跟随链接判定可进入性，并给出链接目标（悬空链接标记 broken） */
+async function applySymlinkInfo(entry, realPath, userPath) {
+  try {
+    const target = await fs.stat(realPath); // 跟随链接（白名单已校验过 realpath）
+    entry.enterable = target.isDirectory();
+    entry.linkTarget = await fs.readlink(realPath);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      entry.enterable = false;
+      entry.broken = true;
+      return;
+    }
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '符号链接无法解析', { path: userPath });
+  }
+}
+
+/** 目录补充：只数一层子项数量 */
+async function applyDirInfo(entry, realPath) {
+  try {
+    const children = await fs.readdir(realPath);
+    entry.childCount = children.length;
+  } catch (error) {
+    throw toApiError(error);
+  }
+}
+
+/**
+ * 取单条目详情。
+ * @param {{rootAbs: string, maxPathLength?: number}} ctx
+ * @param {string} rawPath 用户路径（必须存在；根路径也可，返回存储根本身的信息）
+ */
+/**
+ * 单条目详情。
+ * @param {object} ctx fsContext
+ * @param {string} rawPath 用户路径
+ * @param {{blacklistLayers?: Array}} [options] 黑名单层（契约 §4.2：blacklisted/blacklistLayer 由服务端算）
+ */
+export async function statEntry(ctx, rawPath, options = {}) {
+  const { userPath, realPath } = await resolveRequestPath(
+    {
+      rootAbs: ctx.rootAbs,
+      maxPathLength: ctx.maxPathLength,
+      maxPathSegmentLength: ctx.maxPathSegmentLength,
+    },
+    rawPath,
+  );
+
+  let fileStat;
+  try {
+    fileStat = await fs.lstat(realPath);
+  } catch (error) {
+    throw toApiError(error);
+  }
+
+  const entry = await buildBaseEntry(userPath, realPath, fileStat);
+  if (entry.type === 'symlink') await applySymlinkInfo(entry, realPath, userPath);
+  if (entry.type === 'dir') await applyDirInfo(entry, realPath);
+
+  const layers = Array.isArray(options.blacklistLayers) ? options.blacklistLayers : [];
+  const hit = layers.length > 0
+    ? matchEntry(layers, { name: path.basename(userPath), segments: userPath.split('/').filter(Boolean) })
+    : null;
+  entry.blacklisted = Boolean(hit);
+  entry.blacklistLayer = hit ? hit.layer : null;
+  return entry;
+}

package/server/core/fs/systemTrash.js

@@ -0,0 +1,212 @@
+// 群晖系统回收站（Synology `#recycle`）调用封装
+//
+// 为什么需要它：项目自己的 `storage/trash` 只对"本应用内删除"可恢复，用户在 DSM 的
+// File Station 里看不到、也清不掉；而 NAS 用户的心智是"去 File Station 回收站找回来"。
+// 群晖自带的 `/usr/syno/bin/synorecycle` 正是这个用途 —— 它不是 `rm -rf`，走的是群晖删除流程：
+//
+//   synorecycle --unlink share=<共享名> rpath=<共享内相对路径>   # 文件 → #recycle
+//   synorecycle --rmdir  share=<共享名> rpath=<共享内相对路径>   # 目录 → #recycle
+//
+// 两个实测事实（决定了本模块的边界）：
+// 1. `#recycle` 的权限**可能可读也可能不可读**（取决于部署方是否放开）：
+//    - 可读 → 删后校验可以更强：确认目标真的出现在 `#recycle/<rpath>`；
+//    - 不可读 → 退回只看"原位置是否消失"（不能因为读不到回收站就判失败）；
+// 2. synorecycle 失败时什么都不会发生 → 调用方必须能回退到项目 trash，
+//    所以本模块**只报告失败、绝不自己兜底删除**（函数内没有任何 rm/unlink 作为"补救"）。
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/** 群晖回收站工具（固定路径；不可用就回退项目 trash） */
+const SYNORECYCLE_BIN = '/usr/syno/bin/synorecycle';
+
+/** 卷路径：/volume<数字>/<共享名><剩余>；两位数卷号（/volume10）也要支持 */
+const VOLUME_SHARE_PATTERN = /^\/volume\d+\/([^/]+)(\/.*)?$/;
+
+/** 以这些字符开头的第一段是系统目录，不是共享文件夹（@appdata / @eaDir / #recycle …） */
+const SYSTEM_SHARE_PREFIX = /^[@#]/;
+
+/** 命令超时：删单个文件/目录不该超过它，超时按失败处理（否则任务会一直挂着） */
+const COMMAND_TIMEOUT_MS = 30000;
+
+/**
+ * 探测群晖回收站是否可用。
+ * @returns {{available: boolean, binary: string|null}}
+ */
+export function detect() {
+  try {
+    fs.accessSync(SYNORECYCLE_BIN, fs.constants.X_OK);
+    return { available: true, binary: SYNORECYCLE_BIN };
+  } catch {
+    return { available: false, binary: null };
+  }
+}
+
+/**
+ * 绝对路径 → 群晖回收站参数（共享名 + 共享内相对路径）。
+ *
+ * 规则：`/volume<数字>/<第一段>/<其余>`。
+ * 返回 null 的情况（调用方据此回退，不尝试执行）：
+ * - 不在 /volumeN 下（如项目自己的 storage/、/mnt/xxx）
+ * - 第一段以 @ / # 开头（@appdata / @eaDir / #recycle 不是共享）
+ * - 只有卷根（/volume1）或只有共享根（/volume1/VirtualDSM）—— 删"共享本身"不是这个功能的场景
+ *
+ * @param {string} absPath
+ * @returns {{share: string, rpath: string} | null}
+ */
+export function toSharePath(absPath) {
+  if (typeof absPath !== 'string' || absPath.length === 0) return null;
+  // 统一成 POSIX 分隔符再解析（本项目内部路径本来就是 POSIX，这里只是防御）
+  const normalized = path.posix.normalize(absPath.replace(/\\/g, '/'));
+  const matched = normalized.match(VOLUME_SHARE_PATTERN);
+  if (!matched) return null;
+
+  const share = matched[1];
+  const rest = matched[2] || '';
+  if (!share || SYSTEM_SHARE_PREFIX.test(share)) return null;
+  // 共享根 / 卷根不删（rpath 为空说明只到共享这一层）
+  if (rest.length === 0) return null;
+
+  return { share, rpath: rest };
+}
+
+/**
+ * 回收站里"这份文件应该在哪"：`/volumeN/<共享>/#recycle/<rpath>`。
+ * 实测映射：删 /volume1/VirtualDSM/a/b.txt → /volume1/VirtualDSM/#recycle/a/b.txt
+ */
+function recyclePathOf(absPath) {
+  const normalized = path.posix.normalize(String(absPath).replace(/\\/g, '/'));
+  const matched = normalized.match(VOLUME_SHARE_PATTERN);
+  if (!matched) return null;
+  const shareName = matched[1];
+  const shareRoot = normalized.slice(0, normalized.indexOf(shareName) + shareName.length);
+  const rpath = matched[2] || '';
+  if (rpath.length === 0) return null;
+  return path.posix.join(shareRoot, '#recycle', rpath);
+}
+
+/** 回收站可读才做加强校验（不可读时返回 null，表示"无法判断"，不当作失败） */
+async function recycleDirReadable(absPath) {
+  const normalized = path.posix.normalize(String(absPath).replace(/\\/g, '/'));
+  const matched = normalized.match(VOLUME_SHARE_PATTERN);
+  if (!matched) return null;
+  const shareName = matched[1];
+  const shareRoot = normalized.slice(0, normalized.indexOf(shareName) + shareName.length);
+  const recycleRoot = path.posix.join(shareRoot, '#recycle');
+  try {
+    await fsp.readdir(recycleRoot);
+    return recycleRoot;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 删后加强校验：目标是否真的出现在回收站里。
+ * synorecycle 返回后落点可能有毫秒级延迟，所以**轮询**而不是只看一次。
+ * @returns {Promise<{verifiable: boolean, found: boolean}>}
+ */
+async function verifyInRecycle(absPath) {
+  const candidate = recyclePathOf(absPath);
+  if (!candidate) return { verifiable: false, found: false };
+  const recycleRoot = await recycleDirReadable(absPath);
+  if (!recycleRoot) return { verifiable: false, found: false };
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    if (await exists(candidate)) return { verifiable: true, found: true };
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return { verifiable: true, found: false };
+}
+
+/** 原位置是否还在（stat 成功即存在；权限错误按"存在"处理，宁可判失败也不误报成功） */
+async function exists(absPath) {
+  try {
+    await fsp.lstat(absPath);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return false;
+    return true;
+  }
+}
+
+/**
+ * 执行一次 synorecycle。
+ * @param {string} flag `--unlink` | `--rmdir`
+ * @param {{share: string, rpath: string}} target
+ * @param {string} [binary] 可注入（测试里用假二进制验证失败回退路径）
+ * @returns {Promise<{ok: boolean, reason?: string, detail?: string}>}
+ */
+async function runSynorecycle(flag, target, binary) {
+  const bin = binary || SYNORECYCLE_BIN;
+  try {
+    await execFileAsync(bin, [flag, `share=${target.share}`, `rpath=${target.rpath}`], {
+      timeout: COMMAND_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+    });
+    return { ok: true };
+  } catch (error) {
+    // 捕获退出码与 stderr：出问题时日志里要能看出是"没有权限"还是"共享名不对"
+    const detail = [error && error.code, error && error.stderr, error && error.message]
+      .filter(Boolean)
+      .join(' | ')
+      .slice(0, 500);
+    return { ok: false, reason: 'command_failed', detail };
+  }
+}
+
+/**
+ * 通用流程：解析 → 存在性/类型检查 → 执行 → **删后校验原位置已消失**。
+ * @param {'--unlink'|'--rmdir'} flag
+ * @param {string} absPath
+ * @param {'file'|'dir'} expectType
+ * @param {{binary?: string}} [options]
+ */
+async function recycle(flag, absPath, expectType, options = {}) {
+  const target = toSharePath(absPath);
+  if (!target) return { ok: false, reason: 'not_in_share' };
+
+  const detected = detect();
+  const binary = options.binary || detected.binary;
+  if (!binary) return { ok: false, reason: 'unavailable' };
+
+  let stat = null;
+  try {
+    stat = await fsp.lstat(absPath);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { ok: false, reason: 'not_found' };
+    return { ok: false, reason: 'stat_failed', detail: String(error && error.message).slice(0, 200) };
+  }
+  if (expectType === 'file' && stat.isDirectory()) return { ok: false, reason: 'is_directory' };
+  if (expectType === 'dir' && !stat.isDirectory()) return { ok: false, reason: 'not_a_directory' };
+
+  const run = await runSynorecycle(flag, target, binary);
+  if (!run.ok) return run;
+
+  // 删后校验第一层：原位置必须消失（返回成功却还在 = 假成功，必须按失败上报）
+  if (await exists(absPath)) return { ok: false, reason: 'still_exists', detail: 'synorecycle 返回成功但原位置仍在' };
+
+  // 删后校验第二层（能读回收站时）：确认它真的躺在 #recycle 里；读不到就退回只看原位消失
+  const recycled = await verifyInRecycle(absPath);
+  if (recycled.verifiable && !recycled.found) {
+    return { ok: false, reason: 'not_in_recycle', detail: '原位已消失，但回收站里找不到目标（可能被其他策略清理）' };
+  }
+  return { ok: true, verifiedInRecycle: recycled.verifiable ? recycled.found : null };
+}
+
+/**
+ * 把文件移入群晖系统回收站。
+ * 失败只返回原因，**不做任何兜底删除**（回退由调用方决定）。
+ */
+export async function unlinkFile(absPath, options = {}) {
+  return recycle('--unlink', absPath, 'file', options);
+}
+
+/** 把目录移入群晖系统回收站（同样只报告，不兜底）。 */
+export async function rmdirDir(absPath, options = {}) {
+  return recycle('--rmdir', absPath, 'dir', options);
+}

package/server/core/fs/writeOps.js

@@ -0,0 +1,257 @@
+// 文件系统写操作（M8 前置）：mkdir / rename / move / delete
+//
+// 契约：docs/M0/API规范.md §4.2 的四个端点，形状严格照契约：
+// - mkdir  幂等：已存在目录 → created:false；父目录不存在 → PATH_NOT_FOUND；同名文件占位 → TARGET_EXISTS
+// - rename 仅同目录改名；newName 不含分隔符；冲突绝不覆盖（TARGET_EXISTS）
+// - move   单次 ≤ limits.maxMoveItems；目标同名 → 整批拒绝（不做部分移动）；EXDEV → CROSS_DEVICE_UNSUPPORTED
+// - delete **进回收站，不是真删**：统一走 core/compress/deleter.js（与 M5 删除原文件同一机制），
+//          返回 trashBatch，可恢复；不存在的路径计入 notFound，整体仍 ok
+//
+// 安全：所有路径都经 safePath 白名单（resolveRequestPath，含符号链接复核），绝不直接用请求里的字符串拼路径。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { parentUserPath, resolveRequestPath } from './safePath.js';
+
+/** rename 的新名字不允许出现的字符（分隔符与 NUL） */
+const FORBIDDEN_NAME_CHARS = /[/\\\0]/;
+
+/** 目标是否已存在（lstat；符号链接也算占用，绝不覆盖） */
+async function targetExists(absPath) {
+  try {
+    await fsp.lstat(absPath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+/**
+ * 解析"要创建的目标"：目标本身可能不存在，所以校验的是**父目录的真实路径**（父目录的符号链接
+ * 也不能指向根外），再把 basename 拼回去 —— 既守住白名单，又不会把合法的 mkdir 判死。
+ * @returns {{parentAbs: string, targetAbs: string}}
+ */
+async function resolveCreateTarget(ctx, userPath, absPath) {
+  const parentUser = parentUserPath(userPath);
+  if (parentUser === null) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, '不能在存储根上再建根目录');
+  }
+  const parent = await resolveRequestPath(ctx, parentUser);
+  const parentStat = await fsp.lstat(parent.realPath).catch(() => null);
+  if (!parentStat || !parentStat.isDirectory()) {
+    throw apiError(ERROR_CODES.PATH_NOT_FOUND, '父目录不存在', { path: userPath });
+  }
+  return { parentAbs: parent.realPath, targetAbs: path.join(parent.realPath, path.basename(absPath)) };
+}
+
+/**
+ * POST /fs/mkdir
+ * @param {object} ctx fsContext（rootAbs 等）
+ * @param {{path?: string}} body
+ */
+export async function makeDirectory(ctx, body) {
+  if (typeof body.path !== 'string' || body.path.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'path 必填');
+  }
+  // 目标本身可以不存在（这正是 mkdir 的场景），所以 mustExist:false；真正的越界防护在下面的父目录解析
+  const { userPath, absPath } = await resolveRequestPath(ctx, body.path, { mustExist: false });
+
+  const { parentAbs, targetAbs } = await resolveCreateTarget(ctx, userPath, absPath);
+
+  const existing = await fsp.lstat(targetAbs).catch(() => null);
+  if (existing) {
+    if (existing.isDirectory()) return { path: userPath, created: false }; // 幂等
+    throw apiError(ERROR_CODES.TARGET_EXISTS, '同名文件已存在', { path: userPath });
+  }
+
+  try {
+    await fsp.mkdir(targetAbs);
+  } catch (error) {
+    if (error.code === 'EEXIST') return { path: userPath, created: false };
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw apiError(ERROR_CODES.PERMISSION_DENIED, '没有权限创建目录', { path: userPath });
+    }
+    throw error;
+  }
+  return { path: userPath, created: true };
+}
+
+/** 新名字合法性（空/含分隔符/过长都在进磁盘前拦，避免冒成 500） */
+function assertValidName(newName, ctx) {
+  if (typeof newName !== 'string' || newName.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'newName 必填');
+  }
+  if (FORBIDDEN_NAME_CHARS.test(newName)) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'newName 不能包含路径分隔符', { newName });
+  }
+  if (newName.length > ctx.maxPathSegmentLength) {
+    throw apiError(ERROR_CODES.INVALID_PATH, 'newName 超过单个路径段长度上限', { newName });
+  }
+}
+
+/**
+ * POST /fs/rename（仅同目录改名，绝不覆盖）
+ * @returns {{path: string, oldPath: string}}
+ */
+export async function renameEntry(ctx, body) {
+  if (typeof body.path !== 'string' || body.path.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'path 必填');
+  }
+  assertValidName(body.newName, ctx);
+
+  const { userPath, realPath } = await resolveRequestPath(ctx, body.path);
+  // 目标由"源的真实父目录 + 已校验的新名字"组成：不存在的目标**不能**再走 realpath 校验
+  // （那会把合法的改名判成 PATH_NOT_FOUND）；安全边界由源的真实路径 + newName 非法字符校验兜住。
+  const targetAbs = path.join(path.dirname(realPath), body.newName);
+
+  if (await targetExists(targetAbs)) {
+    throw apiError(ERROR_CODES.TARGET_EXISTS, '目标名称已存在（不会覆盖）', { newName: body.newName });
+  }
+  const sourceStat = await fsp.lstat(realPath).catch(() => null);
+  if (!sourceStat) throw apiError(ERROR_CODES.PATH_NOT_FOUND, '源路径不存在', { path: userPath });
+
+  try {
+    await fsp.rename(realPath, targetAbs);
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw apiError(ERROR_CODES.PERMISSION_DENIED, '没有权限改名', { path: userPath });
+    }
+    throw error;
+  }
+  return {
+    path: path.posix.join(path.posix.dirname(userPath), body.newName),
+    oldPath: userPath,
+  };
+}
+
+/**
+ * 整批校验：源都存在、目标目录内没有同名项（契约：目标同名整批拒绝，不做部分移动）。
+ * 与执行分开是为了让"先验证后动手"这件事一眼可见。
+ */
+async function planMoves(ctx, body) {
+  const target = await resolveRequestPath(ctx, body.targetDir);
+  const targetStat = await fsp.lstat(target.absPath).catch(() => null);
+  if (!targetStat || !targetStat.isDirectory()) {
+    throw apiError(ERROR_CODES.PATH_NOT_FOUND, '目标目录不存在', { targetDir: body.targetDir });
+  }
+
+  const plans = [];
+  for (const rawPath of body.paths) {
+    const source = await resolveRequestPath(ctx, rawPath);
+    const destAbs = path.join(target.realPath, path.basename(source.realPath));
+    if (destAbs === source.realPath) {
+      throw apiError(ERROR_CODES.TARGET_EXISTS, '源与目标相同', { path: source.userPath });
+    }
+    if (await targetExists(destAbs)) {
+      throw apiError(ERROR_CODES.TARGET_EXISTS, '目标目录已有同名项（整批取消）', { path: source.userPath, name: path.basename(destAbs) });
+    }
+    plans.push({ source, destAbs, destUser: path.posix.join(target.userPath, path.basename(destAbs)) });
+  }
+  return plans;
+}
+
+/** 单个 rename；错误码翻译集中在这里 */
+async function moveOne(plan) {
+  try {
+    await fsp.rename(plan.source.realPath, plan.destAbs);
+  } catch (error) {
+    if (error.code === 'EXDEV') {
+      // 契约：跨分区不支持移动，提示改用"复制 + 删除原文件"
+      throw apiError(ERROR_CODES.CROSS_DEVICE_UNSUPPORTED, '跨分区移动不支持，请改用「复制 + 删除原文件」', {
+        path: plan.source.userPath,
+      });
+    }
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw apiError(ERROR_CODES.PERMISSION_DENIED, '没有权限移动', { path: plan.source.userPath });
+    }
+    throw error;
+  }
+}
+
+/**
+ * POST /fs/move（同步；目标同名整批拒绝，避免"搬了一半"）
+ * @returns {{moved: string[], skipped: string[]}}
+ */
+export async function moveEntries(ctx, body) {
+  if (!Array.isArray(body.paths) || body.paths.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'paths 必须是非空字符串数组');
+  }
+  if (body.paths.length > ctx.maxMoveItems) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, `单次最多移动 ${ctx.maxMoveItems} 项`, { count: body.paths.length });
+  }
+  if (typeof body.targetDir !== 'string' || body.targetDir.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'targetDir 必填');
+  }
+
+  const plans = await planMoves(ctx, body);
+  const moved = [];
+  for (const plan of plans) {
+    await moveOne(plan);
+    moved.push(plan.destUser);
+  }
+  return { moved, skipped: [] };
+}
+
+/**
+ * POST /fs/delete（进回收站；复用 deleter，与 M5 删除原文件同一机制）
+ * @param {object} ctx fsContext
+ * @param {{paths?: string[]}} body
+ * @param {{deleter: object, maxDeleteItems: number}} deps
+ */
+export async function deleteEntries(ctx, body, deps) {
+  if (!Array.isArray(body.paths) || body.paths.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'paths 必须是非空字符串数组');
+  }
+  if (body.paths.length > deps.maxDeleteItems) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, `单次最多删除 ${deps.maxDeleteItems} 项`, { count: body.paths.length });
+  }
+
+  const targets = [];
+  const notFound = [];
+  for (const rawPath of body.paths) {
+    let resolved;
+    try {
+      resolved = await resolveRequestPath(ctx, rawPath);
+    } catch (error) {
+      // 契约：路径不存在不算失败，记在 notFound（幂等）。
+      // 但**不能**因此跳过越界校验：先对父目录做严格解析，父目录越界仍然抛 PATH_OUT_OF_ROOT。
+      if (!error || error.code !== ERROR_CODES.PATH_NOT_FOUND) throw error;
+      const shape = path.posix.normalize(String(rawPath));
+      const parentUser = path.posix.dirname(shape);
+      await resolveRequestPath(ctx, parentUser === '.' ? '/' : parentUser); // 越界在这里抛
+      notFound.push({ path: shape.startsWith('/') ? shape : `/${shape}`, missing: true });
+      continue;
+    }
+    const stat = await fsp.lstat(resolved.absPath).catch(() => null);
+    if (!stat) {
+      notFound.push({ path: resolved.userPath, missing: true });
+      continue;
+    }
+    targets.push({ userPath: resolved.userPath, absPath: resolved.absPath, size: stat.isDirectory() ? null : stat.size });
+  }
+
+  if (targets.length === 0) {
+    return { deleted: [], failed: [], notFound, trashBatch: null };
+  }
+
+  const outcome = await deps.deleter.deleteTargets({
+    targets,
+    kind: 'manual',
+    reason: 'fs_delete',
+    // 手动删除显式走回收站：log-only 只记账（那是压缩后自动删除的安全默认），
+    // 用在用户主动点"删除"的路径上会表现为"点了没反应"。回收站仍可恢复。
+    mode: 'trash',
+    // 手动删除没有"压缩成功"这个前置条件；二次确认由前端负责
+    taskId: null,
+    // INV-06 复核基准跟随本次请求的根（多根下不能用全局默认根）
+    rootAbs: deps.rootAbs,
+  });
+
+  const deleted = (outcome.deleted || []).map((entry) => (entry.path || entry.userPath || entry));
+  const failed = (outcome.failed || []).map((entry) => ({ path: entry.path || entry.userPath, code: entry.code || ERROR_CODES.INTERNAL_ERROR }));
+  // mode=log-only 时 deleter 只记账不动文件：如实返回 trashBatch=null，不假装已进回收站
+  return { deleted, failed, notFound, trashBatch: outcome.batchId || null };
+}