ms-vite-plugin 1.4.55 → 1.4.56

package/docs/AGENTS.md

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

package/docs/SKILL.md

@@ -19,6 +19,9 @@ description: 快点JS专用开发助手。用于快点JS项目开发、本地 AP
 - JavaScript 项目使用 JavaScript 文档与写法。
 - Lua 项目使用 Lua 文档与写法。
 - 不要混用 JavaScript、Python 与 Lua API。
+- Lua 只提供英文方法，没有中文别名。
+- Lua 模块通过 `require("device")` 加载；`Sleep`、`StartThread` 等是裸全局。
+- 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/apilua/node.md

@@ -58,11 +58,12 @@ local listPage = node.createNodeSelector({ mode = 2 })
 
 | 字段 | 说明 |
 | --- | --- |
-| `id` | 节点 ID（内部定位用，不要改） |
+| `id` | 节点 ID，不要改 |
 | `identifier` | 控件标识符 |
 | `label` | 标签文案 |
 | `type` | 类型，如 `XCUIElementTypeButton` |
 | `value` | 当前值 |
+| `placeholderValue` | 输入框占位文字 |
 | `title` | 标题 |
 | `enabled` | 是否启用 |
 | `visible` | 是否可见 |
@@ -76,8 +77,16 @@ local listPage = node.createNodeSelector({ mode = 2 })
 
 | 方法 | 说明 |
 | --- | --- |
+| `hittable()` | 当前是否可点击（可见且未被挡住） |
+| `scrollToVisible()` | 仅滚动到可见，不点击；一般不必手动调用 |
+| `tap()` | 单击；不可见时会先自动滚到可见 |
+| `doubleTap()` | 双击；不可见时会先自动滚到可见 |
+| `press(duration?)` | 长按，`duration` 单位毫秒，默认 500；不可见时会先自动滚到可见 |
 | `clickCenter()` | 点击中心坐标（坐标点击，不会自动滚动） |
 | `clickRandom()` | 在节点范围内随机点击（坐标点击，不会自动滚动） |
+| `clearInput()` | 清空输入；不可见时会先自动滚到可见 |
+| `input(text)` | 追加输入，不清空原内容；不可见时会先自动滚到可见 |
+| `setValue(text)` | 设置值（见下方；不可见时会先自动滚到可见） |
 | `parent()` | 父节点 |
 | `child(index)` | 第 `index` 个子节点 |
 | `allChildren()` | 全部子节点 |
@@ -93,7 +102,7 @@ local listPage = node.createNodeSelector({ mode = 2 })
 
 | 方法 | 说明 |
 | --- | --- |
-| `releaseNode()` | 立刻释放选择器；与 `<close>` 二选一即可，重复调用安全 |
+| `releaseNode()` | 立刻释放选择器；与 `<close>` 二选一即可 |
 | `loadNode(timeout?)` | 重新加载界面节点，默认超时 5000ms |
 | `clearSelector()` | 清除已设置的筛选条件 |
 | `xml(timeout?)` | 获取界面 XML，失败返回 `nil` |
@@ -115,7 +124,7 @@ selector:releaseNode()  -- 手动释放
 
 ### 筛选条件
 
-可链式调用，多个条件同时满足（并且关系）。  
+可链式调用，多个条件同时满足（并且关系）。
 带 `Match` 的为模糊/正则匹配。
 
 **文本**
@@ -126,6 +135,7 @@ selector:releaseNode()  -- 手动释放
 | `title` / `titleMatch` | 标题 |
 | `identifier` / `identifierMatch` | 标识符 |
 | `value` / `valueMatch` | 值 |
+| `placeholderValue` / `placeholderValueMatch` | 占位文字 |
 
 **类型与状态**
 
@@ -152,6 +162,7 @@ selector:label("确定"):type("XCUIElementTypeButton"):getOneNodeInfo(3000)
 -- 模糊
 selector:labelMatch(".*登录.*"):getNodeInfo(3000)
 selector:identifierMatch("^login_"):getNodeInfo(3000)
+selector:placeholderValue("请输入账号"):getOneNodeInfo(3000)
 -- 组合
 selector
   :type("XCUIElementTypeTextField")
@@ -165,25 +176,76 @@ selector
 
 ## 节点操作说明
 
+### 是否可点 / 滚到可见
+
+`tap` / `doubleTap` / `press` / `setValue` / `clearInput` / `input` 在元素当前不可见时，会**自动**先滚到可见再操作，一般不用手写滚动：
+
+```lua
+-- 推荐：直接操作，不可见时会自动滚到可见
+btn:tap()
+btn:doubleTap()
+btn:press(800)
+btn:setValue("hello")
+```
+
+- `hittable()`：当前能否点到（可见且未被挡住），用于排查“点了没反应”
+- `scrollToVisible()`：只滚到可见、不点击；仅在你想先露出元素、稍后再操作时使用
+- `clickCenter()` / `clickRandom()`：按坐标点击，**不会**自动滚动
+
 ### 点击
 
 | 方法 | 说明 |
 | --- | --- |
+| `tap()` | 推荐，单击；不可见时自动滚到可见 |
+| `doubleTap()` | 双击；不可见时自动滚到可见 |
+| `press(ms?)` | 长按，默认 500ms；不可见时自动滚到可见 |
 | `clickCenter()` | 点中心坐标，不自动滚动 |
 | `clickRandom()` | 范围内随机点，不自动滚动 |
 
-输入请配合 `ime` 或 `action.input`。
-
 ```lua
 local node = require("node")
 local selector <close> = node.createNodeSelector()
 local btn = selector:label("确定"):type("XCUIElementTypeButton"):getOneNodeInfo(3000)
 
 if btn then
-  btn:clickCenter()
+  btn:tap()
+  btn:doubleTap()
+  btn:press(800)
 end
 ```
 
+### 输入与设值
+
+| 方法 | 说明 |
+| --- | --- |
+| `clearInput()` | 清空；不可见时也会自动滚到可见 |
+| `input(text)` | 追加输入，不清空原内容 |
+| `setValue(text)` | 按控件类型设置；不可见时会先自动滚到可见 |
+
+**`setValue` 行为**
+
+| 控件类型 | 传参 | 效果 |
+| --- | --- | --- |
+| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项（控件本身不可见时也会先自动滚到可见） |
+| 文本框类（TextField 等） | 字符串 | 聚焦后追加输入，不先清空 |
+
+覆盖原内容请先清空：
+
+```lua
+field:clearInput()
+field:setValue("hello")
+-- 或
+field:clearInput()
+field:input("hello")
+```
+
+```lua
+local wheel = selector:type("XCUIElementTypePickerWheel"):getOneNodeInfo(3000)
+if wheel then
+  -- 不可见时会自动滚到可见，再调到目标选项
+  wheel:setValue("1小时")
+end
+```
 
 ### 树导航
 
@@ -191,10 +253,10 @@ end
 local field = selector:type("XCUIElementTypeTextField"):getOneNodeInfo(3000)
 if field then
   local parent = field:parent()
-  local children = parent:allChildren()  or  []
+  local children = parent and parent:allChildren() or {}
   local prev = field:previousSiblings()
   local next = field:nextSiblings()
-  local second = parent:child(1)
+  local second = parent and parent:child(1)
 end
 ```
 
@@ -206,14 +268,12 @@ end
 
 ```lua
 local node = require("node")
-local ime = require("ime")
 local selector <close> = node.createNodeSelector()
 
 local user = selector:type("XCUIElementTypeTextField"):getOneNodeInfo(5000)
 if user then
-  user:clickCenter()
-  ime.clearText()
-  ime.input("demo_user")
+  user:clearInput()
+  user:setValue("demo_user")
 end
 
 local pass = selector
@@ -221,9 +281,8 @@ local pass = selector
   :type("XCUIElementTypeSecureTextField")
   :getOneNodeInfo(3000)
 if pass then
-  pass:clickCenter()
-  ime.clearText()
-  ime.input("password")
+  pass:clearInput()
+  pass:setValue("password")
 end
 
 local login = selector
@@ -232,7 +291,7 @@ local login = selector
   :type("XCUIElementTypeButton")
   :getOneNodeInfo(3000)
 if login then
-  login:clickCenter()
+  login:tap()
 end
 ```
 
@@ -243,7 +302,7 @@ local node = require("node")
 local selector <close> = node.createNodeSelector({ mode = 2 })
 local item = selector:label("第 30 项"):getOneNodeInfo(5000)
 if item then
-  item:clickCenter()
+  item:tap() -- 不在可见区域时会自动滚动
 end
 ```
 
@@ -262,14 +321,17 @@ selector:releaseNode()
 
 ## 常见问题
 
-**找不到节点**  
+**找不到节点**
 加大超时；减少条件或改用 `*Match`；换 `mode`；用 `xml()` 看实际文案和类型。
 
-**点了没反应**  
-确认点到的是目标控件；用 `clickCenter()` / `clickRandom()` 按坐标点击。
+**点了没反应**
+先看 `hittable()`；确认点到的是目标控件；可对比 `clickCenter()`。
+
+**输入叠在旧文字后面**
+`input` / 文本类 `setValue` 是追加，先 `clearInput()`。
 
-**输入叠在旧文字后面**  
-节点没有输入方法，请先 `ime.clearText()` 再 `ime.input()`。
+**滚轮设不中**
+`setValue` 要传界面上显示的选项文案；确认类型是 `PickerWheel`；多列时选对那一列。
 
 **要不要释放**
 要。用 `<close>` 自动释放，或用完调 `releaseNode()`，两种都行。

package/docs/apilua/opencv.md

@@ -59,7 +59,7 @@ local gray = cv.cvtColor(src, { code = cv.COLOR_BGR2GRAY })
 local edges = cv.Canny(gray, { threshold1 = 100, threshold2 = 200 })
 local feat = cv.SIFT(gray, { nfeatures = 500 })
 if feat then
-  logi("keypoints=" .. tostring(#feat.keypoints))
+  print("keypoints=" .. tostring(#feat.keypoints))
   cv.release(feat.descriptors)
 end
 cv.imwrite(file.getInternalDir("documents") .. "/edges.png", edges)
@@ -143,9 +143,11 @@ function imread(path) end
 
 ```lua
 local cv = require("cv")
+local file = require("file")
+local image = require("image")
 local a = cv.imread("template.png")
 local dir = file.getInternalDir("documents")
-local b = cv.imread(`${dir}/shot.jpg`)
+local b = cv.imread(dir .. "/shot.jpg")
 local imageId = image.captureFullScreen()
 local c = cv.imread(imageId)
 image.release(imageId)
@@ -205,8 +207,9 @@ function imwrite(path, mat) end
 
 ```lua
 local cv = require("cv")
+local file = require("file")
 local src = cv.capture()
-cv.imwrite(`${file.getInternalDir("documents")}/out.png`, src)
+cv.imwrite(file.getInternalDir("documents") .. "/out.png", src)
 cv.release(src)
 ```
 
@@ -314,7 +317,7 @@ local cv = require("cv")
 local a = cv.capture()
 local b = cv.clone(a)
 cv.release(a)
-logi(cv.isRelease(a)); // true
+print(cv.isRelease(a)) -- true
 cv.release(b)
 ```
 
@@ -556,17 +559,17 @@ local cv = require("cv")
 cv.rectangle(src, {
   pt1 = { x = 10, y = 10 },
   pt2 = { x = 100, y = 80 },
-  color = [0, 0, 255],
+  color = { 0, 0, 255 },
   thickness = 2,
 })
 cv.circle(src, { center = { x = 50, y = 50 }, radius = 20, color = "#00FF00", thickness = -1 })
-cv.line(src, { pt1 = { x = 0, y = 0 }, pt2 = { x = 100, y = 100 }, color = [255, 0, 0], thickness = 2 })
+cv.line(src, { pt1 = { x = 0, y = 0 }, pt2 = { x = 100, y = 100 }, color = { 255, 0, 0 }, thickness = 2 })
 cv.putText(src, {
   text = "hello",
   org = { x = 20, y = 40 },
   fontFace = cv.FONT_HERSHEY_SIMPLEX,
   fontScale = 1,
-  color = [255, 255, 255],
+  color = { 255, 255, 255 },
   thickness = 2,
 })
 ```
@@ -587,9 +590,9 @@ function fillPoly(mat, options) end
 ```lua
 local cv = require("cv")
 cv.polylines(src, {
-  pts = [[{ x = 0, y = 0 }, { x = 100, y = 0 }, { x = 100, y = 80 }, { x = 0, y = 80 }]],
+  pts = { { x = 0, y = 0 }, { x = 100, y = 0 }, { x = 100, y = 80 }, { x = 0, y = 80 } },
   isClosed = true,
-  color = [0, 255, 0],
+  color = { 0, 255, 0 },
   thickness = 2,
 })
 ```
@@ -621,11 +624,11 @@ function matchTemplate(image, templ, methodOrOptions) end
 ```lua
 local cv = require("cv")
 local loc = cv.matchTemplateLoc(src, templ, { method = cv.TM_CCOEFF_NORMED })
-logi(`best=(${loc.x},${loc.y}) max=${loc.maxVal}`)
+print(string.format("best=(%s,%s) max=%s", loc.x, loc.y, loc.maxVal))
 cv.rectangle(src, {
   pt1 = { x = loc.x, y = loc.y },
   pt2 = { x = loc.x + tw, y = loc.y + th },
-  color = [0, 0, 255],
+  color = { 0, 0, 255 },
   thickness = 2,
 })
 ```
@@ -653,8 +656,8 @@ function findContours(mat, options) end
 
 ```lua
 local cv = require("cv")
-local { contours, hierarchy } = cv.findContours(bin, { mode = cv.RETR_TREE, method = cv.CHAIN_APPROX_SIMPLE })
-logi(`count=${contours.length} h0=${hierarchy[0]}`)
+local ret = cv.findContours(bin, { mode = cv.RETR_TREE, method = cv.CHAIN_APPROX_SIMPLE })
+print("count=" .. tostring(#ret.contours))
 ```
 
 ### boundingRect / minAreaRect / contourArea / arcLength / approxPolyDP

package/package.json

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