ms-vite-plugin 1.4.15 → 1.4.16

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

@@ -1,12 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * 注册文档资源
- * @param server MCP 服务实例
- * @returns 无返回值
- * @example
- * registerDocResources(server)
- */
-export declare function registerDocResources(server: McpServer): void;
 /**
  * 注册文档工具
  * @param server MCP 服务实例

package/dist/mcp/doc-tools.js

@@ -33,73 +33,27 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerDocResources = registerDocResources;
 exports.registerDocTools = registerDocTools;
-const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const z = __importStar(require("zod/v4"));
 const docs_service_1 = require("./docs-service");
+const httpapi_docs_service_1 = require("./httpapi-docs-service");
 const tool_utils_1 = require("./tool-utils");
 const types_1 = require("./types");
 /**
- * 注册文档资源
- * @param server MCP 服务实例
- * @returns 无返回值
+ * 格式化 KuaiJS 文档路径清单
+ * @returns 返回可直接交给 AI 读取的文档路径文本
  * @example
- * registerDocResources(server)
+ * const text = formatDocsPathsText()
  */
-function registerDocResources(server) {
-    server.registerResource("current-language", "kuaijs://docs/current-language", {
-        title: "Current KuaiJS API language",
-        mimeType: "application/json",
-    }, async () => {
-        const language = (0, docs_service_1.getCurrentDocsLanguage)();
-        return {
-            contents: [
-                {
-                    uri: "kuaijs://docs/current-language",
-                    mimeType: "application/json",
-                    text: JSON.stringify({
-                        currentLanguage: language,
-                        label: types_1.DOC_LANGUAGE_LABELS[language],
-                    }, null, 2),
-                },
-            ],
-        };
-    });
-    server.registerResource("api-doc", new mcp_js_1.ResourceTemplate("kuaijs://docs/current/{slug}", {
-        list: async () => {
-            const language = (0, docs_service_1.getCurrentDocsLanguage)();
-            const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
-            return {
-                resources: docs.map((doc) => ({
-                    uri: `kuaijs://docs/current/${doc.slug}`,
-                    name: doc.title,
-                    description: `[${types_1.DOC_LANGUAGE_LABELS[language]}] ${doc.slug}`,
-                    mimeType: "text/markdown",
-                })),
-            };
-        },
-    }), {
-        title: "KuaiJS API documents",
-        mimeType: "text/markdown",
-    }, async (_uri, variables) => {
-        const language = (0, docs_service_1.getCurrentDocsLanguage)();
-        const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
-        const slug = String(variables.slug || "");
-        const target = docs.find((doc) => doc.slug === slug);
-        if (!target) {
-            throw new Error(`文档不存在: ${slug}`);
-        }
-        return {
-            contents: [
-                {
-                    uri: `kuaijs://docs/current/${target.slug}`,
-                    mimeType: "text/markdown",
-                    text: target.content,
-                },
-            ],
-        };
-    });
+function formatDocsPathsText() {
+    const languages = ["js", "js_zh", "python"];
+    return [
+        "KuaiJS 文档路径:",
+        `docsRoot: ${(0, docs_service_1.getDocsRootDir)()}`,
+        ...languages.map((language) => `${language}: ${(0, docs_service_1.getDocsDirByLanguage)(language)} (${types_1.DOC_LANGUAGE_LABELS[language]})`),
+        `httpApi: ${(0, httpapi_docs_service_1.getHttpApiDocPath)()}`,
+        "说明: 直接读取上述 markdown 路径；search/read 工具用于定位具体文档。",
+    ].join("\n");
 }
 /**
  * 注册文档工具
@@ -109,51 +63,37 @@ function registerDocResources(server) {
  * registerDocTools(server)
  */
 function registerDocTools(server) {
-    server.registerTool("get_docs_language", {
-        title: "Get Docs Language",
-        description: "获取当前 KuaiJS API 文档语言。",
+    server.registerTool("get_docs_paths", {
+        title: "Get Docs Paths",
+        description: "获取 KuaiJS 本地文档路径，便于 AI 直接读取 markdown 文件而不是猜测位置。",
         inputSchema: {},
     }, async () => {
-        const language = (0, docs_service_1.getCurrentDocsLanguage)();
-        return (0, tool_utils_1.createTextToolResult)(`当前文档语言: ${language} (${types_1.DOC_LANGUAGE_LABELS[language]})`);
-    });
-    server.registerTool("set_docs_language", {
-        title: "Set Docs Language",
-        description: "设置当前 KuaiJS API 文档语言，影响后续文档查询与读取。",
-        inputSchema: {
-            language: z
-                .enum(["js", "js_zh", "python"])
-                .describe("文档语言：js | js_zh | python"),
-        },
-    }, async ({ language }) => {
-        const active = (0, docs_service_1.setCurrentDocsLanguage)(language);
-        const docsDir = (0, docs_service_1.getDocsDirByLanguage)(active);
-        return (0, tool_utils_1.createTextToolResult)(`文档语言已切换为 ${active} (${types_1.DOC_LANGUAGE_LABELS[active]})\n目录: ${docsDir}`);
+        return (0, tool_utils_1.createTextToolResult)(formatDocsPathsText());
     });
     server.registerTool("list_api_docs", {
         title: "List API Docs",
-        description: "列出当前（或指定）语言下可用的 API 文档。",
+        description: "列出指定语言下可用的 API 文档；不传 language 时默认 js_zh。",
         inputSchema: {
             language: z
                 .enum(["js", "js_zh", "python"])
                 .optional()
-                .describe("可选语言，不传则使用当前语言"),
+                .describe("可选语言，不传默认 js_zh"),
         },
     }, async ({ language }) => {
-        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const activeLanguage = language ?? "js_zh";
         const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
-        const lines = docs.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index));
+        const lines = docs.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index, doc.filePath));
         return (0, tool_utils_1.createTextToolResult)(lines.length === 0
-            ? `当前语言 ${activeLanguage} 下没有可用文档。`
+            ? `文档语言 ${activeLanguage} 下没有可用文档。`
             : [
-                `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
+                `文档语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
                 "",
                 ...lines,
             ].join("\n"));
     });
     server.registerTool("search_api_docs", {
         title: "Search API Docs",
-        description: "在当前（或指定）语言文档中按关键字搜索。",
+        description: "在指定语言文档中按关键字搜索；不传 language 时默认 js_zh。",
         inputSchema: {
             query: z.string().min(1).describe("搜索关键字"),
             limit: z
@@ -167,10 +107,10 @@ function registerDocTools(server) {
             language: z
                 .enum(["js", "js_zh", "python"])
                 .optional()
-                .describe("可选语言，不传则使用当前语言"),
+                .describe("可选语言，不传默认 js_zh"),
         },
     }, async ({ query, limit, language }) => {
-        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const activeLanguage = language ?? "js_zh";
         const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
         const normalizedQuery = query.toLowerCase();
         const matches = docs
@@ -180,31 +120,38 @@ function registerDocTools(server) {
             .slice(0, limit)
             .map((item) => item.doc);
         const text = matches.length === 0
-            ? `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})\n未找到与 "${query}" 匹配的文档。`
+            ? `文档语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})\n未找到与 "${query}" 匹配的文档。`
             : [
-                `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
+                `文档语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
                 "",
-                ...matches.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index)),
+                ...matches.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index, doc.filePath)),
             ].join("\n");
         return (0, tool_utils_1.createTextToolResult)(text);
     });
     server.registerTool("read_api_doc", {
         title: "Read API Doc",
-        description: "读取当前（或指定）语言下某个文档的完整 markdown 内容。",
+        description: "读取指定语言下某个文档的完整 markdown 内容；不传 language 时默认 js_zh。",
         inputSchema: {
             slug: z.string().min(1).describe("文档 slug（文件名，不含 .md）"),
             language: z
                 .enum(["js", "js_zh", "python"])
                 .optional()
-                .describe("可选语言，不传则使用当前语言"),
+                .describe("可选语言，不传默认 js_zh"),
         },
     }, async ({ slug, language }) => {
-        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const activeLanguage = language ?? "js_zh";
         const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
         const target = docs.find((doc) => doc.slug === slug);
         if (!target) {
             return (0, tool_utils_1.createTextToolResult)(`未找到文档 ${slug}.md（语言: ${activeLanguage}）。`, true);
         }
-        return (0, tool_utils_1.createTextToolResult)(`标题: ${target.title}\n语言: ${activeLanguage}\nURI: ${(0, docs_service_1.getDocUri)(activeLanguage, target.slug)}\n\n${target.content}`);
+        return (0, tool_utils_1.createTextToolResult)([
+            `标题: ${target.title}`,
+            `语言: ${activeLanguage}`,
+            `URI: ${(0, docs_service_1.getDocUri)(activeLanguage, target.slug)}`,
+            `path: ${target.filePath}`,
+            "",
+            target.content,
+        ].join("\n"));
     });
 }

package/dist/mcp/docs-service.d.ts

@@ -1,27 +1,4 @@
 import type { ApiDocItem, ApiDocsLanguage } from "./types";
-/**
- * 获取当前文档语言
- * @returns 返回当前语言
- * @example
- * const language = getCurrentDocsLanguage()
- */
-export declare function getCurrentDocsLanguage(): ApiDocsLanguage;
-/**
- * 设置当前文档语言
- * @param language 目标语言
- * @returns 设置后的语言
- * @example
- * const language = setCurrentDocsLanguage("python")
- */
-export declare function setCurrentDocsLanguage(language: ApiDocsLanguage): ApiDocsLanguage;
-/**
- * 根据可选入参解析实际使用的文档语言
- * @param language 工具调用时传入的语言（可选）
- * @returns 返回最终生效的语言
- * @example
- * const activeLanguage = resolveDocsLanguage(undefined)
- */
-export declare function resolveDocsLanguage(language?: ApiDocsLanguage): ApiDocsLanguage;
 /**
  * 获取 docs 根目录
  * @returns 返回 docs 目录绝对路径

package/dist/mcp/docs-service.js

@@ -33,9 +33,6 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCurrentDocsLanguage = getCurrentDocsLanguage;
-exports.setCurrentDocsLanguage = setCurrentDocsLanguage;
-exports.resolveDocsLanguage = resolveDocsLanguage;
 exports.getDocsRootDir = getDocsRootDir;
 exports.getDocsDirByLanguage = getDocsDirByLanguage;
 exports.getApiDocsByLanguage = getApiDocsByLanguage;
@@ -43,40 +40,6 @@ exports.scoreApiDoc = scoreApiDoc;
 exports.getDocUri = getDocUri;
 const fsExtra = __importStar(require("fs-extra"));
 const path = __importStar(require("path"));
-/**
- * 当前 MCP 进程默认文档语言
- */
-let currentDocsLanguage = "js_zh";
-/**
- * 获取当前文档语言
- * @returns 返回当前语言
- * @example
- * const language = getCurrentDocsLanguage()
- */
-function getCurrentDocsLanguage() {
-    return currentDocsLanguage;
-}
-/**
- * 设置当前文档语言
- * @param language 目标语言
- * @returns 设置后的语言
- * @example
- * const language = setCurrentDocsLanguage("python")
- */
-function setCurrentDocsLanguage(language) {
-    currentDocsLanguage = language;
-    return currentDocsLanguage;
-}
-/**
- * 根据可选入参解析实际使用的文档语言
- * @param language 工具调用时传入的语言（可选）
- * @returns 返回最终生效的语言
- * @example
- * const activeLanguage = resolveDocsLanguage(undefined)
- */
-function resolveDocsLanguage(language) {
-    return language ?? currentDocsLanguage;
-}
 /**
  * 获取 docs 根目录
  * @returns 返回 docs 目录绝对路径
@@ -111,9 +74,6 @@ function getDocsDirByLanguage(language) {
  */
 async function getApiDocsByLanguage(language) {
     const docsDir = getDocsDirByLanguage(language);
-    if (!(await fsExtra.pathExists(docsDir))) {
-        throw new Error(`文档目录不存在: ${docsDir}`);
-    }
     const fileNames = await fsExtra.readdir(docsDir);
     const mdFiles = fileNames
         .filter((name) => name.toLowerCase().endsWith(".md"))

package/dist/mcp/httpapi-docs-service.d.ts

@@ -8,6 +8,8 @@ export type HttpApiMethod = "GET" | "POST";
 export type HttpApiDocEntry = {
     /** 稳定 slug，可用于读取单个接口文档 */
     slug: string;
+    /** HTTP API 文档绝对路径 */
+    filePath: string;
     /** 接口请求方法 */
     method: HttpApiMethod;
     /** 接口路径 */
@@ -23,6 +25,13 @@ export type HttpApiDocEntry = {
     /** 接口完整 markdown 片段 */
     content: string;
 };
+/**
+ * 获取 HTTP API 文档路径
+ * @returns 返回 HTTP API 文档绝对路径
+ * @example
+ * const filePath = getHttpApiDocPath()
+ */
+export declare function getHttpApiDocPath(): string;
 /**
  * 读取 HTTP API markdown 文档
  * @returns 返回完整 markdown 文本

package/dist/mcp/httpapi-docs-service.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHttpApiDocPath = getHttpApiDocPath;
 exports.readHttpApiMarkdown = readHttpApiMarkdown;
 exports.createHttpApiSlug = createHttpApiSlug;
 exports.getHttpApiDocEntries = getHttpApiDocEntries;
@@ -62,9 +63,6 @@ function getHttpApiDocPath() {
  */
 async function readHttpApiMarkdown() {
     const filePath = getHttpApiDocPath();
-    if (!(await fsExtra.pathExists(filePath))) {
-        throw new Error("HTTP API 文档不可用。");
-    }
     return fsExtra.readFile(filePath, "utf8");
 }
 /**
@@ -89,10 +87,7 @@ function createHttpApiSlug(method, apiPath) {
  */
 async function getHttpApiDocEntries() {
     const filePath = getHttpApiDocPath();
-    const stat = await fsExtra.stat(filePath).catch(() => null);
-    if (!stat) {
-        throw new Error("HTTP API 文档不可用。");
-    }
+    const stat = await fsExtra.stat(filePath);
     if (cachedHttpApiDocEntries?.mtimeMs === stat.mtimeMs) {
         return cachedHttpApiDocEntries.entries;
     }
@@ -134,6 +129,7 @@ async function getHttpApiDocEntries() {
         }
         entries.push({
             slug: createHttpApiSlug(method, apiPath),
+            filePath,
             method,
             path: apiPath,
             title,

package/dist/mcp/httpapi-tools.js

@@ -59,6 +59,7 @@ function formatHttpApiDocSummary(entry, index) {
         `slug: ${entry.slug}`,
         `section: ${entry.section || "未分组"}`,
         `lines: ${entry.startLine}-${entry.endLine}`,
+        `file: ${entry.filePath}`,
         `uri: ${HTTP_API_ENDPOINT_RESOURCE_PREFIX}/${entry.slug}`,
     ].join("\n");
 }
@@ -183,7 +184,7 @@ function registerHttpApiTools(server) {
                 resources: entries.map((entry) => ({
                     uri: `${HTTP_API_ENDPOINT_RESOURCE_PREFIX}/${entry.slug}`,
                     name: `${entry.method} ${entry.path}`,
-                    description: `${entry.title} [${entry.section || "未分组"}]`,
+                    description: `${entry.title} [${entry.section || "未分组"}] | file: ${entry.filePath}`,
                     mimeType: "text/markdown",
                 })),
             };
@@ -271,6 +272,7 @@ function registerHttpApiTools(server) {
             `slug: ${entry.slug}`,
             `section: ${entry.section || "未分组"}`,
             `lines: ${entry.startLine}-${entry.endLine}`,
+            `file: ${entry.filePath}`,
             "",
             entry.content,
         ].join("\n"));

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

@@ -1,4 +1,73 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type ImageSampleCorner = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+/**
+ * 裁切本地图片
+ * @param imagePath 输入图片路径
+ * @param x 裁切起点 x
+ * @param y 裁切起点 y
+ * @param width 裁切宽度
+ * @param height 裁切高度
+ * @param outputPath 可选输出路径
+ * @returns 返回操作结果文本
+ * @example
+ * await cropLocalImage("./screen.jpg", 0, 0, 100, 100)
+ */
+export declare function cropLocalImage(imagePath: string, x: number, y: number, width: number, height: number, outputPath?: string): Promise<string>;
+/**
+ * 裁切设备截图
+ * @param target 设备 HTTP 地址
+ * @param x 裁切起点 x
+ * @param y 裁切起点 y
+ * @param width 裁切宽度
+ * @param height 裁切高度
+ * @param outputPath 可选输出路径
+ * @returns 返回操作结果文本
+ * @example
+ * await cropDeviceScreen({ ip: "192.168.1.10", port: "9800", label: "192.168.1.10:9800" }, 0, 0, 100, 100)
+ */
+export declare function cropDeviceScreen(target: {
+    ip: string;
+    port: string;
+    label: string;
+}, x: number, y: number, width: number, height: number, outputPath?: string): Promise<string>;
+/**
+ * 读取本地图片颜色
+ * @param imagePath 输入图片路径
+ * @param x 目标坐标 x
+ * @param y 目标坐标 y
+ * @param radius 采样半径
+ * @returns 返回取色结果文本
+ * @example
+ * await pickLocalImageColor("./screen.jpg", 10, 10, 0)
+ */
+export declare function pickLocalImageColor(imagePath: string, x: number, y: number, radius: number): Promise<string>;
+/**
+ * 读取设备截图颜色
+ * @param target 设备 HTTP 地址
+ * @param x 目标坐标 x
+ * @param y 目标坐标 y
+ * @param radius 采样半径
+ * @returns 返回取色结果文本
+ * @example
+ * await pickDeviceScreenColor({ ip: "192.168.1.10", port: "9800", label: "192.168.1.10:9800" }, 10, 10, 0)
+ */
+export declare function pickDeviceScreenColor(target: {
+    ip: string;
+    port: string;
+    label: string;
+}, x: number, y: number, radius: number): Promise<string>;
+/**
+ * 制作本地图片透明图
+ * @param imagePath 输入图片路径
+ * @param outputPath 可选输出路径
+ * @param transparentColor 可选透明色
+ * @param sampleCorner 未传透明色时采样的角落
+ * @param tolerance 颜色容差
+ * @returns 返回操作结果文本
+ * @example
+ * await makeLocalImageTransparent("./button.png", undefined, "#ffffff", "topLeft", 24)
+ */
+export declare function makeLocalImageTransparent(imagePath: string, outputPath: string | undefined, transparentColor: string | undefined, sampleCorner: ImageSampleCorner, tolerance: number): Promise<string>;
 /**
  * 注册图片处理 MCP 工具
  * @param server MCP 服务实例

package/dist/mcp/image-tools.js

@@ -36,6 +36,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.cropLocalImage = cropLocalImage;
+exports.cropDeviceScreen = cropDeviceScreen;
+exports.pickLocalImageColor = pickLocalImageColor;
+exports.pickDeviceScreenColor = pickDeviceScreenColor;
+exports.makeLocalImageTransparent = makeLocalImageTransparent;
 exports.registerImageTools = registerImageTools;
 const fsExtra = __importStar(require("fs-extra"));
 const os = __importStar(require("os"));
@@ -247,6 +252,164 @@ function formatPickedColorText(source, x, y, radius, imageWidth, imageHeight, co
         `rgba: ${color.r},${color.g},${color.b},${color.a}`,
     ].join("\n");
 }
+/**
+ * 裁切本地图片
+ * @param imagePath 输入图片路径
+ * @param x 裁切起点 x
+ * @param y 裁切起点 y
+ * @param width 裁切宽度
+ * @param height 裁切高度
+ * @param outputPath 可选输出路径
+ * @returns 返回操作结果文本
+ * @example
+ * await cropLocalImage("./screen.jpg", 0, 0, 100, 100)
+ */
+async function cropLocalImage(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) {
+        throw new Error(`裁切范围超出图片尺寸: image=${imageWidth}x${imageHeight}, crop=${x},${y},${width},${height}`);
+    }
+    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 [
+        "图片裁切成功",
+        `input: ${inputPath}`,
+        `output: ${targetPath}`,
+        `crop: x=${x}, y=${y}, width=${width}, height=${height}`,
+        `size: ${info.size} bytes`,
+    ].join("\n");
+}
+/**
+ * 裁切设备截图
+ * @param target 设备 HTTP 地址
+ * @param x 裁切起点 x
+ * @param y 裁切起点 y
+ * @param width 裁切宽度
+ * @param height 裁切高度
+ * @param outputPath 可选输出路径
+ * @returns 返回操作结果文本
+ * @example
+ * await cropDeviceScreen({ ip: "192.168.1.10", port: "9800", label: "192.168.1.10:9800" }, 0, 0, 100, 100)
+ */
+async function cropDeviceScreen(target, x, y, width, height, outputPath) {
+    const screenshot = await (0, project_1.getScreenshotOnDevice)({
+        ip: target.ip,
+        port: target.port,
+        transport: "http",
+    });
+    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) {
+        throw new Error(`裁切范围超出截图尺寸: image=${imageWidth}x${imageHeight}, crop=${x},${y},${width},${height}`);
+    }
+    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 [
+        "屏幕裁图成功",
+        `device: ${target.label}`,
+        `output: ${targetPath}`,
+        `screen: ${imageWidth}x${imageHeight}`,
+        `crop: x=${x}, y=${y}, width=${width}, height=${height}`,
+        `size: ${info.size} bytes`,
+    ].join("\n");
+}
+/**
+ * 读取本地图片颜色
+ * @param imagePath 输入图片路径
+ * @param x 目标坐标 x
+ * @param y 目标坐标 y
+ * @param radius 采样半径
+ * @returns 返回取色结果文本
+ * @example
+ * await pickLocalImageColor("./screen.jpg", 10, 10, 0)
+ */
+async function pickLocalImageColor(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 formatPickedColorText(inputPath, x, y, radius, image.width, image.height, picked.color, picked.sampleCount);
+}
+/**
+ * 读取设备截图颜色
+ * @param target 设备 HTTP 地址
+ * @param x 目标坐标 x
+ * @param y 目标坐标 y
+ * @param radius 采样半径
+ * @returns 返回取色结果文本
+ * @example
+ * await pickDeviceScreenColor({ ip: "192.168.1.10", port: "9800", label: "192.168.1.10:9800" }, 10, 10, 0)
+ */
+async function pickDeviceScreenColor(target, x, y, radius) {
+    const screenshot = await (0, project_1.getScreenshotOnDevice)({
+        ip: target.ip,
+        port: target.port,
+        transport: "http",
+    });
+    const image = await readRgbaImage(screenshot);
+    const picked = pickAverageColor(image.data, image.width, image.height, x, y, radius);
+    return formatPickedColorText(target.label, x, y, radius, image.width, image.height, picked.color, picked.sampleCount);
+}
+/**
+ * 制作本地图片透明图
+ * @param imagePath 输入图片路径
+ * @param outputPath 可选输出路径
+ * @param transparentColor 可选透明色
+ * @param sampleCorner 未传透明色时采样的角落
+ * @param tolerance 颜色容差
+ * @returns 返回操作结果文本
+ * @example
+ * await makeLocalImageTransparent("./button.png", undefined, "#ffffff", "topLeft", 24)
+ */
+async function makeLocalImageTransparent(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 [
+        "透明图制作成功",
+        `input: ${inputPath}`,
+        `output: ${targetPath}`,
+        `image: ${info.width}x${info.height}`,
+        `transparentColor: ${formatRgbHex(targetColor)}`,
+        `tolerance: ${tolerance}`,
+        `transparentPixels: ${transparentPixelCount}`,
+        `size: ${output.size} bytes`,
+    ].join("\n");
+}
 /**
  * 注册图片处理 MCP 工具
  * @param server MCP 服务实例