ms-vite-plugin 1.2.2 → 1.2.3

package/dist/mcp/image-tools.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * 注册图片处理 MCP 工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerImageTools(server)
+ */
+export declare function registerImageTools(server: McpServer): void;

package/dist/mcp/image-tools.js

@@ -0,0 +1,444 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerImageTools = registerImageTools;
+const fsExtra = __importStar(require("fs-extra"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const sharp_1 = __importDefault(require("sharp"));
+const z = __importStar(require("zod/v4"));
+const project_1 = require("../project");
+const tool_utils_1 = require("./tool-utils");
+/**
+ * 解析输出路径
+ * @param inputPath 输入图片路径
+ * @param outputPath 可选输出路径
+ * @param suffix 默认文件名后缀
+ * @returns 返回输出图片绝对路径
+ * @example
+ * resolveImageOutputPath("/tmp/a.jpg", undefined, "crop")
+ */
+function resolveImageOutputPath(inputPath, outputPath, suffix) {
+    if (outputPath && outputPath.trim()) {
+        return path.resolve(outputPath.trim());
+    }
+    const parsed = path.parse(path.resolve(inputPath));
+    return path.join(parsed.dir, `${parsed.name}-${suffix}.png`);
+}
+/**
+ * 解析生成类输出路径
+ * @param outputPath 可选输出路径
+ * @param fileNamePrefix 默认文件名前缀
+ * @param extension 文件扩展名（不含点）
+ * @returns 返回输出图片绝对路径
+ * @example
+ * resolveGeneratedImageOutputPath(undefined, "ms-mcp-screen-crop", "png")
+ */
+function resolveGeneratedImageOutputPath(outputPath, fileNamePrefix, extension) {
+    if (outputPath && outputPath.trim()) {
+        return path.resolve(outputPath.trim());
+    }
+    return path.join(os.tmpdir(), `${fileNamePrefix}-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2, 8)}.${extension}`);
+}
+/**
+ * 解析图片路径并确保文件存在
+ * @param imagePath 原始图片路径
+ * @returns 返回绝对路径
+ * @example
+ * const inputPath = await resolveExistingImagePath("./screen.jpg")
+ */
+async function resolveExistingImagePath(imagePath) {
+    const inputPath = path.resolve(imagePath.trim());
+    if (!(await fsExtra.pathExists(inputPath))) {
+        throw new Error(`图片不存在: ${inputPath}`);
+    }
+    return inputPath;
+}
+/**
+ * 解析十六进制颜色
+ * @param value 颜色文本，支持 #RRGGBB 或 RRGGBB
+ * @returns 返回 RGB 颜色
+ * @example
+ * parseHexColor("#ffffff")
+ */
+function parseHexColor(value) {
+    const normalized = value.trim().replace(/^#/, "");
+    if (!/^[0-9a-fA-F]{6}$/.test(normalized)) {
+        throw new Error("transparentColor 必须是 #RRGGBB 或 RRGGBB 格式。");
+    }
+    return {
+        r: Number.parseInt(normalized.slice(0, 2), 16),
+        g: Number.parseInt(normalized.slice(2, 4), 16),
+        b: Number.parseInt(normalized.slice(4, 6), 16),
+    };
+}
+/**
+ * 将 RGB 颜色格式化为 #RRGGBB
+ * @param color RGB 颜色
+ * @returns 返回十六进制颜色文本
+ * @example
+ * formatRgbHex({ r: 255, g: 255, b: 255 })
+ */
+function formatRgbHex(color) {
+    return `#${color.r.toString(16).padStart(2, "0")}${color.g
+        .toString(16)
+        .padStart(2, "0")}${color.b.toString(16).padStart(2, "0")}`;
+}
+/**
+ * 从图片角落采样背景色
+ * @param pixels RGBA 像素数据
+ * @param width 图片宽度
+ * @param height 图片高度
+ * @param corner 采样角落
+ * @returns 返回采样到的 RGB 颜色
+ * @example
+ * sampleCornerColor(pixels, 100, 100, "topLeft")
+ */
+function sampleCornerColor(pixels, width, height, corner) {
+    const x = corner === "topRight" || corner === "bottomRight" ? width - 1 : 0;
+    const y = corner === "bottomLeft" || corner === "bottomRight" ? height - 1 : 0;
+    const offset = (y * width + x) * 4;
+    return {
+        r: pixels[offset] ?? 0,
+        g: pixels[offset + 1] ?? 0,
+        b: pixels[offset + 2] ?? 0,
+    };
+}
+/**
+ * 判断颜色是否在容差范围内
+ * @param pixels RGBA 像素数据
+ * @param offset 像素偏移
+ * @param color 目标 RGB 颜色
+ * @param tolerance RGB 欧氏距离容差
+ * @returns 匹配返回 true
+ * @example
+ * isColorMatch(pixels, 0, { r: 255, g: 255, b: 255 }, 20)
+ */
+function isColorMatch(pixels, offset, color, tolerance) {
+    const dr = (pixels[offset] ?? 0) - color.r;
+    const dg = (pixels[offset + 1] ?? 0) - color.g;
+    const db = (pixels[offset + 2] ?? 0) - color.b;
+    return Math.sqrt(dr * dr + dg * dg + db * db) <= tolerance;
+}
+/**
+ * 读取图片为 RGBA 原始像素
+ * @param input 图片路径或 Buffer
+ * @returns 返回像素和图片尺寸
+ * @example
+ * const image = await readRgbaImage("/tmp/screen.jpg")
+ */
+async function readRgbaImage(input) {
+    const { data, info } = await (0, sharp_1.default)(input)
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    return {
+        data,
+        width: info.width,
+        height: info.height,
+    };
+}
+/**
+ * 获取指定坐标附近的平均颜色
+ * @param data RGBA 像素数据
+ * @param width 图片宽度
+ * @param height 图片高度
+ * @param x 目标坐标 x
+ * @param y 目标坐标 y
+ * @param radius 采样半径
+ * @returns 返回平均 RGBA 颜色和采样像素数量
+ * @example
+ * pickAverageColor(data, 100, 100, 10, 10, 1)
+ */
+function pickAverageColor(data, width, height, x, y, radius) {
+    if (x >= width || y >= height) {
+        throw new Error(`坐标超出图片范围: image=${width}x${height}, point=${x},${y}`);
+    }
+    const startX = Math.max(0, x - radius);
+    const endX = Math.min(width - 1, x + radius);
+    const startY = Math.max(0, y - radius);
+    const endY = Math.min(height - 1, y + radius);
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    let a = 0;
+    let sampleCount = 0;
+    for (let currentY = startY; currentY <= endY; currentY += 1) {
+        for (let currentX = startX; currentX <= endX; currentX += 1) {
+            const offset = (currentY * width + currentX) * 4;
+            r += data[offset] ?? 0;
+            g += data[offset + 1] ?? 0;
+            b += data[offset + 2] ?? 0;
+            a += data[offset + 3] ?? 0;
+            sampleCount += 1;
+        }
+    }
+    return {
+        color: {
+            r: Math.round(r / sampleCount),
+            g: Math.round(g / sampleCount),
+            b: Math.round(b / sampleCount),
+            a: Math.round(a / sampleCount),
+        },
+        sampleCount,
+    };
+}
+/**
+ * 格式化取色结果
+ * @param source 颜色来源
+ * @param x 坐标 x
+ * @param y 坐标 y
+ * @param radius 采样半径
+ * @param imageWidth 图片宽度
+ * @param imageHeight 图片高度
+ * @param color 颜色
+ * @param sampleCount 采样像素数量
+ * @returns 返回 MCP 文本
+ * @example
+ * formatPickedColorText("screen", 1, 1, 0, 100, 100, color, 1)
+ */
+function formatPickedColorText(source, x, y, radius, imageWidth, imageHeight, color, sampleCount) {
+    return [
+        "取色成功",
+        `source: ${source}`,
+        `image: ${imageWidth}x${imageHeight}`,
+        `point: x=${x}, y=${y}`,
+        `radius: ${radius}`,
+        `samplePixels: ${sampleCount}`,
+        `hex: ${formatRgbHex(color)}`,
+        `rgb: ${color.r},${color.g},${color.b}`,
+        `rgba: ${color.r},${color.g},${color.b},${color.a}`,
+    ].join("\n");
+}
+/**
+ * 注册图片处理 MCP 工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerImageTools(server)
+ */
+function registerImageTools(server) {
+    server.registerTool("image_crop", {
+        title: "Image Crop",
+        description: "裁切本地图片并输出 PNG 文件，适合从截图中裁出找图模板。",
+        inputSchema: {
+            imagePath: z.string().min(1).describe("输入图片路径"),
+            x: z.number().int().min(0).describe("裁切起点 x"),
+            y: z.number().int().min(0).describe("裁切起点 y"),
+            width: z.number().int().min(1).describe("裁切宽度"),
+            height: z.number().int().min(1).describe("裁切高度"),
+            outputPath: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("可选输出路径；不传则在输入图片同目录生成 *-crop.png"),
+        },
+    }, async ({ imagePath, x, y, width, height, outputPath }) => {
+        const inputPath = await resolveExistingImagePath(imagePath);
+        const targetPath = resolveImageOutputPath(inputPath, outputPath, "crop");
+        const metadata = await (0, sharp_1.default)(inputPath).metadata();
+        const imageWidth = metadata.width ?? 0;
+        const imageHeight = metadata.height ?? 0;
+        if (x + width > imageWidth || y + height > imageHeight) {
+            return (0, tool_utils_1.createTextToolResult)(`裁切范围超出图片尺寸: image=${imageWidth}x${imageHeight}, crop=${x},${y},${width},${height}`, true);
+        }
+        await fsExtra.ensureDir(path.dirname(targetPath));
+        const info = await (0, sharp_1.default)(inputPath)
+            .extract({ left: x, top: y, width, height })
+            .png()
+            .toFile(targetPath);
+        return (0, tool_utils_1.createTextToolResult)([
+            "图片裁切成功",
+            `input: ${inputPath}`,
+            `output: ${targetPath}`,
+            `crop: x=${x}, y=${y}, width=${width}, height=${height}`,
+            `size: ${info.size} bytes`,
+        ].join("\n"));
+    });
+    server.registerTool("screen_crop", {
+        title: "Screen Crop",
+        description: "从当前默认设备截图中按坐标裁切 PNG 文件，适合自动截取找图模板。",
+        inputSchema: {
+            x: z.number().int().min(0).describe("裁切起点 x"),
+            y: z.number().int().min(0).describe("裁切起点 y"),
+            width: z.number().int().min(1).describe("裁切宽度"),
+            height: z.number().int().min(1).describe("裁切高度"),
+            outputPath: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("可选输出路径；不传则写入系统临时目录"),
+        },
+    }, async ({ x, y, width, height, outputPath }) => {
+        const target = await (0, tool_utils_1.resolveRuntimeHttpTarget)();
+        const screenshot = await (0, project_1.getScreenshotOnDevice)((0, tool_utils_1.createRuntimeHttpRequestOptions)(target));
+        const metadata = await (0, sharp_1.default)(screenshot).metadata();
+        const imageWidth = metadata.width ?? 0;
+        const imageHeight = metadata.height ?? 0;
+        if (x + width > imageWidth || y + height > imageHeight) {
+            return (0, tool_utils_1.createTextToolResult)(`裁切范围超出截图尺寸: image=${imageWidth}x${imageHeight}, crop=${x},${y},${width},${height}`, true);
+        }
+        const targetPath = resolveGeneratedImageOutputPath(outputPath, "ms-mcp-screen-crop", "png");
+        await fsExtra.ensureDir(path.dirname(targetPath));
+        const info = await (0, sharp_1.default)(screenshot)
+            .extract({ left: x, top: y, width, height })
+            .png()
+            .toFile(targetPath);
+        return (0, tool_utils_1.createTextToolResult)([
+            "屏幕裁图成功",
+            `device: ${target.label}`,
+            `output: ${targetPath}`,
+            `screen: ${imageWidth}x${imageHeight}`,
+            `crop: x=${x}, y=${y}, width=${width}, height=${height}`,
+            `size: ${info.size} bytes`,
+        ].join("\n"));
+    });
+    server.registerTool("image_pick_color", {
+        title: "Image Pick Color",
+        description: "读取本地图片指定坐标颜色，返回 hex/rgb/rgba，适合生成找色代码。",
+        inputSchema: {
+            imagePath: z.string().min(1).describe("输入图片路径"),
+            x: z.number().int().min(0).describe("目标坐标 x"),
+            y: z.number().int().min(0).describe("目标坐标 y"),
+            radius: z
+                .number()
+                .int()
+                .min(0)
+                .max(20)
+                .optional()
+                .default(0)
+                .describe("采样半径，0 表示只取单点，默认 0"),
+        },
+    }, async ({ imagePath, x, y, radius }) => {
+        const inputPath = await resolveExistingImagePath(imagePath);
+        const image = await readRgbaImage(inputPath);
+        const picked = pickAverageColor(image.data, image.width, image.height, x, y, radius);
+        return (0, tool_utils_1.createTextToolResult)(formatPickedColorText(inputPath, x, y, radius, image.width, image.height, picked.color, picked.sampleCount));
+    });
+    server.registerTool("screen_pick_color", {
+        title: "Screen Pick Color",
+        description: "从当前默认设备截图中读取指定坐标颜色，返回 hex/rgb/rgba，适合自动生成找色代码。",
+        inputSchema: {
+            x: z.number().int().min(0).describe("目标坐标 x"),
+            y: z.number().int().min(0).describe("目标坐标 y"),
+            radius: z
+                .number()
+                .int()
+                .min(0)
+                .max(20)
+                .optional()
+                .default(0)
+                .describe("采样半径，0 表示只取单点，默认 0"),
+        },
+    }, async ({ x, y, radius }) => {
+        const target = await (0, tool_utils_1.resolveRuntimeHttpTarget)();
+        const screenshot = await (0, project_1.getScreenshotOnDevice)((0, tool_utils_1.createRuntimeHttpRequestOptions)(target));
+        const image = await readRgbaImage(screenshot);
+        const picked = pickAverageColor(image.data, image.width, image.height, x, y, radius);
+        return (0, tool_utils_1.createTextToolResult)(formatPickedColorText(target.label, x, y, radius, image.width, image.height, picked.color, picked.sampleCount));
+    });
+    server.registerTool("image_make_transparent", {
+        title: "Image Make Transparent",
+        description: "将图片中接近指定颜色或角落背景色的像素设为透明，并输出 PNG 文件，适合制作找图模板透明图。",
+        inputSchema: {
+            imagePath: z.string().min(1).describe("输入图片路径"),
+            outputPath: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("可选输出路径；不传则在输入图片同目录生成 *-transparent.png"),
+            transparentColor: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("要透明化的颜色，格式 #RRGGBB；不传则从指定角落采样"),
+            sampleCorner: z
+                .enum(["topLeft", "topRight", "bottomLeft", "bottomRight"])
+                .optional()
+                .default("topLeft")
+                .describe("未传 transparentColor 时采样的背景角落，默认 topLeft"),
+            tolerance: z
+                .number()
+                .int()
+                .min(0)
+                .max(441)
+                .optional()
+                .default(24)
+                .describe("RGB 欧氏距离容差，默认 24，最大 441"),
+        },
+    }, async ({ imagePath, outputPath, transparentColor, sampleCorner, tolerance, }) => {
+        const inputPath = await resolveExistingImagePath(imagePath);
+        const targetPath = resolveImageOutputPath(inputPath, outputPath, "transparent");
+        const { data, info } = await (0, sharp_1.default)(inputPath)
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        const targetColor = transparentColor
+            ? parseHexColor(transparentColor)
+            : sampleCornerColor(data, info.width, info.height, sampleCorner);
+        let transparentPixelCount = 0;
+        for (let offset = 0; offset < data.length; offset += 4) {
+            if (isColorMatch(data, offset, targetColor, tolerance)) {
+                data[offset + 3] = 0;
+                transparentPixelCount += 1;
+            }
+        }
+        await fsExtra.ensureDir(path.dirname(targetPath));
+        const output = await (0, sharp_1.default)(data, {
+            raw: {
+                width: info.width,
+                height: info.height,
+                channels: 4,
+            },
+        })
+            .png()
+            .toFile(targetPath);
+        return (0, tool_utils_1.createTextToolResult)([
+            "透明图制作成功",
+            `input: ${inputPath}`,
+            `output: ${targetPath}`,
+            `image: ${info.width}x${info.height}`,
+            `transparentColor: ${formatRgbHex(targetColor)}`,
+            `tolerance: ${tolerance}`,
+            `transparentPixels: ${transparentPixelCount}`,
+            `size: ${output.size} bytes`,
+        ].join("\n"));
+    });
+}

package/dist/mcp/ocr-tools.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * 注册 OCR MCP 工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerOcrTools(server)
+ */
+export declare function registerOcrTools(server: McpServer): void;

package/dist/mcp/ocr-tools.js

@@ -0,0 +1,348 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOcrTools = registerOcrTools;
+const fsExtra = __importStar(require("fs-extra"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const z = __importStar(require("zod/v4"));
+const tool_utils_1 = require("./tool-utils");
+const APPLE_OCR_LANGUAGES = [
+    "en-US",
+    "fr-FR",
+    "it-IT",
+    "de-DE",
+    "es-ES",
+    "pt-BR",
+    "zh-Hans",
+    "zh-Hant",
+];
+/**
+ * 生成安全的 JavaScript 字面量
+ * @param value 任意 JSON 兼容值
+ * @returns 返回可嵌入脚本的 JSON 字面量
+ * @example
+ * jsonLiteral(["zh-Hans", "en-US"])
+ */
+function jsonLiteral(value) {
+    return JSON.stringify(value);
+}
+/**
+ * 解析 OCR 输出文件路径
+ * @param outputPath 用户指定的可选路径
+ * @returns 返回最终输出文件绝对路径
+ * @example
+ * resolveOcrOutputPath(undefined)
+ */
+function resolveOcrOutputPath(outputPath) {
+    if (outputPath && outputPath.trim()) {
+        return path.resolve(outputPath.trim());
+    }
+    return path.join(os.tmpdir(), `ms-mcp-ocr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+}
+/**
+ * 构建 Apple OCR 运行脚本
+ * @param mode OCR 模式
+ * @param input 输入源
+ * @param x 区域左上角 x
+ * @param y 区域左上角 y
+ * @param ex 区域右下角 x
+ * @param ey 区域右下角 y
+ * @param texts 查找文本数组
+ * @param languages 识别语言数组
+ * @returns 返回可交给 runScript 的 JavaScript 脚本
+ * @example
+ * buildAppleOcrScript("recognize", "screen", 0, 0, 0, 0)
+ */
+function buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages) {
+    if (mode === "findText") {
+        if (!texts || texts.length === 0) {
+            throw new Error("findText 模式必须传 texts。");
+        }
+        return `appleOcr.findText(${jsonLiteral(input)}, ${jsonLiteral(texts)}, ${x}, ${y}, ${ex}, ${ey}, ${jsonLiteral(languages)});`;
+    }
+    if (mode === "numbers") {
+        return `appleOcr.recognizeNumbers(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey});`;
+    }
+    return `appleOcr.recognize(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey}, ${jsonLiteral(languages)});`;
+}
+/**
+ * 构建 Paddle OCR 运行脚本
+ * @param mode OCR 模式
+ * @param input 输入源
+ * @param x 区域左上角 x
+ * @param y 区域左上角 y
+ * @param ex 区域右下角 x
+ * @param ey 区域右下角 y
+ * @param texts 查找文本数组
+ * @param confidenceThreshold 置信度阈值
+ * @param maxSideLen 模型最大边长
+ * @param useGpu 是否使用 GPU
+ * @returns 返回可交给 runScript 的 JavaScript 脚本
+ * @example
+ * buildPaddleOcrScript("recognize", "screen", 0, 0, 0, 0)
+ */
+function buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThreshold, maxSideLen, useGpu) {
+    if (mode === "numbers") {
+        throw new Error("PaddleOCR 文档未提供 numbers 模式，请使用 appleocr 引擎。");
+    }
+    const loadScript = `const __loaded = paddleOcr.loadV5(${maxSideLen}, ${useGpu});`;
+    const loadFailedScript = 'let __ocrResult; if (!__loaded) { __ocrResult = { success: false, error: "PaddleOCR loadV5 failed" }; }';
+    if (mode === "findText") {
+        if (!texts || texts.length === 0) {
+            throw new Error("findText 模式必须传 texts。");
+        }
+        return [
+            loadScript,
+            loadFailedScript,
+            `if (__loaded) { __ocrResult = paddleOcr.findText(${jsonLiteral(input)}, ${jsonLiteral(texts)}, ${x}, ${y}, ${ex}, ${ey}, ${confidenceThreshold}); }`,
+            "__ocrResult;",
+        ].join("\n");
+    }
+    return [
+        loadScript,
+        loadFailedScript,
+        `if (__loaded) { __ocrResult = paddleOcr.recognize(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey}, ${confidenceThreshold}); }`,
+        "__ocrResult;",
+    ].join("\n");
+}
+/**
+ * 构建 OCR 运行脚本
+ * @param engine OCR 引擎
+ * @param mode OCR 模式
+ * @param input 输入源
+ * @param x 区域左上角 x
+ * @param y 区域左上角 y
+ * @param ex 区域右下角 x
+ * @param ey 区域右下角 y
+ * @param texts 查找文本数组
+ * @param languages Apple OCR 识别语言数组
+ * @param confidenceThreshold PaddleOCR 置信度阈值
+ * @param paddleMaxSideLen PaddleOCR 模型最大边长
+ * @param paddleUseGpu PaddleOCR 是否使用 GPU
+ * @returns 返回可交给 runScript 的 JavaScript 脚本
+ * @example
+ * buildOcrScript("appleocr", "recognize", "screen", 0, 0, 0, 0)
+ */
+function buildOcrScript(engine, mode, input, x, y, ex, ey, texts, languages, confidenceThreshold, paddleMaxSideLen, paddleUseGpu) {
+    if (engine === "paddleocr") {
+        return buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThreshold, paddleMaxSideLen, paddleUseGpu);
+    }
+    return buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages);
+}
+/**
+ * 调用设备 runScript 接口
+ * @param ip 设备 IP
+ * @param port 设备端口
+ * @param script JavaScript 脚本文本
+ * @param timeoutMs 超时时间
+ * @returns 返回 runScript 的 JSON 响应
+ * @example
+ * await callRunScript("192.168.1.10", "9800", "1 + 1;", 30000)
+ */
+async function callRunScript(ip, port, script, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(`http://${ip}:${port}/api/runScript`, {
+            method: "POST",
+            signal: controller.signal,
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ script }),
+        });
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`runScript 响应不是有效 JSON: ${text}`);
+        }
+        if (!response.ok) {
+            throw new Error(`runScript HTTP ${response.status}: ${text}`);
+        }
+        return {
+            status: response.status,
+            body,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`runScript 请求超时: ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * 格式化 OCR 工具结果
+ * @param response runScript 响应
+ * @param outputPath 可选输出文件路径
+ * @returns 返回 MCP 文本内容
+ * @example
+ * await formatOcrToolText({ success: true, result: [] })
+ */
+async function formatOcrToolText(response, outputPath) {
+    const resultCount = Array.isArray(response.result)
+        ? response.result.length
+        : undefined;
+    const responseText = (0, tool_utils_1.formatRuntimeJsonText)(response);
+    if (outputPath || responseText.length > 12000) {
+        const targetPath = resolveOcrOutputPath(outputPath);
+        await fsExtra.ensureDir(path.dirname(targetPath));
+        await fsExtra.writeJson(targetPath, response, { spaces: 2 });
+        return [
+            "OCR 执行成功",
+            ...(resultCount === undefined ? [] : [`resultCount: ${resultCount}`]),
+            `resultType: ${response.resultType ?? "unknown"}`,
+            `output: ${targetPath}`,
+        ].join("\n");
+    }
+    return [
+        "OCR 执行成功",
+        ...(resultCount === undefined ? [] : [`resultCount: ${resultCount}`]),
+        `resultType: ${response.resultType ?? "unknown"}`,
+        "",
+        responseText,
+    ].join("\n");
+}
+/**
+ * 注册 OCR MCP 工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerOcrTools(server)
+ */
+function registerOcrTools(server) {
+    server.registerTool("ocr_recognize", {
+        title: "OCR Recognize",
+        description: "通过设备 POST /api/runScript 执行快点JS OCR。支持 appleocr 与 paddleocr，默认 appleocr；OCR 没有独立 HTTP 接口时使用本工具。",
+        inputSchema: {
+            engine: z
+                .enum(["appleocr", "paddleocr"])
+                .optional()
+                .default("appleocr")
+                .describe("OCR 引擎：appleocr=Apple Vision，paddleocr=PaddleOCR"),
+            mode: z
+                .enum(["recognize", "numbers", "findText"])
+                .optional()
+                .default("recognize")
+                .describe("OCR 模式：recognize=识别文本，numbers=识别数字，findText=查找文本"),
+            input: z
+                .string()
+                .min(1)
+                .optional()
+                .default("screen")
+                .describe('输入源，默认 "screen"，也可传图片路径、URL 或 imageId'),
+            x: z.number().int().min(0).optional().default(0).describe("区域左上角 x"),
+            y: z.number().int().min(0).optional().default(0).describe("区域左上角 y"),
+            ex: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .default(0)
+                .describe("区域右下角 x；全屏可传 0"),
+            ey: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .default(0)
+                .describe("区域右下角 y；全屏可传 0"),
+            texts: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("findText 模式要查找的文本数组"),
+            languages: z
+                .array(z.enum(APPLE_OCR_LANGUAGES))
+                .optional()
+                .describe('Apple OCR 识别语言数组，默认由运行时使用 ["zh-Hans", "en-US"]'),
+            confidenceThreshold: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .default(0.6)
+                .describe("PaddleOCR 置信度阈值，默认 0.6"),
+            paddleMaxSideLen: z
+                .number()
+                .int()
+                .min(32)
+                .max(4096)
+                .optional()
+                .default(640)
+                .describe("PaddleOCR loadV5 最大边长，默认 640"),
+            paddleUseGpu: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("PaddleOCR loadV5 是否使用 GPU，默认 false"),
+            outputPath: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("可选输出 JSON 路径；不传且结果很长时写入系统临时目录"),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(1000)
+                .max(600000)
+                .optional()
+                .default(60000)
+                .describe("runScript 请求超时时间，默认 60000 毫秒"),
+        },
+    }, async ({ engine, mode, input, x, y, ex, ey, texts, languages, confidenceThreshold, paddleMaxSideLen, paddleUseGpu, outputPath, timeoutMs, }) => {
+        const target = await (0, tool_utils_1.resolveRuntimeHttpTarget)();
+        const script = buildOcrScript(engine, mode, input, x, y, ex, ey, texts, languages, confidenceThreshold, paddleMaxSideLen, paddleUseGpu);
+        const response = await callRunScript(target.ip, target.port, script, timeoutMs);
+        const text = await formatOcrToolText(response.body, outputPath);
+        return (0, tool_utils_1.createTextToolResult)([
+            text,
+            "",
+            `device: ${target.label}`,
+            `engine: ${engine}`,
+            `mode: ${mode}`,
+            `input: ${input}`,
+            `region: x=${x}, y=${y}, ex=${ex}, ey=${ey}`,
+            `runScript: POST /api/runScript`,
+            `status: ${response.status}`,
+        ].join("\n"), response.body.success === false);
+    });
+}

package/dist/mcp/tools.js

@@ -8,6 +8,8 @@ const device_config_1 = require("./device-config");
 Object.defineProperty(exports, "DEFAULT_DEVICE_PORT", { enumerable: true, get: function () { return device_config_1.DEFAULT_DEVICE_PORT; } });
 const doc_tools_1 = require("./doc-tools");
 const httpapi_tools_1 = require("./httpapi-tools");
+const image_tools_1 = require("./image-tools");
+const ocr_tools_1 = require("./ocr-tools");
 const runtime_tools_1 = require("./runtime-tools");
 /**
  * 创建并注册 MCP 工具
@@ -23,6 +25,8 @@ function createMcpServer() {
     (0, doc_tools_1.registerDocResources)(server);
     (0, doc_tools_1.registerDocTools)(server);
     (0, httpapi_tools_1.registerHttpApiTools)(server);
+    (0, image_tools_1.registerImageTools)(server);
+    (0, ocr_tools_1.registerOcrTools)(server);
     (0, runtime_tools_1.registerRuntimeTools)(server);
     return server;
 }

package/docs/SKILL.md

@@ -163,6 +163,12 @@ MCP 可用时：
 - `get_logs`
 - `take_screenshot`
 - `get_node_source`
+- `image_crop`
+- `screen_crop`
+- `image_pick_color`
+- `screen_pick_color`
+- `ocr_recognize`
+- `image_make_transparent`
 
 ### 通用 HTTP API
 
@@ -170,6 +176,8 @@ MCP 可用时：
 
 控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；命令 fallback 时可用已确认文档的 `curl` 调用。
 
+OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScript` 执行快点JS OCR 脚本。`ocr_recognize` 支持 `appleocr` 和 `paddleocr`，默认 `appleocr`。`runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
+
 ## 禁止事项
 
 - 不要在没有查询文档的情况下回答 API 用法或编写 API 调用代码。

package/docs/mcp-agent-description.md

@@ -163,6 +163,12 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 - `get_logs`
 - `take_screenshot`
 - `get_node_source`
+- `image_crop`
+- `screen_crop`
+- `image_pick_color`
+- `screen_pick_color`
+- `ocr_recognize`
+- `image_make_transparent`
 
 ### 通用 HTTP API 调用
 
@@ -175,6 +181,13 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 - 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
 - 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或已确认接口的 `curl` fallback。
 - 获取截图：优先使用 `take_screenshot`；命令 fallback 可用 `npx ms screenshot`。
+- 从本地图片裁切找图模板：使用 `image_crop`。
+- 从当前设备截图裁切找图模板：使用 `screen_crop`。
+- 从本地图片指定坐标取色：使用 `image_pick_color`。
+- 从当前设备截图指定坐标取色：使用 `screen_pick_color`。
+- 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize`；支持用户指定 `appleocr` 或 `paddleocr`，默认 `appleocr`。
+- OCR 没有独立 HTTP 接口，通过 `POST /api/runScript` 执行快点JS OCR 脚本；`runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
+- 制作透明找图模板：使用 `image_make_transparent`。
 - 获取节点 XML：优先使用 `get_node_source`。
 - 查看日志：优先使用 `get_logs`。
 - 运行项目：优先使用 `run_project` 或 `run_ui_project`；命令 fallback 可用 `npx ms run` 或 `npx ms run-ui`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {
@@ -26,6 +26,7 @@
     "commander": "^14.0.3",
     "crc": "^4.3.2",
     "fs-extra": "^11.3.4",
+    "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "vite": "^8.0.9",
     "vite-plugin-bundle-obfuscator": "^1.11.0",