ms-vite-plugin 1.4.15 → 1.4.16

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

@@ -1,4 +1,54 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type OcrEngine = "appleocr" | "paddleocr";
+export type OcrMode = "recognize" | "numbers" | "findText";
+export type ScriptResultResponse = {
+    success?: boolean;
+    result?: unknown;
+    resultType?: string;
+    error?: string;
+};
+export type OcrRecognitionOptions = {
+    engine: OcrEngine;
+    mode: OcrMode;
+    input: string;
+    x: number;
+    y: number;
+    ex: number;
+    ey: number;
+    texts?: string[];
+    languages?: string[];
+    confidenceThreshold: number;
+    exactMatch: boolean;
+    outputPath?: string;
+    timeoutMs: number;
+};
+export type OcrRecognitionResult = {
+    status: number;
+    body: ScriptResultResponse;
+    text: string;
+};
+export declare const APPLE_OCR_LANGUAGES: readonly ["en-US", "fr-FR", "it-IT", "de-DE", "es-ES", "pt-BR", "zh-Hans", "zh-Hant"];
+/**
+ * 格式化 OCR 工具结果
+ * @param response runScript 响应
+ * @param outputPath 可选输出文件路径
+ * @returns 返回 MCP 文本内容
+ * @example
+ * await formatOcrToolText({ success: true, result: [] })
+ */
+export declare function formatOcrToolText(response: ScriptResultResponse, outputPath?: string): Promise<string>;
+/**
+ * 在指定 HTTP 设备上执行 OCR 识别
+ * @param target 设备 HTTP 地址
+ * @param options OCR 参数
+ * @returns 返回 HTTP 状态码、原始结果与格式化文本
+ * @example
+ * await runOcrRecognitionOnDevice({ ip: "192.168.1.10", port: "9800" }, options)
+ */
+export declare function runOcrRecognitionOnDevice(target: {
+    ip: string;
+    port: string;
+}, options: OcrRecognitionOptions): Promise<OcrRecognitionResult>;
 /**
  * 注册 OCR MCP 工具
  * @param server MCP 服务实例

package/dist/mcp/ocr-tools.js

@@ -33,13 +33,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLE_OCR_LANGUAGES = void 0;
+exports.formatOcrToolText = formatOcrToolText;
+exports.runOcrRecognitionOnDevice = runOcrRecognitionOnDevice;
 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 = [
+exports.APPLE_OCR_LANGUAGES = [
     "en-US",
     "fr-FR",
     "it-IT",
@@ -82,21 +85,22 @@ function resolveOcrOutputPath(outputPath) {
  * @param ey 区域右下角 y
  * @param texts 查找文本数组
  * @param languages 识别语言数组
+ * @param exactMatch 是否完整匹配文本
  * @returns 返回可交给 runScript 的 JavaScript 脚本
  * @example
  * buildAppleOcrScript("recognize", "screen", 0, 0, 0, 0)
  */
-function buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages) {
+function buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages, exactMatch = false) {
     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)});`;
+        return `appleOcr.findTextAbs(${jsonLiteral(input)}, ${jsonLiteral(texts)}, ${x}, ${y}, ${ex}, ${ey}, ${jsonLiteral(languages)}, ${exactMatch});`;
     }
     if (mode === "numbers") {
-        return `appleOcr.recognizeNumbers(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey});`;
+        return `appleOcr.recognizeNumbersAbs(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey});`;
     }
-    return `appleOcr.recognize(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey}, ${jsonLiteral(languages)});`;
+    return `appleOcr.recognizeAbs(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey}, ${jsonLiteral(languages)});`;
 }
 /**
  * 构建 Paddle OCR 运行脚本
@@ -108,35 +112,22 @@ function buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages) {
  * @param ey 区域右下角 y
  * @param texts 查找文本数组
  * @param confidenceThreshold 置信度阈值
- * @param maxSideLen 模型最大边长
- * @param useGpu 是否使用 GPU
+ * @param exactMatch 是否完整匹配文本
  * @returns 返回可交给 runScript 的 JavaScript 脚本
  * @example
  * buildPaddleOcrScript("recognize", "screen", 0, 0, 0, 0)
  */
-function buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThreshold, maxSideLen, useGpu) {
+function buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThreshold, exactMatch) {
     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 `paddleOcr.findTextAbs(${jsonLiteral(input)}, ${jsonLiteral(texts)}, ${x}, ${y}, ${ex}, ${ey}, ${confidenceThreshold}, ${exactMatch});`;
     }
-    return [
-        loadScript,
-        loadFailedScript,
-        `if (__loaded) { __ocrResult = paddleOcr.recognize(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey}, ${confidenceThreshold}); }`,
-        "__ocrResult;",
-    ].join("\n");
+    return `paddleOcr.recognizeAbs(${jsonLiteral(input)}, ${x}, ${y}, ${ex}, ${ey}, ${confidenceThreshold});`;
 }
 /**
  * 构建 OCR 运行脚本
@@ -150,17 +141,16 @@ function buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThresh
  * @param texts 查找文本数组
  * @param languages Apple OCR 识别语言数组
  * @param confidenceThreshold PaddleOCR 置信度阈值
- * @param paddleMaxSideLen PaddleOCR 模型最大边长
- * @param paddleUseGpu PaddleOCR 是否使用 GPU
+ * @param exactMatch 是否完整匹配文本
  * @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) {
+function buildOcrScript(engine, mode, input, x, y, ex, ey, texts, languages, confidenceThreshold, exactMatch) {
     if (engine === "paddleocr") {
-        return buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThreshold, paddleMaxSideLen, paddleUseGpu);
+        return buildPaddleOcrScript(mode, input, x, y, ex, ey, texts, confidenceThreshold, exactMatch);
     }
-    return buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages);
+    return buildAppleOcrScript(mode, input, x, y, ex, ey, texts, languages, exactMatch);
 }
 /**
  * 调用设备 runScript 接口
@@ -242,6 +232,24 @@ async function formatOcrToolText(response, outputPath) {
         responseText,
     ].join("\n");
 }
+/**
+ * 在指定 HTTP 设备上执行 OCR 识别
+ * @param target 设备 HTTP 地址
+ * @param options OCR 参数
+ * @returns 返回 HTTP 状态码、原始结果与格式化文本
+ * @example
+ * await runOcrRecognitionOnDevice({ ip: "192.168.1.10", port: "9800" }, options)
+ */
+async function runOcrRecognitionOnDevice(target, options) {
+    const script = buildOcrScript(options.engine, options.mode, options.input, options.x, options.y, options.ex, options.ey, options.texts, options.languages, options.confidenceThreshold, options.exactMatch);
+    const response = await callRunScript(target.ip, target.port, script, options.timeoutMs);
+    const text = await formatOcrToolText(response.body, options.outputPath);
+    return {
+        status: response.status,
+        body: response.body,
+        text,
+    };
+}
 /**
  * 注册 OCR MCP 工具
  * @param server MCP 服务实例
@@ -252,7 +260,7 @@ async function formatOcrToolText(response, outputPath) {
 function registerOcrTools(server) {
     server.registerTool("ocr_recognize", {
         title: "OCR Recognize",
-        description: "通过设备 POST /api/runScript 执行快点JS OCR。支持 appleocr 与 paddleocr，默认 appleocr；OCR 没有独立 HTTP 接口时使用本工具。",
+        description: "在当前默认设备执行 OCR。支持 appleocr 与 paddleocr，默认 appleocr；返回坐标使用绝对坐标。",
         inputSchema: {
             engine: z
                 .enum(["appleocr", "paddleocr"])
@@ -291,9 +299,14 @@ function registerOcrTools(server) {
                 .optional()
                 .describe("findText 模式要查找的文本数组"),
             languages: z
-                .array(z.enum(APPLE_OCR_LANGUAGES))
+                .array(z.enum(exports.APPLE_OCR_LANGUAGES))
                 .optional()
                 .describe('Apple OCR 识别语言数组，默认由运行时使用 ["zh-Hans", "en-US"]'),
+            exactMatch: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("findText 模式是否要求整条识别文本完全匹配目标文本"),
             confidenceThreshold: z
                 .number()
                 .min(0)
@@ -301,19 +314,6 @@ function registerOcrTools(server) {
                 .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)
@@ -328,20 +328,31 @@ function registerOcrTools(server) {
                 .default(60000)
                 .describe("runScript 请求超时时间，默认 60000 毫秒"),
         },
-    }, async ({ engine, mode, input, x, y, ex, ey, texts, languages, confidenceThreshold, paddleMaxSideLen, paddleUseGpu, outputPath, timeoutMs, }) => {
+    }, async ({ engine, mode, input, x, y, ex, ey, texts, languages, exactMatch, confidenceThreshold, 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);
+        const response = await runOcrRecognitionOnDevice(target, {
+            engine,
+            mode,
+            input,
+            x,
+            y,
+            ex,
+            ey,
+            texts,
+            languages,
+            confidenceThreshold,
+            exactMatch,
+            outputPath,
+            timeoutMs,
+        });
         return (0, tool_utils_1.createTextToolResult)([
-            text,
+            response.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/runtime-tools.js

@@ -185,7 +185,7 @@ function registerRuntimeTools(server) {
     });
     server.registerTool("get_node_source", {
         title: "Get Node Source",
-        description: "获取当前默认设备页面节点 XML（/api/source），写入文件后返回路径，避免长文本响应被截断。",
+        description: "获取当前默认设备页面节点 XML，写入文件后返回路径，避免长文本响应被截断。",
         inputSchema: {
             maxDepth: z
                 .number()
@@ -203,20 +203,28 @@ function registerRuntimeTools(server) {
                 .optional()
                 .default(120)
                 .describe("设备端节点抓取超时秒数，默认 120"),
+            mode: z
+                .number()
+                .int()
+                .min(1)
+                .max(2)
+                .optional()
+                .default(1)
+                .describe("节点抓取模式：1=完整节点树，2=可见节点优化模式"),
             outputPath: z
                 .string()
                 .min(1)
                 .optional()
                 .describe("可选输出文件路径，不传则写入系统临时目录"),
         },
-    }, async ({ maxDepth, timeout, outputPath }) => {
+    }, async ({ maxDepth, timeout, mode, outputPath }) => {
         const target = await (0, tool_utils_1.resolveRuntimeHttpTarget)();
         const requestOptions = (0, tool_utils_1.createRuntimeHttpRequestOptions)(target);
-        const source = await (0, project_1.getSourceOnDevice)(requestOptions, maxDepth, timeout);
+        const source = await (0, project_1.getSourceOnDevice)(requestOptions, maxDepth, timeout, mode);
         const targetPath = resolveOutputPath(outputPath, "ms-mcp-node-source", "xml");
         await fsExtra.ensureDir(path.dirname(targetPath));
         await fsExtra.writeFile(targetPath, source, "utf8");
-        return (0, tool_utils_1.createTextToolResult)(`节点获取成功: ${target.label}\nmaxDepth: ${maxDepth}\ntimeout: ${timeout}\npath: ${targetPath}\nsize: ${Buffer.byteLength(source, "utf8")} bytes`);
+        return (0, tool_utils_1.createTextToolResult)(`节点获取成功: ${target.label}\nmaxDepth: ${maxDepth}\ntimeout: ${timeout}\nmode: ${mode}\npath: ${targetPath}\nsize: ${Buffer.byteLength(source, "utf8")} bytes`);
     });
     server.registerTool("get_logs", {
         title: "Get Device Logs",

package/dist/mcp/tool-utils.d.ts

@@ -67,8 +67,9 @@ export declare function formatRuntimeJsonText(value: unknown): string;
  * @param title 文档标题
  * @param slug 文档 slug
  * @param index 列表序号
+ * @param filePath 文档文件绝对路径
  * @returns 返回用于列表展示的文本块
  * @example
- * formatApiDocSummary("js", "Tap", "tap", 0)
+ * formatApiDocSummary("js", "Tap", "tap", 0, "/tmp/tap.md")
  */
-export declare function formatApiDocSummary(language: ApiDocsLanguage, title: string, slug: string, index: number): string;
+export declare function formatApiDocSummary(language: ApiDocsLanguage, title: string, slug: string, index: number, filePath?: string): string;

package/dist/mcp/tool-utils.js

@@ -87,10 +87,16 @@ function formatRuntimeJsonText(value) {
  * @param title 文档标题
  * @param slug 文档 slug
  * @param index 列表序号
+ * @param filePath 文档文件绝对路径
  * @returns 返回用于列表展示的文本块
  * @example
- * formatApiDocSummary("js", "Tap", "tap", 0)
+ * formatApiDocSummary("js", "Tap", "tap", 0, "/tmp/tap.md")
  */
-function formatApiDocSummary(language, title, slug, index) {
-    return `${index + 1}. ${title}\nslug: ${slug}\nuri: ${(0, docs_service_1.getDocUri)(language, slug)}`;
+function formatApiDocSummary(language, title, slug, index, filePath) {
+    return [
+        `${index + 1}. ${title}`,
+        `slug: ${slug}`,
+        `uri: ${(0, docs_service_1.getDocUri)(language, slug)}`,
+        ...(filePath ? [`path: ${filePath}`] : []),
+    ].join("\n");
 }

package/dist/mcp/tools.js

@@ -22,7 +22,6 @@ function createMcpServer() {
         name: "ms-vite-plugin-mcp",
         version: version_1.PACKAGE_VERSION,
     });
-    (0, doc_tools_1.registerDocResources)(server);
     (0, doc_tools_1.registerDocTools)(server);
     (0, httpapi_tools_1.registerHttpApiTools)(server);
     (0, image_tools_1.registerImageTools)(server);

package/dist/project.d.ts

@@ -39,11 +39,12 @@ export declare function getScreenshotBase64OnDevice(options: DeviceCliOptions):
  * @param options 命令选项（transport 仅支持 http）
  * @param maxDepth 节点最大深度，默认 50
  * @param timeout 获取节点超时秒数，默认 120
+ * @param mode 节点抓取模式，1=完整节点树，2=可见节点优化模式
  * @returns 返回 XML 字符串
  * @example
- * const xml = await getSourceOnDevice({ ip: "192.168.1.10", port: "9800" }, 50, 120)
+ * const xml = await getSourceOnDevice({ ip: "192.168.1.10", port: "9800" }, 50, 120, 1)
  */
-export declare function getSourceOnDevice(options: DeviceCliOptions, maxDepth?: number, timeout?: number): Promise<string>;
+export declare function getSourceOnDevice(options: DeviceCliOptions, maxDepth?: number, timeout?: number, mode?: number): Promise<string>;
 /**
  * 在设备上获取当前日志文件最新行
  * @param options 命令选项（仅支持 http 传输）

package/dist/project.js

@@ -428,11 +428,12 @@ async function getScreenshotBase64OnDevice(options) {
  * @param options 命令选项（transport 仅支持 http）
  * @param maxDepth 节点最大深度，默认 50
  * @param timeout 获取节点超时秒数，默认 120
+ * @param mode 节点抓取模式，1=完整节点树，2=可见节点优化模式
  * @returns 返回 XML 字符串
  * @example
- * const xml = await getSourceOnDevice({ ip: "192.168.1.10", port: "9800" }, 50, 120)
+ * const xml = await getSourceOnDevice({ ip: "192.168.1.10", port: "9800" }, 50, 120, 1)
  */
-async function getSourceOnDevice(options, maxDepth = 50, timeout = 120) {
+async function getSourceOnDevice(options, maxDepth = 50, timeout = 120, mode = 1) {
     const transport = parseTransport(options);
     if (!Number.isInteger(maxDepth) || maxDepth < 1) {
         throw new Error(`无效 maxDepth: ${maxDepth}`);
@@ -440,12 +441,16 @@ async function getSourceOnDevice(options, maxDepth = 50, timeout = 120) {
     if (!Number.isInteger(timeout) || timeout < 1) {
         throw new Error(`无效 timeout: ${timeout}`);
     }
+    if (!Number.isInteger(mode) || (mode !== 1 && mode !== 2)) {
+        throw new Error(`无效 mode: ${mode}`);
+    }
     if (transport === "ws") {
         await ensureWsReady(options);
         const result = await ws_manager_1.WSManager.request("source", {
             max_depth: maxDepth,
             timeout,
             maxDepth,
+            mode,
         });
         if (!result.success || typeof result.data !== "string") {
             throw new Error(`获取节点失败: ${String(result.message ?? "unknown")}`);
@@ -456,6 +461,7 @@ async function getSourceOnDevice(options, maxDepth = 50, timeout = 120) {
     const url = new URL(`http://${ip}:${port}/api/source`);
     url.searchParams.set("max_depth", String(maxDepth));
     url.searchParams.set("timeout", String(timeout));
+    url.searchParams.set("mode", String(mode));
     const response = await fetch(url.toString(), { method: "GET" });
     if (!response.ok) {
         throw new Error(`获取节点失败，状态码: ${response.status}`);

package/docs/AGENTS.md

@@ -36,26 +36,27 @@
 
 ## 文档优先
 
-回答快点JS API 问题或编写脚本前，必须先查询当前语言对应的快点JS文档。
+回答快点JS API 问题或编写脚本前，必须先查询目标语言对应的快点JS文档。
 
-MCP 可用时：
+MCP 入口：
 
-1. 使用 `set_docs_language` 设置语言：`js`、`js_zh` 或 `python`。
-2. 使用 `search_api_docs` 搜索相关模块或 API。
-3. 使用 `read_api_doc` 读取完整文档。
+1. 使用 `get_docs_paths` 获取本地文档路径。
+2. 使用 `search_api_docs` 搜索相关模块或 API，按需传 `language`。
+3. 使用 `read_api_doc` 读取完整文档，按需传 `language`。
 4. 只依据已确认的文档内容回答或编写代码。
 
-MCP 不可用时：
+CLI 入口：
 
-1. 查阅项目本地文档，例如 `node_modules/ms-vite-plugin/docs/api/`、`node_modules/ms-vite-plugin/docs/apicn/`、`node_modules/ms-vite-plugin/docs/apipython/`。
-2. 只使用文档中已经确认的 API。
-3. 在回复中说明使用了本地文档作为 MCP fallback。
+1. 使用 `npx ms docs paths` 获取本地文档路径。
+2. 使用 `npx ms docs search <query> --language js_zh|js|python` 搜索语言 API 文档。
+3. 使用 `npx ms docs read <slug> --language js_zh|js|python` 读取完整文档。
+4. 只使用文档中已经确认的 API。
 
 ## HTTP API 工作流
 
 调用设备 HTTP API 前，必须先查询 HTTP API 文档。不要猜测接口路径、请求方法或参数名称。
 
-MCP 可用时：
+MCP 入口：
 
 1. 使用 `search_http_api_docs` 搜索目标能力、中文标题或接口路径。
 2. 使用 `read_http_api_doc` 读取目标接口片段。
@@ -64,17 +65,19 @@ MCP 可用时：
 
 `http_api_call` 只能调用 HTTP API 文档中已声明的接口，并且会校验 `docSlug`、`method`、`path` 是否匹配。
 
-命令 fallback 时：
+CLI 入口：
 
-1. 先在本地 HTTP API 文档中确认接口存在。
-2. 再用 `curl` 调用明确存在的接口。
-3. 不要把未确认的路径当成可用接口。
+1. 使用 `npx ms docs paths` 获取 HTTP API 文档路径。
+2. 使用 `npx ms http-docs search <query>` 搜索目标接口。
+3. 使用 `npx ms http-docs read <identifier> --method GET|POST` 读取目标接口片段。
+4. 使用 `npx ms http-call -i <device-ip> --port <port> --method <method> --path <path> --doc-slug <slug>` 调用明确存在的接口。
+5. 不要把未确认的路径当成可用接口。
 
 ## 设备与运行
 
 设备相关操作以用户指定的设备为准。不要假设设备或工作区已经设置。
 
-MCP 可用时：
+MCP 入口：
 
 1. 使用 `get_device` 查看当前默认设备。
 2. 如果未设置设备，使用 `set_device` 设置设备 IP 和端口。
@@ -84,25 +87,32 @@ MCP 可用时：
 6. 使用 `stop_project` 停止当前设备上的项目。
 7. 使用 `package_project` 执行生产打包。
 
-命令可用时，可以在项目根目录使用：
+CLI 入口可以使用：
 
 ```bash
 npx ms --help
+npx ms docs paths
 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 source -i <device-ip> --port <port> --mode 1 --output <path>
+npx ms logs -i <device-ip> --port <port> --limit 200
+npx ms ocr -i <device-ip> --port <port> --engine appleocr --mode recognize
+npx ms screen-crop -i <device-ip> --port <port> --x <x> --y <y> --width <w> --height <h> --output <path>
+npx ms screen-pick-color -i <device-ip> --port <port> --x <x> --y <y>
+npx ms image-crop --image <path> --x <x> --y <y> --width <w> --height <h> --output <path>
+npx ms image-transparent --image <path> --output <path>
 npx ms stop -i <device-ip> --port <port>
 npx ms package
 ```
 
-命令必须在快点JS项目根目录运行，项目根目录通常包含 `package.json` 和 `scripts/`。不要用未确认的通用 Node.js、浏览器或 Python 命令替代 MCP 或项目自带 `ms` CLI。
+`build`、`package`、`run`、`run-ui` 需要在快点JS项目根目录运行，项目根目录通常包含 `package.json` 和 `scripts/`。文档、HTTP API 查询/调用、截图、节点、日志、OCR、图片处理、停止和 WS 状态命令可以在任意目录使用。不要用未确认的通用 Node.js、浏览器或 Python 命令替代 MCP 或项目自带 `ms` CLI。
 
 ## 工具分组
 
 ### 文档
 
-- `set_docs_language`
-- `get_docs_language`
+- `get_docs_paths`
 - `list_api_docs`
 - `search_api_docs`
 - `read_api_doc`
@@ -141,28 +151,28 @@ npx ms package
 ## 工具选择规则
 
 - 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
-- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或已确认接口的 `curl` fallback。
-- 获取截图：优先使用 `take_screenshot`；命令 fallback 可用 `npx ms screenshot`。
-- 获取节点 XML：优先使用 `get_node_source`。
-- 查看日志：优先使用 `get_logs`。
-- 从本地图片裁切找图模板：使用 `image_crop`，输出到 `res`。
-- 从当前设备截图裁切找图模板：使用 `screen_crop`，输出到 `res`。
-- 从本地图片指定坐标取色：使用 `image_pick_color`。
-- 从当前设备截图指定坐标取色：使用 `screen_pick_color`。
-- 制作透明找图模板：使用 `image_make_transparent`，输出到 `res`。
-- 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize`。
-- 运行项目：优先使用 `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`。
+- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或 `npx ms http-call`。
+- 获取截图：使用 `take_screenshot` 或 `npx ms screenshot`。
+- 获取节点 XML：使用 `get_node_source` 或 `npx ms source --mode 1`。
+- 查看日志：使用 `get_logs` 或 `npx ms logs`。
+- 从本地图片裁切找图模板：使用 `image_crop` 或 `npx ms image-crop`，输出到 `res`。
+- 从当前设备截图裁切找图模板：使用 `screen_crop` 或 `npx ms screen-crop`，输出到 `res`。
+- 从本地图片指定坐标取色：使用 `image_pick_color` 或 `npx ms image-pick-color`。
+- 从当前设备截图指定坐标取色：使用 `screen_pick_color` 或 `npx ms screen-pick-color`。
+- 制作透明找图模板：使用 `image_make_transparent` 或 `npx ms image-transparent`，输出到 `res`。
+- 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize` 或 `npx ms ocr`。
+- 运行项目：使用 `run_project`、`run_ui_project`、`npx ms run` 或 `npx ms run-ui`。
+- 停止项目：使用 `stop_project` 或 `npx ms stop`。
+- 打包项目：使用 `package_project` 或 `npx ms package`。
 
 ## OCR 规则
 
-OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScript` 执行快点JS OCR 脚本。
+OCR 识别使用 `ocr_recognize`，不要手写未确认的 OCR 调用链路。
 
 - `ocr_recognize` 支持 `appleocr` 和 `paddleocr`。
 - 默认使用 `appleocr`。
 - 数字识别优先使用 `appleocr`，因为 PaddleOCR 文档未提供独立 numbers 模式。
-- `runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
+- PaddleOCR 识别和查找方法会自动加载所需模型，不需要先手动调用 `loadV5`。
 
 ## 验证要求
 
@@ -170,7 +180,7 @@ OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScrip
 
 1. 使用 MCP `run_project` 或命令 `npx ms run -i <device-ip> --port <port>` 同步并运行项目。
 2. 使用 MCP `take_screenshot` 或命令 `npx ms screenshot ...` 获取截图。
-3. 必要时使用 `get_logs` 或日志 HTTP API 查看运行日志。
+3. 必要时使用 `get_logs` 或命令 `npx ms logs` 查看运行日志。
 4. 在回复中说明截图或日志是否确认了预期行为。
 
 UI 预览发起后不需要长时间等待结果，可以通过截图查看当前界面效果。
@@ -184,7 +194,7 @@ UI 预览发起后不需要长时间等待结果，可以通过截图查看当
 - 不要混用 JavaScript 与 Python API。
 - 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
 - 不要对快点JS Python 脚本运行 `py_compile` 或其他 CPython 编译校验。
-- 不要在没有查询 HTTP API 文档的情况下调用 `http_api_call` 或 `curl`。
+- 不要在没有查询 HTTP API 文档的情况下调用 `http_api_call` 或 `ms http-call`。
 - 不要把完整 URL 传给 `http_api_call.path`，只能传 `/api/...`、`/logger/...`、`/mirror/...` 这类相对路径。
 - 不要调用 HTTP API 文档中未声明的接口。
 - 不要用 `http_api_call` 替代截图落文件、节点 XML 落文件、日志缓存、项目打包和项目运行等专用工具。