ms-vite-plugin 1.4.10 → 1.4.12

package/docs/api/yolocls.md

@@ -0,0 +1,272 @@
+# YOLO 图像分类模块 (YoloCls)
+
+YOLO 图像分类模块基于 YOLOv8-cls / YOLO11-cls / YOLO26-cls 分类模型和 NCNN 框架，提供整图分类、区域分类和模型资源管理能力。
+
+## 功能概览
+
+- **模型管理**: 加载和释放 YOLOv8-cls / YOLO11-cls / YOLO26-cls NCNN 模型
+- **图像分类**: 对屏幕截图、图片文件、HTTP 图片或图片 ID 执行整图分类
+- **区域分类**: 先裁剪指定区域，再对裁剪结果执行分类
+- **结果处理**: 返回 Ultralytics `Probs` 风格的完整概率、top1、top5 和对应置信度
+- **资源控制**: 支持释放单个模型或释放全部已加载模型
+
+## 适用场景
+
+- 判断当前屏幕或图片属于哪个业务类别
+- 对截图中的固定区域进行状态识别
+- 对自定义 YOLO-cls 模型导出的 NCNN 模型执行端侧推理
+
+## 数据结构
+
+### YoloClsProbs
+
+YOLO 分类概率结果，字段命名与 Ultralytics `Probs` 保持一致。
+
+```typescript
+interface YoloClsProbs {
+  data: number[]; // 所有类别概率，下标即类别 ID
+  top1: number | null; // 概率最高的类别 ID
+  top5: number[]; // 概率最高的 5 个类别 ID
+  top1conf: number | null; // top1 对应的概率
+  top5conf: number[]; // top5 对应的概率
+}
+```
+
+**字段说明:**
+
+| 字段名     | 类型             | 描述                                                       |
+| ---------- | ---------------- | ---------------------------------------------------------- |
+| `data`     | `number[]`       | 所有类别概率数组，下标即类别 ID                            |
+| `top1`     | `number \| null` | 概率最高的类别 ID；分类失败时为 `null`                     |
+| `top5`     | `number[]`       | 概率最高的 5 个类别 ID，按概率从高到低排序                 |
+| `top1conf` | `number \| null` | `top1` 对应的概率；分类失败时为 `null`                     |
+| `top5conf` | `number[]`       | `top5` 对应的概率，顺序与 `top5` 一致                      |
+
+**结果说明:**
+
+- `top1` 等于 `top5[0]`，`top1conf` 等于 `data[top1]`。
+- 当模型类别数少于 5 时，`top5` 和 `top5conf` 的长度会小于 5。
+- 分类失败时返回空结果：`data`、`top5`、`top5conf` 为空数组，`top1` 和 `top1conf` 为 `null`。
+
+## API 参考
+
+### 模型管理
+
+#### load - 加载 YOLO 分类模型（支持 YOLOv8-cls / YOLO11-cls / YOLO26-cls）
+
+加载模型是使用图像分类能力的前提。支持 Ultralytics 官方 YOLOv8-cls、YOLO11-cls、YOLO26-cls 导出的 NCNN 分类模型，常见模型名使用 `-cls` 后缀，例如 `yolov8n-cls`、`yolo11n-cls`、`yolo26n-cls`。
+
+```typescript
+function load(
+  paramPath: string,
+  binPath: string,
+  nc?: number,
+  useGpu?: boolean
+): string | null;
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                               |
+| ----------- | ------- | -------- | ------ | -------------------------------------------------- |
+| `paramPath` | string  | 是       |        | NCNN 模型的 param 文件路径                         |
+| `binPath`   | string  | 是       |        | NCNN 模型的 bin 文件路径                           |
+| `nc`        | number  | 否       | 0      | 模型类别数量；传 `0` 或省略时按模型输出自动推断，显式传入但不匹配时分类返回空结果 |
+| `useGpu`    | boolean | 否       | false  | 是否使用 GPU 推理                                  |
+
+**返回值:**
+
+| 类型             | 描述                                      |
+| ---------------- | ----------------------------------------- |
+| `string \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+
+**示例:**
+
+```javascript
+// 模型文件通常放在 res 目录
+const modelId = yoloCls.load(
+  "yolo11n_cls_ncnn_model/model.ncnn.param",
+  "yolo11n_cls_ncnn_model/model.ncnn.bin",
+  1000, // ImageNet 分类模型通常为 1000 类
+  false
+);
+
+if (modelId) {
+  logi(`YOLO 分类模型加载成功，ID: ${modelId}`);
+} else {
+  logi("YOLO 分类模型加载失败，请检查模型文件路径和格式");
+}
+```
+
+### 图像分类
+
+#### classify - 对输入图像执行分类
+
+对整张输入图像执行分类，返回完整概率数组和 top1/top5 结果。
+
+```typescript
+function classify(
+  modelId: string,
+  img: string,
+  targetSize?: number
+): YoloClsProbs;
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelId`    | string | 是       |        | 模型 ID（通过 `load` 获取）                                                                                                                  |
+| `img`        | string | 是       |        | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `string` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `targetSize` | number | 否       | 224    | 分类输入大小，应与模型训练或导出时的输入尺寸一致                                                                                             |
+
+**返回值:**
+
+| 类型           | 描述                                                |
+| -------------- | --------------------------------------------------- |
+| `YoloClsProbs` | Ultralytics `Probs` 风格分类结果，包含 top1/top5 等 |
+
+**示例:**
+
+```javascript
+const modelId = yoloCls.load(
+  "yolo11n_cls_ncnn_model/model.ncnn.param",
+  "yolo11n_cls_ncnn_model/model.ncnn.bin",
+  1000,
+  false
+);
+
+if (!modelId) {
+  logi("模型加载失败");
+  return;
+}
+
+const probs = yoloCls.classify(
+  modelId,
+  "screen", // 使用当前屏幕
+  224 // 分类模型常用输入尺寸
+);
+
+if (probs.top1 !== null) {
+  logi(`top1 类别ID: ${probs.top1}`);
+  logi(`top1 置信度: ${(probs.top1conf * 100).toFixed(2)}%`);
+} else {
+  logi("分类失败或无有效结果");
+}
+
+for (let i = 0; i < probs.top5.length; i++) {
+  logi(
+    `top${i + 1}: 类别ID=${probs.top5[i]}, 置信度=${probs.top5conf[i].toFixed(4)}`
+  );
+}
+
+// 如需读取某个类别的原始概率，可直接访问 data[classId]
+const classId = 0;
+if (probs.data.length > classId) {
+  logi(`类别 ${classId} 概率: ${probs.data[classId].toFixed(4)}`);
+}
+
+yoloCls.free(modelId);
+```
+
+#### classifyRegion - 对指定区域执行分类
+
+先从输入图像中裁剪指定区域，再对裁剪结果执行分类。适合只关心屏幕某个固定区域状态的场景。
+
+```typescript
+function classifyRegion(
+  modelId: string,
+  img: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  targetSize?: number
+): YoloClsProbs;
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelId`    | string | 是       |        | 模型 ID（通过 `load` 获取）                                                                                                                  |
+| `img`        | string | 是       |        | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `string` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `x`          | number | 否       | 0      | 裁剪区域左上角 x 坐标                                                                                                                        |
+| `y`          | number | 否       | 0      | 裁剪区域左上角 y 坐标                                                                                                                        |
+| `ex`         | number | 否       | 0      | 裁剪区域右下角 x 坐标                                                                                                                        |
+| `ey`         | number | 否       | 0      | 裁剪区域右下角 y 坐标                                                                                                                        |
+| `targetSize` | number | 否       | 224    | 分类输入大小，应与模型训练或导出时的输入尺寸一致                                                                                             |
+
+**返回值:**
+
+| 类型           | 描述                                                |
+| -------------- | --------------------------------------------------- |
+| `YoloClsProbs` | Ultralytics `Probs` 风格分类结果，包含 top1/top5 等 |
+
+**示例:**
+
+```javascript
+const regionProbs = yoloCls.classifyRegion(
+  modelId,
+  "screen",
+  100,
+  100,
+  500,
+  400,
+  224
+);
+
+if (regionProbs.top1 !== null) {
+  logi(
+    `区域分类 top1=${regionProbs.top1}, 置信度=${regionProbs.top1conf.toFixed(4)}`
+  );
+}
+```
+
+### 资源管理
+
+#### free - 释放指定模型资源
+
+释放指定分类模型占用的资源。
+
+```typescript
+function free(modelId: string): void;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述            |
+| --------- | ------ | -------- | ------ | --------------- |
+| `modelId` | string | 是       |        | 要释放的模型 ID |
+
+**示例:**
+
+```javascript
+if (modelId) {
+  yoloCls.free(modelId);
+  logi(`YOLO 分类模型 ${modelId} 资源已释放`);
+}
+```
+
+#### freeAll - 释放所有模型资源
+
+释放所有已加载的 YOLO 分类模型资源。
+
+```typescript
+function freeAll(): void;
+```
+
+**示例:**
+
+```javascript
+yoloCls.freeAll();
+logi("所有 YOLO 分类模型资源已释放");
+```
+
+## 使用注意事项
+
+- `targetSize` 默认值为 224，常见 YOLO-cls 模型使用该尺寸；自定义模型请填写训练或导出时使用的输入尺寸。
+- `nc` 传 `0` 或省略时会根据模型输出自动推断类别数量；显式传入但和模型输出不匹配时返回空结果。
+- `classifyRegion` 中 `x/y/ex/ey` 全部为 `0` 时表示不裁剪，直接对整张图分类。
+- 裁剪区域必须位于图像范围内，并且 `ex > x`、`ey > y`。
+- 分类结果中的类别 ID 需要结合训练时的类别列表解释；本模块只返回类别 ID 和概率。

package/docs/apicn/appleocr.md

@@ -131,6 +131,32 @@ const 屏幕识别结果 = $苹果OCR.识别("screen", 0, 0, 1920, 1080);
 logi(`屏幕识别结果: ${JSON.stringify(屏幕识别结果)}`);
 ```
 
+#### 识别绝对坐标
+
+执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `识别` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function 识别绝对坐标(
+  输入源: 字符串,
+  图片边界框左上角x坐标?: 数字,
+  图片边界框左上角y坐标?: 数字,
+  图片边界框右下角x坐标?: 数字,
+  图片边界框右下角y坐标?: 数字,
+  识别语言数组?: 数组<字符串>,
+): 数组<OCR识别结果>;
+```
+
+**示例:**
+
+```javascript
+const 绝对坐标结果 = $苹果OCR.识别绝对坐标("screen", 100, 100, 500, 300);
+if (绝对坐标结果.length > 0) {
+  $点击(绝对坐标结果[0].centerX, 绝对坐标结果[0].centerY);
+}
+```
+
 ### 数字识别
 
 #### 识别数字
@@ -179,6 +205,31 @@ $打印信息日志(`识别到 ${数字识别结果.length} 个数字区域`);
 });
 ```
 
+#### 识别数字绝对坐标
+
+执行数字 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `识别数字` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function 识别数字绝对坐标(
+  输入源: 字符串,
+  图片边界框左上角x坐标?: 数字,
+  图片边界框左上角y坐标?: 数字,
+  图片边界框右下角x坐标?: 数字,
+  图片边界框右下角y坐标?: 数字,
+): 数组<OCR识别结果>;
+```
+
+**示例:**
+
+```javascript
+const 绝对坐标数字结果 = $苹果OCR.识别数字绝对坐标("screen", 100, 100, 500, 300);
+if (绝对坐标数字结果.length > 0) {
+  $点击(绝对坐标数字结果[0].centerX, 绝对坐标数字结果[0].centerY);
+}
+```
+
 ### 文本查找
 
 #### 查找文本
@@ -231,3 +282,30 @@ $打印信息日志(`识别到 ${文本识别结果.length} 个文本区域`);
   $打印信息日志(`中心点: (${result.centerX}, ${result.centerY})`);
 });
 ```
+
+#### 查找文本绝对坐标
+
+查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `查找文本` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function 查找文本绝对坐标(
+  输入源: 字符串,
+  要查找的文本数组: 数组<字符串>,
+  图片边界框左上角x坐标?: 数字,
+  图片边界框左上角y坐标?: 数字,
+  图片边界框右下角x坐标?: 数字,
+  图片边界框右下角y坐标?: 数字,
+  识别语言数组?: 数组<字符串>,
+): 数组<OCR识别结果>;
+```
+
+**示例:**
+
+```javascript
+const 绝对坐标命中 = $苹果OCR.查找文本绝对坐标("screen", ["确定"], 100, 100, 500, 400);
+if (绝对坐标命中.length > 0) {
+  $点击(绝对坐标命中[0].centerX, 绝对坐标命中[0].centerY);
+}
+```

package/docs/apicn/global.md

@@ -392,6 +392,55 @@ if ($获取CPU自动限流()) {
 }
 ```
 
+### $设置CPU限流延迟
+
+设置 CPU 限流单次 sleep 延迟范围（毫秒）。默认 `minMs=3`、`maxMs=30`。仅在 CPU 自动限流开启且触发限流时生效。
+
+```typescript
+declare function $设置CPU限流延迟(最小毫秒: 数字, 最大毫秒: 数字): { minMs: 数字; maxMs: 数字 };
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                     |
+| ---------- | ------ | -------- | ------ | ---------------------------------------- |
+| `最小毫秒` | `数字` | 是       | -      | 最低延迟（毫秒）                         |
+| `最大毫秒` | `数字` | 是       | -      | 最高延迟（毫秒）；小于最小毫秒时自动对齐 |
+
+**返回值:**
+
+| 类型                        | 描述               |
+| --------------------------- | ------------------ |
+| `{ minMs: 数字; maxMs: 数字 }` | 实际生效的延迟范围 |
+
+**示例:**
+
+```javascript
+const 延迟 = $设置CPU限流延迟(3, 30);
+$打印信息日志(`CPU 限流延迟: ${延迟.minMs}~${延迟.maxMs}ms`);
+```
+
+### $获取CPU限流延迟
+
+获取 CPU 限流延迟范围（毫秒）。
+
+```typescript
+declare function $获取CPU限流延迟(): { minMs: 数字; maxMs: 数字 };
+```
+
+**返回值:**
+
+| 类型                        | 描述               |
+| --------------------------- | ------------------ |
+| `{ minMs: 数字; maxMs: 数字 }` | 当前最低与最高延迟 |
+
+**示例:**
+
+```javascript
+const 延迟 = $获取CPU限流延迟();
+$打印信息日志(`CPU 限流延迟: ${延迟.minMs}~${延迟.maxMs}ms`);
+```
+
 ### $设置停止回调
 
 设置停止回调函数（仅主线程调用）。

package/docs/apicn/node.md

@@ -23,6 +23,10 @@ function $创建节点选择器(params?: {
    * 代表要获取节点的层级，越少速度越快，默认 50
    */
   maxDepth?: 数字;
+  /**
+   * 抓取模式：模式 1、模式 2，默认模式 1
+   */
+  mode?: 数字;
 }): $节点选择器;
 ```
 
@@ -31,6 +35,7 @@ function $创建节点选择器(params?: {
 | 参数名     | 类型 | 是否必填 | 默认值 | 描述                        |
 | ---------- | ---- | -------- | ------ | --------------------------- |
 | `maxDepth` | 数字 | 否       | 50     | 遍历的最大层级深度，默认 50 |
+| `mode` | 数字 | 否       | 1      | 抓取模式。模式 1、模式 2，默认模式 1 |
 
 **返回值：**
 
@@ -44,6 +49,7 @@ function $创建节点选择器(params?: {
 // 创建选择器
 const selector = $创建节点选择器({
   maxDepth: 20, // 最大20层深度
+  mode: 1, // 默认模式 1
 });
 ```
 

package/docs/apicn/paddleocr.md

@@ -64,20 +64,23 @@ interface OCR识别结果 {
 #### 加载 V5 模型 - 初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
 
 ```typescript
-function 加载V5模型(最大边长?: 数字): 布尔值;
+function 加载V5模型(最大边长?: 数字, useGpu?: 布尔值): 布尔值;
 ```
 
 **参数:**
 
-| 参数名     | 类型 | 是否必填 | 默认值 | 描述                             |
-| ---------- | ---- | -------- | ------ | -------------------------------- |
-| `最大边长` | 数字 | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                             |
+| ---------- | ------ | -------- | ------ | -------------------------------- |
+| `最大边长` | 数字   | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+| `useGpu`   | 布尔值 | 否       | false  | 是否启用 GPU 加速                |
 
 **返回值:**
 
-| 类型   | 描述             |
-| ------ | ---------------- |
-| 布尔值 | 是否成功加载模型 |
+| 类型   | 描述                                                |
+| ------ | --------------------------------------------------- |
+| 布尔值 | 加载成功或模型已加载返回 `true`，否则返回 `false` |
+
+重复调用 `加载V5模型` 时，如果模型已经加载，会直接返回 `true`，不会重新加载或应用新的参数。需要更换加载参数时，先调用 `释放资源()` 释放模型。
 
 **示例:**
 
@@ -164,6 +167,30 @@ const urlResults = $PaddleOCR.识别(
 $打印信息日志(`网络图片识别结果: ${JSON.stringify(urlResults)}`);
 ```
 
+#### 识别绝对坐标 - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `识别` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function 识别绝对坐标(
+  输入源: 字符串,
+  图片边界框左上角x坐标?: 数字,
+  图片边界框左上角y坐标?: 数字,
+  图片边界框右下角x坐标?: 数字,
+  图片边界框右下角y坐标?: 数字,
+  置信度阈值?: 数字,
+): 数组<OCR识别结果>;
+```
+
+**示例:**
+
+```javascript
+const 绝对坐标结果 = $PaddleOCR.识别绝对坐标("screen", 100, 100, 500, 300);
+if (绝对坐标结果.length > 0) {
+  $动作.点击(绝对坐标结果[0].centerX, 绝对坐标结果[0].centerY);
+}
+```
+
 #### 查找文本 - 在识别结果中查找目标文本并返回对应子串坐标。
 
 ```typescript
@@ -238,6 +265,31 @@ const 区域命中结果 = $PaddleOCR.查找文本(
 $打印信息日志(`区域命中数量: ${区域命中结果.length}`);
 ```
 
+#### 查找文本绝对坐标 - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `查找文本` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function 查找文本绝对坐标(
+  输入源: 字符串,
+  目标文本数组: 数组<字符串>,
+  图片边界框左上角x坐标?: 数字,
+  图片边界框左上角y坐标?: 数字,
+  图片边界框右下角x坐标?: 数字,
+  图片边界框右下角y坐标?: 数字,
+  置信度阈值?: 数字,
+): 数组<OCR识别结果>;
+```
+
+**示例:**
+
+```javascript
+const 绝对坐标命中 = $PaddleOCR.查找文本绝对坐标("screen", ["确定"], 100, 100, 500, 400, 0.6);
+if (绝对坐标命中.length > 0) {
+  $动作.点击(绝对坐标命中[0].centerX, 绝对坐标命中[0].centerY);
+}
+```
+
 ### 资源管理
 
 #### 释放资源 - 释放 OCR 模型占用的内存资源。