ms-vite-plugin 1.4.10 → 1.4.11

package/docs/api/appleocr.md

@@ -131,6 +131,32 @@ const screenResults = appleOcr.recognize("screen", 0, 0, 1920, 1080);
 logi(`屏幕识别结果: ${JSON.stringify(screenResults)}`);
 ```
 
+#### recognizeAbs
+
+执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `recognize` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function recognizeAbs(
+  input: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  languages?: string[],
+): OCRResult[];
+```
+
+**示例:**
+
+```javascript
+const absResults = appleOcr.recognizeAbs("screen", 100, 100, 500, 300);
+if (absResults.length > 0) {
+  action.click(absResults[0].centerX, absResults[0].centerY);
+}
+```
+
 ### 数字识别
 
 #### recognizeNumbers
@@ -179,6 +205,31 @@ numberResults.forEach((result, index) => {
 });
 ```
 
+#### recognizeNumbersAbs
+
+执行数字 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `recognizeNumbers` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function recognizeNumbersAbs(
+  input: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+): OCRResult[];
+```
+
+**示例:**
+
+```javascript
+const absNumberResults = appleOcr.recognizeNumbersAbs("screen", 100, 100, 500, 300);
+if (absNumberResults.length > 0) {
+  action.click(absNumberResults[0].centerX, absNumberResults[0].centerY);
+}
+```
+
 ### 文本查找
 
 #### findText
@@ -227,3 +278,30 @@ textResults.forEach((result, index) => {
   logi(`中心点: (${result.centerX}, ${result.centerY})`);
 });
 ```
+
+#### findTextAbs
+
+查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `findText` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function findTextAbs(
+  input: string,
+  texts: string[],
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  languages?: string[],
+): OCRResult[];
+```
+
+**示例:**
+
+```javascript
+const absHits = appleOcr.findTextAbs("screen", ["确定"], 100, 100, 500, 400);
+if (absHits.length > 0) {
+  action.click(absHits[0].centerX, absHits[0].centerY);
+}
+```

package/docs/api/global.md

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

package/docs/api/node.md

@@ -20,6 +20,7 @@
 ```typescript
 function createNodeSelector(params?: {
   maxDepth?: number; // 最大层级深度，默认 50
+  mode?: number; // 抓取模式：模式 1、模式 2，默认模式 1
 }): NodeSelector;
 ```
 
@@ -28,6 +29,7 @@ function createNodeSelector(params?: {
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述                        |
 | ---------- | ------ | -------- | ------ | --------------------------- |
 | `maxDepth` | number | 否       | 50     | 遍历的最大层级深度，默认 50 |
+| `mode` | number | 否       | 1      | 抓取模式。模式 1、模式 2，默认模式 1 |
 
 **返回值：**
 
@@ -41,6 +43,7 @@ function createNodeSelector(params?: {
 // 创建选择器
 const selector = createNodeSelector({
   maxDepth: 20, // 最大20层深度
+  mode: 1, // 默认模式 1
 });
 ```
 

package/docs/api/paddleocr.md

@@ -64,20 +64,23 @@ interface OCRResult {
 #### loadV5 - 初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
 
 ```typescript
-function loadV5(maxSideLen?: number): boolean;
+function loadV5(maxSideLen?: number, useGpu?: boolean): boolean;
 ```
 
 **参数:**
 
-| 参数名       | 类型   | 是否必填 | 默认值 | 描述                             |
-| ------------ | ------ | -------- | ------ | -------------------------------- |
-| `maxSideLen` | number | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+| 参数名       | 类型    | 是否必填 | 默认值 | 描述                                |
+| ------------ | ------- | -------- | ------ | ----------------------------------- |
+| `maxSideLen` | number  | 否       | 640    | 输入图像的最大边长，默认值为 640    |
+| `useGpu`     | boolean | 否       | false  | 是否启用 GPU 加速                   |
 
 **返回值:**
 
-| 类型    | 描述             |
-| ------- | ---------------- |
-| boolean | 是否成功加载模型 |
+| 类型    | 描述                                       |
+| ------- | ------------------------------------------ |
+| boolean | 加载成功或模型已加载返回 `true`，否则返回 `false` |
+
+重复调用 `loadV5` 时，如果模型已经加载，会直接返回 `true`，不会重新加载或应用新的参数。需要更换加载参数时，先调用 `free()` 释放模型。
 
 **示例:**
 
@@ -119,7 +122,7 @@ function recognize(
 
 | 类型          | 描述                                                                              |
 | ------------- | --------------------------------------------------------------------------------- |
-| `OCRResult[]` | 识别结果数组，每个元素为 OCRResult 对象，包含文本内容、位置信息和置信度等详细数据 |
+| `OCRResult[]` | 识别结果数组，坐标相对于裁剪区域 |
 
 **示例:**
 
@@ -137,7 +140,7 @@ fullScreenResults.forEach((result, index) => {
   logi(`文本 ${index + 1}: ${JSON.stringify(result)}`);
 });
 
-// 识别屏幕指定区域
+// 识别屏幕指定区域（返回相对裁剪区域的坐标）
 const regionResults = paddleOcr.recognize("screen", 100, 100, 500, 300);
 logi(`指定区域识别结果: ${JSON.stringify(regionResults)}`);
 
@@ -163,6 +166,30 @@ const urlResults = paddleOcr.recognize(
 logi(`网络图片识别结果: ${JSON.stringify(urlResults)}`);
 ```
 
+#### recognizeAbs - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `recognize` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function recognizeAbs(
+  input: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  confidenceThreshold?: number,
+): OCRResult[];
+```
+
+**示例:**
+
+```javascript
+const absResults = paddleOcr.recognizeAbs("screen", 100, 100, 500, 300);
+if (absResults.length > 0) {
+  action.click(absResults[0].centerX, absResults[0].centerY);
+}
+```
+
 #### findText - 在识别结果中查找目标文本并返回对应子串坐标。
 
 ```typescript
@@ -193,7 +220,7 @@ function findText(
 
 | 类型          | 描述                                                                                                        |
 | ------------- | ----------------------------------------------------------------------------------------------------------- |
-| `OCRResult[]` | 匹配结果数组。每个元素为命中的文本片段坐标信息，`text` 字段为命中的目标文本，其他字段包含位置和置信度等信息 |
+| `OCRResult[]` | 匹配结果数组，坐标相对于裁剪区域 |
 
 **示例:**
 
@@ -224,11 +251,36 @@ if (hitResults.length > 0) {
   logi("未命中目标文本");
 }
 
-// 在指定区域查找目标文本
+// 在指定区域查找目标文本（返回相对裁剪区域的坐标）
 const regionHits = paddleOcr.findText("screen", ["下一步"], 100, 100, 500, 400);
 logi(`区域命中数量: ${regionHits.length}`);
 ```
 
+#### findTextAbs - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+参数与 `findText` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```typescript
+function findTextAbs(
+  input: string,
+  targetTexts: string[],
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  confidenceThreshold?: number,
+): OCRResult[];
+```
+
+**示例:**
+
+```javascript
+const absHits = paddleOcr.findTextAbs("screen", ["确定"], 100, 100, 500, 400, 0.6);
+if (absHits.length > 0) {
+  action.click(absHits[0].centerX, absHits[0].centerY);
+}
+```
+
 ### 资源管理
 
 #### free - 释放 OCR 模型占用的内存资源。

package/docs/api/yolo.md

@@ -67,19 +67,21 @@ interface YoloResult {
 function load(
   paramPath: string,
   binPath: string,
-  nc: number,
-  version?: number
+  nc?: number,
+  version?: number,
+  useGpu?: boolean
 ): string | null;
 ```
 
 **参数:**
 
-| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                        |
-| ----------- | ------ | -------- | ------ | ------------------------------------------- |
-| `paramPath` | string | 是       |        | NCNN 模型的 param 文件绝对路径              |
-| `binPath`   | string | 是       |        | NCNN 模型的 bin 文件绝对路径                |
-| `nc`        | number | 是       |        | 模型的标签数量，可在标签集 data.yaml 中查看 |
-| `version`   | number | 否       | 11     | YOLO 模型版本号（仅支持 8/11/26）           |
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                        |
+| ----------- | ------- | -------- | ------ | ------------------------------------------- |
+| `paramPath` | string  | 是       |        | NCNN 模型的 param 文件绝对路径              |
+| `binPath`   | string  | 是       |        | NCNN 模型的 bin 文件绝对路径                |
+| `nc`        | number  | 否       | 0      | 模型的标签数量；传 `0` 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空数组 |
+| `version`   | number  | 否       | 11     | YOLO 模型版本号（仅支持 8/11/26）           |
+| `useGpu`    | boolean | 否       | false  | 是否启用 GPU 加速                           |
 
 **返回值:**
 
@@ -94,24 +96,26 @@ function load(
 const modelId = yolo.load(
   "yolov8n_ncnn_model/model.ncnn.param",
   "yolov8n_ncnn_model/model.ncnn.bin",
-  80,
-  8
+  0,
+  8,
+  false
 );
 ```
 
 #### loadV11 - 加载 YOLOv11 模型（兼容 yolov8 模型），这是使用目标检测功能的前提。
 
 ```typescript
-function loadV11(paramPath: string, binPath: string, nc: number): string | null;
+function loadV11(paramPath: string, binPath: string, nc?: number, useGpu?: boolean): string | null;
 ```
 
 **参数:**
 
-| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                        |
-| ----------- | ------ | -------- | ------ | ------------------------------------------- |
-| `paramPath` | string | 是       |        | NCNN 模型的 param 文件绝对路径              |
-| `binPath`   | string | 是       |        | NCNN 模型的 bin 文件绝对路径                |
-| `nc`        | number | 是       |        | 模型的标签数量，可在标签集 data.yaml 中查看 |
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                        |
+| ----------- | ------- | -------- | ------ | ------------------------------------------- |
+| `paramPath` | string  | 是       |        | NCNN 模型的 param 文件绝对路径              |
+| `binPath`   | string  | 是       |        | NCNN 模型的 bin 文件绝对路径                |
+| `nc`        | number  | 否       | 0      | 模型的标签数量；传 `0` 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空数组 |
+| `useGpu`    | boolean | 否       | false  | 是否启用 GPU 加速                           |
 
 **返回值:**
 
@@ -127,7 +131,8 @@ function loadV11(paramPath: string, binPath: string, nc: number): string | null;
 const modelId = yolo.loadV11(
   "yolo11n_ncnn_model/model.ncnn.param",
   "yolo11n_ncnn_model/model.ncnn.bin",
-  80 // COCO 数据集有 80 个类别
+  0, // 自动根据模型输出推断类别数量
+  false
 );
 
 if (modelId) {
@@ -175,7 +180,7 @@ function detect(
 const modelId = yolo.loadV11(
   "/yolo11n_ncnn_model/model.ncnn.param",
   "/yolo11n_ncnn_model/model.ncnn.bin",
-  80
+  0
 );
 
 if (!modelId) {
@@ -261,6 +266,41 @@ const fastResults = yolo.detect(
 logi(`快速检测结果: ${fastResults.length} 个物体`);
 ```
 
+#### detectAbs - 对指定区域执行目标检测，并将结果坐标映射为原图/全屏绝对坐标。
+
+```typescript
+function detectAbs(
+  modelId: string,
+  img: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  targetSize?: number,
+  threshold?: number,
+  nmsThreshold?: number
+): YoloResult[];
+```
+
+**示例:**
+
+```javascript
+const absResults = yolo.detectAbs(
+  modelId,
+  "screen",
+  100,
+  100,
+  500,
+  400,
+  640,
+  0.4,
+  0.5
+);
+if (absResults.length > 0) {
+  action.click(absResults[0].centerX, absResults[0].centerY);
+}
+```
+
 ### 资源管理
 
 #### free - 释放指定模型的资源。

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 和概率。