ms-vite-plugin 1.4.56 → 1.4.58

package/docs/AGENTS.md

@@ -13,7 +13,7 @@
 - Lua 项目使用 Lua 文档与写法。
 - 不要混用 JavaScript、Python 与 Lua API。
 - Lua 只提供英文方法，没有中文别名。
-- Lua 模块通过 `require("device")` 加载；`Sleep`、`StartThread` 等是裸全局。
+- Lua 模块通过 `require("device")` 加载；`Sleep`、`StartThread`、`logd` / `logi` / `logw` / `loge` 等是裸全局。
 - 不要把快点JS Python 脚本当成普通 CPython 脚本。
 - 不要对快点JS Python 脚本运行 `python -m py_compile`、`py_compile` 或类似 CPython 编译校验。
 - 不要创建、保留或同步 `__pycache__`、`.pyc` 作为项目改动。

package/docs/SKILL.md

@@ -20,7 +20,7 @@ description: 快点JS专用开发助手。用于快点JS项目开发、本地 AP
 - Lua 项目使用 Lua 文档与写法。
 - 不要混用 JavaScript、Python 与 Lua API。
 - Lua 只提供英文方法，没有中文别名。
-- Lua 模块通过 `require("device")` 加载；`Sleep`、`StartThread` 等是裸全局。
+- Lua 模块通过 `require("device")` 加载；`Sleep`、`StartThread`、`logd` / `logi` / `logw` / `loge` 等是裸全局。
 - Lua 用户模块请用 `require("foo")` / `require("lib.bar")`。Release 打包默认会把 `scripts` 下除 `main.lua` 外的用户 `.lua` 合并进单个 `main.lua`；不要用 `dofile` / `loadfile` 按路径加载这些文件。
 - 文档未确认的能力必须明确说明无法确认，并给出保守方案。
 - 快点JS Python 脚本不使用 CPython 编译校验；不要运行 `python -m py_compile`、`py_compile` 或类似命令。

package/docs/api/image.md

@@ -504,6 +504,7 @@ function findImage(
   rgb?: boolean,
   options?: {
     scaleFactors?: number[];
+    orz?: number;
   },
 ): {
   index: number; // 模板图片索引，从 0 开始
@@ -533,8 +534,9 @@ function findImage(
 | `limit`                | number    | 是       | -                           | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                                    |
 | `method`               | number    | 是       | -                           | 匹配方法，见下方说明                                                                                                                 |
 | `rgb`                  | boolean   | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                                     |
-| `options`              | object    | 否       | -                           | 额外选项，目前仅 method=`99` 时生效                                                                                                  |
+| `options`              | object    | 否       | -                           | 额外选项。`scaleFactors` 仅 method=`99` 生效；`orz` 用于按方向取结果                                                                 |
 | `options.scaleFactors` | number\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+| `options.orz`          | number    | 否       | 不传                        | 查找方向（1-8），与找色 `orz` 相同。不传或非 1-8 时仍按相似度从高到低返回。传入 1-8 时按该方向取前 `limit` 个达标结果；`limit=1` 时只返回该方向第一个，不会把其余命中都找出来。method `0`（SIFT）会先完成匹配再按方向排序截取 |
 
 #### method 匹配方法说明
 
@@ -744,6 +746,24 @@ if (matches.length > 0) {
   action.click(best.centerX, best.centerY, 100, false);
 }
 
+// 只要右下角那一个（界面上可能有很多份，不必全找出来）
+const corner = image.findImage(
+  "screen",
+  "btn.png",
+  0,
+  0,
+  0,
+  0,
+  0.9,
+  1,
+  5,
+  false,
+  { orz: 5 }, // 与找色相同：5 右下角起，纵向开始
+);
+if (corner.length > 0) {
+  action.click(corner[0].centerX, corner[0].centerY, 100, false);
+}
+
 // 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
 //    假设模板是在宽度 750 的设备上截的
 const templateDeviceWidth = 750;

package/docs/apicn/image.md

@@ -511,6 +511,7 @@ function 找图(
   是否使用RGB找图?: 布尔值,
   选项?: {
     scaleFactors?: 数字[];
+    orz?: 数字;
   },
 ): {
   index: 数字; // 模板图片索引，从 0 开始
@@ -542,8 +543,9 @@ function 找图(
 | `限制数量`          | 数字    | 是       | -                           | 最大查找数量，每个模板图片最多找 限制数量 个匹配结果                                                                          |
 | `方法`              | 数字    | 是       | -                           | 匹配方法，见下方说明                                                                                                          |
 | `是否使用RGB找图`   | 布尔值  | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                              |
-| `选项`              | 对象    | 否       | -                           | 额外选项，目前仅 方法=`99` 时生效                                                                                             |
+| `选项`              | 对象    | 否       | -                           | 额外选项。`scaleFactors` 仅 方法=`99` 生效；`orz` 用于按方向取结果                                                             |
 | `选项.scaleFactors` | 数字\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 方法=`99` 生效。模板相对当前图的缩放比列表（**不是** `$设备.获取屏幕缩放比例()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+| `选项.orz`          | 数字    | 否       | 不传                        | 查找方向（1-8），与单点找色的查找方向相同。不传或非 1-8 时仍按相似度从高到低返回。传入 1-8 时按该方向取前 `限制数量` 个达标结果；`限制数量=1` 时只返回该方向第一个，不会把其余命中都找出来。方法 `0`（SIFT）会先完成匹配再按方向排序截取 |
 
 #### 方法（method）匹配说明
 
@@ -753,6 +755,24 @@ if (匹配区域数组.length > 0) {
   $动作.点击(best.centerX, best.centerY, 100, false);
 }
 
+// 只要右下角那一个（界面上可能有很多份，不必全找出来）
+const 右下角 = $图片.找图(
+  "screen",
+  "btn.png",
+  0,
+  0,
+  0,
+  0,
+  0.9,
+  1,
+  5,
+  false,
+  { orz: 5 }, // 与单点找色相同：5 右下角起，纵向开始
+);
+if (右下角.length > 0) {
+  $动作.点击(右下角[0].centerX, 右下角[0].centerY, 100, false);
+}
+
 // 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
 //    假设模板是在宽度 750 的设备上截的
 const 模板设备宽 = 750;

package/docs/apilua/global.md

@@ -18,6 +18,7 @@
 - **时间工具**: 获取时间戳
 - **应用控制**: 切换应用到前台
 - **Agent 设置**: 读取和设置 Agent 触控模式
+- **日志输出**: 全局 `logd` / `logi` / `logw` / `loge`，等同 `logger` 对应方法
 
 ## 全局常量
 
@@ -652,3 +653,97 @@ function ToJsonString(data) end
 print(ToJsonString({ a = 1, b = 2 }))
 ```
 
+## 全局日志函数
+
+全局日志函数是 `logger` 模块对应方法的便捷别名，可以直接调用而无需 `require("logger")`。可变参会按空格拼接为一行。级别和是否写文件仍由 `logger.setLoggerLevel` / `logger.setLogToFile` 控制。
+
+`print` 仍可用，默认走信息级别；需要调试 / 警告 / 错误级别时用下面这些函数。
+
+### logd
+
+输出调试级别的日志，等同于 `logger.debug(...)`。
+
+```lua
+---@param ... any
+function logd(...) end
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `...`  | any  | 是       | -      | 要输出的日志内容 |
+
+**示例:**
+
+```lua
+logd("程序开始执行")
+logd("当前用户:", username)
+```
+
+### logi
+
+输出信息级别的日志，等同于 `logger.info(...)`。
+
+```lua
+---@param ... any
+function logi(...) end
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `...`  | any  | 是       | -      | 要输出的日志内容 |
+
+**示例:**
+
+```lua
+logi("应用程序启动成功")
+logi("处理了", count, "条记录")
+```
+
+### logw
+
+输出警告级别的日志，等同于 `logger.warn(...)`。
+
+```lua
+---@param ... any
+function logw(...) end
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `...`  | any  | 是       | -      | 要输出的日志内容 |
+
+**示例:**
+
+```lua
+logw("电池电量低于 20%")
+logw("网络连接不稳定")
+```
+
+### loge
+
+输出错误级别的日志，等同于 `logger.error(...)`。
+
+```lua
+---@param ... any
+function loge(...) end
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `...`  | any  | 是       | -      | 要输出的日志内容 |
+
+**示例:**
+
+```lua
+loge("网络请求失败")
+loge("文件读取错误")
+```
+

package/docs/apilua/image.md

@@ -614,8 +614,9 @@ function findImage(imageId, templateImageId, x, y, ex, ey, threshold, limit, met
 | `limit`                | number    | 是       | -                           | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                                    |
 | `method`               | number    | 是       | -                           | 匹配方法，见下方说明                                                                                                                 |
 | `rgb`                  | boolean   | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                                     |
-| `options`              | table    | 否       | -                           | 额外选项，目前仅 method=`99` 时生效                                                                                                  |
+| `options`              | table    | 否       | -                           | 额外选项。`scaleFactors` 仅 method=`99` 生效；`orz` 用于按方向取结果                                                                 |
 | `options.scaleFactors` | number\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+| `options.orz`          | number    | 否       | 不传                        | 查找方向（1-8），与找色 `orz` 相同。不传或非 1-8 时仍按相似度从高到低返回。传入 1-8 时按该方向取前 `limit` 个达标结果；`limit=1` 时只返回该方向第一个，不会把其余命中都找出来。method `0`（SIFT）会先完成匹配再按方向排序截取 |
 
 #### method 匹配方法说明
 
@@ -824,6 +825,24 @@ if #matches > 0 then
   print("找到匹配，置信度: " .. tostring(best.confidence))
   action.click(best.centerX, best.centerY, 100, false)
 end
+
+-- 只要右下角那一个（界面上可能有很多份，不必全找出来）
+local corner = image.findImage(
+  "screen",
+  "btn.png",
+  0,
+  0,
+  0,
+  0,
+  0.9,
+  1,
+  5,
+  false,
+  { orz = 5 } -- 与找色相同：5 右下角起，纵向开始
+)
+if #corner > 0 then
+  action.click(corner[1].centerX, corner[1].centerY, 100, false)
+end
 -- 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
 --    假设模板是在宽度 750 的设备上截的
 local templateDeviceWidth = 750

package/docs/apilua/logger.md

@@ -14,6 +14,8 @@
 
 - **关闭存储日志** 可使用 `setLogToFile(false)` 关闭将日志输出到文件的功能。
 
+- **全局别名** `logd` / `logi` / `logw` / `loge` 是裸全局，分别等同 `logger.debug` / `logger.info` / `logger.warn` / `logger.error`，无需 `require("logger")`。
+
 ## 日志级别
 
 日志模块支持以下级别（按严重程度排序）：

package/docs/apipython/image.md

@@ -479,8 +479,9 @@ def findImage(id: str, templateImageId: str, x: int, y: int, ex: int, ey: int, t
 | `limit`                | int          | 是       | <br />                      | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                             |
 | `method`               | int          | 是       | <br />                      | 匹配方法，见下方说明                                                                                                          |
 | `rgb`                  | bool         | 否       | `False`                     | 是否使用 RGB 找图，默认 `False` 会自动转灰度找图                                                                              |
-| `options`              | dict         | 否       | `{}`                        | 额外选项，目前仅 method=`99` 时生效                                                                                           |
+| `options`              | dict         | 否       | `{}`                        | 额外选项。`scaleFactors` 仅 method=`99` 生效；`orz` 用于按方向取结果                                                           |
 | `options.scaleFactors` | list\[float] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+| `options.orz`          | int          | 否       | 不传                        | 查找方向（1-8），与找色 `orz` 相同。不传或非 1-8 时仍按相似度从高到低返回。传入 1-8 时按该方向取前 `limit` 个达标结果；`limit=1` 时只返回该方向第一个，不会把其余命中都找出来。method `0`（SIFT）会先完成匹配再按方向排序截取 |
 
 #### method 匹配方法说明
 
@@ -690,6 +691,23 @@ if len(matches) > 0:
     print(f"找到匹配，置信度: {best.confidence}")
     action.click(best.centerX, best.centerY, 100, False)
 
+# 只要右下角那一个（界面上可能有很多份，不必全找出来）
+corner = image.findImage(
+    "screen",
+    "btn.png",
+    0,
+    0,
+    0,
+    0,
+    0.9,
+    1,
+    5,
+    False,
+    {"orz": 5},  # 与找色相同：5 右下角起，纵向开始
+)
+if corner:
+    action.click(corner[0].centerX, corner[0].centerY, 100, False)
+
 # 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
 #    假设模板是在宽度 750 的设备上截的
 template_device_width = 750

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.56",
+  "version": "1.4.58",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {