ms-vite-plugin 1.4.14 → 1.4.16

package/docs/api/paddleocr.md

@@ -4,11 +4,11 @@ PaddleOCR 模块基于百度飞桨 PaddleOCR 技术，提供强大的光学字
 
 ## 功能概览
 
-- **模型管理**: PP-OCRv5 模型加载和资源管理
+- **自动加载**: 识别和查找方法会自动加载所需模型，无需先手动加载
 - **多源识别**: 支持屏幕截图、图片文件、URL 等多种输入源
 - **区域识别**: 支持指定区域的精确文字识别
 - **结构化结果**: 提供详细的文本位置、置信度和方向信息
-- **资源控制**: 完整的模型生命周期管理
+- **资源释放**: 可在需要时释放 OCR 资源
 
 ## 数据类型
 
@@ -61,7 +61,9 @@ interface OCRResult {
 
 ### 模型管理
 
-#### loadV5 - 初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
+#### loadV5 - 可选预加载 PP-OCRv5 模型。
+
+识别和查找方法会自动加载所需模型，通常不需要先调用 `loadV5`。只有需要提前加载或指定模型参数时才调用。
 
 ```typescript
 function loadV5(maxSideLen?: number, useGpu?: boolean): boolean;
@@ -69,29 +71,17 @@ function loadV5(maxSideLen?: number, useGpu?: boolean): boolean;
 
 **参数:**
 
-| 参数名       | 类型    | 是否必填 | 默认值 | 描述                                |
-| ------------ | ------- | -------- | ------ | ----------------------------------- |
-| `maxSideLen` | number  | 否       | 640    | 输入图像的最大边长，默认值为 640    |
-| `useGpu`     | boolean | 否       | false  | 是否启用 GPU 加速                   |
+| 参数名       | 类型    | 是否必填 | 默认值 | 描述                             |
+| ------------ | ------- | -------- | ------ | -------------------------------- |
+| `maxSideLen` | number  | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+| `useGpu`     | boolean | 否       | false  | 是否启用 GPU 加速                |
 
 **返回值:**
 
-| 类型    | 描述                                       |
-| ------- | ------------------------------------------ |
+| 类型    | 描述                                                |
+| ------- | --------------------------------------------------- |
 | boolean | 加载成功或模型已加载返回 `true`，否则返回 `false` |
 
-重复调用 `loadV5` 时，如果模型已经加载，会直接返回 `true`，不会重新加载或应用新的参数。需要更换加载参数时，先调用 `free()` 释放模型。
-
-**示例:**
-
-```javascript
-// 使用默认参数加载模型
-const loaded = paddleOcr.loadV5();
-if (loaded) {
-  logi("PP-OCRv5 模型加载成功");
-}
-```
-
 ### 文字识别
 
 #### recognize - 执行 OCR 文字识别，支持多种输入源和指定识别区域。
@@ -127,12 +117,6 @@ function recognize(
 **示例:**
 
 ```javascript
-// 首先加载模型
-if (!paddleOcr.loadV5()) {
-  logi("模型加载失败");
-  return;
-}
-
 // 识别整个屏幕
 const fullScreenResults = paddleOcr.recognize("screen", 0, 0, 0, 0);
 logi(`识别到 ${fullScreenResults.length} 个文本区域`);
@@ -227,12 +211,6 @@ function findText(
 **示例:**
 
 ```javascript
-// 首先加载模型
-if (!paddleOcr.loadV5()) {
-  logi("模型加载失败");
-  return;
-}
-
 // 在整个屏幕中查找目标文本
 const hitResults = paddleOcr.findText(
   "screen",

package/docs/apicn/paddleocr.md

@@ -4,11 +4,11 @@ PaddleOCR 模块基于百度飞桨 PaddleOCR 技术，提供强大的光学字
 
 ## 功能概览
 
-- **模型管理**: PP-OCRv5 模型加载和资源管理
+- **自动加载**: 识别和查找方法会自动加载所需模型，无需先手动加载
 - **多源识别**: 支持屏幕截图、图片文件、URL 等多种输入源
 - **区域识别**: 支持指定区域的精确文字识别
 - **结构化结果**: 提供详细的文本位置、置信度和方向信息
-- **资源控制**: 完整的模型生命周期管理
+- **资源释放**: 可在需要时释放 OCR 资源
 
 ## 数据类型
 
@@ -61,7 +61,9 @@ interface OCR识别结果 {
 
 ### 模型管理
 
-#### 加载 V5 模型 - 初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
+#### 加载 V5 模型 - 可选预加载 PP-OCRv5 模型。
+
+识别和查找方法会自动加载所需模型，通常不需要先调用 `加载V5模型`。只有需要提前加载或指定模型参数时才调用。
 
 ```typescript
 function 加载V5模型(最大边长?: 数字, useGpu?: 布尔值): 布尔值;
@@ -80,18 +82,6 @@ function 加载V5模型(最大边长?: 数字, useGpu?: 布尔值): 布尔值;
 | ------ | --------------------------------------------------- |
 | 布尔值 | 加载成功或模型已加载返回 `true`，否则返回 `false` |
 
-重复调用 `加载V5模型` 时，如果模型已经加载，会直接返回 `true`，不会重新加载或应用新的参数。需要更换加载参数时，先调用 `释放资源()` 释放模型。
-
-**示例:**
-
-```javascript
-// 使用默认参数加载模型
-const 是否加载成功 = $PaddleOCR.加载V5模型();
-if (是否加载成功) {
-  $打印信息日志("PP-OCRv5 模型加载成功");
-}
-```
-
 ### 文字识别
 
 #### 识别 - 执行 OCR 文字识别，支持多种输入源和指定识别区域。
@@ -127,13 +117,6 @@ function 识别(
 **示例:**
 
 ```javascript
-// 首先加载模型
-const 是否加载成功 = $PaddleOCR.加载V5模型();
-if (!是否加载成功) {
-  $打印错误日志("模型加载失败");
-  return;
-}
-
 // 识别整个屏幕
 const fullScreenResults = $PaddleOCR.识别("screen", 0, 0, 0, 0);
 $打印信息日志(`识别到 ${fullScreenResults.length} 个文本区域`);
@@ -228,13 +211,6 @@ function 查找文本(
 **示例:**
 
 ```javascript
-// 首先加载模型
-const 是否加载成功 = $PaddleOCR.加载V5模型();
-if (!是否加载成功) {
-  $打印错误日志("模型加载失败");
-  return;
-}
-
 // 在整个屏幕中查找目标文本
 const 命中结果 = $PaddleOCR.查找文本(
   "screen",

package/docs/apipython/paddleocr.md

@@ -4,11 +4,11 @@ PaddleOCR 模块基于百度飞桨 PaddleOCR 技术，提供强大的光学字
 
 ## 功能概览
 
-- **模型管理**: PP-OCRv5 模型加载和资源管理
+- **自动加载**: 识别和查找方法会自动加载所需模型，无需先手动加载
 - **多源识别**: 支持屏幕截图、图片文件、URL 等多种输入源
 - **区域识别**: 支持指定区域的精确文字识别
 - **结构化结果**: 提供详细的文本位置、置信度和方向信息
-- **资源控制**: 完整的模型生命周期管理
+- **资源释放**: 可在需要时释放 OCR 资源
 
 ## 类型定义
 
@@ -38,9 +38,9 @@ class OCRResult(TypedDict):
 
 ### 模型管理
 
-#### `loadV5` - 初始化 PP-OCRv5 模型
+#### `loadV5` - 可选预加载 PP-OCRv5 模型
 
-初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
+识别和查找方法会自动加载所需模型，通常不需要先调用 `loadV5`。只有需要提前加载或指定模型参数时才调用。
 
 ```python
 def loadV5(maxSideLen: int = 640, useGpu: bool = False) -> bool
@@ -59,19 +59,6 @@ def loadV5(maxSideLen: int = 640, useGpu: bool = False) -> bool
 | ------ | --------------------------------------------------- |
 | `bool` | 加载成功或模型已加载返回 `True`，否则返回 `False` |
 
-重复调用 `loadV5` 时，如果模型已经加载，会直接返回 `True`，不会重新加载或应用新的参数。需要更换加载参数时，先调用 `free()` 释放模型。
-
-**示例：**
-
-```python
-from kuaijs import paddleocr
-
-# 使用默认参数加载模型
-loaded = paddleocr.loadV5()
-if loaded:
-    print("PP-OCRv5 模型加载成功")
-```
-
 ### 文字识别
 
 #### `recognize` - 执行 OCR 文字识别
@@ -111,30 +98,26 @@ def recognize(
 ```python
 from kuaijs import paddleocr
 
-# 首先加载模型
-if not paddleocr.loadV5():
-    print("模型加载失败")
-else:
-    # 识别整个屏幕
-    full_screen_results = paddleocr.recognize("screen", 0, 0, 0, 0)
-    print(f"识别到 {len(full_screen_results)} 个文本区域")
-    for r in full_screen_results:
-        print(f"文本: {r.text}, 置信度: {r.confidence}")
-
-    # 识别屏幕指定区域
-    region_results = paddleocr.recognize("screen", 100, 100, 500, 300)
-    if region_results:
-        top = region_results[0]
-        print(f"指定区域文本: {top.text}, 中心: ({top.centerX}, {top.centerY})")
-
-    # 识别图片文件
-    image_results = paddleocr.recognize("/path/to/image.png", 0, 0, 800, 600)
-    for r in image_results:
-        print(f"图片文字: {r.text}")
-
-    # 识别网络图片
-    url_results = paddleocr.recognize("https://example.com/image.jpg", 0, 0, 1000, 800)
-    print(f"网络图片识别结果数量: {len(url_results)}")
+# 识别整个屏幕
+full_screen_results = paddleocr.recognize("screen", 0, 0, 0, 0)
+print(f"识别到 {len(full_screen_results)} 个文本区域")
+for r in full_screen_results:
+    print(f"文本: {r.text}, 置信度: {r.confidence}")
+
+# 识别屏幕指定区域
+region_results = paddleocr.recognize("screen", 100, 100, 500, 300)
+if region_results:
+    top = region_results[0]
+    print(f"指定区域文本: {top.text}, 中心: ({top.centerX}, {top.centerY})")
+
+# 识别图片文件
+image_results = paddleocr.recognize("/path/to/image.png", 0, 0, 800, 600)
+for r in image_results:
+    print(f"图片文字: {r.text}")
+
+# 识别网络图片
+url_results = paddleocr.recognize("https://example.com/image.jpg", 0, 0, 1000, 800)
+print(f"网络图片识别结果数量: {len(url_results)}")
 ```
 
 #### `recognizeAbs` - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标
@@ -201,21 +184,17 @@ def findText(
 ```python
 from kuaijs import paddleocr
 
-# 首先加载模型
-if not paddleocr.loadV5():
-    print("模型加载失败")
+# 在整个屏幕中查找目标文本
+hit_results = paddleocr.findText("screen", ["登录", "确定"], 0, 0, 0, 0, 0.6, False)
+if hit_results:
+    for i, r in enumerate(hit_results, 1):
+        print(f"命中{i}: {r.text}, 中心点=({r.centerX}, {r.centerY}), 置信度={r.confidence}")
 else:
-    # 在整个屏幕中查找目标文本
-    hit_results = paddleocr.findText("screen", ["登录", "确定"], 0, 0, 0, 0, 0.6, False)
-    if hit_results:
-        for i, r in enumerate(hit_results, 1):
-            print(f"命中{i}: {r.text}, 中心点=({r.centerX}, {r.centerY}), 置信度={r.confidence}")
-    else:
-        print("未命中目标文本")
-
-    # 在指定区域查找目标文本
-    region_hits = paddleocr.findText("screen", ["下一步"], 100, 100, 500, 400)
-    print(f"区域命中数量: {len(region_hits)}")
+    print("未命中目标文本")
+
+# 在指定区域查找目标文本
+region_hits = paddleocr.findText("screen", ["下一步"], 100, 100, 500, 400)
+print(f"区域命中数量: {len(region_hits)}")
 ```
 
 #### `findTextAbs` - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标

package/docs/mcp-agent-description.md

@@ -28,32 +28,41 @@ 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>
 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。
 
 ## 文档优先
 
-回答或写代码前，优先查询当前语言对应的快点JS文档。
+回答或写代码前，优先查询目标语言对应的快点JS文档。
 
 语言 API 文档工具：
 
-- `set_docs_language`
-- `get_docs_language`
+- `get_docs_paths`
 - `list_api_docs`
 - `search_api_docs`
 - `read_api_doc`
@@ -63,27 +72,28 @@ HTTP API 文档工具：
 - `search_http_api_docs`
 - `read_http_api_doc`
 
-MCP 可用时，按以下流程使用语言 API：
+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 不可用时，可以查阅项目本地文档作为 fallback，例如：
+CLI 入口：
 
-- `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/`
+- `npx ms docs paths`
+- `npx ms docs search <query> --language js_zh|js|python`
+- `npx ms docs read <slug> --language js_zh|js|python`
+- `npx ms http-docs search <query>`
+- `npx ms http-docs read <identifier> --method GET|POST`
 
-使用本地文档 fallback 时，要在回复中说明依据来自本地文档。
+使用本地文档路径或 CLI 查询时，要在回复中说明依据来自本地文档。
 
 ## HTTP API 工作流
 
 调用设备 HTTP API 前，必须先查询 HTTP API 文档中的对应接口说明。不要猜测接口路径、请求方法或参数名称。
 
-MCP 可用时：
+MCP 入口：
 
 1. 使用 `search_http_api_docs` 搜索目标能力、中文标题或接口路径。
 2. 使用 `read_http_api_doc` 读取目标接口片段。
@@ -107,11 +117,13 @@ 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. 不要把未确认的路径当成可用接口。
 
 ## 项目目录职责
 
@@ -137,8 +149,7 @@ MCP 可用时：
 
 - 使用 `get_device` 查看当前默认设备。
 - 使用 `set_device` 设置设备 IP 和端口。
-- 设备设置后会自动启动日志 SSE 后台订阅。
-- 使用 `get_logs` 查看日志缓存快照。
+- 使用 `get_logs` 查看当前日志最新行。
 
 UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot` 查看当前界面效果。
 
@@ -146,8 +157,7 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 
 ### 文档
 
-- `set_docs_language`
-- `get_docs_language`
+- `get_docs_paths`
 - `list_api_docs`
 - `search_api_docs`
 - `read_api_doc`
@@ -181,27 +191,27 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 
 - `http_api_call`
 
-控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 不再作为大量独立 MCP 工具暴露。MCP 可用时必须通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；命令 fallback 时可以用已确认文档的 `curl` 调用。
+控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 不再作为大量独立 MCP 工具暴露。MCP 入口使用 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call`；CLI 入口使用 `ms http-docs` 和 `ms http-call`。
 
 ## 工具选择规则
 
 - 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
-- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或已确认接口的 `curl` fallback。
-- 获取截图：优先使用 `take_screenshot`；命令 fallback 可用 `npx ms screenshot`。
-- 从本地图片裁切找图模板：使用 `image_crop`，输出到 `res`。
-- 从当前设备截图裁切找图模板：使用 `screen_crop`，输出到 `res`。
-- 从本地图片指定坐标取色：使用 `image_pick_color`。
-- 从当前设备截图指定坐标取色：使用 `screen_pick_color`。
-- 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize`；支持用户指定 `appleocr` 或 `paddleocr`，默认 `appleocr`。
-- OCR 没有独立 HTTP 接口，通过 `POST /api/runScript` 执行快点JS OCR 脚本；`runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
-- 制作透明找图模板：使用 `image_make_transparent`，输出到 `res`。
-- 获取节点 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 运行时能力。
+- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或 `npx ms http-call`。
+- 获取截图：使用 `take_screenshot` 或 `npx ms screenshot`。
+- 从本地图片裁切找图模板：使用 `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`。
+- 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize` 或 `npx ms ocr`。
+- OCR 识别支持 `appleocr` 和 `paddleocr`，默认 `appleocr`，识别结果坐标可直接用于点击。
+- 制作透明找图模板：使用 `image_make_transparent` 或 `npx ms image-transparent`，输出到 `res`。
+- 获取节点 XML：使用 `get_node_source` 或 `npx ms source --mode 1`。
+- 查看日志：使用 `get_logs` 或 `npx ms logs`。
+- 运行项目：使用 `run_project`、`run_ui_project`、`npx ms run` 或 `npx ms run-ui`。
+- 停止项目：使用 `stop_project` 或 `npx ms stop`。
+- 打包项目：使用 `package_project` 或 `npx ms package`。
+
+对设备操作使用 MCP 工具或项目自带 `ms` CLI；不要改写成未确认的通用构建命令，也不要假设存在浏览器、Node.js 或通用 Python 运行时能力。
 
 ## 验证要求
 
@@ -221,7 +231,7 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 - 不要混用 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.14",
+  "version": "1.4.16",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {