ms-vite-plugin 1.4.47 → 1.4.49

package/docs/api/image.md

@@ -488,6 +488,8 @@ if (imageId) {
 
 ### findImage - 找图
 
+在大图（通常是屏幕截图）中查找小图（模板）。支持多种匹配算法，可按 `|` 同时传入多个模板。
+
 ```typescript
 function findImage(
   imageId: string,
@@ -504,7 +506,7 @@ function findImage(
     scaleFactors?: number[];
   },
 ): {
-  index: number; // 模板图片索引
+  index: number; // 模板图片索引，从 0 开始
   x: number;
   y: number;
   width: number;
@@ -514,55 +516,277 @@ function findImage(
   ey: number;
   centerX: number;
   centerY: number;
+  scaleX?: number; // 仅 method=99 返回：命中时模板的横向缩放比例
+  scaleY?: number; // 仅 method=99 返回：命中时模板的纵向缩放比例
 }[];
 ```
 
 **参数：**
 
-| 参数名                 | 类型      | 是否必填 | 默认值                      | 描述                                                                                                                          |
-| ---------------------- | --------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `imageId`              | string    | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）                                |
-| `templateImageId`      | string    | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
-| `x, y`                 | number    | 是       | -                           | 搜索区域左上角坐标                                                                                                            |
-| `ex, ey`               | number    | 是       | -                           | 搜索区域右下角坐标                                                                                                            |
-| `threshold`            | number    | 是       | -                           | 匹配阈值 (0.0-1.0) 全分辨率匹配时建议 0.5-0.6 其他建议 0.9-0.995                                                              |
-| `limit`                | number    | 是       | -                           | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                             |
-| `method`               | number    | 是       | -                           | 匹配方法 0 SIFT 全分辨率 1 TM_SQDIFF_NORMED 3 TM_CCORR_NORMED 5 TM_CCOEFF_NORMED 99 全分辨率缩放匹配法                        |
-| `rgb`                  | boolean   | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                              |
-| `options`              | object    | 否       | -                           | 选项                                                                                                                          |
-| `options.scaleFactors` | number\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 缩放匹配法缩放因子数组，默认 `[1.0, 0.9, 1.1, 0.8, 1.2]` 会在这些缩放比例下进行匹配。                                         |
+| 参数名                 | 类型      | 是否必填 | 默认值                      | 描述                                                                                                                                 |
+| ---------------------- | --------- | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `imageId`              | string    | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）                                       |
+| `templateImageId`      | string    | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找        |
+| `x, y`                 | number    | 是       | -                           | 搜索区域左上角坐标                                                                                                                   |
+| `ex, ey`               | number    | 是       | -                           | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界                                                                              |
+| `threshold`            | number    | 是       | -                           | 匹配阈值 (0.0-1.0)。method `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995`                                   |
+| `limit`                | number    | 是       | -                           | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                                    |
+| `method`               | number    | 是       | -                           | 匹配方法，见下方说明                                                                                                                 |
+| `rgb`                  | boolean   | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                                     |
+| `options`              | object    | 否       | -                           | 额外选项，目前仅 method=`99` 时生效                                                                                                  |
+| `options.scaleFactors` | number\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+
+#### method 匹配方法说明
+
+| method | 名称                   | 原理简述                                                                                         | 适用场景                                         | 速度     |
+| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- |
+| `5`    | TM_CCOEFF_NORMED       | 标准模板匹配（归一化相关系数），模板必须与目标**像素尺寸一致**                                   | 同分辨率、同尺寸截图模板，最常用                 | 快       |
+| `3`    | TM_CCORR_NORMED        | 标准模板匹配（归一化相关）                                                                       | 同尺寸模板；PNG 透明模板带 mask 时内部会优先用它 | 快       |
+| `1`    | TM_SQDIFF_NORMED       | 标准模板匹配（归一化平方差），分数越小越像，引擎已换算为越大越像                                 | 同尺寸模板                                       | 快       |
+| `0`    | SIFT 全分辨率          | 提取 SIFT 特征点做匹配，对旋转、轻微形变更鲁棒，不要求模板与目标同尺寸                           | 目标可能旋转/形变，或跨分辨率找图                | 较慢     |
+| `99`   | 全分辨率缩放匹配法     | 把**模板**按多个比例缩放后，再做 `TM_CCOEFF_NORMED` 模板匹配（有透明通道时用 `TM_CCORR_NORMED`） | 目标与模板尺寸不完全一致，但形状相同             | 中等偏慢 |
+
+#### 什么是「缩放」全分辨率找图（method = 99）
+
+这里的「缩放」**不是**把屏幕截图缩小，也**不是**设备显示缩放（`device.getScreenScale()`），而是：
+
+> 在匹配前，把**模板小图**按 `scaleFactors` 里的比例逐个放大/缩小，再与**原尺寸**搜索区域做模板匹配。
+
+- `factor = 1.0`：模板保持原像素尺寸去匹配
+- `factor < 1.0`：先把模板缩小再匹配（当前屏幕上的目标比模板更小）
+- `factor > 1.0`：先把模板放大再匹配（当前屏幕上的目标比模板更大）
+
+引擎内部是 `Imgproc.resize(template, fx=factor, fy=factor)`，**横向、纵向使用同一个比例**（等比缩放）。  
+返回结果里的 `width` / `height` 是缩放后的模板尺寸，`scaleX` / `scaleY` 是本次命中用到的比例。
+
+工作流程：
+
+1. 读取搜索区域（大图）和模板（小图），默认转灰度（`rgb=true` 时保留彩色）。
+2. 按 `scaleFactors` **数组顺序**，对模板执行等比缩放。
+3. 若缩放后的模板比搜索区域还大，跳过该比例。
+4. 用缩放后的模板做 `TM_CCOEFF_NORMED` 匹配（透明 PNG 用 `TM_CCORR_NORMED` + alpha mask）。
+5. 收集 `confidence >= threshold` 的命中；重叠区域去重，保留置信度更高者。
+6. 找满 `limit` 个后提前结束——所以**更可能命中的比例要放前面**。
+
+#### 如何选择 `scaleFactors`（重点）
+
+`scaleFactors` 不是随便填几个小数，而是回答这个问题：
+
+> 「模板图里的目标，到当前屏幕上会变成原来的几倍宽/高？」
+
+##### 1. 先算「目标比例」baseScale
+
+UI 随分辨率等比变化时（大多数 App / 游戏界面）：
+
+```text
+baseScale = 当前设备逻辑宽 / 截取模板时设备的逻辑宽
+```
+
+也可用高：
+
+```text
+baseScale = 当前设备逻辑高 / 截取模板时设备的逻辑高
+```
+
+宽高比一致时两者相同；不一致时优先用**与布局更相关的那条边**（竖屏 App 常用高，横屏游戏常用宽），或取两者平均。
+
+这里的「逻辑宽高」请用找图坐标系对应的尺寸，一般是 `device.getScreenRealSize()`（实际像素分辨率）。  
+**不要**把 `device.getScreenScale()`（屏幕 scale 因子）直接当成 `scaleFactors` 里的值——两者不是一回事。
+
+若你确切知道模板像素尺寸和屏幕上目标像素尺寸，也可以直接：
+
+```text
+baseScale = 屏幕上目标宽度(px) / 模板宽度(px)
+// 或
+baseScale = 屏幕上目标高度(px) / 模板高度(px)
+```
+
+**数值例子：**
+
+| 截模板设备     | 当前运行设备   | 计算                         | baseScale |
+| -------------- | -------------- | ---------------------------- | --------- |
+| iPhone 8 750px | 同机           | 750 / 750                    | `1.0`     |
+| 750 宽         | 1170 宽        | 1170 / 750                   | `1.56`    |
+| 1170 宽        | 750 宽         | 750 / 1170                   | `0.641`   |
+| 1080 宽安卓    | 1440 宽安卓    | 1440 / 1080                  | `1.333`   |
+| 模板按钮 120px | 屏上按钮 96px  | 96 / 120                     | `0.8`     |
+
+含义对照：
+
+| baseScale | 含义                                       | 引擎会对模板做什么      |
+| --------- | ------------------------------------------ | ----------------------- |
+| `1.0`     | 当前目标与模板同尺寸                       | 不缩放                  |
+| `0.64`    | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配         |
+| `1.56`    | 当前目标大约是模板的 156%（低分屏模板跑高分） | 放大到 156% 再匹配      |
+
+##### 2. 再围绕 baseScale 生成搜索列表
+
+真实设备上还会有状态栏、安全区、App 缩放、截图工具裁切误差等，baseScale 很少绝对精确，所以要在 baseScale **附近扫一小段**：
+
+```text
+scaleFactors ≈ [ baseScale,
+                 baseScale ± step,
+                 baseScale ± 2*step,
+                 ... ]
+```
+
+推荐参数：
+
+| 项目           | 建议                                      | 原因 |
+| -------------- | ----------------------------------------- | ---- |
+| 中心值         | 算出来的 `baseScale`                      | 最可能命中，必须放第一位 |
+| 步进 `step`    | `0.05`～`0.1`                             | 太疏容易跳过真实尺寸；太密浪费时间 |
+| 半宽度         | `±0.1`～`±0.2`（约 ±10%～20%）            | 覆盖状态栏/安全区/轻微布局差 |
+| 总档数         | 3～7 个                                   | 每多一档就多跑一轮全图模板匹配 |
+| 阈值 threshold | `0.5`～`0.6` 起调                         | 缩放插值会降低相关分数，别用 0.9+ |
+| 顺序           | **baseScale 最先**，再左右交替扩开        | 找满 limit 会提前结束 |
+
+生成示例（伪代码思路）：
+
+```javascript
+// 截模板时的设备宽（写进脚本配置，或写在模板文件名里）
+const templateDeviceWidth = 750;
+// 当前设备实际宽
+const currentWidth = device.getScreenRealSize().width;
+const baseScale = currentWidth / templateDeviceWidth;
+
+// 围绕 baseScale，步进 0.05，左右各扩 2 档 → 共 5 个
+function buildScaleFactors(base, step = 0.05, halfRange = 2) {
+  const list = [Number(base.toFixed(4))];
+  for (let i = 1; i <= halfRange; i++) {
+    list.push(Number((base - step * i).toFixed(4)));
+    list.push(Number((base + step * i).toFixed(4)));
+  }
+  // 过滤掉无意义的比例
+  return list.filter((s) => s > 0.05 && s < 8);
+}
+
+const scaleFactors = buildScaleFactors(baseScale);
+// 例如 baseScale=1.56, step=0.05, halfRange=2
+// → [1.56, 1.51, 1.61, 1.46, 1.66]
+```
+
+##### 3. 按场景怎么选
+
+| 场景 | 怎么设 `scaleFactors` | threshold |
+| ---- | --------------------- | --------- |
+| 模板就是本机截的，尺寸确定一致 | 不必用 99，直接 method `5`；若坚持用 99 则 `[1.0]` | `0.9+` / `0.55` |
+| 已知截图机型与当前机型分辨率 | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档 | `0.5`～`0.6` |
+| 多机型跑同一套模板，分辨率跨度大 | 按每台设备运行时动态算 baseScale，不要写死默认那组 | `0.5`～`0.6` |
+| 完全不知道模板来源分辨率 | 先用 method `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右 |
+| 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]` | `0.55`～`0.65` |
+| 横竖屏切换 / 目标会旋转 | method `99` **不够**，改用 method `0` SIFT | `0.5`～`0.6` |
+
+默认值 `[1.0, 0.9, 1.1, 0.8, 1.2]` 的定位：
+
+- 假设「模板大致接近当前尺寸」，在 80%～120% 之间盲扫
+- **只适合尺寸差不大的兜底**，不适合 750 ↔ 1170 这种跨度（baseScale≈1.56，默认列表根本扫不到）
+- 生产脚本应**按设备算 baseScale**，不要依赖这组默认值硬扛跨分辨率
+
+##### 4. 常见误区
+
+1. **把 `device.getScreenScale()` 填进 scaleFactors**  
+   `getScreenScale()` 是屏幕 scale（如 2x/3x 显示倍率），不是「模板相对当前图」的缩放比。
+
+2. **跨大分辨率仍用默认 `[1.0, 0.9, 1.1, 0.8, 1.2]`**  
+   真实 baseScale 在 1.5 时，默认列表全军覆没。
+
+3. **threshold 仍用 0.9**  
+   resize 插值会损失细节，method `99` 相关分通常明显低于同尺寸 method `5`，建议从 `0.55` 左右调。
+
+4. **档位又多又密**  
+   全屏 × 10 个 factor ≈ 10 次模板匹配，卡顿明显。先算准 baseScale，再小范围扩。
+
+5. **模板含大量透明/JPEG 压缩噪点**  
+   缩放后更易误匹配；优先 PNG 透明模板，并尽量裁紧目标外轮廓。
+
+6. **搜索区域小于放大后的模板**  
+   该 factor 会被跳过。放大场景请保证 ROI 足够大，或全屏搜。
+
+##### 5. 与 method `0`（SIFT）怎么选
+
+|                | method `99` 缩放匹配               | method `0` SIFT                    |
+| -------------- | ---------------------------------- | ---------------------------------- |
+| 尺寸变化       | 支持（靠你提供的比例穷举）         | 支持（特征点，不靠固定比例）       |
+| 你需要知道比例 | 最好先算 baseScale                 | 不需要                             |
+| 旋转 / 形变    | 基本不支持                         | 较鲁棒                             |
+| 阈值建议       | `0.5`–`0.6`                        | `0.5`–`0.6`                        |
+| 透明 PNG 模板  | 支持（alpha 作权重 mask）          | 支持（alpha 作特征掩码）           |
+| 性能           | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢               |
+| 推荐           | 比例可估算的跨分辨率找图           | 比例未知、或有旋转/透视时          |
 
 **返回值：**
 
-| 类型    | 描述                                                                                       |
-| ------- | ------------------------------------------------------------------------------------------ |
-| `array` | 找到的匹配结果数组，每个元素包含位置、尺寸和置信度，其中 index 代表模板图片的索引从 0 开始 |
+| 类型    | 描述                                                                                                                                      |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `array` | 匹配结果数组。`index` 为模板在 `templateImageId` 中的索引（从 0 开始）。method=`99` 时额外包含 `scaleX`、`scaleY`（本次命中使用的缩放比） |
 
 **示例：**
 
 ```javascript
+// 1) 同分辨率标准找图（最常用，模板就是本机截的）
 const matches = image.findImage(
   "screen",
   "template.jpg|template2.jpg",
   0,
   0,
   400,
-  800, // 搜索区域
-  0.8, // 80% 匹配度
-  3, // 最多找 3 个
-  5, // 匹配方法
-  false, // 不使用 rgb 找图
+  800,
+  0.9,
+  3,
+  5, // TM_CCOEFF_NORMED
+  false,
 );
 
 if (matches.length > 0) {
   const best = matches[0];
   logi(`找到匹配，置信度: ${best.confidence}`);
+  action.click(best.centerX, best.centerY, 100, false);
+}
 
-  // 点击匹配区域的中心
-  const centerX = best.centerX;
-  const centerY = best.centerY;
-  action.click(centerX, centerY, 100, false);
+// 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
+//    假设模板是在宽度 750 的设备上截的
+const templateDeviceWidth = 750;
+const currentWidth = device.getScreenRealSize().width;
+const baseScale = currentWidth / templateDeviceWidth;
+
+function buildScaleFactors(base, step = 0.05, halfRange = 2) {
+  const list = [Number(base.toFixed(4))];
+  for (let i = 1; i <= halfRange; i++) {
+    list.push(Number((base - step * i).toFixed(4)));
+    list.push(Number((base + step * i).toFixed(4)));
+  }
+  return list.filter((s) => s > 0.05 && s < 8);
 }
+
+const scaleFactors = buildScaleFactors(baseScale);
+// 750 → 1170 时约等于 [1.56, 1.51, 1.61, 1.46, 1.66]
+logi(`baseScale=${baseScale.toFixed(3)} scaleFactors=${JSON.stringify(scaleFactors)}`);
+
+const scaled = image.findImage(
+  "screen",
+  "btn_start.png",
+  0,
+  0,
+  0,
+  0, // 全屏；放大模板时 ROI 太小会被跳过
+  0.55, // 多尺度建议 0.5-0.6，不要用 0.9
+  1,
+  99,
+  false,
+  { scaleFactors },
+);
+
+if (scaled.length > 0) {
+  const hit = scaled[0];
+  logi(
+    `命中 scale=${hit.scaleX} 尺寸=${hit.width}x${hit.height} 置信度=${hit.confidence}`,
+  );
+  action.click(hit.centerX, hit.centerY, 100, false);
+}
+
+// 3) 已知模板宽和屏幕目标大概宽时，直接用像素比
+// const baseScale = expectedTargetWidthPx / templateWidthPx;
 ```
 
 ## 图像处理

package/docs/apicn/image.md

@@ -495,6 +495,8 @@ if (图片ID) {
 
 ### 找图 - 在图片中查找模板图片。
 
+在大图（通常是屏幕截图）中查找小图（模板）。支持多种匹配算法，可按 `|` 同时传入多个模板。
+
 ```typescript
 function 找图(
   图片ID: 字符串,
@@ -511,7 +513,7 @@ function 找图(
     scaleFactors?: 数字[];
   },
 ): {
-  index: 数字; // 模板图片索引
+  index: 数字; // 模板图片索引，从 0 开始
   x: 数字;
   y: 数字;
   width: 数字;
@@ -521,6 +523,8 @@ function 找图(
   centerY: 数字;
   ex: 数字;
   ey: 数字;
+  scaleX?: 数字; // 仅 方法=99 返回：命中时模板的横向缩放比例
+  scaleY?: 数字; // 仅 方法=99 返回：命中时模板的纵向缩放比例
 }[];
 ```
 
@@ -532,46 +536,268 @@ function 找图(
 | `模板图片ID`        | 字符串  | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
 | `区域左上角x`       | 数字    | 是       | -                           | 搜索区域左上角坐标                                                                                                            |
 | `区域左上角y`       | 数字    | 是       | -                           | 搜索区域左上角坐标                                                                                                            |
-| `区域右下角x`       | 数字    | 是       | -                           | 搜索区域右下角坐标                                                                                                            |
-| `区域右下角y`       | 数字    | 是       | -                           | 搜索区域右下角坐标                                                                                                            |
-| `阈值`              | 数字    | 是       | -                           | 匹配阈值 (0.0-1.0) 全分辨率匹配时建议 0.5-0.6 其他建议 0.9-0.995                                                              |
+| `区域右下角x`       | 数字    | 是       | -                           | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧边界                                                                             |
+| `区域右下角y`       | 数字    | 是       | -                           | 搜索区域右下角坐标；传 `0` 表示延伸到图片底部边界                                                                             |
+| `阈值`              | 数字    | 是       | -                           | 匹配阈值 (0.0-1.0)。方法 `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995`                              |
 | `限制数量`          | 数字    | 是       | -                           | 最大查找数量，每个模板图片最多找 限制数量 个匹配结果                                                                          |
-| `方法`              | 数字    | 是       | -                           | 匹配方法 0 SIFT 全分辨率 1 TM_SQDIFF_NORMED 3 TM_CCORR_NORMED 5 TM_CCOEFF_NORMED 99 全分辨率缩放匹配法                        |
+| `方法`              | 数字    | 是       | -                           | 匹配方法，见下方说明                                                                                                          |
 | `是否使用RGB找图`   | 布尔值  | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                              |
-| `选项`              | 对象    | 否       | -                           | 选项                                                                                                                          |
-| `选项.scaleFactors` | 数字\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 缩放匹配法缩放因子数组，默认 `[1.0, 0.9, 1.1, 0.8, 1.2]` 会在这些缩放比例下进行匹配。                                         |
+| `选项`              | 对象    | 否       | -                           | 额外选项，目前仅 方法=`99` 时生效                                                                                             |
+| `选项.scaleFactors` | 数字\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 方法=`99` 生效。模板相对当前图的缩放比列表（**不是** `$设备.获取屏幕缩放比例()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+
+#### 方法（method）匹配说明
+
+| 方法 | 名称               | 原理简述                                                                                         | 适用场景                                         | 速度     |
+| ---- | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- |
+| `5`  | TM_CCOEFF_NORMED   | 标准模板匹配（归一化相关系数），模板必须与目标**像素尺寸一致**                                   | 同分辨率、同尺寸截图模板，最常用                 | 快       |
+| `3`  | TM_CCORR_NORMED    | 标准模板匹配（归一化相关）                                                                       | 同尺寸模板；PNG 透明模板带 mask 时内部会优先用它 | 快       |
+| `1`  | TM_SQDIFF_NORMED   | 标准模板匹配（归一化平方差），分数越小越像，引擎已换算为越大越像                                 | 同尺寸模板                                       | 快       |
+| `0`  | SIFT 全分辨率      | 提取 SIFT 特征点做匹配，对旋转、轻微形变更鲁棒，不要求模板与目标同尺寸                           | 目标可能旋转/形变，或跨分辨率找图                | 较慢     |
+| `99` | 全分辨率缩放匹配法 | 把**模板**按多个比例缩放后，再做 `TM_CCOEFF_NORMED` 模板匹配（有透明通道时用 `TM_CCORR_NORMED`） | 目标与模板尺寸不完全一致，但形状相同             | 中等偏慢 |
+
+#### 什么是「缩放」全分辨率找图（方法 = 99）
+
+这里的「缩放」**不是**把屏幕截图缩小，也**不是**设备显示缩放（`$设备.获取屏幕缩放比例()`），而是：
+
+> 在匹配前，把**模板小图**按 `scaleFactors` 里的比例逐个放大/缩小，再与**原尺寸**搜索区域做模板匹配。
+
+- `factor = 1.0`：模板保持原像素尺寸去匹配
+- `factor < 1.0`：先把模板缩小再匹配（当前屏幕上的目标比模板更小）
+- `factor > 1.0`：先把模板放大再匹配（当前屏幕上的目标比模板更大）
+
+引擎内部是对模板做等比缩放（横向、纵向同一个比例）。  
+返回结果里的 `width` / `height` 是缩放后的模板尺寸，`scaleX` / `scaleY` 是本次命中用到的比例。
+
+工作流程：
+
+1. 读取搜索区域（大图）和模板（小图），默认转灰度（`是否使用RGB找图=true` 时保留彩色）。
+2. 按 `scaleFactors` **数组顺序**，对模板执行等比缩放。
+3. 若缩放后的模板比搜索区域还大，跳过该比例。
+4. 用缩放后的模板做 `TM_CCOEFF_NORMED` 匹配（透明 PNG 用 `TM_CCORR_NORMED` + alpha mask）。
+5. 收集 `confidence >= 阈值` 的命中；重叠区域去重，保留置信度更高者。
+6. 找满 `限制数量` 个后提前结束——所以**更可能命中的比例要放前面**。
+
+#### 如何选择 `scaleFactors`（重点）
+
+`scaleFactors` 不是随便填几个小数，而是回答这个问题：
+
+> 「模板图里的目标，到当前屏幕上会变成原来的几倍宽/高？」
+
+##### 1. 先算「目标比例」baseScale
+
+UI 随分辨率等比变化时（大多数 App / 游戏界面）：
+
+```text
+baseScale = 当前设备逻辑宽 / 截取模板时设备的逻辑宽
+```
+
+也可用高：
+
+```text
+baseScale = 当前设备逻辑高 / 截取模板时设备的逻辑高
+```
+
+宽高比一致时两者相同；不一致时优先用**与布局更相关的那条边**（竖屏 App 常用高，横屏游戏常用宽），或取两者平均。
+
+这里的「逻辑宽高」请用找图坐标系对应的尺寸，一般是 `$设备.获取屏幕实际宽高()`（实际像素分辨率）。  
+**不要**把 `$设备.获取屏幕缩放比例()`（屏幕 scale 因子）直接当成 `scaleFactors` 里的值——两者不是一回事。
+
+若你确切知道模板像素尺寸和屏幕上目标像素尺寸，也可以直接：
+
+```text
+baseScale = 屏幕上目标宽度(px) / 模板宽度(px)
+// 或
+baseScale = 屏幕上目标高度(px) / 模板高度(px)
+```
+
+**数值例子：**
+
+| 截模板设备     | 当前运行设备   | 计算        | baseScale |
+| -------------- | -------------- | ----------- | --------- |
+| iPhone 8 750px | 同机           | 750 / 750   | `1.0`     |
+| 750 宽         | 1170 宽        | 1170 / 750  | `1.56`    |
+| 1170 宽        | 750 宽         | 750 / 1170  | `0.641`   |
+| 1080 宽安卓    | 1440 宽安卓    | 1440 / 1080 | `1.333`   |
+| 模板按钮 120px | 屏上按钮 96px  | 96 / 120    | `0.8`     |
+
+含义对照：
+
+| baseScale | 含义                                         | 引擎会对模板做什么 |
+| --------- | -------------------------------------------- | ------------------ |
+| `1.0`     | 当前目标与模板同尺寸                         | 不缩放             |
+| `0.64`    | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配    |
+| `1.56`    | 当前目标大约是模板的 156%（低分屏模板跑高分） | 放大到 156% 再匹配 |
+
+##### 2. 再围绕 baseScale 生成搜索列表
+
+真实设备上还会有状态栏、安全区、App 缩放、截图工具裁切误差等，baseScale 很少绝对精确，所以要在 baseScale **附近扫一小段**：
+
+```text
+scaleFactors ≈ [ baseScale,
+                 baseScale ± step,
+                 baseScale ± 2*step,
+                 ... ]
+```
+
+推荐参数：
+
+| 项目           | 建议                               | 原因                                       |
+| -------------- | ---------------------------------- | ------------------------------------------ |
+| 中心值         | 算出来的 `baseScale`               | 最可能命中，必须放第一位                   |
+| 步进 `step`    | `0.05`～`0.1`                      | 太疏容易跳过真实尺寸；太密浪费时间         |
+| 半宽度         | `±0.1`～`±0.2`（约 ±10%～20%）     | 覆盖状态栏/安全区/轻微布局差               |
+| 总档数         | 3～7 个                            | 每多一档就多跑一轮全图模板匹配             |
+| 阈值           | `0.5`～`0.6` 起调                  | 缩放插值会降低相关分数，别用 0.9+          |
+| 顺序           | **baseScale 最先**，再左右交替扩开 | 找满限制数量会提前结束                     |
+
+生成示例：
+
+```javascript
+// 截模板时的设备宽（写进脚本配置，或写在模板文件名里）
+const 模板设备宽 = 750;
+// 当前设备实际宽
+const 当前宽 = $设备.获取屏幕实际宽高().width;
+const baseScale = 当前宽 / 模板设备宽;
+
+// 围绕 baseScale，步进 0.05，左右各扩 2 档 → 共 5 个
+function 生成缩放比例(base, step = 0.05, halfRange = 2) {
+  const list = [Number(base.toFixed(4))];
+  for (let i = 1; i <= halfRange; i++) {
+    list.push(Number((base - step * i).toFixed(4)));
+    list.push(Number((base + step * i).toFixed(4)));
+  }
+  // 过滤掉无意义的比例
+  return list.filter((s) => s > 0.05 && s < 8);
+}
+
+const scaleFactors = 生成缩放比例(baseScale);
+// 例如 baseScale=1.56, step=0.05, halfRange=2
+// → [1.56, 1.51, 1.61, 1.46, 1.66]
+```
+
+##### 3. 按场景怎么选
+
+| 场景                                   | 怎么设 `scaleFactors`                                          | 阈值          |
+| -------------------------------------- | -------------------------------------------------------------- | ------------- |
+| 模板就是本机截的，尺寸确定一致         | 不必用 99，直接方法 `5`；若坚持用 99 则 `[1.0]`                | `0.9+` / `0.55` |
+| 已知截图机型与当前机型分辨率           | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档                  | `0.5`～`0.6`  |
+| 多机型跑同一套模板，分辨率跨度大       | 按每台设备运行时动态算 baseScale，不要写死默认那组             | `0.5`～`0.6`  |
+| 完全不知道模板来源分辨率               | 先用方法 `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右    |
+| 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]`                                | `0.55`～`0.65` |
+| 横竖屏切换 / 目标会旋转                | 方法 `99` **不够**，改用方法 `0` SIFT                          | `0.5`～`0.6`  |
+
+默认值 `[1.0, 0.9, 1.1, 0.8, 1.2]` 的定位：
+
+- 假设「模板大致接近当前尺寸」，在 80%～120% 之间盲扫
+- **只适合尺寸差不大的兜底**，不适合 750 ↔ 1170 这种跨度（baseScale≈1.56，默认列表根本扫不到）
+- 生产脚本应**按设备算 baseScale**，不要依赖这组默认值硬扛跨分辨率
+
+##### 4. 常见误区
+
+1. **把 `$设备.获取屏幕缩放比例()` 填进 scaleFactors**  
+   获取屏幕缩放比例是屏幕 scale（如 2x/3x 显示倍率），不是「模板相对当前图」的缩放比。
+
+2. **跨大分辨率仍用默认 `[1.0, 0.9, 1.1, 0.8, 1.2]`**  
+   真实 baseScale 在 1.5 时，默认列表全军覆没。
+
+3. **阈值仍用 0.9**  
+   resize 插值会损失细节，方法 `99` 相关分通常明显低于同尺寸方法 `5`，建议从 `0.55` 左右调。
+
+4. **档位又多又密**  
+   全屏 × 10 个 factor ≈ 10 次模板匹配，卡顿明显。先算准 baseScale，再小范围扩。
+
+5. **模板含大量透明/JPEG 压缩噪点**  
+   缩放后更易误匹配；优先 PNG 透明模板，并尽量裁紧目标外轮廓。
+
+6. **搜索区域小于放大后的模板**  
+   该 factor 会被跳过。放大场景请保证 ROI 足够大，或全屏搜。
+
+##### 5. 与方法 `0`（SIFT）怎么选
+
+|                | 方法 `99` 缩放匹配                 | 方法 `0` SIFT                      |
+| -------------- | ---------------------------------- | ---------------------------------- |
+| 尺寸变化       | 支持（靠你提供的比例穷举）         | 支持（特征点，不靠固定比例）       |
+| 你需要知道比例 | 最好先算 baseScale                 | 不需要                             |
+| 旋转 / 形变    | 基本不支持                         | 较鲁棒                             |
+| 阈值建议       | `0.5`–`0.6`                        | `0.5`–`0.6`                        |
+| 透明 PNG 模板  | 支持（alpha 作权重 mask）          | 支持（alpha 作特征掩码）           |
+| 性能           | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢               |
+| 推荐           | 比例可估算的跨分辨率找图           | 比例未知、或有旋转/透视时          |
 
 **返回值：**
 
-| 类型   | 描述                                                                                   |
-| ------ | -------------------------------------------------------------------------------------- |
-| `数组` | 找到的匹配结果数组，每个元素包含位置、尺寸和置信度，其中 index 为模板图片索引从 0 开始 |
+| 类型   | 描述                                                                                                                                  |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `数组` | 匹配结果数组。`index` 为模板在 `模板图片ID` 中的索引（从 0 开始）。方法=`99` 时额外包含 `scaleX`、`scaleY`（本次命中使用的缩放比） |
 
 **示例：**
 
 ```javascript
+// 1) 同分辨率标准找图（最常用，模板就是本机截的）
 const 匹配区域数组 = $图片.找图(
   "screen",
   "template.jpg|template2.jpg",
   0,
   0,
   400,
-  800, // 搜索区域
-  0.8, // 80% 匹配度
-  3, // 最多找 3 个
-  5, // 匹配方法
-  false, // 不使用 rgb 找图
+  800,
+  0.9,
+  3,
+  5, // TM_CCOEFF_NORMED
+  false,
 );
 
 if (匹配区域数组.length > 0) {
   const best = 匹配区域数组[0];
   $打印信息日志(`找到匹配，置信度: ${best.confidence}`);
+  $动作.点击(best.centerX, best.centerY, 100, false);
+}
 
-  // 点击匹配区域的中心
-  const centerX = best.centerX;
-  const centerY = best.centerY;
-  $动作.点击(centerX, centerY, 100, false);
+// 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
+//    假设模板是在宽度 750 的设备上截的
+const 模板设备宽 = 750;
+const 当前宽 = $设备.获取屏幕实际宽高().width;
+const baseScale = 当前宽 / 模板设备宽;
+
+function 生成缩放比例(base, step = 0.05, halfRange = 2) {
+  const list = [Number(base.toFixed(4))];
+  for (let i = 1; i <= halfRange; i++) {
+    list.push(Number((base - step * i).toFixed(4)));
+    list.push(Number((base + step * i).toFixed(4)));
+  }
+  return list.filter((s) => s > 0.05 && s < 8);
 }
+
+const scaleFactors = 生成缩放比例(baseScale);
+// 750 → 1170 时约等于 [1.56, 1.51, 1.61, 1.46, 1.66]
+$打印信息日志(
+  `baseScale=${baseScale.toFixed(3)} scaleFactors=${JSON.stringify(scaleFactors)}`,
+);
+
+const 缩放匹配 = $图片.找图(
+  "screen",
+  "btn_start.png",
+  0,
+  0,
+  0,
+  0, // 全屏；放大模板时 ROI 太小会被跳过
+  0.55, // 多尺度建议 0.5-0.6，不要用 0.9
+  1,
+  99,
+  false,
+  { scaleFactors },
+);
+
+if (缩放匹配.length > 0) {
+  const hit = 缩放匹配[0];
+  $打印信息日志(
+    `命中 scale=${hit.scaleX} 尺寸=${hit.width}x${hit.height} 置信度=${hit.confidence}`,
+  );
+  $动作.点击(hit.centerX, hit.centerY, 100, false);
+}
+
+// 3) 已知模板宽和屏幕目标大概宽时，直接用像素比
+// const baseScale = 预期目标宽度px / 模板宽度px;
 ```
 
 ## 图像处理