ms-vite-plugin 1.4.10 → 1.4.12

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/pip.md

@@ -1,12 +1,14 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
+悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
 
 ## 功能特性
 
-- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **显示模式**：支持日志、保活和自定义三种显示模式
+- **关闭控制**：支持主动关闭悬浮窗
 - **状态查询**：判断悬浮窗是否正在显示
-- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
+- **尺寸设置**：日志模式和自定义模式支持设置内容宽高，并按模式分别持久化
+- **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
 
 ## API 方法
 
@@ -39,7 +41,7 @@ if (isActive) {
 function switchToLogMode(): boolean;
 ```
 
-切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
 
 **返回值：**
 
@@ -60,7 +62,7 @@ const success = pip.switchToLogMode();
 function switchToKeepAliveMode(): boolean;
 ```
 
-切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
 
 **返回值：**
 
@@ -75,13 +77,13 @@ takeMeToFront();
 const success = pip.switchToKeepAliveMode();
 ```
 
-### switchToOffMode - 切换到关闭模式
+### switchToCustomMode - 切换到自定义模式
 
 ```typescript
-function switchToOffMode(): boolean;
+function switchToCustomMode(): boolean;
 ```
 
-切换到关闭模式并关闭悬浮窗。
+切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
 
 **返回值：**
 
@@ -92,22 +94,195 @@ function switchToOffMode(): boolean;
 **示例：**
 
 ```typescript
-const success = pip.switchToOffMode();
+takeMeToFront();
+pip.switchToCustomMode();
+pip.setCustomText("运行中\n进度 1/3");
+pip.setCustomTextColor("#34c759");
+pip.setCustomTextSize(18);
+```
+
+### closeWindow - 关闭悬浮窗
+
+```typescript
+function closeWindow(): boolean;
+```
+
+关闭悬浮窗。
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
+
+**示例：**
+
+```typescript
+const success = pip.closeWindow();
+```
+
+### setContentSize - 设置内容尺寸
+
+```typescript
+function setContentSize(width: number, height: number): boolean;
+```
+
+设置日志模式或自定义模式的悬浮窗内容尺寸。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+
+**参数：**
+
+| 参数     | 类型             | 必填 | 描述                                           |
+| -------- | ---------------- | ---- | ---------------------------------------------- |
+| `width`  | `number` | 是   | 目标内容宽度 |
+| `height` | `number` | 是   | 目标内容高度 |
+
+**返回值：**
+
+| 类型      | 描述                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `boolean` | `true` 代表尺寸已提交；`false` 代表当前模式不允许设置或宽高无效 |
+
+**示例：**
+
+```typescript
+pip.switchToLogMode();
+pip.setContentSize(280, 120);
+
+pip.switchToCustomMode();
+pip.setContentSize(120, 180);
+```
+
+### setCustomText - 设置自定义文本
+
+```typescript
+function setCustomText(text: string): boolean;
+```
+
+设置自定义模式显示的纯文本内容。该方法只更新自定义文本数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数   | 类型     | 必填 | 描述                                        |
+| ------ | -------- | ---- | ------------------------------------------- |
+| `text` | `string` | 是   | 要显示的文本，支持真实换行和字符串中的 `\n` |
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表文本已提交 |
+
+**示例：**
+
+```typescript
+pip.setCustomText("运行中\n进度 1/3");
+pip.switchToCustomMode();
+```
+
+### setCustomTextColor - 设置自定义文字颜色
+
+```typescript
+function setCustomTextColor(color: string): boolean;
+```
+
+设置自定义模式显示文本的文字颜色。该方法只更新文字颜色数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数    | 类型     | 必填 | 描述                                                        |
+| ------- | -------- | ---- | ----------------------------------------------------------- |
+| `color` | `string` | 是   | 文字颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用白色 |
+
+**返回值：**
+
+| 类型      | 描述                       |
+| --------- | -------------------------- |
+| `boolean` | `true` 代表文字颜色已提交 |
+
+**示例：**
+
+```typescript
+pip.setCustomTextColor("#34c759");
+pip.switchToCustomMode();
+```
+
+### setCustomTextSize - 设置自定义文字大小
+
+```typescript
+function setCustomTextSize(fontSize: number): boolean;
+```
+
+设置自定义模式显示文本的文字大小。该方法只更新文字大小数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数       | 类型     | 必填 | 描述                       |
+| ---------- | -------- | ---- | -------------------------- |
+| `fontSize` | `number` | 是   | 文字字号，必须是有效数字 |
+
+**返回值：**
+
+| 类型      | 描述                                                   |
+| --------- | ------------------------------------------------------ |
+| `boolean` | `true` 代表文字大小已提交；`false` 代表字号无效 |
+
+**示例：**
+
+```typescript
+pip.setCustomTextSize(18);
+pip.switchToCustomMode();
+```
+
+### setCustomBackgroundColor - 设置自定义背景色
+
+```typescript
+function setCustomBackgroundColor(color: string): boolean;
+```
+
+设置自定义模式显示区域的背景色。该方法只更新背景色数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数    | 类型     | 必填 | 描述                                                        |
+| ------- | -------- | ---- | ----------------------------------------------------------- |
+| `color` | `string` | 是   | 背景颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用黑色 |
+
+**返回值：**
+
+| 类型      | 描述                     |
+| --------- | ------------------------ |
+| `boolean` | `true` 代表背景色已提交 |
+
+**示例：**
+
+```typescript
+pip.setCustomBackgroundColor("#111111");
+pip.switchToCustomMode();
 ```
 
 ## 完整使用示例
 
 ```typescript
 takeMeToFront();
+
 pip.switchToLogMode();
+pip.setContentSize(280, 120);
+
+pip.setCustomText("任务运行中\n1/3");
+pip.setCustomTextColor("#34c759");
+pip.setCustomTextSize(18);
+pip.setCustomBackgroundColor("#111111");
+pip.switchToCustomMode();
+pip.setContentSize(120, 180);
 ```
 
 ## 注意事项
 
-1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
+1. **前台限制**：首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
 3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
-4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
+4. **尺寸持久化**：日志模式和自定义模式分别保存尺寸，互不共用；保活模式不接受脚本尺寸
+5. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
 
 ## 故障排除
 
@@ -116,3 +291,8 @@ pip.switchToLogMode();
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
 - 确认应用当前在前台
+
+### setContentSize 返回 false
+
+- 确认当前模式是日志模式或自定义模式
+- 确认宽度和高度都传入了有效数字

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 - 释放指定模型的资源。