file-toolkit-mcp 1.0.0

package/src/tools/file-tools.js

@@ -0,0 +1,348 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { z } from 'zod';
+import { defineTool } from '../lib/registry.js';
+import { runBatch } from '../lib/batch.js';
+import { expandInputs, resolveOutputDir, displayPath, OUTPUT_DIR_NAME } from '../lib/paths.js';
+import {
+  planRename,
+  executeRename,
+  findLatestLog,
+  undoRename,
+  RENAME_LOG_PREFIX,
+} from '../lib/rename.js';
+import { inspectFile } from '../lib/inspect.js';
+import { buildResult, mdTable, summarize, formatBytes } from '../lib/result.js';
+import { describeError, invalid } from '../lib/errors.js';
+
+const MAX_INLINE_ROWS = 40;
+
+export function registerFileTools(server) {
+  defineTool(server, {
+    name: 'batch_rename',
+    title: '批量重命名',
+    action: '批量重命名',
+    description:
+      '按规则批量重命名文件。支持加前缀、加后缀、替换字符串、按序号编号（pattern 里用 {n} 表示序号，例如 "product-{n:3}" 生成 product-001）、改扩展名。重要：默认只预览不执行，用户确认预览结果后再用 confirm=true 真正改名。执行后可以随时用 rename_undo 回滚。',
+    inputSchema: {
+      input_files: z
+        .array(z.string())
+        .describe('要重命名的文件路径，可以传文件夹。传文件夹时配合 only_extensions 限定范围。'),
+      only_extensions: z
+        .array(z.string())
+        .optional()
+        .describe('只处理这些后缀的文件，例如 ["jpg","png"]。用户在文件夹语境下说"图片"时用这个限定。'),
+      pattern: z
+        .string()
+        .optional()
+        .describe(
+          '新的文件名模板。{n}=序号、{n:3}=补零到3位、{name}=原文件名（不含后缀）、{ext}=原后缀。例如"product-{n:3}"。不填则保留原文件名。',
+        ),
+      prefix: z.string().optional().describe('在原文件名前面加的内容。'),
+      suffix: z.string().optional().describe('在原文件名后面、扩展名前面加的内容。'),
+      find: z.string().optional().describe('要被替换掉的字符串。'),
+      replace: z.string().optional().describe('替换成什么，配合 find 使用。默认替换为空（即删除）。'),
+      new_extension: z.string().optional().describe('把扩展名改成这个，例如 "jpg"（不带点）。'),
+      start_number: z.number().optional().describe('序号从几开始，默认 1。'),
+      confirm: z
+        .boolean()
+        .optional()
+        .describe(
+          '是否真正执行。默认 false，只返回预览让用户确认。用户看过预览并同意之后，重新调用并传 true。',
+        ),
+    },
+    handler: async (args) => {
+      const {
+        input_files,
+        only_extensions = null,
+        pattern = null,
+        prefix = '',
+        suffix = '',
+        find = null,
+        replace = '',
+        new_extension = null,
+        start_number = 1,
+        confirm = false,
+      } = args;
+
+      const hasRule = Boolean(
+        pattern || prefix || suffix || find !== null || new_extension,
+      );
+      if (!hasRule) {
+        throw invalid(
+          '没有给出重命名规则',
+          '请说明要怎么改，例如加前缀、替换文字、按序号编号，或者改扩展名。',
+        );
+      }
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: only_extensions && only_extensions.length > 0 ? only_extensions : null,
+        label: '文件',
+      });
+
+      const logDir = await resolveOutputDir({ inputs: files });
+
+      const items = await planRename(files, {
+        pattern,
+        prefix,
+        suffix,
+        find,
+        replace,
+        newExtension: new_extension,
+        startNumber: start_number,
+      });
+
+      const previewRows = items.map((item, index) => [
+        String(index + 1),
+        item.from,
+        item.to,
+        item.status === 'ready'
+          ? '待执行'
+          : item.status === 'unchanged'
+            ? '无变化'
+            : `跳过：${item.conflictReason}`,
+      ]);
+
+      const ready = items.filter((i) => i.status === 'ready');
+      const unchanged = items.filter((i) => i.status === 'unchanged');
+      const conflicts = items.filter((i) => i.status === 'conflict');
+
+      const notes = [];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      // 预览模式：只告诉用户会发生什么
+      if (!confirm) {
+        if (ready.length === 0) {
+          notes.push('没有需要改动的文件（要么名字本来就是这个规则，要么都存在冲突）。');
+        } else {
+          notes.push(
+            `以上是预览，**还没有改动任何文件**。确认没问题后，再次调用 batch_rename 并把 confirm 设为 true 即可执行。`,
+          );
+        }
+        if (conflicts.length > 0) {
+          notes.push(`⚠️ 有 ${conflicts.length} 个文件因为冲突会被跳过，不会影响其他文件。`);
+        }
+
+        return buildResult({
+          title: `🔍 重命名预览：${ready.length} 个待执行，${unchanged.length} 个无变化，${conflicts.length} 个有冲突。`,
+          table: mdTable(['#', '原文件名', '新文件名', '状态'], previewRows.slice(0, MAX_INLINE_ROWS)),
+          notes,
+          data: {
+            willChange: ready.length,
+            unchanged: unchanged.length,
+            conflicts: conflicts.length,
+            executed: false,
+          },
+        });
+      }
+
+      // 执行模式
+      if (ready.length === 0) {
+        return buildResult({
+          title: '没有需要改动的文件，未做任何操作。',
+          table: mdTable(['#', '原文件名', '新文件名', '状态'], previewRows.slice(0, MAX_INLINE_ROWS)),
+          notes,
+        });
+      }
+
+      const { done, skipped, logPath } = await executeRename(items, { logDirectory: logDir });
+
+      const resultRows = [
+        ...done.map((item) => [item.from, item.to, '已改名']),
+        ...skipped.map((item) => [
+          item.from,
+          item.to,
+          item.status === 'unchanged' ? '无变化' : `跳过：${item.conflictReason}`,
+        ]),
+      ];
+
+      const finalNotes = [
+        `成功改名 ${done.length} 个文件。`,
+        logPath
+          ? `回滚记录已保存：\`${displayPath(logPath)}\`。如果改得不满意，直接说"撤销重命名"即可还原。`
+          : '',
+        ...warnings.map((w) => `· ${w}`),
+      ].filter(Boolean);
+
+      return buildResult({
+        title: `🏷️ 重命名完成：${done.length} 个成功，${skipped.length} 个跳过。`,
+        table: mdTable(['原文件名', '新文件名', '结果'], resultRows.slice(0, MAX_INLINE_ROWS)),
+        notes: finalNotes,
+        data: {
+          renamed: done.length,
+          skipped: skipped.length,
+          logFile: logPath,
+          executed: true,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'rename_undo',
+    title: '撤销重命名',
+    action: '撤销重命名',
+    description:
+      '把上一次批量重命名的结果还原。默认会自动找最近一次的改名记录；如果用户明确给了记录文件路径，用 log_file 传进来。只要文件还在原位、名字没被再次改过，就能完整还原。',
+    inputSchema: {
+      log_file: z
+        .string()
+        .optional()
+        .describe('重命名记录文件的完整路径。批次重命名完成后返回过这个路径。'),
+      search_directory: z
+        .string()
+        .optional()
+        .describe('如果不确定记录在哪，给出当时重命名文件所在的目录，会去里面的 file-toolkit-output 找最近一次记录。'),
+    },
+    handler: async (args) => {
+      const { log_file, search_directory } = args;
+
+      let logDir;
+      if (search_directory) {
+        logDir = path.join(path.resolve(search_directory), OUTPUT_DIR_NAME);
+      } else if (log_file) {
+        logDir = path.dirname(path.resolve(log_file));
+      } else {
+        logDir = path.join(process.cwd(), OUTPUT_DIR_NAME);
+      }
+
+      const logPath = await findLatestLog(logDir, log_file ?? null);
+      if (!logPath) {
+        throw invalid(
+          '没有找到改名记录',
+          `我在 ${displayPath(logDir)} 里没有找到 ${RENAME_LOG_PREFIX}*.json。` +
+            '请把当时重命名文件所在的目录用 search_directory 告诉我，或直接给出 log_file 的完整路径。',
+        );
+      }
+
+      let stat;
+      try {
+        stat = await fs.stat(logPath);
+      } catch {
+        throw invalid('这个记录文件不存在', `路径：${logPath}`);
+      }
+
+      const { restored, missing } = await undoRename(logPath);
+
+      const rows = restored.map((r) => [path.basename(r.from), path.basename(r.to), '已还原']);
+
+      const notes = [
+        `依据的记录文件：\`${displayPath(logPath)}\`（${stat.size} 字节）`,
+      ];
+      if (missing.length > 0) {
+        notes.push(
+          `⚠️ 有 ${missing.length} 个文件不在原来的位置了（可能已被移动或删除），这部分无法还原。`,
+        );
+      }
+
+      return buildResult({
+        title: `↩️ 撤销完成：已还原 ${restored.length} 个文件名${missing.length > 0 ? `，${missing.length} 个找不到` : ''}。`,
+        table: mdTable(['当前文件名', '还原为', '结果'], rows.slice(0, MAX_INLINE_ROWS)),
+        notes,
+        data: {
+          restored: restored.length,
+          missing: missing.length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'file_info',
+    title: '查看文件信息',
+    action: '读取文件信息',
+    description:
+      '查看文件的基本信息：大小、类型、创建和修改时间、MIME 类型。图片会额外给出宽高和格式，PDF 会额外给出页数。支持一次查看多个文件或整个文件夹。',
+    inputSchema: {
+      input_files: z
+        .array(z.string())
+        .describe('要查看的文件路径，可以传文件也可以传文件夹，支持一次多个。'),
+      only_extensions: z
+        .array(z.string())
+        .optional()
+        .describe('传文件夹时，只查看这些后缀的文件，例如 ["jpg","png"]。'),
+    },
+    handler: async (args) => {
+      const { input_files, only_extensions = null } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: only_extensions && only_extensions.length > 0 ? only_extensions : null,
+        label: '文件',
+      });
+
+      const results = await runBatch(files, async (file) => inspectFile(file));
+
+      const notes = [];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      // 单个文件：用逐字段的形式，读起来更清楚
+      if (results.length === 1 && results[0].ok) {
+        const info = results[0];
+        const lines = [
+          `📄 **${info.name}**`,
+          '',
+          `- 位置：\`${displayPath(info.path)}\``,
+          `- 类型：${info.kind}（MIME：${info.mimeType}）`,
+          `- 后缀：${info.extension ? `.${info.extension}` : '无'}`,
+          `- 大小：${formatBytes(info.sizeBytes)}（${info.sizeBytes.toLocaleString('en-US')} 字节）`,
+          `- 创建时间：${info.createdAt ?? '系统未提供'}`,
+          `- 修改时间：${info.modifiedAt ?? '未知'}`,
+        ];
+        if (info.width && info.height) {
+          lines.push(`- 图片尺寸：${info.width}×${info.height}（格式 ${info.imageFormat}）`);
+        }
+        if (info.pdfPages !== null) {
+          lines.push(`- PDF 页数：${info.pdfPages} 页`);
+        }
+        if (info.note) lines.push(`- 注意：${info.note}`);
+        for (const w of warnings) lines.push(`- ${w}`);
+        lines.push('', '```json', JSON.stringify(info, null, 2), '```');
+        return lines.join('\n');
+      }
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', '—', '—', describeError(r.error, { action: '读取' })];
+        }
+        return [
+          r.name,
+          r.kind,
+          formatBytes(r.sizeBytes),
+          r.width && r.height
+            ? `${r.width}×${r.height}`
+            : r.pdfPages !== null
+              ? `${r.pdfPages} 页`
+              : '—',
+          r.modifiedAt ?? '未知',
+        ];
+      });
+
+      const okResults = results.filter((r) => r.ok);
+      const totalBytes = okResults.reduce((sum, r) => sum + r.sizeBytes, 0);
+
+      if (results.length > MAX_INLINE_ROWS) {
+        notes.push(`结果较多，上面只列出前 ${MAX_INLINE_ROWS} 个，完整数据见下方 JSON。`);
+      }
+
+      return buildResult({
+        title: `📂 ${summarize('文件信息读取', results)}合计 ${formatBytes(totalBytes)}。`,
+        table: mdTable(['文件名', '类型', '大小', '尺寸 / 页数', '修改时间'], rows.slice(0, MAX_INLINE_ROWS)),
+        notes,
+        data: {
+          count: results.length,
+          totalBytes,
+          items: okResults.map((r) => ({
+            name: r.name,
+            path: r.path,
+            kind: r.kind,
+            sizeBytes: r.sizeBytes,
+            width: r.width,
+            height: r.height,
+            pdfPages: r.pdfPages,
+            modifiedAt: r.modifiedAt,
+          })),
+        },
+      });
+    },
+  });
+}

package/src/tools/image-tools.js

@@ -0,0 +1,294 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { z } from 'zod';
+import { defineTool } from '../lib/registry.js';
+import { runBatch } from '../lib/batch.js';
+import {
+  expandInputs,
+  resolveOutputDir,
+  uniquePath,
+  assertNotOverwritingInput,
+  displayPath,
+} from '../lib/paths.js';
+import {
+  compressImage,
+  convertImage,
+  resizeImage,
+  IMAGE_EXTENSIONS,
+  normalizeFormat,
+} from '../lib/image.js';
+import { buildResult, mdTable, summarize, formatBytes, formatDelta } from '../lib/result.js';
+import { describeError, invalid } from '../lib/errors.js';
+
+const EXT_FOR_FORMAT = { jpeg: 'jpg', png: 'png', webp: 'webp' };
+
+const INPUT_FILES = z
+  .array(z.string())
+  .describe('要处理的图片路径，可以传文件也可以传文件夹（会自动收集里面的图片），支持一次传多个。');
+
+const OUTPUT_DIRECTORY = z
+  .string()
+  .optional()
+  .describe('输出目录。不填则默认写到第一个文件所在目录下的 file-toolkit-output 文件夹，原文件不会被改动。');
+
+export function registerImageTools(server) {
+  defineTool(server, {
+    name: 'image_compress',
+    title: '压缩图片',
+    action: '压缩图片',
+    description:
+      '压缩 jpg / png / webp 图片的体积。可以指定目标体积（例如"压到 1MB 以下"），工具会自动调画质去逼近；也可以直接指定画质。支持批量处理整个文件夹。需要缩小图片尺寸时用 image_resize，需要换格式时用 image_convert。',
+    inputSchema: {
+      input_files: INPUT_FILES,
+      target_size_kb: z
+        .number()
+        .optional()
+        .describe('期望压缩到的体积，单位 KB。例如用户说"压到 500KB 以下"就传 500。不填则改用 quality 参数。'),
+      quality: z
+        .number()
+        .optional()
+        .describe('固定压缩质量 1-100，数值越小体积越小，默认 80。只有在不填 target_size_kb 时才生效。'),
+      max_width: z.number().optional().describe('顺便把图片宽度限制到不超过这个像素值。'),
+      max_height: z.number().optional().describe('顺便把图片高度限制到不超过这个像素值。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, target_size_kb, quality, max_width, max_height, output_directory } = args;
+
+      if (target_size_kb !== undefined && quality !== undefined) {
+        throw invalid(
+          '不能同时指定目标体积和固定画质',
+          '请二选一：想自动逼近某个体积就只给 target_size_kb，想固定画质就只给 quality。',
+        );
+      }
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: IMAGE_EXTENSIONS,
+        label: '图片',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const before = (await fs.stat(file)).size;
+        const out = await compressImage(file, {
+          targetSize: target_size_kb !== undefined ? Math.round(target_size_kb * 1024) : null,
+          quality: quality !== undefined ? quality : null,
+          maxWidth: max_width ?? null,
+          maxHeight: max_height ?? null,
+        });
+        const target = await uniquePath(outputDir, path.basename(file));
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, out.buffer);
+        return {
+          before,
+          after: out.buffer.length,
+          outPath: target,
+          reached: out.reachedTarget,
+          usedQuality: out.quality,
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', '—', '失败', describeError(r.error, { action: '压缩' })];
+        }
+        return [
+          path.basename(r.file),
+          formatBytes(r.before),
+          formatBytes(r.after),
+          formatDelta(r.before, r.after),
+          displayPath(r.outPath),
+        ];
+      });
+
+      const notes = [];
+      const missed = results.filter((r) => r.ok && r.reached === false);
+      if (missed.length > 0) {
+        notes.push(
+          `⚠️ 有 ${missed.length} 个文件即使降到最低画质仍然超过目标体积，已按能达到的最小体积输出。` +
+            '如果必须严格达标，可以再用 image_resize 限制尺寸，或者转成 webp。',
+        );
+      }
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `🗜️ ${summarize('图片压缩', results)}`,
+        table: mdTable(['文件', '原大小', '压缩后', '变化', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'image_convert',
+    title: '转换图片格式',
+    action: '转换图片格式',
+    description:
+      '在 jpg / png / webp 之间互转图片格式，支持批量。把 png 的透明背景转成 jpg 时会自动铺白底。只处理扩展名匹配的图片，其他文件会被自动忽略。',
+    inputSchema: {
+      input_files: INPUT_FILES,
+      output_format: z
+        .enum(['jpg', 'jpeg', 'png', 'webp'])
+        .describe('目标格式。用户说"转成 JPG"就传 jpg，"转成 webp"就传 webp。'),
+      quality: z.number().optional().describe('目标格式的有损压缩质量 1-100，默认 90。png 为无损时该参数影响较小。'),
+      max_width: z.number().optional().describe('顺便把宽度限制到不超过这个像素值。'),
+      max_height: z.number().optional().describe('顺便把高度限制到不超过这个像素值。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, output_format, quality, max_width, max_height, output_directory } = args;
+      const format = normalizeFormat(output_format);
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: IMAGE_EXTENSIONS,
+        label: '图片',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+      const targetExt = EXT_FOR_FORMAT[format];
+
+      const results = await runBatch(files, async (file) => {
+        const before = (await fs.stat(file)).size;
+        const out = await convertImage(file, {
+          format,
+          quality: quality ?? 90,
+          maxWidth: max_width ?? null,
+          maxHeight: max_height ?? null,
+        });
+        const stem = path.basename(file, path.extname(file));
+        const target = await uniquePath(outputDir, `${stem}.${targetExt}`);
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, out.buffer);
+        return {
+          before,
+          after: out.buffer.length,
+          outPath: target,
+          width: out.width,
+          height: out.height,
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', '—', '失败', describeError(r.error, { action: '转换' })];
+        }
+        return [
+          path.basename(r.file),
+          formatBytes(r.before),
+          `${formatBytes(r.after)} (${r.width}×${r.height})`,
+          formatDelta(r.before, r.after),
+          displayPath(r.outPath),
+        ];
+      });
+
+      const notes = [];
+      notes.push(`已统一转换为 ${targetExt.toUpperCase()} 格式。`);
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `🔄 ${summarize('格式转换', results)}`,
+        table: mdTable(['文件', '原大小', '转换后', '变化', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          format: targetExt,
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'image_resize',
+    title: '调整图片尺寸',
+    action: '调整图片尺寸',
+    description:
+      '按宽度、高度或百分比缩放图片，支持批量。fit_mode 决定缩放方式：fit 等比缩放到不超过给定宽高（默认）、max 只缩小绝不放大、cover 裁切填满、stretch 强制拉伸。不要用这个工具改格式，改格式请用 image_convert。',
+    inputSchema: {
+      input_files: INPUT_FILES,
+      width: z.number().optional().describe('目标宽度（像素）。'),
+      height: z.number().optional().describe('目标高度（像素）。'),
+      scale_percent: z
+        .number()
+        .optional()
+        .describe('按百分比缩放，例如 50 表示缩小到一半。与 width / height 三选一。'),
+      fit_mode: z
+        .enum(['fit', 'max', 'cover', 'stretch'])
+        .optional()
+        .describe(
+          '缩放方式。fit=等比缩放到不超过给定宽高；max=等比缩放但绝不放大（用户说"最大宽度"时用它）；cover=等比缩放并裁掉多余部分；stretch=强制拉伸到精确尺寸。默认 fit。',
+        ),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, width, height, scale_percent, fit_mode, output_directory } = args;
+
+      if (width === undefined && height === undefined && scale_percent === undefined) {
+        throw invalid(
+          '没有指定新的尺寸',
+          '请告诉我要缩到多宽、多高，或者按百分之多少缩放，例如 width=1200。',
+        );
+      }
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: IMAGE_EXTENSIONS,
+        label: '图片',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const out = await resizeImage(file, {
+          width: width ?? null,
+          height: height ?? null,
+          scalePercent: scale_percent ?? null,
+          fitMode: fit_mode ?? 'fit',
+        });
+        const target = await uniquePath(outputDir, path.basename(file));
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, out.buffer);
+        return {
+          outPath: target,
+          width: out.width,
+          height: out.height,
+          originalWidth: out.originalWidth,
+          originalHeight: out.originalHeight,
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', '—', '失败', describeError(r.error, { action: '缩放' })];
+        }
+        return [
+          path.basename(r.file),
+          `${r.originalWidth}×${r.originalHeight}`,
+          `${r.width}×${r.height}`,
+          '成功',
+          displayPath(r.outPath),
+        ];
+      });
+
+      const notes = [];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `📐 ${summarize('尺寸调整', results)}`,
+        table: mdTable(['文件', '原尺寸', '新尺寸', '结果', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+}