ms-vite-plugin 1.4.10 → 1.4.12

package/docs/apipython/appleocr.md

@@ -125,6 +125,31 @@ chinese_results = appleocr.recognize("screen", 0, 0, 1920, 1080, ["zh-Hans", "en
 print(f"中英文识别结果: {chinese_results}")
 ```
 
+#### `recognizeAbs` - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标
+
+参数与 `recognize` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```python
+def recognizeAbs(
+    input: str,
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    languages: Optional[List[str]] = None
+) -> List[OCRResult]
+```
+
+**示例:**
+
+```python
+from kuaijs import appleocr, action
+
+abs_results = appleocr.recognizeAbs("screen", 100, 100, 500, 300)
+if abs_results:
+    action.click(abs_results[0]["centerX"], abs_results[0]["centerY"])
+```
+
 ### 数字识别
 
 #### recognizeNumbers
@@ -174,6 +199,30 @@ for i, result in enumerate(number_results):
     print(f"位置: ({result.centerX}, {result.centerY})")
 ```
 
+#### `recognizeNumbersAbs` - 执行数字 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标
+
+参数与 `recognizeNumbers` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```python
+def recognizeNumbersAbs(
+    input: str,
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0
+) -> List[OCRResult]
+```
+
+**示例:**
+
+```python
+from kuaijs import appleocr, action
+
+abs_number_results = appleocr.recognizeNumbersAbs("screen", 100, 100, 500, 300)
+if abs_number_results:
+    action.click(abs_number_results[0]["centerX"], abs_number_results[0]["centerY"])
+```
+
 ### 文本查找
 
 #### findText
@@ -224,3 +273,29 @@ for i, result in enumerate(text_results):
     print(f"位置: ({result.x}, {result.y}) - ({result.ex}, {result.ey})")
     print(f"中心点: ({result.centerX}, {result.centerY})")
 ```
+
+#### `findTextAbs` - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标
+
+参数与 `findText` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```python
+def findTextAbs(
+    input: str,
+    texts: List[str],
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    languages: Optional[List[str]] = None
+) -> List[OCRResult]
+```
+
+**示例:**
+
+```python
+from kuaijs import appleocr, action
+
+abs_hits = appleocr.findTextAbs("screen", ["确定"], 100, 100, 500, 400)
+if abs_hits:
+    action.click(abs_hits[0]["centerX"], abs_hits[0]["centerY"])
+```

package/docs/apipython/g.md

@@ -153,6 +153,59 @@ if g.getCpuAutoThrottle():
     print("CPU 自动限流已开启")
 ```
 
+#### `setCpuThrottleDelay` - 设置 CPU 限流延迟
+
+设置 CPU 限流单次 sleep 延迟范围（毫秒）。默认 `min_ms=3`、`max_ms=30`。仅在 CPU 自动限流开启且触发限流时生效。
+
+```python
+def setCpuThrottleDelay(min_ms: int, max_ms: int) -> dict
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 默认值 | 描述                               |
+| --------- | ----- | -------- | ------ | ---------------------------------- |
+| `min_ms`  | `int` | 是       | -      | 最低延迟（毫秒）                   |
+| `max_ms`  | `int` | 是       | -      | 最高延迟（毫秒）；小于 min_ms 时自动对齐 |
+
+**返回值:**
+
+| 类型   | 描述               |
+| ------ | ------------------ |
+| `dict` | `{"minMs": int, "maxMs": int}`，实际生效的延迟范围 |
+
+**示例:**
+
+```python
+from kuaijs import g
+
+delay = g.setCpuThrottleDelay(3, 30)
+print(f"CPU 限流延迟: {delay['minMs']}~{delay['maxMs']}ms")
+```
+
+#### `getCpuThrottleDelay` - 获取 CPU 限流延迟
+
+获取 CPU 限流延迟范围（毫秒）。
+
+```python
+def getCpuThrottleDelay() -> dict
+```
+
+**返回值:**
+
+| 类型   | 描述               |
+| ------ | ------------------ |
+| `dict` | `{"minMs": int, "maxMs": int}`，当前最低与最高延迟 |
+
+**示例:**
+
+```python
+from kuaijs import g
+
+delay = g.getCpuThrottleDelay()
+print(f"CPU 限流延迟: {delay['minMs']}~{delay['maxMs']}ms")
+```
+
 #### `restartScript` - 重启脚本
 
 ```python

package/docs/apipython/node.md

@@ -46,6 +46,7 @@ class NodeInfo:
 
 class NodeSelectorOptions(TypedDict, total=False):
     maxDepth: int  # 最大层级深度，默认 50
+    mode: int  # 抓取模式：模式 1、模式 2，默认模式 1
 ```
 
 ## 节点选择器 (NodeSelector)
@@ -67,6 +68,7 @@ def createNodeSelector(params: Optional[NodeSelectorOptions] = None) -> NodeSele
 | 参数名     | 类型 | 是否必填 | 默认值 | 描述                  |
 | ---------- | ---- | -------- | ------ | --------------------- |
 | `maxDepth` | int  | 否       | 50     | 最大层级深度，默认 50 |
+| `mode` | int  | 否       | 1      | 抓取模式。模式 1、模式 2，默认模式 1 |
 
 **返回值：** `NodeSelector`
 
@@ -77,7 +79,8 @@ from kuaijs import node
 
 # 创建选择器
 selector = node.createNodeSelector({
-    "maxDepth": 20  # 最大20层深度
+    "maxDepth": 20,  # 最大20层深度
+    "mode": 1  # 默认模式 1
 })
 ```
 

package/docs/apipython/overview.md

@@ -5,7 +5,7 @@
 - 导入方式：
 
 ```python
-from kuaijs import action, hid, image, appleocr, paddleocr, yolo, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
+from kuaijs import action, hid, image, appleocr, paddleocr, yolo, yolocls, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
 ```
 
 ## 下载资源

package/docs/apipython/paddleocr.md

@@ -43,7 +43,7 @@ class OCRResult(TypedDict):
 初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
 
 ```python
-def loadV5(maxSideLen: int = 640) -> bool
+def loadV5(maxSideLen: int = 640, useGpu: bool = False) -> bool
 ```
 
 **参数：**
@@ -51,12 +51,15 @@ def loadV5(maxSideLen: int = 640) -> bool
 | 参数名       | 类型 | 是否必填 | 默认值 | 描述                             |
 | ------------ | ---- | -------- | ------ | -------------------------------- |
 | `maxSideLen` | int  | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+| `useGpu`     | bool | 否       | False  | 是否启用 GPU 加速                |
 
 **返回值：**
 
-| 类型   | 描述             |
-| ------ | ---------------- |
-| `bool` | 是否成功加载模型 |
+| 类型   | 描述                                                |
+| ------ | --------------------------------------------------- |
+| `bool` | 加载成功或模型已加载返回 `True`，否则返回 `False` |
+
+重复调用 `loadV5` 时，如果模型已经加载，会直接返回 `True`，不会重新加载或应用新的参数。需要更换加载参数时，先调用 `free()` 释放模型。
 
 **示例：**
 
@@ -134,6 +137,29 @@ else:
     print(f"网络图片识别结果数量: {len(url_results)}")
 ```
 
+#### `recognizeAbs` - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标
+
+参数与 `recognize` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```python
+def recognizeAbs(
+    input: str,
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    confidenceThreshold: float = 0.6
+) -> List[OCRResult]
+```
+
+**示例：**
+
+```python
+abs_results = paddleocr.recognizeAbs("screen", 100, 100, 500, 300)
+if abs_results:
+    print(f"绝对坐标中心点: ({abs_results[0].centerX}, {abs_results[0].centerY})")
+```
+
 #### `findText` - 在识别结果中查找目标文本并返回对应子串坐标
 
 在 OCR 识别结果中查找指定文本，返回匹配文本的坐标和置信度等信息。
@@ -190,6 +216,30 @@ else:
     print(f"区域命中数量: {len(region_hits)}")
 ```
 
+#### `findTextAbs` - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标
+
+参数与 `findText` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
+
+```python
+def findTextAbs(
+    input: str,
+    targetTexts: List[str],
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    confidenceThreshold: float = 0.6
+) -> List[OCRResult]
+```
+
+**示例：**
+
+```python
+abs_hits = paddleocr.findTextAbs("screen", ["确定"], 100, 100, 500, 400, 0.6)
+if abs_hits:
+    print(f"绝对坐标中心点: ({abs_hits[0].centerX}, {abs_hits[0].centerY})")
+```
+
 ### 资源管理
 
 #### `free` - 释放 OCR 模型占用的内存资源

package/docs/apipython/pip.md

@@ -1,12 +1,14 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
+悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
 
 ## 功能特性
 
-- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **显示模式**：支持日志、保活和自定义三种显示模式
+- **关闭控制**：支持主动关闭悬浮窗
 - **状态查询**：判断悬浮窗是否正在显示
-- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
+- **尺寸设置**：日志模式和自定义模式支持设置内容宽高，并按模式分别持久化
+- **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
 
 ## API 参考
 
@@ -35,7 +37,7 @@ if pip.isPipActive():
 
 ### switchToLogMode - 切换到日志模式
 
-切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
 
 ```python
 def switchToLogMode() -> bool
@@ -58,7 +60,7 @@ success = pip.switchToLogMode()
 
 ### switchToKeepAliveMode - 切换到保活模式
 
-切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
 
 ```python
 def switchToKeepAliveMode() -> bool
@@ -79,12 +81,12 @@ utils.takeMeToFront()
 success = pip.switchToKeepAliveMode()
 ```
 
-### switchToOffMode - 切换到关闭模式
+### switchToCustomMode - 切换到自定义模式
 
-切换到关闭模式并关闭悬浮窗。
+切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
 
 ```python
-def switchToOffMode() -> bool
+def switchToCustomMode() -> bool
 ```
 
 **返回值：**
@@ -95,10 +97,185 @@ def switchToOffMode() -> bool
 
 **示例：**
 
+```python
+from kuaijs import pip, utils
+
+utils.takeMeToFront()
+pip.switchToCustomMode()
+pip.setCustomText("运行中\n进度 1/3")
+pip.setCustomTextColor("#34c759")
+pip.setCustomTextSize(18)
+```
+
+### closeWindow - 关闭悬浮窗
+
+关闭悬浮窗。
+
+```python
+def closeWindow() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+success = pip.closeWindow()
+```
+
+### setContentSize - 设置内容尺寸
+
+设置日志模式或自定义模式的悬浮窗内容尺寸。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+
+```python
+def setContentSize(width: float, height: float) -> bool
+```
+
+**参数：**
+
+| 参数     | 类型             | 必填 | 描述                          |
+| -------- | ---------------- | ---- | ----------------------------- |
+| `width`  | `float` | 是   | 目标内容宽度 |
+| `height` | `float` | 是   | 目标内容高度 |
+
+**返回值：**
+
+| 类型   | 描述                                                                |
+| ------ | ------------------------------------------------------------------- |
+| `bool` | `True` 代表尺寸已提交；`False` 代表当前模式不允许设置或宽高无效 |
+
+**示例：**
+
 ```python
 from kuaijs import pip
 
-success = pip.switchToOffMode()
+pip.switchToLogMode()
+pip.setContentSize(280, 120)
+
+pip.switchToCustomMode()
+pip.setContentSize(120, 180)
+```
+
+### setCustomText - 设置自定义文本
+
+设置自定义模式显示的纯文本内容。该方法只更新自定义文本数据，不会自动切换到自定义模式。
+
+```python
+def setCustomText(text: str) -> bool
+```
+
+**参数：**
+
+| 参数   | 类型  | 必填 | 描述                                        |
+| ------ | ----- | ---- | ------------------------------------------- |
+| `text` | `str` | 是   | 要显示的文本，支持真实换行和字符串中的 `\n` |
+
+**返回值：**
+
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表文本已提交 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomText("运行中\n进度 1/3")
+pip.switchToCustomMode()
+```
+
+### setCustomTextColor - 设置自定义文字颜色
+
+设置自定义模式显示文本的文字颜色。该方法只更新文字颜色数据，不会自动切换到自定义模式。
+
+```python
+def setCustomTextColor(color: str) -> bool
+```
+
+**参数：**
+
+| 参数    | 类型  | 必填 | 描述                                                       |
+| ------- | ----- | ---- | ---------------------------------------------------------- |
+| `color` | `str` | 是   | 文字颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用白色 |
+
+**返回值：**
+
+| 类型   | 描述                      |
+| ------ | ------------------------- |
+| `bool` | `True` 代表文字颜色已提交 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomTextColor("#34c759")
+pip.switchToCustomMode()
+```
+
+### setCustomTextSize - 设置自定义文字大小
+
+设置自定义模式显示文本的文字大小。该方法只更新文字大小数据，不会自动切换到自定义模式。
+
+```python
+def setCustomTextSize(fontSize: float) -> bool
+```
+
+**参数：**
+
+| 参数       | 类型    | 必填 | 描述                       |
+| ---------- | ------- | ---- | -------------------------- |
+| `fontSize` | `float` | 是   | 文字字号，必须是有效数字 |
+
+**返回值：**
+
+| 类型   | 描述                                                  |
+| ------ | ----------------------------------------------------- |
+| `bool` | `True` 代表文字大小已提交；`False` 代表字号无效 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomTextSize(18)
+pip.switchToCustomMode()
+```
+
+### setCustomBackgroundColor - 设置自定义背景色
+
+设置自定义模式显示区域的背景色。该方法只更新背景色数据，不会自动切换到自定义模式。
+
+```python
+def setCustomBackgroundColor(color: str) -> bool
+```
+
+**参数：**
+
+| 参数    | 类型  | 必填 | 描述                                                       |
+| ------- | ----- | ---- | ---------------------------------------------------------- |
+| `color` | `str` | 是   | 背景颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用黑色 |
+
+**返回值：**
+
+| 类型   | 描述                    |
+| ------ | ----------------------- |
+| `bool` | `True` 代表背景色已提交 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomBackgroundColor("#111111")
+pip.switchToCustomMode()
 ```
 
 ## 完整使用示例
@@ -107,15 +284,25 @@ success = pip.switchToOffMode()
 from kuaijs import pip, utils
 
 utils.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. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
 
 ## 故障排除
 
@@ -124,3 +311,8 @@ pip.switchToLogMode()
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
 - 确认应用当前在前台
+
+### setContentSize 返回 False
+
+- 确认当前模式是日志模式或自定义模式
+- 确认宽度和高度都传入了有效数字

package/docs/apipython/yolo.md

@@ -65,7 +65,7 @@ class YoloResult(TypedDict):
 加载模型是使用目标检测功能的前提。
 
 ```python
-def load(paramPath: str, binPath: str, nc: int, version: int = 11) -> Optional[str]
+def load(paramPath: str, binPath: str, nc: int = 0, version: int = 11, useGpu: bool = False) -> Optional[str]
 ```
 
 **参数:**
@@ -74,8 +74,9 @@ def load(paramPath: str, binPath: str, nc: int, version: int = 11) -> Optional[s
 | ----------- | ---- | -------- | ------ | ------------------------------------------- |
 | `paramPath` | str  | 是       | -      | NCNN 模型的 param 文件绝对路径              |
 | `binPath`   | str  | 是       | -      | NCNN 模型的 bin 文件绝对路径                |
-| `nc`        | int  | 是       | -      | 模型的标签数量（在标签集 data.yaml 中查看） |
+| `nc`        | int  | 否       | 0      | 模型的标签数量；传 `0` 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空列表 |
 | `version`   | int  | 否       | 11     | YOLO 模型版本号（仅支持 8/11/26）           |
+| `useGpu`    | bool | 否       | False  | 是否启用 GPU 加速                           |
 
 **返回值:**
 
@@ -92,8 +93,9 @@ from kuaijs import yolo
 model_id = yolo.load(
     "yolov8n_ncnn_model/model.ncnn.param",
     "yolov8n_ncnn_model/model.ncnn.bin",
-    80,
+    0,
     8,
+    False,
 )
 ```
 
@@ -102,7 +104,7 @@ model_id = yolo.load(
 加载模型是使用目标检测功能的前提。
 
 ```python
-def loadV11(paramPath: str, binPath: str, nc: int) -> Optional[str]
+def loadV11(paramPath: str, binPath: str, nc: int = 0, useGpu: bool = False) -> Optional[str]
 ```
 
 **参数:**
@@ -111,7 +113,8 @@ def loadV11(paramPath: str, binPath: str, nc: int) -> Optional[str]
 | ----------- | ---- | -------- | ------ | ------------------------------------------- |
 | `paramPath` | str  | 是       | -      | NCNN 模型的 param 文件绝对路径              |
 | `binPath`   | str  | 是       | -      | NCNN 模型的 bin 文件绝对路径                |
-| `nc`        | int  | 是       | -      | 模型的标签数量（在标签集 data.yaml 中查看） |
+| `nc`        | int  | 否       | 0      | 模型的标签数量；传 `0` 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空列表 |
+| `useGpu`    | bool | 否       | False  | 是否启用 GPU 加速                           |
 
 **返回值:**
 
@@ -129,7 +132,8 @@ from kuaijs import yolo
 model_id = yolo.loadV11(
     "yolo11n_ncnn_model/model.ncnn.param",
     "yolo11n_ncnn_model/model.ncnn.bin",
-    80 # COCO 数据集有 80 个类别
+    0, # 自动根据模型输出推断类别数量
+    False,
 )
 
 if model_id:
@@ -176,7 +180,7 @@ def detect(
 from kuaijs import yolo
 
 # 首先加载模型
-mid = yolo.loadV11("yolo11n_ncnn_model/model.ncnn.param", "yolo11n_ncnn_model/model.ncnn.bin", 80)
+mid = yolo.loadV11("yolo11n_ncnn_model/model.ncnn.param", "yolo11n_ncnn_model/model.ncnn.bin", 0)
 
 if not mid:
     print("模型加载失败")
@@ -227,6 +231,32 @@ else:
     print(f"网络图片检测结果: {len(url_results)} 个物体")
 ```
 
+#### detectAbs - 对指定区域执行目标检测，并将结果坐标映射为原图/全屏绝对坐标
+
+```python
+def detectAbs(
+    modelId: str,
+    img: str,
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    targetSize: int = 640,
+    threshold: float = 0.4,
+    nmsThreshold: float = 0.5
+) -> List[YoloResult]
+```
+
+**示例:**
+
+```python
+from kuaijs import yolo, action
+
+abs_results = yolo.detectAbs(mid, "screen", 100, 100, 500, 400, 640, 0.4, 0.5)
+if abs_results:
+    action.click(abs_results[0]["centerX"], abs_results[0]["centerY"])
+```
+
 ### 资源管理
 
 #### free - 释放指定模型