ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/appleocr.md

@@ -0,0 +1,281 @@
+# AppleOCR 模块
+
+AppleOCR 模块基于 Apple Vision 框架，提供原生的光学字符识别（OCR）功能。该模块利用 iOS 系统内置的机器学习能力，无需额外模型文件，具有高效、准确的特点。
+
+<span style="color: red;">此模块仅支持 iOS 系统。</span>
+
+## 核心特性
+
+### 🚀 性能优势
+
+- **原生支持**: 基于 Apple Vision 框架，无需额外模型文件
+- **高性能**: 利用 iOS 系统优化，识别速度快
+- **低资源占用**: 无需加载大型模型文件
+
+### 🌍 多语言支持
+
+- **默认语言**: 中文和英文（["zh-Hans", "en-US"]）
+- **支持语言**: ["en-US", "fr-FR", "it-IT", "de-DE", "es-ES", "pt-BR", "zh-Hans", "zh-Hant"]
+
+### 📱 多种输入源
+
+- **屏幕截图**: 直接识别当前屏幕内容
+- **图片文件**: 支持本地图片文件路径
+- **图片 ID**: 通过 image 模块获取的图片 ID
+- **区域识别**: 支持指定区域的精确文字识别
+
+## 数据类型
+
+### OCRResult
+
+识别结果对象，包含以下属性：
+
+```lua
+---@class OCRResult
+---@field text string 识别的文本内容
+---@field confidence number 识别置信度 (0-1)
+---@field x number 文本区域左上角 x 坐标
+---@field y number 文本区域左上角 y 坐标
+---@field width number 文本区域宽度
+---@field height number 文本区域高度
+---@field ex number 文本区域右下角 x 坐标
+---@field ey number 文本区域右下角 y 坐标
+---@field centerX number 文本区域中心点 x 坐标
+---@field centerY number 文本区域中心点 y 坐标
+```
+
+**字段说明：**
+
+| 参数名              | 类型   | 描述                                   |
+| ------------------- | ------ | -------------------------------------- |
+| `text`              | string | 识别的文本内容                         |
+| `confidence`        | number | 识别置信度 (0-1)，值越高表示识别越准确 |
+| `x`, `y`            | number | 文本区域左上角坐标                     |
+| `width`, `height`   | number | 文本区域宽度和高度                     |
+| `ex`, `ey`          | number | 文本区域右下角坐标                     |
+| `centerX`, `centerY` | number | 文本区域中心点坐标                    |
+
+## API 参考
+
+### 文字识别
+
+#### recognize - 执行 OCR 识别。
+
+执行 OCR 识别。传入裁剪区域时，返回坐标相对于裁剪区域。全屏识别时 `x/y/ex/ey` 传 `0`。
+
+```lua
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param languages string[]?
+---@return OCRResult[]
+function recognize(input, x, y, ex, ey, languages) end
+```
+
+**参数:**
+
+| 参数名      | 类型     | 是否必填 | 默认值                  | 描述                                                                                                    |
+| ----------- | -------- | -------- | ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `input`     | string   | 是       |                         | 输入源，支持 `"screen"`、图片文件路径、URL 字符串或 imageId                                             |
+| `x`         | number   | 否       | 0                       | 裁剪区域左上角 x 坐标；全屏识别传 0                                                                     |
+| `y`         | number   | 否       | 0                       | 裁剪区域左上角 y 坐标；全屏识别传 0                                                                     |
+| `ex`        | number   | 否       | 0                       | 裁剪区域右下角 x 坐标；全屏识别传 0                                                                     |
+| `ey`        | number   | 否       | 0                       | 裁剪区域右下角 y 坐标；全屏识别传 0                                                                     |
+| `languages` | string[] | 否       | `{"zh-Hans", "en-US"}` | 识别语言数组，支持 `{"en-US", "fr-FR", "it-IT", "de-DE", "es-ES", "pt-BR", "zh-Hans", "zh-Hant"}`     |
+
+**返回值:**
+
+| 类型          | 描述                                           |
+| ------------- | ---------------------------------------------- |
+| `OCRResult[]` | 识别结果数组，坐标相对于裁剪区域               |
+
+**示例:**
+
+```lua
+local appleocr = require("appleocr")
+local action = require("action")
+
+local results = appleocr.recognize("screen", 100, 100, 500, 300)
+if #results > 0 then
+  action.click(results[1].centerX, results[1].centerY)
+end
+```
+
+#### recognizeAbs - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。
+
+```lua
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param languages string[]?
+---@return OCRResult[]
+function recognizeAbs(input, x, y, ex, ey, languages) end
+```
+
+**参数:** 与 `recognize` 相同；返回坐标为原图或全屏绝对坐标。
+
+**示例:**
+
+```lua
+local appleocr = require("appleocr")
+local action = require("action")
+local absResults = appleocr.recognizeAbs("screen", 100, 100, 500, 300)
+if #absResults > 0 then
+  action.click(absResults[1].centerX, absResults[1].centerY)
+end
+```
+
+### 数字识别
+
+#### recognizeNumbers - 执行数字 OCR 识别。
+
+执行数字 OCR 识别。传入裁剪区域时，返回坐标相对于裁剪区域。
+
+**支持字符**: 0-9 数字、逗号(,)、小数点(.)、加号(+)、减号(-)
+
+```lua
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@return OCRResult[]
+function recognizeNumbers(input, x, y, ex, ey) end
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                                                |
+| ------- | ------ | -------- | ------ | --------------------------------------------------- |
+| `input` | string | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 字符串或 imageId |
+| `x`     | number | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                 |
+| `y`     | number | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                 |
+| `ex`    | number | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0                 |
+| `ey`    | number | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0                 |
+
+**返回值:**
+
+| 类型          | 描述                                           |
+| ------------- | ---------------------------------------------- |
+| `OCRResult[]` | 数字识别结果数组，坐标相对于裁剪区域           |
+
+**示例:**
+
+```lua
+local appleocr = require("appleocr")
+local action = require("action")
+
+local numberResults = appleocr.recognizeNumbers("screen", 100, 100, 500, 300)
+if #numberResults > 0 then
+  action.click(numberResults[1].centerX, numberResults[1].centerY)
+end
+```
+
+#### recognizeNumbersAbs - 执行数字 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+**支持字符**: 0-9 数字、逗号(,)、小数点(.)、加号(+)、减号(-)
+
+```lua
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@return OCRResult[]
+function recognizeNumbersAbs(input, x, y, ex, ey) end
+```
+
+**参数:** 与 `recognizeNumbers` 相同；返回坐标为原图或全屏绝对坐标。
+
+**示例:**
+
+```lua
+local appleocr = require("appleocr")
+local absNumberResults = appleocr.recognizeNumbersAbs("screen", 100, 100, 500, 300)
+```
+
+### 文本查找
+
+#### findText - 查找目标子串。
+
+在整段识别文本中查找指定子串。传入裁剪区域时，返回坐标相对于裁剪区域。
+
+```lua
+---@param input string
+---@param texts string[]
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param languages string[]?
+---@param exactMatch boolean?
+---@return OCRResult[]
+function findText(input, texts, x, y, ex, ey, languages, exactMatch) end
+```
+
+**参数:**
+
+| 参数名       | 类型     | 是否必填 | 默认值                  | 描述                                                                                                  |
+| ------------ | -------- | -------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `input`      | string   | 是       |                         | 输入源，支持 `"screen"`、图片文件路径、URL 字符串或 imageId                                           |
+| `texts`      | string[] | 是       |                         | 要查找的目标文本数组，可匹配识别结果中的子串                                                          |
+| `x`          | number   | 否       | 0                       | 裁剪区域左上角 x 坐标；全屏识别传 0                                                                   |
+| `y`          | number   | 否       | 0                       | 裁剪区域左上角 y 坐标；全屏识别传 0                                                                   |
+| `ex`         | number   | 否       | 0                       | 裁剪区域右下角 x 坐标；全屏识别传 0                                                                   |
+| `ey`         | number   | 否       | 0                       | 裁剪区域右下角 y 坐标；全屏识别传 0                                                                   |
+| `languages`  | string[] | 否       | `{"zh-Hans", "en-US"}` | 识别语言数组                                                                                          |
+| `exactMatch` | boolean  | 否       | false                   | 是否完整匹配；`false` 表示包含匹配，`true` 要求整条 OCR 识别结果文本等于目标文本                       |
+
+**返回值:**
+
+| 类型          | 描述                                           |
+| ------------- | ---------------------------------------------- |
+| `OCRResult[]` | 命中子串的识别结果数组，坐标相对于裁剪区域     |
+
+**示例:**
+
+```lua
+local appleocr = require("appleocr")
+local action = require("action")
+
+local hits = appleocr.findText("screen", { "开始" }, 100, 100, 500, 400)
+if #hits > 0 then
+  action.click(hits[1].centerX, hits[1].centerY)
+end
+```
+
+#### findTextAbs - 查找目标子串，并将子串结果坐标映射为原图/全屏绝对坐标。
+
+传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。`texts` 也可以是逗号分隔字符串。
+
+```lua
+---@param input string
+---@param texts string[]|string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param languages string[]?
+---@param exactMatch boolean?
+---@return OCRResult[]
+function findTextAbs(input, texts, x, y, ex, ey, languages, exactMatch) end
+```
+
+**参数:** 与 `findText` 相同；返回坐标为原图或全屏绝对坐标。
+
+**示例:**
+
+```lua
+local appleocr = require("appleocr")
+local action = require("action")
+local absHits = appleocr.findTextAbs("screen", { "开始" }, 100, 100, 500, 400)
+if #absHits > 0 then
+  action.click(absHits[1].centerX, absHits[1].centerY)
+end
+```

package/docs/apilua/cloud.md

@@ -0,0 +1,183 @@
+# 云控模块 (Cloud)
+
+云控模块用于在主脚本中使用内置云控 WebSocket 连接。脚本可以主动连接云控服务器、判断连接状态、断开连接、上报事件数据，并监听服务器事件数据。
+
+## 注意事项
+
+- `cloud` 只在主脚本上下文注册，不支持在线程脚本里调用。
+- 服务器事件只有一个主脚本监听槽位，多次调用 `onEvent` 会覆盖旧监听。
+
+## 协议
+
+脚本上报数据时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptReport",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+服务器下发脚本事件时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptEvent",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+`event` 是脚本和服务器约定的自定义事件名。`data` 在 JS 中是普通 Object，必须能被 JSON 序列化。
+设备总览自定义字段读取最新一次 `cloud:status` 上报数据；上报时事件名固定为 `cloud:status`，`data` 是 key-value 对象。
+
+## API 参考
+
+### connect - 连接云控服务器
+
+```lua
+---@param url string
+---@param deviceNo string?
+---@return boolean
+function connect(url, deviceNo) end
+```
+
+**参数**
+
+| 参数名     | 类型   | 是否必填 | 默认值         | 描述 |
+| ---------- | ------ | -------- | -------------- | ---- |
+| `url`      | string | 是       | -              | 完整 `ws://` 或 `wss://` 云控地址 |
+| `deviceNo` | string | 否       | 已保存设备编号 | 连接时追加到 query 的设备编号 |
+
+**返回值**
+
+| 类型    | 描述 |
+| ------- | ---- |
+| boolean | URL 校验通过且连接请求已提交时返回 true |
+
+**说明**
+
+- `connect` 只能在主脚本上下文调用。
+- `connect` 只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+
+**示例**
+
+```lua
+local cloud = require("cloud")
+local accepted = cloud.connect("wss = //example.com/control", "device-001")
+print("云控连接请求:", accepted)
+```
+
+### isConnected - 判断是否已连接
+
+```lua
+---@return boolean
+function isConnected() end
+```
+
+**返回值**
+
+| 类型    | 描述 |
+| ------- | ---- |
+| boolean | WebSocket 已连接时返回 true |
+
+**示例**
+
+```lua
+local cloud = require("cloud")
+if cloud.isConnected() then
+  cloud.report("status", { value = "ready" })
+end
+```
+
+### disconnect - 断开连接
+
+```lua
+function disconnect() end
+```
+
+断开云控 WebSocket 并停止自动重连。
+
+**示例**
+
+```lua
+local cloud = require("cloud")
+cloud.disconnect()
+```
+
+### report - 上报数据
+
+```lua
+---@param event string
+---@param data table
+---@return boolean
+function report(event, data) end
+```
+
+**参数**
+
+| 参数名  | 类型      | 是否必填 | 默认值 | 描述 |
+| ------- | --------- | -------- | ------ | ---- |
+| `event` | string    | 是       | -      | 自定义事件名 |
+| `data`  | table | 是 | - | 要上报的普通 Object 参数 |
+
+**返回值**
+
+| 类型    | 描述 |
+| ------- | ---- |
+| boolean | 已连接且 JSON 文本帧已提交写出时返回 true |
+
+**示例**
+
+```lua
+local cloud = require("cloud")
+local ok = cloud.report("taskFinished", {
+  taskId = "A-1001",
+  success = true,
+  costMs = 1280,
+})
+print("上报结果:", ok)
+```
+
+**上报云控状态**
+
+设备总览自定义字段读取设备最新 `cloud:status` 上报数据。服务端按设备只保存最新一份状态；同一设备再次上报会覆盖前一次状态。
+
+`data` 的 key 必须使用云控端已经配置好的设备总览自定义字段名。上报了云控端未配置的多余字段时，协议仍可发送，但云控端设备总览不会显示这些字段。
+
+```lua
+local cloud = require("cloud")
+cloud.report("cloud = status", {
+  taskName = "巡检任务",
+  progress = 80,
+  online = true,
+})
+```
+
+### onEvent - 监听服务器事件
+
+```lua
+---@param callback function?
+function onEvent(callback) end
+```
+
+监听服务器发送的 `scriptEvent` 协议帧。传入 `nil` 会取消主脚本监听。
+此回调注册接口只能在主线程调用，不能在线程脚本中调用。
+
+**参数**
+
+| 参数名     | 类型                          | 是否必填 | 描述 |
+| ---------- | ----------------------------- | -------- | ---- |
+| `callback` | `(event, data) => void` 或 `nil` | 是    | 事件处理函数，或传 `nil` 取消监听 |
+
+**示例**
+
+```lua
+local cloud = require("cloud")
+cloud.onEvent(function(event, data)
+  if event == "startTask" then
+    print("任务参数:", data)
+  end
+end)
+```

package/docs/apilua/config.md

@@ -0,0 +1,181 @@
+# 配置模块 (Config)
+
+配置模块提供了读取、更新和删除应用配置的功能。
+
+网页的 ms.setConfig 对应 config.set
+
+网页的 ms.getConfig 对应 config.get
+
+网页的 ms.getAllConfig 对应 config.all
+
+网页的 ms.removeConfig 对应 config.remove
+
+## API 参考
+
+### all - 获取所有配置的 JSON 格式数据。
+
+```lua
+---@return table
+function all() end
+```
+
+**返回值:**
+
+| 类型                  | 描述               |
+| --------------------- | ------------------ |
+| `table` | 包含所有配置的对象 |
+
+**示例:**
+
+```lua
+local config = require("config")
+local allConfigs = config.all()
+print("所有配置: " .. tostring(ToJsonString(allConfigs, nil, 2)))
+```
+
+### setAll - 设置所有配置项。
+
+```lua
+---@param config table
+---@return boolean
+function setAll(config) end
+```
+
+**参数:**
+
+| 参数名   | 类型                  | 是否必填 | 默认值 | 描述             |
+| -------- | --------------------- | -------- | ------ | ---------------- |
+| `config` | `table` | 是       | -      | 完整配置对象     |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 设置是否成功 |
+
+**示例:**
+
+```lua
+local config = require("config")
+local success = config.setAll({ maxRetries = 5, debugEnabled = true })
+if success then
+  print("所有配置已更新")
+end
+```
+
+### set - 更新或设置配置项的值。
+
+```lua
+---@param key string
+---@param value any
+---@return boolean
+function set(key, value) end
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述       |
+| ------- | ------ | -------- | ------ | ---------- |
+| `key`   | string | 是       | -      | 配置键名   |
+| `value` | any    | 是       | -      | 新的配置值 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 更新是否成功 |
+
+**示例:**
+
+```lua
+local config = require("config")
+-- 更新不同类型的配置
+local success1 = config.set("maxRetries", 5)
+local success2 = config.set("apiBaseUrl", "https://api.example.com")
+local success3 = config.set("debugEnabled", true)
+
+if success1  and  success2  and  success3 then
+  print("配置更新成功")
+end
+```
+
+### get - 读取配置项的值。
+
+```lua
+---@param key string
+---@return any | nil
+function get(key) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `key`  | string | 是       | -      | 配置键名 |
+
+**返回值:**
+
+| 类型          | 描述   |
+| ------------- | ------ |
+| `any \| nil` | 配置值 |
+
+**示例:**
+
+```lua
+local config = require("config")
+local maxRetries = config.get("maxRetries")
+if maxRetries ~= nil then
+  print("最大重试次数: " .. tostring(maxRetries))
+end
+```
+
+### getKuiConfig - 获取 KUI 的配置。
+
+```lua
+---@return table
+function getKuiConfig() end
+```
+
+**返回值:**
+
+| 类型                  | 描述                                                     |
+| --------------------- | -------------------------------------------------------- |
+| `table` | `KUI_CONFIG` 对应的对象，配置不存在或无法转换时返回空对象 |
+
+**示例:**
+
+```lua
+local config = require("config")
+local kuiConfig = config.getKuiConfig()
+print("KUI 配置: " .. tostring(ToJsonString(kuiConfig, nil, 2)))
+```
+
+### remove - 删除指定的配置项。
+
+```lua
+---@param key string
+---@return boolean
+function remove(key) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述             |
+| ------ | ------ | -------- | ------ | ---------------- |
+| `key`  | string | 是       | -      | 要删除的配置键名 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 删除是否成功 |
+
+**示例:**
+
+```lua
+local config = require("config")
+local deleted = config.remove("temporaryConfig")
+if deleted then
+  print("临时配置已删除")
+end
+```