file-toolkit-mcp 1.0.0

package/src/lib/image.js

@@ -0,0 +1,331 @@
+/**
+ * 图片处理：压缩、格式转换、尺寸调整。
+ *
+ * 全部走 sharp（libvips，Apache-2.0），不需要用户安装 ImageMagick，
+ * 也不需要联网，所有编解码都在本机完成。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import sharp from 'sharp';
+import { ToolError, assertThat, invalid } from './errors.js';
+
+/** 本项目支持的图片格式 */
+export const IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'webp'];
+
+const FORMAT_ALIASES = {
+  jpg: 'jpeg',
+  jpeg: 'jpeg',
+  jpe: 'jpeg',
+  png: 'png',
+  webp: 'webp',
+};
+
+const EXT_FOR_FORMAT = {
+  jpeg: 'jpg',
+  png: 'png',
+  webp: 'webp',
+};
+
+/**
+ * 归一化格式名。传入 "JPG"/"jpeg"/".png" 都能正确识别。
+ */
+export function normalizeFormat(input) {
+  const key = String(input ?? '').trim().toLowerCase().replace(/^\./, '');
+  const format = FORMAT_ALIASES[key];
+  assertThat(
+    format,
+    `不支持的目标格式：${input}`,
+    '目前支持 jpg、png、webp 三种。',
+  );
+  return format;
+}
+
+function openImage(file) {
+  // failOn: 'error' —— 容忍部分 jpg 尾部的垃圾字节，但真正的损坏仍然报错
+  return sharp(file, { failOn: 'error' });
+}
+
+/** 读取图片基本信息 */
+export async function readImageMeta(file) {
+  const meta = await openImage(file).metadata();
+  return {
+    width: meta.width ?? null,
+    height: meta.height ?? null,
+    format: meta.format ?? null,
+    channels: meta.channels ?? null,
+    hasAlpha: Boolean(meta.hasAlpha),
+  };
+}
+
+function encode(pipeline, { format, quality }) {
+  switch (format) {
+    case 'jpeg':
+      // jpeg 不支持透明通道，先铺白底，否则透明区域会变成黑块
+      return pipeline
+        .flatten({ background: '#ffffff' })
+        .jpeg({ quality, mozjpeg: true, chromaSubsampling: '4:2:0' });
+    case 'webp':
+      return pipeline.webp({ quality, effort: 4 });
+    case 'png':
+      // PNG 是无损格式：要真正减小体积必须走调色板量化
+      return pipeline.png({
+        compressionLevel: 9,
+        palette: true,
+        quality,
+        effort: 7,
+      });
+    default:
+      throw invalid(`不支持的目标格式：${format}`);
+  }
+}
+
+function applyResize(pipeline, { maxWidth, maxHeight }) {
+  if (!maxWidth && !maxHeight) return pipeline;
+  return pipeline.resize({
+    width: maxWidth || undefined,
+    height: maxHeight || undefined,
+    fit: 'inside',
+    withoutEnlargement: true,
+  });
+}
+
+/**
+ * 压缩单张图片，尽量逼近目标体积。
+ *
+ * 策略：如果只给了 quality，一次到位；
+ * 如果给了 target_size，用二分法在 quality 1~100 之间逼近，最多 8 轮。
+ *
+ * @returns {Promise<{ buffer: Buffer, quality: number|null, width: number, height: number }>}
+ */
+export async function compressImage(file, options = {}) {
+  const {
+    quality = null,
+    targetSize = null,
+    maxWidth = null,
+    maxHeight = null,
+  } = options;
+
+  const meta = await readImageMeta(file);
+  const format = FORMAT_ALIASES[meta.format] ?? 'jpeg';
+
+  // 每轮都重新构造管道：sharp 实例复用会让中间状态互相污染
+  const render = async (q) => {
+    let pipeline = openImage(file).rotate();
+    pipeline = applyResize(pipeline, { maxWidth, maxHeight });
+    pipeline = encode(pipeline, { format, quality: q });
+    return pipeline.toBuffer({ resolveWithObject: true });
+  };
+
+  if (targetSize && Number.isFinite(targetSize) && targetSize > 0) {
+    let low = 1;
+    let high = 100;
+    let best = null;
+    let bestQuality = null;
+
+    for (let round = 0; round < 8 && low <= high; round += 1) {
+      const q = Math.round((low + high) / 2);
+      const { data } = await render(q);
+
+      if (data.length <= targetSize) {
+        // 已经达标，记录后继续尝试更高的画质
+        if (!best || data.length > best.length) {
+          best = data;
+          bestQuality = q;
+        }
+        low = q + 1;
+      } else {
+        high = q - 1;
+      }
+    }
+
+    if (!best) {
+      // 最低画质仍然超标：返回最低画质的结果，由调用方如实告知用户
+      const { data, info } = await render(1);
+      return {
+        buffer: data,
+        quality: 1,
+        width: info.width,
+        height: info.height,
+        reachedTarget: false,
+      };
+    }
+
+    const info = await sharp(best).metadata();
+    return {
+      buffer: best,
+      quality: bestQuality,
+      width: info.width ?? meta.width,
+      height: info.height ?? meta.height,
+      reachedTarget: true,
+    };
+  }
+
+  const q = Number.isFinite(quality) ? Math.min(100, Math.max(1, Math.round(quality))) : 80;
+  const { data, info } = await render(q);
+  return {
+    buffer: data,
+    quality: q,
+    width: info.width,
+    height: info.height,
+    reachedTarget: null,
+  };
+}
+
+/**
+ * 转换图片格式。
+ */
+export async function convertImage(file, options = {}) {
+  const { format, quality = 90, maxWidth = null, maxHeight = null } = options;
+  const targetFormat = normalizeFormat(format);
+
+  let pipeline = openImage(file).rotate();
+  pipeline = applyResize(pipeline, { maxWidth, maxHeight });
+  pipeline = encode(pipeline, { format: targetFormat, quality });
+
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+  return {
+    buffer: data,
+    width: info.width,
+    height: info.height,
+    format: targetFormat,
+  };
+}
+
+/**
+ * 调整图片尺寸。
+ *
+ * fit_mode 语义（面向自然语言，不用 sharp 的术语）：
+ *   fit    等比缩放到不超过给定宽高（默认）
+ *   max    同 fit，但绝不放大超过原图
+ *   cover  等比缩放到填满给定宽高，多余部分裁掉
+ *   stretch 拉伸到精确宽高（会变形）
+ */
+export async function resizeImage(file, options = {}) {
+  const {
+    width = null,
+    height = null,
+    fitMode = 'fit',
+    scalePercent = null,
+    quality = 90,
+  } = options;
+
+  const meta = await readImageMeta(file);
+  if (!meta.width || !meta.height) {
+    throw new ToolError('无法读取这张图片的尺寸', {
+      hint: '文件可能已损坏，或它不是标准图片。',
+    });
+  }
+
+  let targetWidth = width;
+  let targetHeight = height;
+
+  if (Number.isFinite(scalePercent)) {
+    const ratio = scalePercent / 100;
+    if (ratio <= 0) throw invalid('缩放比例必须大于 0', '例如 50 表示缩小到一半。');
+    targetWidth = Math.max(1, Math.round(meta.width * ratio));
+    targetHeight = Math.max(1, Math.round(meta.height * ratio));
+  }
+
+  if (!targetWidth && !targetHeight) {
+    throw invalid(
+      '没有指定新的尺寸',
+      '请告诉我要缩到多宽、多高，或者按百分之多少缩放。',
+    );
+  }
+
+  const fitMap = {
+    fit: { fit: 'inside', withoutEnlargement: false },
+    max: { fit: 'inside', withoutEnlargement: true },
+    cover: { fit: 'cover', withoutEnlargement: false },
+    stretch: { fit: 'fill', withoutEnlargement: false },
+  };
+
+  const preset = fitMap[fitMode];
+  assertThat(
+    preset,
+    `不支持的缩放方式：${fitMode}`,
+    '可选 fit（等比缩放）、max（只缩小不放大）、cover（裁切填满）、stretch（拉伸）。',
+  );
+
+  const format = FORMAT_ALIASES[meta.format] ?? 'jpeg';
+
+  let pipeline = openImage(file).rotate().resize({
+    width: targetWidth || undefined,
+    height: targetHeight || undefined,
+    fit: preset.fit,
+    withoutEnlargement: preset.withoutEnlargement,
+    background: { r: 255, g: 255, b: 255, alpha: 1 },
+  });
+  pipeline = encode(pipeline, { format, quality });
+
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+  return {
+    buffer: data,
+    width: info.width,
+    height: info.height,
+    originalWidth: meta.width,
+    originalHeight: meta.height,
+  };
+}
+
+/**
+ * 图片 -> PDF（单张或多张）。
+ * 走 pdf-lib，纯 JS，不依赖任何系统组件。
+ */
+export async function imagesToPdf(files, options = {}) {
+  const { PDFDocument } = await import('pdf-lib');
+  const { pageSize = 'fit', margin = 0 } = options;
+
+  const pdf = await PDFDocument.create();
+
+  for (const file of files) {
+    const buffer = await fs.readFile(file);
+    const meta = await readImageMeta(file);
+    const ext = (meta.format ?? path.extname(file).slice(1)).toLowerCase();
+
+    let embedded;
+    if (ext === 'jpeg' || ext === 'jpg') {
+      embedded = await pdf.embedJpg(buffer);
+    } else if (ext === 'png') {
+      embedded = await pdf.embedPng(buffer);
+    } else {
+      // webp 等格式 pdf-lib 不认，先转成 png
+      const png = await openImage(file).png().toBuffer();
+      embedded = await pdf.embedPng(png);
+    }
+
+    const imgW = embedded.width;
+    const imgH = embedded.height;
+
+    let pageW = imgW + margin * 2;
+    let pageH = imgH + margin * 2;
+
+    if (pageSize === 'a4') {
+      pageW = 595.28;
+      pageH = 841.89;
+    }
+
+    const page = pdf.addPage([pageW, pageH]);
+
+    let drawW = imgW;
+    let drawH = imgH;
+    if (pageSize === 'a4') {
+      const scale = Math.min(
+        (pageW - margin * 2) / imgW,
+        (pageH - margin * 2) / imgH,
+      );
+      drawW = imgW * scale;
+      drawH = imgH * scale;
+    }
+
+    page.drawImage(embedded, {
+      x: (pageW - drawW) / 2,
+      y: (pageH - drawH) / 2,
+      width: drawW,
+      height: drawH,
+    });
+  }
+
+  return Buffer.from(await pdf.save());
+}

package/src/lib/inspect.js

@@ -0,0 +1,108 @@
+/**
+ * 文件信息提取。
+ * 图片尺寸走 sharp，PDF 页数走 pdf-lib，其余用 Node 内置能力。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readImageMeta, IMAGE_EXTENSIONS } from './image.js';
+import { readPdfMeta } from './pdf.js';
+
+const MIME_TYPES = {
+  jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp',
+  gif: 'image/gif', bmp: 'image/bmp', svg: 'image/svg+xml', tif: 'image/tiff',
+  tiff: 'image/tiff', heic: 'image/heic', avif: 'image/avif', ico: 'image/x-icon',
+  pdf: 'application/pdf',
+  json: 'application/json', csv: 'text/csv', tsv: 'text/tab-separated-values',
+  md: 'text/markdown', markdown: 'text/markdown', html: 'text/html', htm: 'text/html',
+  txt: 'text/plain', log: 'text/plain', xml: 'application/xml',
+  yml: 'application/yaml', yaml: 'application/yaml',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  zip: 'application/zip', rar: 'application/vnd.rar', '7z': 'application/x-7z-compressed',
+  tar: 'application/x-tar', gz: 'application/gzip',
+  mp3: 'audio/mpeg', wav: 'audio/wav', m4a: 'audio/mp4', flac: 'audio/flac',
+  mp4: 'video/mp4', mov: 'video/quicktime', avi: 'video/x-msvideo',
+  mkv: 'video/x-matroska', webm: 'video/webm',
+  js: 'text/javascript', mjs: 'text/javascript', cjs: 'text/javascript',
+  ts: 'text/typescript', css: 'text/css', sh: 'text/x-shellscript',
+  py: 'text/x-python', java: 'text/x-java',
+  dmg: 'application/x-apple-diskimage',
+  apk: 'application/vnd.android.package-archive',
+};
+
+/** 把扩展名翻译成人能看懂的类型名 */
+function describeKind(ext) {
+  if (['jpg', 'jpeg', 'png', 'webp', 'gif', 'bmp', 'tif', 'tiff', 'heic', 'avif', 'svg', 'ico'].includes(ext)) return '图片';
+  if (ext === 'pdf') return 'PDF 文档';
+  if (['doc', 'docx', 'odt', 'rtf'].includes(ext)) return 'Word 文档';
+  if (['xls', 'xlsx', 'ods'].includes(ext)) return '表格文件';
+  if (['ppt', 'pptx', 'odp'].includes(ext)) return '演示文稿';
+  if (['zip', 'rar', '7z', 'tar', 'gz', 'bz2', 'xz'].includes(ext)) return '压缩包';
+  if (['mp3', 'wav', 'm4a', 'flac', 'aac', 'ogg'].includes(ext)) return '音频';
+  if (['mp4', 'mov', 'avi', 'mkv', 'webm', 'flv', 'wmv'].includes(ext)) return '视频';
+  if (['txt', 'md', 'markdown', 'log', 'json', 'csv', 'tsv', 'xml', 'yml', 'yaml', 'html', 'htm'].includes(ext)) return '文本';
+  if (['js', 'mjs', 'cjs', 'ts', 'py', 'java', 'go', 'rs', 'c', 'cpp', 'sh', 'css', 'rb', 'php'].includes(ext)) return '代码';
+  if (['app', 'exe', 'dmg', 'pkg', 'msi', 'deb', 'rpm', 'apk'].includes(ext)) return '程序安装包';
+  if (ext === '') return '无扩展名文件';
+  return '其他';
+}
+
+function formatTime(date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+  );
+}
+
+/**
+ * 读取单个文件的信息。
+ * 图片或 PDF 损坏时不会让整个调用失败，只是把对应字段标为无法读取。
+ */
+export async function inspectFile(filePath) {
+  const st = await fs.stat(filePath);
+  const ext = path.extname(filePath).toLowerCase().replace(/^\./, '');
+
+  const info = {
+    path: path.resolve(filePath),
+    name: path.basename(filePath),
+    extension: ext || null,
+    kind: describeKind(ext),
+    mimeType: MIME_TYPES[ext] ?? 'application/octet-stream',
+    sizeBytes: st.size,
+    createdAt: formatTime(st.birthtime),
+    modifiedAt: formatTime(st.mtime),
+    accessedAt: formatTime(st.atime),
+    width: null,
+    height: null,
+    imageFormat: null,
+    pdfPages: null,
+    note: null,
+  };
+
+  if (IMAGE_EXTENSIONS.includes(ext)) {
+    try {
+      const meta = await readImageMeta(filePath);
+      info.width = meta.width;
+      info.height = meta.height;
+      info.imageFormat = meta.format;
+    } catch {
+      info.note = '这个文件用的是图片扩展名，但内容无法当作图片读取';
+    }
+  } else if (ext === 'pdf') {
+    try {
+      const meta = await readPdfMeta(filePath);
+      info.pdfPages = meta.pages;
+    } catch {
+      info.note = '这个文件用的是 pdf 扩展名，但内容无法当作 PDF 读取';
+    }
+  }
+
+  return info;
+}

package/src/lib/paths.js

@@ -0,0 +1,231 @@
+/**
+ * 路径解析与「统一输出目录规则」。
+ *
+ * 全部工具共用同一套输出策略，避免每个工具各写一套导致行为不一致：
+ *
+ *   1. 用户显式指定 output_directory  -> 用它
+ *   2. 没指定                        -> 用第一个输入文件所在目录下的 file-toolkit-output/
+ *   3. 输出文件已存在                 -> 自动追加序号（name (2).ext），永不覆盖
+ *   4. 输出路径与任一输入文件相同      -> 直接拒绝，永不覆盖原文件
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { ToolError, assertThat } from './errors.js';
+
+export const OUTPUT_DIR_NAME = 'file-toolkit-output';
+
+/** 单个操作默认最多处理多少个文件，防止一次调用把内存打满 */
+export const DEFAULT_MAX_FILES = 500;
+
+/**
+ * 转成绝对路径。相对路径以 base（默认当前工作目录）为基准。
+ */
+export function toAbsolute(input, base = process.cwd()) {
+  assertThat(
+    typeof input === 'string' && input.trim() !== '',
+    '文件路径不能为空',
+    '请提供要处理文件的完整路径。',
+  );
+  const cleaned = input.trim().replace(/^["']|["']$/g, '');
+  return path.resolve(base, cleaned);
+}
+
+async function statOrNull(p) {
+  try {
+    return await fs.stat(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把用户给的输入展开成实际要处理的文件列表。
+ *
+ * 支持三种写法：
+ *   - 单个文件
+ *   - 目录（自动收集里面的文件，可按扩展名过滤）
+ *   - 多个以上任意组合
+ *
+ * @param {string[]} inputs 用户给的路径列表
+ * @param {{ extensions?: string[]|null, recursive?: boolean, maxFiles?: number, label?: string }} [options]
+ * @returns {Promise<{ files: string[], warnings: string[] }>}
+ */
+export async function expandInputs(inputs, options = {}) {
+  const {
+    extensions = null,
+    recursive = true,
+    maxFiles = DEFAULT_MAX_FILES,
+    label = '文件',
+  } = options;
+
+  assertThat(
+    Array.isArray(inputs) && inputs.length > 0,
+    '没有提供任何要处理的文件',
+    '请告诉我要处理哪个文件或哪个文件夹。',
+  );
+
+  const wanted = extensions
+    ? new Set(extensions.map((e) => e.toLowerCase().replace(/^\./, '')))
+    : null;
+
+  const files = [];
+  const warnings = [];
+  const seen = new Set();
+
+  const accept = (filePath) => {
+    if (wanted) {
+      const ext = path.extname(filePath).toLowerCase().replace(/^\./, '');
+      if (!wanted.has(ext)) return;
+    }
+    const abs = path.resolve(filePath);
+    if (seen.has(abs)) return;
+    seen.add(abs);
+    files.push(abs);
+  };
+
+  for (const raw of inputs) {
+    const abs = toAbsolute(raw);
+    const st = await statOrNull(abs);
+
+    if (!st) {
+      warnings.push(`跳过不存在的路径：${abs}`);
+      continue;
+    }
+
+    if (st.isFile()) {
+      accept(abs);
+      continue;
+    }
+
+    if (st.isDirectory()) {
+      const walk = async (dir) => {
+        let entries = [];
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch (error) {
+          warnings.push(`无法读取目录 ${dir}：${error?.message ?? error}`);
+          return;
+        }
+        for (const entry of entries) {
+          if (entry.name.startsWith('.')) continue;
+          // 跳过工具自己的输出目录，避免把上一轮结果又处理一遍
+          if (entry.isDirectory() && entry.name === OUTPUT_DIR_NAME) continue;
+          const full = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            if (recursive) await walk(full);
+          } else if (entry.isFile()) {
+            accept(full);
+          }
+        }
+      };
+      await walk(abs);
+      continue;
+    }
+
+    warnings.push(`跳过不支持的文件类型：${abs}`);
+  }
+
+  files.sort((a, b) => a.localeCompare(b, 'zh-Hans-CN', { numeric: true }));
+
+  if (files.length > maxFiles) {
+    throw new ToolError(
+      `一次要处理的${label}太多了（${files.length} 个，上限 ${maxFiles} 个）`,
+      { hint: '请分批处理，或缩小到具体的子文件夹。' },
+    );
+  }
+
+  // 一个都没找到时，把「为什么没找到」如实说出来，
+  // 否则用户只会看到一句笼统的「没找到文件」，不知道是路径写错了还是格式不对。
+  if (files.length === 0) {
+    const extHint = wanted
+      ? `支持的文件后缀：${[...wanted].map((e) => `.${e}`).join('、')}。`
+      : '';
+    const reasons =
+      warnings.length > 0 ? `\n具体原因：\n- ${warnings.join('\n- ')}` : '';
+    throw new ToolError(`没有找到可以处理的${label}`, {
+      hint: `${extHint}请确认路径是否正确。${reasons}`,
+    });
+  }
+
+  return { files, warnings };
+}
+
+/**
+ * 决定这一次操作的输出目录。
+ *
+ * @param {{ inputs?: string[], outputDirectory?: string, anchor?: string }} params
+ *        anchor：当输入是新建内容（没有源文件）时，用它作为基准目录
+ */
+export async function resolveOutputDir({ inputs = [], outputDirectory, anchor } = {}) {
+  if (outputDirectory && String(outputDirectory).trim() !== '') {
+    const dir = toAbsolute(outputDirectory);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+  }
+
+  let base = anchor ? toAbsolute(anchor) : null;
+  if (!base && inputs.length > 0) base = toAbsolute(inputs[0]);
+  if (!base) base = process.cwd();
+
+  const st = await statOrNull(base);
+  const baseDir = st && st.isFile() ? path.dirname(base) : base;
+
+  // 如果输入本身就在 file-toolkit-output 里，就地输出，不再套一层同名目录
+  if (path.basename(baseDir) === OUTPUT_DIR_NAME) {
+    await fs.mkdir(baseDir, { recursive: true });
+    return baseDir;
+  }
+
+  const dir = path.join(baseDir, OUTPUT_DIR_NAME);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * 在目录下生成一个不会覆盖已有文件的路径。
+ * 名字冲突时依次尝试 "name (2).ext"、"name (3).ext"……
+ */
+export async function uniquePath(dir, filename) {
+  const ext = path.extname(filename);
+  const stem = path.basename(filename, ext);
+
+  let candidate = path.join(dir, filename);
+  let counter = 1;
+  while (await statOrNull(candidate)) {
+    counter += 1;
+    candidate = path.join(dir, `${stem} (${counter})${ext}`);
+    if (counter > 9999) {
+      throw new ToolError('输出目录里同名文件太多，无法生成新文件名', {
+        hint: '请清理输出目录，或指定另一个 output_directory。',
+      });
+    }
+  }
+  return candidate;
+}
+
+/**
+ * 双保险：确认输出路径没有落在任何一个输入文件上。
+ * 正常流程下不会触发，触发即代表逻辑有问题，宁可直接失败也不要覆盖用户文件。
+ */
+export function assertNotOverwritingInput(outPath, inputPaths) {
+  const target = path.resolve(outPath);
+  const clash = inputPaths.find((p) => path.resolve(p) === target);
+  if (clash) {
+    throw new ToolError('输出路径和原文件重复，为避免覆盖原文件已中止', {
+      hint: '请指定另一个 output_directory。',
+    });
+  }
+  return true;
+}
+
+/**
+ * 推测「输出目录」的相对展示形式，用于回显给用户。
+ */
+export function displayPath(p) {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (home && path.resolve(p).startsWith(path.resolve(home))) {
+    return `~${path.resolve(p).slice(path.resolve(home).length)}`;
+  }
+  return path.resolve(p);
+}