ms-vite-plugin 1.4.14 → 1.4.16

package/dist/project.js

@@ -39,7 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getScreenshotOnDevice = getScreenshotOnDevice;
 exports.getScreenshotBase64OnDevice = getScreenshotBase64OnDevice;
 exports.getSourceOnDevice = getSourceOnDevice;
-exports.watchDeviceLogsBySse = watchDeviceLogsBySse;
+exports.getCurrentLogLinesOnDevice = getCurrentLogLinesOnDevice;
 exports.runOnDevice = runOnDevice;
 exports.runUIOnDevice = runUIOnDevice;
 exports.stopOnDevice = stopOnDevice;
@@ -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}`);
@@ -463,196 +469,40 @@ async function getSourceOnDevice(options, maxDepth = 50, timeout = 120) {
     return response.text();
 }
 /**
- * 将 SSE 文本块解析为事件字段结构
- * @param rawBlock 单个 SSE 事件文本块（以空行分隔）
- * @returns 返回事件名与数据字符串
- * @example
- * parseSseEventBlock("event: log\ndata: {\"level\":\"info\"}")
- */
-function parseSseEventBlock(rawBlock) {
-    const lines = rawBlock.split(/\r?\n/);
-    let eventName = "message";
-    const dataLines = [];
-    for (const line of lines) {
-        if (!line || line.startsWith(":")) {
-            continue;
-        }
-        if (line.startsWith("event:")) {
-            eventName = line.slice("event:".length).trim() || "message";
-            continue;
-        }
-        if (line.startsWith("data:")) {
-            dataLines.push(line.slice("data:".length).trimStart());
-        }
-    }
-    return {
-        event: eventName,
-        data: dataLines.join("\n"),
-    };
-}
-/**
- * 将原始日志对象标准化为 DeviceLogEntry
- * @param payload 日志原始对象
- * @returns 返回标准化日志对象
- * @example
- * normalizeLogEntry({ level: "info", message: "ok", timestamp: "2026-01-01T00:00:00Z" })
- */
-function normalizeLogEntry(payload) {
-    const levelText = String(payload.level ?? "info").toLowerCase();
-    const messageText = String(payload.message ?? "");
-    const timestampText = typeof payload.timestamp === "string" && payload.timestamp
-        ? payload.timestamp
-        : new Date().toISOString();
-    return {
-        level: levelText,
-        message: messageText,
-        timestamp: timestampText,
-    };
-}
-/**
- * 监听设备 SSE 日志并返回原始结果
- * @param ip 设备 IP 地址
- * @param port 设备端口
- * @param durationMs 监听时长（毫秒），默认 15000；传 0 表示不设超时，持续监听
- * @param maxLogs 最多收集日志条数，默认 200
- * @param stopOnRuntimeStopped 若为 true，则在运行状态从 true 回落到 false 后结束监听
- * @param stopOnRuntimeContinuous 若为 true，则在确认持续运行态后结束监听（用于 single 模式快速返回）
- * @returns 返回日志与运行状态
+ * 在设备上获取当前日志文件最新行
+ * @param options 命令选项（仅支持 http 传输）
+ * @param count 需要读取的最新日志行数，默认 200，最大 5000
+ * @returns 返回最新日志行和是否还有更早日志
  * @example
- * const result = await watchDeviceLogsBySse("192.168.1.10", 9800, 30000, 300, true, true)
+ * const result = await getCurrentLogLinesOnDevice({ ip: "192.168.1.10", port: "9800" }, 200)
  */
-async function watchDeviceLogsBySse(ip, port, durationMs = 15000, maxLogs = 200, stopOnRuntimeStopped = false, stopOnRuntimeContinuous = false) {
-    if (!ip.trim()) {
-        throw new Error("监听日志失败: 设备 IP 不能为空");
+async function getCurrentLogLinesOnDevice(options, count = 200) {
+    const transport = parseTransport(options);
+    if (transport !== "http") {
+        throw new Error("获取日志失败: 当前日志行接口仅支持 http 传输");
     }
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error(`监听日志失败: 无效端口 ${port}`);
-    }
-    if (!Number.isInteger(durationMs) || durationMs < 0) {
-        throw new Error(`监听日志失败: 无效 durationMs ${durationMs}`);
-    }
-    if (!Number.isInteger(maxLogs) || maxLogs < 1) {
-        throw new Error(`监听日志失败: 无效 maxLogs ${maxLogs}`);
-    }
-    const url = `http://${ip}:${port}/logger/sse`;
-    const logs = [];
-    const runtimeStatus = [];
-    const controller = new AbortController();
-    let stopReason = "unknown";
-    let seenRunningStatus = false;
-    let runningStatusCount = 0;
-    let shouldStopReading = false;
-    const timeoutHandle = durationMs > 0
-        ? setTimeout(() => {
-            stopReason = "timeout";
-            controller.abort();
-        }, durationMs)
-        : undefined;
-    try {
-        const response = await fetch(url, {
-            method: "GET",
-            signal: controller.signal,
-            headers: {
-                Accept: "text/event-stream",
-            },
-        });
-        if (!response.ok || !response.body) {
-            throw new Error(`监听日志失败: ${response.status} ${response.statusText || "unknown"}`);
-        }
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder("utf-8");
-        let buffer = "";
-        while (true) {
-            if (shouldStopReading) {
-                break;
-            }
-            const { value, done } = await reader.read();
-            if (done) {
-                if (stopReason === "unknown") {
-                    stopReason = "stream_closed";
-                }
-                break;
-            }
-            buffer += decoder.decode(value, { stream: true });
-            // SSE 事件以双换行分隔，这里逐块解析，避免半包解析错误
-            let splitIndex = buffer.search(/\r?\n\r?\n/);
-            while (splitIndex >= 0) {
-                const rawBlock = buffer.slice(0, splitIndex);
-                buffer = buffer.slice(splitIndex + (buffer[splitIndex] === "\r" ? 4 : 2));
-                const event = parseSseEventBlock(rawBlock);
-                if (event.data) {
-                    try {
-                        const parsed = JSON.parse(event.data);
-                        if (event.event === "log") {
-                            // 日志缓冲使用环形窗口，持续监听时不会无限增长
-                            if (logs.length >= maxLogs) {
-                                logs.shift();
-                            }
-                            logs.push(normalizeLogEntry(parsed));
-                        }
-                        else if (event.event === "runtime_status") {
-                            if (runtimeStatus.length >= maxLogs) {
-                                runtimeStatus.shift();
-                            }
-                            runtimeStatus.push({
-                                raw: parsed,
-                                timestamp: new Date().toISOString(),
-                            });
-                            if (parsed.isRunning === true) {
-                                seenRunningStatus = true;
-                                runningStatusCount += 1;
-                                // 连续收到运行态，视为长期任务，single 模式可立即返回并转持续监听
-                                if (stopOnRuntimeContinuous && runningStatusCount >= 2) {
-                                    stopReason = "runtime_continuous";
-                                    controller.abort();
-                                    shouldStopReading = true;
-                                    break;
-                                }
-                            }
-                            else if (parsed.isRunning === false) {
-                                runningStatusCount = 0;
-                            }
-                            if (stopOnRuntimeStopped &&
-                                seenRunningStatus &&
-                                parsed.isRunning === false) {
-                                stopReason = "runtime_stopped";
-                                controller.abort();
-                                shouldStopReading = true;
-                                break;
-                            }
-                        }
-                    }
-                    catch {
-                        // 兼容非 JSON 数据：不抛错，继续监听后续事件
-                    }
-                }
-                splitIndex = buffer.search(/\r?\n\r?\n/);
-            }
-            if (shouldStopReading) {
-                break;
-            }
-        }
+    if (!Number.isInteger(count) || count < 1 || count > 5000) {
+        throw new Error(`获取日志失败: 无效 count ${count}`);
     }
-    catch (error) {
-        // 监听超时是预期行为，忽略 AbortError 并正常输出已采集日志
-        if (!(error instanceof Error &&
-            (error.name === "AbortError" ||
-                error.message === "The operation was aborted."))) {
-            throw error;
-        }
-        if (stopReason === "unknown") {
-            stopReason = "manual_abort";
-        }
+    const { ip, port } = parseHttpOptions(options);
+    const url = new URL(`http://${ip}:${port}/logger/current/lines`);
+    url.searchParams.set("count", String(count));
+    const response = await fetch(url.toString(), { method: "GET" });
+    if (response.status === 404) {
+        return {
+            lines: [],
+            hasMore: false,
+        };
     }
-    finally {
-        if (timeoutHandle) {
-            clearTimeout(timeoutHandle);
-        }
+    if (!response.ok) {
+        throw new Error(`获取日志失败，状态码: ${response.status}`);
     }
+    const payload = (await response.json());
     return {
-        logs,
-        runtimeStatus,
-        stopReason,
+        lines: Array.isArray(payload.lines)
+            ? payload.lines.map((line) => String(line))
+            : [],
+        hasMore: payload.hasMore === true,
     };
 }
 /**

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 落文件、日志缓存、项目打包和项目运行等专用工具。

package/docs/SKILL.md

@@ -33,22 +33,32 @@ MCP 工具和项目命令都可以使用。
 
 可以使用命令的情况：
 
-- MCP transport 断开或不可用。
 - 用户明确要求使用命令。
 - 需要快速验证项目本地 `ms` CLI 能力。
-- 使用项目自带 KuaiJS CLI 进行同步、运行、停止、截图。
+- 使用项目自带 KuaiJS CLI 查询文档、调用已确认的 HTTP API、同步、运行、停止、截图、抓节点、查日志和 OCR。
 
 允许的常用命令示例：
 
 ```bash
 npx ms --help
+npx ms docs paths
+npx ms docs search <query> --language js_zh
+npx ms http-docs search <query>
+npx ms http-call -i <device-ip> --port <port> --method GET --path <path> --doc-slug <slug>
 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>
 ```
 
-使用 `curl` 调用设备 HTTP API 前，必须先通过 MCP HTTP API 文档或本地 HTTP API 文档确认接口存在、方法、路径、参数位置和返回结构。
+使用 `ms http-call` 调用设备 HTTP API 前，必须先通过 MCP HTTP API 文档或 `ms http-docs` 确认接口存在、方法、路径、参数位置和返回结构。
 
 ## 目录职责
 
@@ -74,58 +84,66 @@ npx ms stop -i <device-ip> --port <port>
 
 回答快点JS API 或编写脚本前，先确认语言并查询对应语言文档。
 
-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/apipython/`、`node_modules/ms-vite-plugin/docs/httpapi/`。
-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` 读取目标接口片段。
 3. 确认 `method`、`path`、参数位置、参数类型和返回结构。
 4. 使用 `http_api_call` 调用接口，并传入文档返回的 `docSlug`。
 
-命令 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 和端口。
-3. 设置设备后，日志 SSE 后台订阅会自动启动。
-4. 使用 `get_logs` 获取日志缓存快照。
+3. 使用 `get_logs` 获取当前日志最新行。
 
-命令 fallback 时：
+CLI 入口：
 
 - 用 `npx ms run -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>` 获取节点 XML。
+- 用 `npx ms logs -i <device-ip> --port <port> --limit 200` 查看当前日志。
+- 用 `npx ms ocr -i <device-ip> --port <port> --engine appleocr --mode recognize` 执行 OCR。
+- 用 `npx ms screen-crop` 或 `npx ms image-crop` 裁切找图模板。
+- 用 `npx ms screen-pick-color` 或 `npx ms image-pick-color` 获取颜色。
+- 用 `npx ms image-transparent` 制作透明找图模板。
 - 用 `npx ms stop -i <device-ip> --port <port>` 停止项目。
 
 UI 预览发起后不需要长时间等待结果，可以用截图查看当前界面效果。
 
 ## 项目运行工作流
 
-MCP 可用时：
+MCP 入口：
 
 1. 使用 `set_workspace` 设置快点JS项目根目录。
 2. 使用 `get_workspace` 确认当前工作区。
@@ -134,20 +152,19 @@ MCP 可用时：
 5. 使用 `stop_project` 停止当前设备上的项目。
 6. 使用 `package_project` 执行生产打包。
 
-命令可用时：
+CLI 入口：
 
-1. 使用项目根目录执行 `npx ms --help` 确认 CLI。
+1. 使用 `npx ms --help` 确认 CLI。
 2. 使用 `npx ms run -i <device-ip> --port <port>` 同步并运行。
 3. 使用 `npx ms screenshot ...` 验证界面。
 
-工作区必须包含 `package.json` 和 `scripts/`。
+`build`、`package`、`run`、`run-ui` 需要在快点JS项目根目录运行，项目根目录必须包含 `package.json` 和 `scripts/`。文档、HTTP API 查询/调用、截图、节点、日志、OCR、图片处理、停止和 WS 状态命令可以在任意目录使用。
 
 ## 工具分组
 
 ### 文档
 
-- `set_docs_language`
-- `get_docs_language`
+- `get_docs_paths`
 - `list_api_docs`
 - `search_api_docs`
 - `read_api_doc`
@@ -181,9 +198,9 @@ MCP 可用时：
 
 - `http_api_call`
 
-控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；命令 fallback 时可用已确认文档的 `curl` 调用。
+控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；CLI 入口使用 `ms http-docs` 和 `ms http-call`。
 
-OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScript` 执行快点JS OCR 脚本。`ocr_recognize` 支持 `appleocr` 和 `paddleocr`，默认 `appleocr`。`runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
+使用 `ocr_recognize` 执行 OCR 识别。`ocr_recognize` 支持 `appleocr` 和 `paddleocr`，默认 `appleocr`，识别结果坐标可直接用于点击。
 
 图片与识别工作流：
 
@@ -204,4 +221,4 @@ OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScrip
 
 ## 文档入口
 
-优先通过 MCP 文档工具查询 API 文档。MCP 不可用时，可以查阅项目本地 `node_modules/ms-vite-plugin/docs/` 文档作为 fallback，并在说明中明确这一点。
+优先直接读取项目本地 `node_modules/ms-vite-plugin/docs/` 文档；也可以使用 MCP 文档工具或 `ms docs` / `ms http-docs` 定位具体文档。