ms-vite-plugin 1.4.47 → 1.4.49

package/docs/apipython/image.md

@@ -461,6 +461,8 @@ if imageId:
 
 ### findImage - 找图
 
+在大图（通常是屏幕截图）中查找小图（模板）。支持多种匹配算法，可按 `|` 同时传入多个模板。
+
 ```python
 def findImage(id: str, templateImageId: str, x: int, y: int, ex: int, ey: int, threshold: float, limit: int, method: int, rgb: bool = False, options: dict = {}) -> List[Rect]
 ```
@@ -472,46 +474,264 @@ def findImage(id: str, templateImageId: str, x: int, y: int, ex: int, ey: int, t
 | `imageId`              | str          | 是       | <br />                      | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）                                |
 | `templateImageId`      | str          | 是       | <br />                      | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
 | `x, y`                 | int          | 是       | <br />                      | 搜索区域左上角坐标                                                                                                            |
-| `ex, ey`               | int          | 是       | <br />                      | 搜索区域右下角坐标                                                                                                            |
-| `threshold`            | float        | 是       | <br />                      | 匹配阈值 (0.0-1.0) 全分辨率匹配时建议 0.5-0.6 其他建议 0.9-0.995                                                              |
+| `ex, ey`               | int          | 是       | <br />                      | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界                                                                       |
+| `threshold`            | float        | 是       | <br />                      | 匹配阈值 (0.0-1.0)。method `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995`                            |
 | `limit`                | int          | 是       | <br />                      | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                             |
-| `method`               | int          | 是       | <br />                      | 匹配方法 0 SIFT 全分辨率 1 TM_SQDIFF_NORMED 3 TM_CCORR_NORMED 5 TM_CCOEFF_NORMED 99 全分辨率缩放匹配法                        |
+| `method`               | int          | 是       | <br />                      | 匹配方法，见下方说明                                                                                                          |
 | `rgb`                  | bool         | 否       | `False`                     | 是否使用 RGB 找图，默认 `False` 会自动转灰度找图                                                                              |
-| `options`              | dict         | 否       | `{}`                        | 选项                                                                                                                          |
-| `options.scaleFactors` | list\[float] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 缩放匹配法缩放因子数组，默认 `[1.0, 0.9, 1.1, 0.8, 1.2]` 会在这些缩放比例下进行匹配。                                         |
+| `options`              | dict         | 否       | `{}`                        | 额外选项，目前仅 method=`99` 时生效                                                                                           |
+| `options.scaleFactors` | list\[float] | 否       | `[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`：先把模板放大再匹配（当前屏幕上的目标比模板更大）
+
+引擎内部是对模板做等比缩放（横向、纵向同一个比例）。  
+返回结果里的 `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 会提前结束                      |
+
+生成示例：
+
+```python
+from kuaijs import device
+
+# 截模板时的设备宽（写进脚本配置，或写在模板文件名里）
+template_device_width = 750
+# 当前设备实际宽
+current_width = device.getScreenRealSize().width
+base_scale = current_width / template_device_width
+
+def build_scale_factors(base, step=0.05, half_range=2):
+    scales = [round(base, 4)]
+    for i in range(1, half_range + 1):
+        scales.append(round(base - step * i, 4))
+        scales.append(round(base + step * i, 4))
+    # 过滤掉无意义的比例
+    return [s for s in scales if 0.05 < s < 8]
+
+scale_factors = build_scale_factors(base_scale)
+# 例如 base_scale=1.56, step=0.05, half_range=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 数量近似成正比，通常更快 | 特征提取重，通常更慢               |
+| 推荐           | 比例可估算的跨分辨率找图           | 比例未知、或有旋转/透视时          |
 
 **返回值：**
 
-| 类型         | 描述                                                                                       |
-| ------------ | ------------------------------------------------------------------------------------------ |
-| `List[Rect]` | 找到的匹配结果数组，每个元素包含位置、尺寸和置信度，其中 index 代表模板图片的索引从 0 开始 |
+| 类型         | 描述                                                                                                                                      |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `List[Rect]` | 匹配结果数组。`index` 为模板在 `templateImageId` 中的索引（从 0 开始）。method=`99` 时额外包含 `scaleX`、`scaleY`（本次命中使用的缩放比） |
 
 **示例：**
 
 ```python
-from kuaijs import image, action
+from kuaijs import image, action, device
 
+# 1) 同分辨率标准找图（最常用，模板就是本机截的）
 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 len(matches) > 0:
     best = matches[0]
     print(f"找到匹配，置信度: {best.confidence}")
+    action.click(best.centerX, best.centerY, 100, False)
+
+# 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
+#    假设模板是在宽度 750 的设备上截的
+template_device_width = 750
+current_width = device.getScreenRealSize().width
+base_scale = current_width / template_device_width
+
+
+def build_scale_factors(base, step=0.05, half_range=2):
+    scales = [round(base, 4)]
+    for i in range(1, half_range + 1):
+        scales.append(round(base - step * i, 4))
+        scales.append(round(base + step * i, 4))
+    return [s for s in scales if 0.05 < s < 8]
+
+
+scale_factors = build_scale_factors(base_scale)
+# 750 → 1170 时约等于 [1.56, 1.51, 1.61, 1.46, 1.66]
+print(f"baseScale={base_scale:.3f} scaleFactors={scale_factors}")
+
+scaled = image.findImage(
+    "screen",
+    "btn_start.png",
+    0,
+    0,
+    0,
+    0,  # 全屏；放大模板时 ROI 太小会被跳过
+    0.55,  # 多尺度建议 0.5-0.6，不要用 0.9
+    1,
+    99,
+    False,
+    {"scaleFactors": scale_factors},
+)
+
+if len(scaled) > 0:
+    hit = scaled[0]
+    print(
+        f"命中 scale={hit.scaleX} 尺寸={hit.width}x{hit.height} 置信度={hit.confidence}"
+    )
+    action.click(hit.centerX, hit.centerY, 100, False)
 
-    # 点击匹配区域的中心
-    centerX = best.centerX
-    centerY = best.centerY
-    action.click(centerX, centerY, 100, False)
+# 3) 已知模板宽和屏幕目标大概宽时，直接用像素比
+# base_scale = expected_target_width_px / template_width_px
 ```
 
 ## 图像处理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.47",
+  "version": "1.4.49",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {
@@ -17,7 +17,7 @@
     "ms-mcp": "dist/mcp-server.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node scripts/minify-dist.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -42,6 +42,7 @@
     "@types/node": "^25.9.0",
     "@types/uuid": "^11.0.0",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.2",
     "typescript": "~6.0.3"
   }
 }