ms-vite-plugin 1.4.43 → 1.4.46

package/docs/apicn/dotocr.md

@@ -1,71 +1,100 @@
-# 点阵 OCR 模块（$点阵OCR）
+# 点阵 OCR 模块 ($点阵OCR)
 
-`$点阵OCR` 使用图色工具生成的固定像素点阵字库识别文字。字库保存在项目的 `res/fonts` 目录，使用方式与 YOLO 模型一致：先加载资源取得字库 ID，再复用该 ID 进行识别，使用完毕后释放。
+点阵 OCR 模块基于图色工具生成的固定像素点阵字库，提供精确的文字识别与查找功能。字库保存在项目的 `res/fonts` 目录，使用前需先加载字库取得字库 ID，再复用该 ID 进行识别，使用完毕后释放。
 
 点阵模板按照制作时的原始像素尺寸匹配，不会自动缩放到其他分辨率。目标文字的字号、缩放比例或像素形状发生变化时，应制作对应的字库特征。
 
 ## 功能概览
 
-- **字库管理**：加载、缓存和释放项目字库
-- **文字识别**：返回按阅读顺序排列的识别结果数组
-- **文本查找**：先识别再按行定位目标串，返回命中位置的绝对坐标
-- **多源输入**：支持 `"screen"`、图片文件路径、URL 或 imageId
-- **绝对坐标**：裁剪区域内的结果会映射回原图或全屏坐标
+- **字库管理**: 加载、缓存和释放项目字库
+- **文字识别**: 返回按阅读顺序排列的识别结果数组
+- **文本查找**: 先识别再按行定位目标串，返回命中位置的绝对坐标
+- **多源输入**: 支持屏幕截图、图片文件、URL 或 imageId
+- **区域识别**: 支持指定区域的精确文字识别
+- **绝对坐标**: 裁剪区域内的结果会映射回原图或全屏坐标
+- **资源控制**: 完整的字库生命周期管理
 
 ## 数据类型
 
-### OCR字符
+### OCR 字符
+
+识别结果的数据结构，包含完整的文本信息和位置数据：
 
 ```typescript
 interface OCR字符 {
+  /** 识别的文本内容 */
   text: 字符串;
+  /** 识别置信度 (0-1) */
   confidence: 数字;
+  /** 文本区域左上角 x 坐标 */
   x: 数字;
+  /** 文本区域左上角 y 坐标 */
   y: 数字;
+  /** 文本区域右下角 x 坐标 */
   ex: 数字;
+  /** 文本区域右下角 y 坐标 */
   ey: 数字;
+  /** 文本区域宽度 */
   width: 数字;
+  /** 文本区域高度 */
   height: 数字;
+  /** 文本区域中心点 x 坐标 */
   centerX: 数字;
+  /** 文本区域中心点 y 坐标 */
   centerY: 数字;
 }
 ```
 
-| 字段名               | 类型   | 描述                                   |
-| -------------------- | ------ | -------------------------------------- |
-| `OCR字符.text`       | 字符串 | 识别文本；查找结果中为命中的目标字符串 |
-| `confidence`         | 数字   | 置信度，范围为 0-1                     |
-| `x`, `y`             | 数字   | 结果区域左上角绝对坐标                 |
-| `ex`, `ey`           | 数字   | 结果区域右下角绝对坐标                 |
-| `width`, `height`    | 数字   | 结果区域宽度和高度                     |
-| `centerX`, `centerY` | 数字   | 结果区域中心点绝对坐标                 |
+**数据结构说明：**
+
+| 字段               | 类型   | 描述                                                     |
+| ------------------ | ------ | -------------------------------------------------------- |
+| `text`             | 字符串 | 识别出的文本内容；查找结果中为命中的目标字符串           |
+| `confidence`       | 数字   | 识别置信度，范围 0-1，值越高表示识别越准确               |
+| `x, y, ex, ey`     | 数字   | 文本区域的坐标，分别为左上角和右下角的 x、y 绝对坐标     |
+| `width, height`    | 数字   | 文本区域的宽度和高度                                     |
+| `centerX, centerY` | 数字   | 文本区域的中心点绝对坐标                                 |
 
 ## API 参考
 
 ### 字库管理
 
-#### 加载字库 - 加载并缓存字库
+#### 加载字库 - 加载并缓存点阵字库。
+
+加载字库是使用点阵识别功能的前提。建议在脚本初始化时加载一次并保存字库 ID，后续识别时复用，不要每次识别都重新加载。
 
 ```typescript
 function 加载字库(字库资源路径: 字符串): 字符串 | null;
 ```
 
+**参数:**
+
 | 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                        |
 | -------------- | ------ | -------- | ------ | --------------------------------------------------------------------------- |
 | `字库资源路径` | 字符串 | 是       |        | 资源路径，运行时会自动处理 `res` 目录解析；常见写法如 `/fonts/default.json` |
 
-**返回值：**加载成功返回字库 ID，失败返回 `null`。加载后的字库 ID 会复用到后续识别与释放流程。
+**返回值:**
+
+| 类型           | 描述                                      |
+| -------------- | ----------------------------------------- |
+| `字符串 \| null` | 加载成功返回字库 ID 字符串，失败返回 null |
+
+**示例:**
 
 ```javascript
 const 字库ID = $点阵OCR.加载字库("/fonts/default.json");
-if (!字库ID) throw new Error("字库加载失败");
+if (!字库ID) {
+  $打印信息日志("字库加载失败");
+  return;
+}
+$打印信息日志(`字库加载成功: ${字库ID}`);
 ```
 
-建议在脚本初始化时加载一次并保存字库 ID，后续识别时复用，不要每次识别都重新加载。
-
 ### 文字识别
 
-#### 识别绝对坐标 - 识别文字并返回绝对坐标
+#### 识别绝对坐标 - 执行点阵 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。结果按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
 
 ```typescript
 function 识别绝对坐标(
@@ -79,25 +108,40 @@ function 识别绝对坐标(
 ): 数组<OCR字符>;
 ```
 
-| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                         |
-| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------- |
-| `字库ID`     | 字符串 | 是       |        | `加载字库` 返回的字库 ID                                                                     |
-| `输入源`     | 字符串 | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                        |
-| `左`, `上`   | 数字   | 否       | 0      | 裁剪区域左上角坐标                                                                           |
-| `右`, `下`   | 数字   | 否       | 0      | 裁剪区域右下角坐标；`右` 或 `下` 为 0 时分别使用图像宽度或高度                               |
-| `置信度阈值` | 数字   | 否       | 0.8     | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求像素完全一致 |
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                          |
+| ------------ | ------ | -------- | ------ | --------------------------------------------------------------------------------------------- |
+| `字库ID`     | 字符串 | 是       |        | 字库 ID，通过 `加载字库` 获取                                                                 |
+| `输入源`     | 字符串 | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                         |
+| `左`         | 数字   | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                                                           |
+| `上`         | 数字   | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                                                           |
+| `右`         | 数字   | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0；为 0 时使用图像宽度                                      |
+| `下`         | 数字   | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0；为 0 时使用图像高度                                      |
+| `置信度阈值` | 数字   | 否       | 0.8    | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求像素完全一致              |
 
-**返回值：**`数组<OCR字符>`。按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
+**返回值:**
+
+| 类型          | 描述                                           |
+| ------------- | ---------------------------------------------- |
+| `数组<OCR字符>` | 识别结果数组，坐标为原图或全屏绝对坐标         |
+
+**示例:**
 
 ```javascript
 const 结果 = $点阵OCR.识别绝对坐标(字库ID, "screen", 100, 200, 600, 280, 0.8);
-$打印信息日志(结果[0]?.text);
-$打印信息日志(`坐标: ${结果[0]?.x}, ${结果[0]?.y}`);
+$打印信息日志(`识别数量: ${结果.length}`);
+if (结果.length > 0) {
+  $打印信息日志(`文本: ${结果[0].text}, 坐标: (${结果[0].x}, ${结果[0].y})`);
+  $动作.点击(结果[0].centerX, 结果[0].centerY);
+}
 ```
 
 ### 文本查找
 
-#### 查找文本绝对坐标 - 查找指定字符串并返回绝对坐标
+#### 查找文本绝对坐标 - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+先识别再按行定位目标串。传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。每个目标最多返回一次命中（最先匹配到的行），每项的 `text` 是目标字符串。
 
 ```typescript
 function 查找文本绝对坐标(
@@ -113,17 +157,27 @@ function 查找文本绝对坐标(
 ): 数组<OCR字符>;
 ```
 
-| 参数名       | 类型          | 是否必填 | 默认值 | 描述                                                                  |
-| ------------ | ------------- | -------- | ------ | --------------------------------------------------------------------- |
-| `字库ID`     | 字符串        | 是       |        | `加载字库` 返回的字库 ID                                              |
-| `输入源`     | 字符串        | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                 |
-| `目标文本`   | 数组<字符串>  | 是       |        | 要查找的字符串数组，例如 `["商店", "背包"]`                           |
-| `左`, `上`   | 数字          | 否       | 0      | 裁剪区域左上角坐标                                                    |
-| `右`, `下`   | 数字          | 否       | 0      | 裁剪区域右下角坐标；`右` 或 `下` 为 0 时分别使用图像宽度或高度        |
-| `置信度阈值` | 数字          | 否       | 0.8    | 单字符识别相似度下限；语义同 `识别绝对坐标`                           |
-| `完整匹配`   | 布尔值        | 否       | false   | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+**参数:**
+
+| 参数名       | 类型         | 是否必填 | 默认值 | 描述                                                                  |
+| ------------ | ------------ | -------- | ------ | --------------------------------------------------------------------- |
+| `字库ID`     | 字符串       | 是       |        | 字库 ID，通过 `加载字库` 获取                                         |
+| `输入源`     | 字符串       | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                 |
+| `目标文本`   | 数组<字符串> | 是       |        | 要查找的字符串数组，例如 `["商店", "背包"]`                           |
+| `左`         | 数字         | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                                   |
+| `上`         | 数字         | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                                   |
+| `右`         | 数字         | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0；为 0 时使用图像宽度              |
+| `下`         | 数字         | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0；为 0 时使用图像高度              |
+| `置信度阈值` | 数字         | 否       | 0.8    | 单字符识别相似度下限；语义同 `识别绝对坐标`                           |
+| `完整匹配`   | 布尔值       | 否       | false  | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+
+**返回值:**
+
+| 类型            | 描述                                                   |
+| --------------- | ------------------------------------------------------ |
+| `数组<OCR字符>` | 命中结果数组，坐标为原图或全屏绝对坐标                 |
 
-**返回值：**命中结果数组。每个目标最多返回一次命中（最先匹配到的行）；每项的 `text` 是目标字符串。
+**示例:**
 
 ```javascript
 const 命中 = $点阵OCR.查找文本绝对坐标(
@@ -137,25 +191,43 @@ const 命中 = $点阵OCR.查找文本绝对坐标(
   0.8,
   false,
 );
-if (命中.length > 0) $动作.点击(命中[0].centerX, 命中[0].centerY);
+if (命中.length > 0) {
+  $动作.点击(命中[0].centerX, 命中[0].centerY);
+}
 ```
 
 ### 资源管理
 
-#### 释放 - 释放指定字库
+#### 释放 - 释放指定字库的资源。
 
 ```typescript
 function 释放(字库ID: 字符串): void;
 ```
 
-#### 释放全部 - 释放全部点阵字库
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述            |
+| -------- | ------ | -------- | ------ | --------------- |
+| `字库ID` | 字符串 | 是       |        | 要释放的字库 ID |
+
+**示例:**
+
+```javascript
+if (字库ID) {
+  $点阵OCR.释放(字库ID);
+  $打印信息日志(`字库 ${字库ID} 资源已释放`);
+}
+```
+
+#### 释放全部 - 释放全部已加载点阵字库的资源。
 
 ```typescript
 function 释放全部(): void;
 ```
 
+**示例:**
+
 ```javascript
-$点阵OCR.释放(字库ID);
-// 或在需要清理全部已加载的点阵字库时：
 $点阵OCR.释放全部();
+$打印信息日志("所有点阵字库资源已释放");
 ```

package/docs/apicn/global.md

@@ -12,7 +12,7 @@
 - **脚本生命周期**: 设置停止回调、异常回调、重启脚本等
 - **时间工具**: 获取时间戳
 - **应用控制**: 切换应用到前台
-- **Agent 设置**: 读取和设置 Agent 快速模式
+- **Agent 设置**: 读取和设置 Agent 触控模式
 
 ## 全局常量
 
@@ -310,7 +310,7 @@ $打印信息日志("应用已切换到前台");
 
 ### $设置 Agent 快速模式
 
-设置 Agent 快速模式。快速模式默认开启，设置会持久化。开启后，Agent 执行动作响应更快，但开始执行时电量可能快速消耗。
+设置 Agent 快速模式（兼容旧接口）。开启对应模式 `1`，关闭对应模式 `0`。推荐改用 `$设置Agent触控模式`。设置会持久化。
 
 ```typescript
 declare function $设置Agent快速模式(是否开启: 布尔值): 布尔值;
@@ -337,7 +337,7 @@ $打印信息日志(`Agent 快速模式: ${是否开启}`);
 
 ### $获取 Agent 快速模式
 
-获取 Agent 快速模式当前状态。快速模式默认开启，设置会持久化。
+获取 Agent 快速模式当前状态（兼容旧接口）。
 
 ```typescript
 declare function $获取Agent快速模式(): 布尔值;
@@ -357,6 +357,58 @@ if ($获取Agent快速模式()) {
 }
 ```
 
+### $设置 Agent 触控模式
+
+设置 Agent 触控模式。默认 `1`，设置会持久化。
+
+- `0` 标准：等待完整执行完成
+- `1` 快速：更快的执行速度
+- `2` 真实点击：更接近真实手指触控
+
+```typescript
+declare function $设置Agent触控模式(模式: 数字): 数字;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                         |
+| ------ | ------ | -------- | ------ | ---------------------------- |
+| `模式` | `数字` | 是       | -      | 0 标准 / 1 快速 / 2 真实点击 |
+
+**返回值:**
+
+| 类型   | 描述           |
+| ------ | -------------- |
+| `数字` | 实际生效的模式 |
+
+**示例:**
+
+```javascript
+const 模式 = $设置Agent触控模式(1);
+$打印信息日志(`Agent 触控模式: ${模式}`);
+```
+
+### $获取 Agent 触控模式
+
+获取 Agent 触控模式。默认 `1`，设置会持久化。
+
+```typescript
+declare function $获取Agent触控模式(): 数字;
+```
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `数字` | 当前模式（0/1/2） |
+
+**示例:**
+
+```javascript
+const 模式 = $获取Agent触控模式();
+$打印信息日志(`当前触控模式: ${模式}`);
+```
+
 ### $设置CPU自动限流
 
 设置脚本 CPU 自动限流。默认开启。开启后，脚本 API 在 CPU 占用接近系统杀进程阈值时会轻微让步，降低被系统终止的风险。
@@ -411,7 +463,10 @@ if ($获取CPU自动限流()) {
 设置 CPU 限流单次 sleep 延迟范围（毫秒）。默认 `minMs=3`、`maxMs=30`。仅在 CPU 自动限流开启且触发限流时生效。
 
 ```typescript
-declare function $设置CPU限流延迟(最小毫秒: 数字, 最大毫秒: 数字): { minMs: 数字; maxMs: 数字 };
+declare function $设置CPU限流延迟(
+  最小毫秒: 数字,
+  最大毫秒: 数字,
+): { minMs: 数字; maxMs: 数字 };
 ```
 
 **参数:**
@@ -423,8 +478,8 @@ declare function $设置CPU限流延迟(最小毫秒: 数字, 最大毫秒: 数
 
 **返回值:**
 
-| 类型                        | 描述               |
-| --------------------------- | ------------------ |
+| 类型                           | 描述               |
+| ------------------------------ | ------------------ |
 | `{ minMs: 数字; maxMs: 数字 }` | 实际生效的延迟范围 |
 
 **示例:**
@@ -444,8 +499,8 @@ declare function $获取CPU限流延迟(): { minMs: 数字; maxMs: 数字 };
 
 **返回值:**
 
-| 类型                        | 描述               |
-| --------------------------- | ------------------ |
+| 类型                           | 描述               |
+| ------------------------------ | ------------------ |
 | `{ minMs: 数字; maxMs: 数字 }` | 当前最低与最高延迟 |
 
 **示例:**
@@ -467,8 +522,8 @@ declare const $设置停止回调: (
 
 **参数:**
 
-| 参数名 | 类型                                                       | 是否必填 | 默认值 | 描述         |
-| ------ | ---------------------------------------------------------- | -------- | ------ | ------------ |
+| 参数名 | 类型                                                  | 是否必填 | 默认值 | 描述         |
+| ------ | ----------------------------------------------------- | -------- | ------ | ------------ |
 | `回调` | (状态: "success" \| "error" \| "stopped") => 无返回值 | 是       | -      | 停止回调函数 |
 
 **说明:**

package/docs/apicn/node.md

@@ -73,15 +73,15 @@ const listPage = $创建节点选择器({ mode: 2 });
 | 方法 | 说明 |
 | --- | --- |
 | `hittable()` | 当前是否可点击（可见且未被挡住） |
-| `scrollToVisible()` | 滚动到可见区域 |
-| `tap()` | 单击（不可见时会先尝试滚到可见） |
-| `doubleTap()` | 双击 |
-| `press(duration?)` | 长按，`duration` 单位毫秒，默认 500 |
-| `点击中心()` | 点击中心坐标 |
-| `点击随机范围()` | 在节点范围内随机点击 |
-| `clearInput()` | 清空输入内容 |
-| `input(text)` | 追加输入（不先清空） |
-| `setValue(text)` | 设置值（见下方） |
+| `scrollToVisible()` | 仅滚动到可见，不点击；一般不必手动调用 |
+| `tap()` | 单击；不可见时会先自动滚到可见 |
+| `doubleTap()` | 双击；不可见时会先自动滚到可见 |
+| `press(duration?)` | 长按，`duration` 单位毫秒，默认 500；不可见时会先自动滚到可见 |
+| `点击中心()` | 点击中心坐标（坐标点击，不会自动滚动） |
+| `点击随机范围()` | 在节点范围内随机点击（坐标点击，不会自动滚动） |
+| `clearInput()` | 清空输入内容（内部会先 `tap` 聚焦，因而也会自动滚到可见） |
+| `input(text)` | 追加输入（不先清空；内部会先 `tap` 聚焦） |
+| `setValue(text)` | 设置值（见下方；不可见时会先自动滚到可见） |
 | `parent()` | 父节点 |
 | `child(index)` | 第 `index` 个子节点 |
 | `allChildren()` | 全部子节点 |
@@ -170,28 +170,29 @@ selector
 
 ### 是否可点 / 滚到可见
 
+`tap` / `doubleTap` / `press` / `setValue`（以及内部会先 `tap` 的 `clearInput` / `input`）在元素当前不可见时，会**自动**先滚到可见再操作，一般不用手写滚动：
+
 ```typescript
-if (node.hittable()) {
-  node.tap();
-} else {
-  node.scrollToVisible();
-  node.tap();
-}
+// 推荐：直接操作，不可见时会自动滚到可见
+node.tap();
+node.doubleTap();
+node.press(800);
+node.setValue("hello");
 ```
 
-- `hittable()`：当前能否点到  
-- `scrollToVisible()`：手动滚到可见  
-- `tap` / `doubleTap` / `press`：不可见时会自动尝试滚到可见再操作  
+- `hittable()`：当前能否点到（可见且未被挡住），用于排查“点了没反应”
+- `scrollToVisible()`：只滚到可见、不点击；仅在你想先露出元素、稍后再操作时使用
+- `点击中心()` / `点击随机范围()`：按坐标点击，**不会**自动滚动
 
 ### 点击
 
 | 方法 | 说明 |
 | --- | --- |
-| `tap()` | 推荐，单击 |
-| `doubleTap()` | 双击 |
-| `press(ms?)` | 长按，默认 500ms |
-| `点击中心()` | 点中心坐标 |
-| `点击随机范围()` | 范围内随机点 |
+| `tap()` | 推荐，单击；不可见时自动滚到可见 |
+| `doubleTap()` | 双击；不可见时自动滚到可见 |
+| `press(ms?)` | 长按，默认 500ms；不可见时自动滚到可见 |
+| `点击中心()` | 点中心坐标，不自动滚动 |
+| `点击随机范围()` | 范围内随机点，不自动滚动 |
 
 ```typescript
 const btn = selector
@@ -210,15 +211,15 @@ if (btn) {
 
 | 方法 | 说明 |
 | --- | --- |
-| `clearInput()` | 清空 |
-| `input(text)` | 追加输入，不清空原内容 |
-| `setValue(text)` | 按控件类型设置 |
+| `clearInput()` | 清空（内部先 `tap` 聚焦，不可见时也会自动滚到可见） |
+| `input(text)` | 追加输入，不清空原内容（内部先 `tap` 聚焦） |
+| `setValue(text)` | 按控件类型设置；不可见时会先自动滚到可见 |
 
 **`setValue` 行为**
 
 | 控件类型 | 传参 | 效果 |
 | --- | --- | --- |
-| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项 |
+| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项（控件本身不可见时也会先自动滚到可见） |
 | 文本框类（TextField 等） | 字符串 | 聚焦后追加输入，不先清空 |
 
 覆盖原内容请先清空：
@@ -231,6 +232,7 @@ field.setValue("hello");
 ```typescript
 const wheel = selector.类型("XCUIElementTypePickerWheel").获取一个节点信息(3000);
 if (wheel) {
+  // 不可见时会自动滚到可见，再调到目标选项
   wheel.setValue("1小时");
 }
 ```