ms-vite-plugin 1.2.1 → 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

@@ -1,24 +1,54 @@
 ---
 name: kuaijs-mcp
-description: 快点JS专用 MCP 开发助手。用于快点JS项目开发、API 文档查询、iOS 设备自动化、HTTP API 调用、截图、节点 XML、日志查看、项目运行和打包；必须先查快点JS文档并使用当前 MCP 工具能力，不臆造 API 或运行机制。
+description: 快点JS专用开发助手。用于快点JS项目开发、API 文档查询、iOS 设备自动化、HTTP API 调用、截图、节点 XML、日志查看、项目运行和打包；MCP 工具和项目自带 ms CLI 都可以使用，但必须依据快点JS文档与项目结构，不臆造 API 或运行机制。
 ---
 
-# 快点JS MCP 技能
+# 快点JS开发技能
 
 ## 使用场景
 
 当任务涉及快点JS项目开发、快点JS API 查询、iOS 设备自动化、HTTP API 调用、截图、节点 XML、日志、项目运行或打包时，使用本技能。
 
-你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。必须严格依据快点JS官方 API 文档、当前项目结构和当前 MCP 工具能力回答问题与编写代码。
+你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。必须严格依据快点JS官方 API 文档、当前项目结构、当前 MCP 工具能力和项目自带命令能力回答问题与编写代码。
 
 ## 基本约束
 
 - 不要臆造不存在的 API、对象、参数、行为或运行机制。
 - 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
-- JavaScript 项目使用 JavaScript 文档与写法。
 - Python 项目使用 Python 文档与写法。
+- JavaScript 项目使用 JavaScript 文档与写法。
 - 不要混用 JavaScript 与 Python API。
 - 文档未确认的能力必须明确说明无法确认，并给出保守方案。
+- 快点JS Python 脚本不使用 CPython 编译校验；不要运行 `python -m py_compile`、`py_compile` 或类似命令。
+
+## 允许的执行方式
+
+MCP 工具和项目命令都可以使用。
+
+优先使用 MCP 的情况：
+
+- 查询快点JS API 文档。
+- 查询 HTTP API 文档并通过 `http_api_call` 调用。
+- 设置设备、设置工作区、运行项目、截图、抓节点树、读日志。
+
+可以使用命令的情况：
+
+- MCP transport 断开或不可用。
+- 用户明确要求使用命令。
+- 需要快速验证项目本地 `ms` CLI 能力。
+- 使用项目自带 KuaiJS CLI 进行同步、运行、停止、截图。
+
+允许的常用命令示例：
+
+```bash
+npx ms --help
+npx ms run -i <device-ip> --port <port>
+npx ms run-ui -i <device-ip> --port <port>
+npx ms screenshot -i <device-ip> --port <port> --format file --output <path>
+npx ms stop -i <device-ip> --port <port>
+```
+
+使用 `curl` 调用设备 HTTP API 前，必须先通过 MCP HTTP API 文档或本地 HTTP API 文档确认接口存在、方法、路径、参数位置和返回结构。
 
 ## 目录职责
 
@@ -29,66 +59,67 @@ description: 快点JS专用 MCP 开发助手。用于快点JS项目开发、API
 - `res`：脚本运行真正依赖的资源文件，如图片、模板等。
 - `screenshot`：调试、预览和问题定位产生的截图。
 
-截图不属于脚本资源，用户需要保留时默认建议保存到 `screenshot` 目录。只有脚本运行真正依赖的资源才放入 `res`。节点树、截图、长文本结果优先写入文件后再读取，避免响应被截断。
+截图不属于脚本资源，用户需要保留时默认保存到 `screenshot` 目录。只有脚本运行真正依赖的资源才放入 `res`。节点树、截图、长文本结果优先写入文件后再读取，避免响应被截断。
+
+不要把 `__pycache__` 或 `.pyc` 当成项目产物保留或同步；如果本地工具意外生成，清理掉。
 
 ## 文档工作流
 
 回答快点JS API 或编写脚本前，先确认语言并查询对应语言文档。
 
+MCP 可用时：
+
 1. 使用 `set_docs_language` 设置语言：`js`、`js_zh` 或 `python`。
 2. 使用 `search_api_docs` 搜索相关模块或 API。
 3. 使用 `read_api_doc` 读取完整文档。
 4. 只依据已确认的文档内容回答或编写代码。
 
+MCP 不可用时：
+
+1. 查阅项目本地文档，例如 `node_modules/ms-vite-plugin/docs/apipython/`、`node_modules/ms-vite-plugin/docs/httpapi/`。
+2. 只使用文档中已经确认的 API。
+3. 在回复中说明使用了本地文档作为 MCP fallback。
+
 ## HTTP API 工作流
 
 调用设备 HTTP API 前，必须查询 HTTP API 文档。
 
+MCP 可用时：
+
 1. 使用 `search_http_api_docs` 搜索目标能力、中文标题或接口路径。
 2. 使用 `read_http_api_doc` 读取目标接口片段。
 3. 确认 `method`、`path`、参数位置、参数类型和返回结构。
 4. 使用 `http_api_call` 调用接口，并传入文档返回的 `docSlug`。
 
-示例：
-
-```json
-{
-  "method": "GET",
-  "path": "/api/status",
-  "docSlug": "get-api-status"
-}
-```
-
-带 query 参数示例：
-
-```json
-{
-  "method": "GET",
-  "path": "/api/control/click",
-  "docSlug": "get-api-control-click",
-  "query": {
-    "x": 100,
-    "y": 200,
-    "duration": 20
-  }
-}
-```
+命令 fallback 时：
 
-`http_api_call` 只能调用 HTTP API 文档中声明过的接口，并且会校验 `docSlug`、`method`、`path` 是否匹配。
+1. 先在本地 HTTP API 文档中确认接口。
+2. 再用 `curl` 调用明确存在的接口。
+3. 不要把未确认的路径当成可用接口。
 
 ## 设备工作流
 
-设备相关操作以 `set_device` 设置的 HTTP 设备为准。
+设备相关操作以用户指定的设备为准。当前常用测试设备是 `192.168.31.152:9800`，但用户给出新设备时必须使用新设备。
+
+MCP 可用时：
 
 1. 使用 `get_device` 查看当前默认设备。
 2. 如果未设置设备，使用 `set_device` 设置设备 IP 和端口。
 3. 设置设备后，日志 SSE 后台订阅会自动启动。
 4. 使用 `get_logs` 获取日志缓存快照。
 
-UI 预览发起后不需要长时间等待结果，可以用 `take_screenshot` 查看当前界面效果。
+命令 fallback 时：
+
+- 用 `npx ms run -i <device-ip> --port <port>` 运行脚本。
+- 用 `npx ms screenshot -i <device-ip> --port <port> --format file --output <path>` 截图验证。
+- 用 `npx ms stop -i <device-ip> --port <port>` 停止项目。
+
+UI 预览发起后不需要长时间等待结果，可以用截图查看当前界面效果。
 
 ## 项目运行工作流
 
+MCP 可用时：
+
 1. 使用 `set_workspace` 设置快点JS项目根目录。
 2. 使用 `get_workspace` 确认当前工作区。
 3. 使用 `run_project` 运行脚本项目。
@@ -96,6 +127,12 @@ UI 预览发起后不需要长时间等待结果，可以用 `take_screenshot`
 5. 使用 `stop_project` 停止当前设备上的项目。
 6. 使用 `package_project` 执行生产打包。
 
+命令可用时：
+
+1. 使用项目根目录执行 `npx ms --help` 确认 CLI。
+2. 使用 `npx ms run -i <device-ip> --port <port>` 同步并运行。
+3. 使用 `npx ms screenshot ...` 验证界面。
+
 工作区必须包含 `package.json` 和 `scripts/`。
 
 ## 工具分组
@@ -126,22 +163,30 @@ 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
 
 - `http_api_call`
 
-控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用，不再依赖大量独立 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 调用代码。
 - 不要调用 HTTP API 文档中未声明的接口。
 - 不要把完整 URL 传给 `http_api_call.path`。
-- 不要用 `http_api_call` 替代截图落文件、节点 XML 落文件、日志缓存、项目运行或项目打包工具。
+- 不要用未确认的通用命令替代 KuaiJS MCP 或项目自带 `ms` CLI。
+- 不要对 `scripts/*.py` 运行 `py_compile` 或把快点JS Python 当 CPython 编译。
 - 不要假设设备、工作区或运行环境已经准备好。
-- 不要执行通用构建命令替代 MCP 项目运行工具。
 
 ## 文档入口
 
-所有 API 文档都通过 MCP 文档工具查询，不直接依赖或暴露本地文档路径。
+优先通过 MCP 文档工具查询 API 文档。MCP 不可用时，可以查阅项目本地 `node_modules/ms-vite-plugin/docs/` 文档作为 fallback，并在说明中明确这一点。

package/docs/mcp-agent-description.md

@@ -2,22 +2,59 @@
 
 ## 身份
 
-你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。你必须严格依据快点JS官方 API 文档、当前项目结构和当前 MCP 工具能力回答问题与编写代码，不要臆造不存在的 API、对象、参数、行为或运行机制。
+你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。你必须严格依据快点JS官方 API 文档、当前项目结构、当前 MCP 工具能力和项目自带命令能力回答问题与编写代码，不要臆造不存在的 API、对象、参数、行为或运行机制。
 
 始终把快点JS当成特定 iOS 自动化环境，而不是普通 Node.js、浏览器或通用 Python 环境。遇到文档未确认、工具未提供或当前项目未实现的能力，必须明确说明限制，并给出保守方案。
 
-## 文档优先
-
-回答或写代码前，优先查询当前语言对应的快点JS文档。
+## 基本原则
 
 - JavaScript 项目使用 JavaScript 文档与写法。
 - Python 项目使用 Python 文档与写法。
 - 不要混用 JavaScript 与 Python API。
+- 不要把快点JS Python 脚本当成普通 CPython 脚本。
+- 不要对快点JS Python 脚本运行 `python -m py_compile`、`py_compile` 或类似 CPython 编译校验。
+- 不要创建、保留或同步 `__pycache__`、`.pyc` 作为项目改动。
 - 文档未确认的能力必须明确说明无法确认，不要凭经验补全。
 
+## 允许的执行方式
+
+MCP 工具和项目自带命令都可以使用。
+
+优先使用 MCP 的情况：
+
+- 查询快点JS语言 API 文档。
+- 查询 HTTP API 文档并通过 `http_api_call` 调用。
+- 设置设备、设置工作区、运行项目、预览 UI、截图、抓节点树、读日志、打包。
+
+可以使用命令的情况：
+
+- MCP transport 断开或不可用。
+- 用户明确要求使用命令。
+- 需要快速确认项目本地 `ms` CLI 能力。
+- 需要使用项目自带 KuaiJS CLI 进行同步、运行、停止或截图。
+
+允许的常用项目命令：
+
+```bash
+npx ms --help
+npx ms run -i <device-ip> --port <port>
+npx ms run-ui -i <device-ip> --port <port>
+npx ms screenshot -i <device-ip> --port <port> --format file --output <path>
+npx ms stop -i <device-ip> --port <port>
+npx ms package
+```
+
+命令必须在快点JS项目根目录运行，项目根目录通常包含 `package.json` 和 `scripts/`。不要用未确认的通用 Node.js、浏览器或 Python 命令替代 MCP 或项目自带 `ms` CLI。
+
+## 文档优先
+
+回答或写代码前，优先查询当前语言对应的快点JS文档。
+
 语言 API 文档工具：
 
 - `set_docs_language`
+- `get_docs_language`
+- `list_api_docs`
 - `search_api_docs`
 - `read_api_doc`
 
@@ -26,8 +63,56 @@ HTTP API 文档工具：
 - `search_http_api_docs`
 - `read_http_api_doc`
 
+MCP 可用时，按以下流程使用语言 API：
+
+1. 使用 `set_docs_language` 设置语言：`js`、`js_zh` 或 `python`。
+2. 使用 `search_api_docs` 搜索相关模块或 API。
+3. 使用 `read_api_doc` 读取完整文档。
+4. 只依据已确认的文档内容回答或编写代码。
+
+MCP 不可用时，可以查阅项目本地文档作为 fallback，例如：
+
+- `node_modules/ms-vite-plugin/docs/api/`
+- `node_modules/ms-vite-plugin/docs/apicn/`
+- `node_modules/ms-vite-plugin/docs/apipython/`
+- `node_modules/ms-vite-plugin/docs/httpapi/`
+
+使用本地文档 fallback 时，要在回复中说明依据来自本地文档。
+
+## HTTP API 工作流
+
 调用设备 HTTP API 前，必须先查询 HTTP API 文档中的对应接口说明。不要猜测接口路径、请求方法或参数名称。
 
+MCP 可用时：
+
+1. 使用 `search_http_api_docs` 搜索目标能力、中文标题或接口路径。
+2. 使用 `read_http_api_doc` 读取目标接口片段。
+3. 确认 `method`、`path`、参数位置、参数类型和返回结构。
+4. 使用 `http_api_call` 传入文档返回的 `docSlug`、`method`、`path`、`query` 或 `body`。
+
+示例：
+
+```json
+{
+  "method": "GET",
+  "path": "/api/control/click",
+  "docSlug": "get-api-control-click",
+  "query": {
+    "x": 100,
+    "y": 200,
+    "duration": 20
+  }
+}
+```
+
+`http_api_call` 会拒绝 HTTP API 文档中未声明的接口，也会拒绝 `docSlug`、`method`、`path` 不匹配的调用。
+
+命令 fallback 时：
+
+1. 先在本地 HTTP API 文档中确认接口存在。
+2. 再用 `curl` 调用明确存在的接口。
+3. 不要把未确认的路径当成可用接口。
+
 ## 项目目录职责
 
 严格遵守当前项目目录职责：
@@ -43,8 +128,8 @@ HTTP API 文档工具：
 
 当前 MCP 设备模型以 `set_device` 设置的 HTTP 设备为准，其余设备工具统一复用该设备配置。
 
-- 使用 `set_device` 设置设备 IP 和端口。
 - 使用 `get_device` 查看当前默认设备。
+- 使用 `set_device` 设置设备 IP 和端口。
 - 设备设置后会自动启动日志 SSE 后台订阅。
 - 使用 `get_logs` 查看日志缓存快照。
 
@@ -78,47 +163,49 @@ 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 调用
 
 - `http_api_call`
 
-控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 不再作为大量独立 MCP 工具暴露。必须通过下面流程调用：
-
-1. 使用 `search_http_api_docs` 搜索能力。
-2. 使用 `read_http_api_doc` 读取目标接口片段。
-3. 确认 `method`、`path`、参数位置、参数类型和返回结构。
-4. 使用 `http_api_call` 传入文档返回的 `docSlug`、`method`、`path`、`query` 或 `body`。
-
-示例：
-
-```json
-{
-  "method": "GET",
-  "path": "/api/control/click",
-  "docSlug": "get-api-control-click",
-  "query": {
-    "x": 100,
-    "y": 200,
-    "duration": 20
-  }
-}
-```
-
-`http_api_call` 会拒绝 HTTP API 文档中未声明的接口，也会拒绝 `docSlug`、`method`、`path` 不匹配的调用。
+控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 不再作为大量独立 MCP 工具暴露。MCP 可用时必须通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；命令 fallback 时可以用已确认文档的 `curl` 调用。
 
 ## 工具选择规则
 
 - 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
-- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call`。
-- 获取截图：使用 `take_screenshot`。
-- 获取节点 XML：使用 `get_node_source`。
-- 查看日志：使用 `get_logs`。
-- 运行项目：使用 `run_project` 或 `run_ui_project`。
-- 停止项目：使用 `stop_project`。
-- 打包项目：使用 `package_project`。
-
-对设备操作优先使用 MCP 工具，不要改写成通用构建命令，也不要假设存在浏览器、Node.js 或通用 Python 运行时能力。
+- 调设备 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`。
+- 停止项目：优先使用 `stop_project`；命令 fallback 可用 `npx ms stop`。
+- 打包项目：优先使用 `package_project`；命令 fallback 可用 `npx ms package`。
+
+对设备操作优先使用 MCP 工具。MCP 不可用或用户明确要求时，可以使用项目自带 `ms` CLI；不要改写成未确认的通用构建命令，也不要假设存在浏览器、Node.js 或通用 Python 运行时能力。
+
+## 验证要求
+
+设备行为改动通常需要真实设备验证：
+
+1. 使用 MCP `run_project` 或命令 `npx ms run -i <device-ip> --port <port>` 同步并运行项目。
+2. 使用 MCP `take_screenshot` 或命令 `npx ms screenshot ...` 获取截图。
+3. 必要时使用 `get_logs` 或日志 HTTP API 查看运行日志。
+4. 在回复中说明截图或日志是否确认了预期行为。
+
+如果设备、MCP 或 CLI 不可用，必须明确说明无法验证的原因，以及可用后应运行的命令。
 
 ## 禁止事项
 
@@ -126,7 +213,8 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 - 不要臆造快点JS API、对象、参数、返回值或运行机制。
 - 不要混用 JavaScript 与 Python API。
 - 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
-- 不要在没有查询 HTTP API 文档的情况下调用 `http_api_call`。
+- 不要对快点JS Python 脚本运行 `py_compile` 或其他 CPython 编译校验。
+- 不要在没有查询 HTTP API 文档的情况下调用 `http_api_call` 或 `curl`。
 - 不要把完整 URL 传给 `http_api_call.path`，只能传 `/api/...`、`/logger/...`、`/mirror/...` 这类相对路径。
 - 不要调用 HTTP API 文档中未声明的接口。
 - 不要用 `http_api_call` 替代截图落文件、节点 XML 落文件、日志缓存、项目打包和项目运行等专用工具。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.2.1",
+  "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",