ms-types 0.9.35 → 0.9.37

package/types/lua/dotocr.lua

@@ -2,22 +2,33 @@
 ---@class DotOCR
 local _DotOCR = {}
 
+---@class OCRChar
+---@field text string 识别出的文本；查找结果中为命中的目标字符串
+---@field confidence number 识别置信度 (0-1)
+---@field x integer 文本区域左上角 x 坐标
+---@field y integer 文本区域左上角 y 坐标
+---@field ex integer 文本区域右下角 x 坐标
+---@field ey integer 文本区域右下角 y 坐标
+---@field width integer 文本区域宽度
+---@field height integer 文本区域高度
+---@field centerX integer 文本区域中心点 x 坐标
+---@field centerY integer 文本区域中心点 y 坐标
+
 --- 点阵 OCR；全局 `dotocr`
 
---- loadFont
+--- 从资源路径加载字库并缓存
 ---@param fontPath string
----@return string|nil
+---@return string|nil 字库 ID，失败返回 nil
 function _DotOCR.loadFont(fontPath) return nil end
 
---- free
+--- 释放指定字库
 ---@param fontId string
 function _DotOCR.free(fontId) end
 
---- freeAll
-
+--- 释放全部已加载的点阵字库
 function _DotOCR.freeAll() end
 
---- recognizeAbs
+--- 识别文字并返回原图或全屏绝对坐标
 ---@param fontId string
 ---@param input string
 ---@param x integer|nil
@@ -25,10 +36,14 @@ function _DotOCR.freeAll() end
 ---@param ex integer|nil
 ---@param ey integer|nil
 ---@param confidenceThreshold number|nil
----@return table[]
-function _DotOCR.recognizeAbs(fontId, input, x, y, ex, ey, confidenceThreshold) return {} end
+---@return OCRChar[]
+function _DotOCR.recognizeAbs(fontId, input, x, y, ex, ey, confidenceThreshold)
+    ---@type OCRChar[]
+    local ret = {}
+    return ret
+end
 
---- findTextAbs
+--- 先识别再按行查找目标串，返回命中位置的绝对坐标
 ---@param fontId string
 ---@param input string
 ---@param targetTexts string[]
@@ -38,8 +53,12 @@ function _DotOCR.recognizeAbs(fontId, input, x, y, ex, ey, confidenceThreshold)
 ---@param ey integer|nil
 ---@param confidenceThreshold number|nil
 ---@param exactMatch boolean|nil
----@return table[]
-function _DotOCR.findTextAbs(fontId, input, targetTexts, x, y, ex, ey, confidenceThreshold, exactMatch) return {} end
+---@return OCRChar[]
+function _DotOCR.findTextAbs(fontId, input, targetTexts, x, y, ex, ey, confidenceThreshold, exactMatch)
+    ---@type OCRChar[]
+    local ret = {}
+    return ret
+end
 
 ---@type DotOCR
 dotocr = _DotOCR

package/types/lua/file.lua

@@ -19,7 +19,7 @@ function _File.mkdirs(path) return true end
 
 --- 读取文件
 --- @param path string 路径
---- @return string 内容
+--- @return string 内容，失败为空串
 function _File.readFile(path) return '' end
 
 --- 写入文件
@@ -40,7 +40,7 @@ function _File.deleteAllFile(path) return true end
 
 --- 读取资源文件（res 目录）
 --- @param name string 文件名
---- @return string|nil 内容
+--- @return string 内容，失败为空串
 function _File.readResFile(name) return '' end
 
 --- 获取 res 资源的本地文件路径；用完后应调用 cleanupResFile
@@ -74,12 +74,12 @@ function _File.appendLine(path, data) return true end
 --- 读取指定行
 --- @param path string 路径
 --- @param lineNo integer 行号
---- @return string|nil 内容
+--- @return string 内容，失败为空串
 function _File.readLine(path, lineNo) return '' end
 
 --- 读取所有行
 --- @param path string 路径
---- @return string[] 行列表
+--- @return string[] 行列表，失败为空表
 function _File.readAllLines(path) return {} end
 
 --- 复制文件
@@ -90,7 +90,7 @@ function _File.copy(src, dest) return true end
 
 --- 计算文件MD5
 --- @param path string 路径
---- @return string|nil MD5值
+--- @return string MD5 值，失败为空串
 function _File.fileMD5(path) return '' end
 
 ---@type File

package/types/lua/global.lua

@@ -27,8 +27,8 @@ AppName = ''
 ---@type string
 AppBundleId = ''
 
---- 脚本 package.json 内容（表）
----@type table
+--- 脚本 package.json 内容（动态键值表）
+---@type table<string, any>
 PackageJson = {}
 
 ---@class CpuThrottleDelay
@@ -63,11 +63,11 @@ function Sleep(ms) end
 function Time() return 0 end
 
 --- 将表转为 JSON 字符串
----@param data table
+---@param data table<string, any>|any[]
 ---@return string
 function ToJsonString(data) return '' end
 
---- 启动同 VM 协作协程（不是 OS 线程），返回协程名
+--- 启动协作协程，返回协程名
 ---@param func function
 ---@return string
 function StartThread(func) return '' end
@@ -76,7 +76,7 @@ function StartThread(func) return '' end
 ---@param threadName string
 function StopThread(threadName) end
 
---- 当前协作协程是否应退出。主脚本收到停止后由引擎 hook / Sleep 直接中断，不必轮询本函数。
+--- 当前协程是否应退出
 ---@return boolean
 function ShouldInterruptThread() return false end
 

package/types/lua/hid.lua

@@ -268,12 +268,14 @@ function _HID.unlock() return true end
 --- @return boolean 成功
 function _HID.takeMeToFront() return true end
 
---- 当前打开应用信息（iOS18+）
---- @return {name: string, bundleId: string} 信息；无前台应用时为空表
+---@class HidCurrentAppInfo
+---@field name string 应用名称
+---@field bundleId string 应用 Bundle ID
+
+--- 当前打开应用信息（iOS18+）；无前台应用时为 nil
+--- @return HidCurrentAppInfo|nil
 function _HID.currentAppInfo()
-    ---@type table
-    local ret
-    return ret
+    return nil
 end
 
 ---@type HID

package/types/lua/hotupdate.lua

@@ -2,22 +2,40 @@
 ---@class HotUpdate
 local _HotUpdate = {}
 
---- 检查更新
---- @param options {url: string|nil, version: integer|nil, timeout: integer|nil}|nil 
---- @return {needUpdate: boolean, data?: table, error?: string} 结果
-function _HotUpdate.checkUpdate(options)
-    return {
-        needUpdate = true,
-        data = {version = 1, url = "https://example.com/update.zip"}
-    }
+---@class HotUpdateResponse
+---@field download_url string 新包下载地址
+---@field version integer 新包版本号
+---@field download_timeout integer 下载超时（秒）
+---@field dialog boolean 是否用对话框展示
+---@field msg string 对话框消息
+---@field force boolean 对话框模式下是否强制更新
+---@field md5 string|nil 更新包 MD5
+
+---@class HotUpdateResult
+---@field needUpdate boolean 是否需要更新
+---@field error string|nil 检查失败时的错误
+---@field data HotUpdateResponse|nil 需要更新时的服务器数据
+
+---@class HotUpdateInstallResult
+---@field updated boolean 是否已安装
+---@field error string|nil 安装失败时的错误
+
+--- 检查更新（无参数）
+---@return HotUpdateResult
+function _HotUpdate.checkUpdate()
+    ---@type HotUpdateResult
+    return { needUpdate = false }
 end
 
---- 下载并安装
---- @return {updated: boolean, error?: string} 结果
-function _HotUpdate.downloadAndInstall() return {updated = true, error = nil} end
+--- 下载并安装；成功后会自动重启脚本
+---@return HotUpdateInstallResult
+function _HotUpdate.downloadAndInstall()
+    ---@type HotUpdateInstallResult
+    return { updated = false }
+end
 
---- 当前版本
---- @return integer 版本号
+--- 当前版本号；失败返回 0
+---@return integer
 function _HotUpdate.getCurrentVersion() return 0 end
 
 ---@type HotUpdate

package/types/lua/http.lua

@@ -4,7 +4,7 @@ local _Http = {}
 
 ---@class HttpRequestOptions
 ---@field url string         @请求地址
----@field timeout integer|nil @请求超时（毫秒）
+---@field timeout integer|nil @请求超时（毫秒），默认 30000
 ---@field method string|nil   @请求方法 GET/POST/...
 ---@field proxy {host:string, port:integer}|nil @代理服务器
 ---@field followRedirects boolean|nil @是否跟随重定向
@@ -47,7 +47,7 @@ end
 --- GET 请求（同名：httpGet）
 --- @param url string
 --- @param params table<string,string>|nil
---- @param timeout integer|nil
+--- @param timeout integer|nil 默认 30000
 --- @param headers table<string,string>|nil
 --- @return string|nil
 function _Http.httpGet(url, params, timeout, headers) return '' end
@@ -56,7 +56,7 @@ function _Http.httpGet(url, params, timeout, headers) return '' end
 --- @param url string
 --- @param params table<string,string>|nil
 --- @param files table<string,string>|nil
---- @param timeout integer|nil
+--- @param timeout integer|nil 默认 30000
 --- @param headers table<string,string>|nil
 --- @return string|nil
 function _Http.httpPost(url, params, files, timeout, headers) return '' end
@@ -64,7 +64,7 @@ function _Http.httpPost(url, params, files, timeout, headers) return '' end
 --- POST JSON 请求
 --- @param url string
 --- @param json table|nil
---- @param timeout integer|nil
+--- @param timeout integer|nil 默认 30000
 --- @param headers table<string,string>|nil
 --- @return string|nil
 function _Http.postJSON(url, json, timeout, headers) return '' end
@@ -72,7 +72,7 @@ function _Http.postJSON(url, json, timeout, headers) return '' end
 --- 下载文件（同名：downloadFile）
 --- @param url string
 --- @param file string
---- @param timeout integer|nil
+--- @param timeout integer|nil 默认 30000
 --- @param headers table<string,string>|nil
 --- @return boolean
 function _Http.downloadFile(url, file, timeout, headers) return true end

package/types/lua/image.lua

@@ -21,6 +21,12 @@ local _Image = {}
 ---@field centerY integer 中心y坐标
 ---@field ex integer 右下角x坐标
 ---@field ey integer 右下角y坐标
+---@field scaleX number|nil 仅 method=99：命中时模板横向缩放
+---@field scaleY number|nil 仅 method=99：命中时模板纵向缩放
+
+---@class FindImageOptions
+---@field scaleFactors number[]|nil 仅 method=99：模板缩放比例列表
+---@field orz integer|nil 查找方向 1-8，与 findColor 相同
 
 --- 截取屏幕；坐标缺省 0 表示全屏
 --- @param x integer|nil 左上角 x
@@ -131,9 +137,9 @@ function _Image.cmpColor(id, points, threshold) return true end
 --- @param ey integer|nil 右下y
 --- @param threshold number 相似度 0.0-1.0
 --- @param limit integer|nil 限制个数
---- @param method integer|nil 匹配方法 0|1|3|5|99
+--- @param method integer|nil 匹配方法 0|1|3|5|99，默认 5
 --- @param rgb boolean|nil 是否使用RGB
---- @param options table|nil 选项。scaleFactors 仅 method=99；orz 为查找方向 1-8（与 findColor 相同）
+--- @param options FindImageOptions|nil 选项。scaleFactors 仅 method=99；orz 为查找方向 1-8
 --- @return Rect[] 结果矩形列表
 function _Image.findImage(id, templateImageId, x, y, ex, ey, threshold, limit,
                           method, rgb, options) return {} end

package/types/lua/mysql.lua

@@ -9,9 +9,11 @@ local _MySQL = {}
 ---@field password string 密码
 ---@field database string 数据库名
 ---@field charset string|nil 字符集
+---@field connectTimeout integer|nil 连接超时（毫秒），默认 5000
+---@field queryTimeout integer|nil 查询超时（毫秒），默认 30000
 
 ---@class MySQLResult
----@field rows table[] 结果集
+---@field rows table<string, any>[] 结果集行
 ---@field affectedRows integer 受影响的行数
 ---@field success boolean 是否成功
 ---@field insertId integer|nil 插入ID

package/types/lua/node.lua

@@ -40,7 +40,7 @@ local _Node = {}
 ---@field clickCenter fun(self: NodeInfo, duration: integer|nil): boolean 点击中心
 ---@field clickRandom fun(self: NodeInfo, duration: integer|nil): boolean 点击随机位置
 ---@field parent fun(self: NodeInfo): NodeInfo|nil 父节点
----@field child fun(self: NodeInfo, index: integer): NodeInfo|nil 子节点
+---@field child fun(self: NodeInfo, index: integer): NodeInfo|nil 子节点，index 从 0 开始
 ---@field allChildren fun(self: NodeInfo): NodeInfo[] 所有子节点
 ---@field siblings fun(self: NodeInfo): NodeInfo[] 所有兄弟节点
 ---@field previousSiblings fun(self: NodeInfo): NodeInfo[] 前兄弟节点

package/types/lua/system.lua

@@ -2,15 +2,10 @@
 ---@class System
 local _System = {}
 
----@class ProcessArguments
----@field env table<string, any> 环境变量映射（键为字符串，值为任意类型）
----@field args string[] 启动参数列表
-
 ---@class ActivateAppInfo
 ---@field name string 应用名称
 ---@field pid integer 进程 ID
 ---@field bundleId string 应用 Bundle ID
----@field processArguments ProcessArguments 启动参数信息
 
 ---@class MemoryInfo
 ---@field used integer 已使用内存（MB）
@@ -20,10 +15,8 @@ local _System = {}
 
 --- 启动应用
 --- @param bundleId string 应用 Bundle ID
---- @param args string[]|nil 启动参数
---- @param env table<string, any>|nil 环境变量
 --- @return boolean 成功
-function _System.startApp(bundleId, args, env) return true end
+function _System.startApp(bundleId) return true end
 
 --- 停止应用
 --- @param bundleId string 应用 Bundle ID

package/types/lua/yolocls.lua

@@ -2,7 +2,14 @@
 ---@class YoloCls
 local _YoloCls = {}
 
---- load
+---@class YoloClsProbs
+---@field data number[] 所有类别概率；Lua 下标从 1 起，类别 0 对应 data[1]
+---@field top1 integer|nil 概率最高的类别 ID；分类失败时为 nil
+---@field top5 integer[] 概率最高的 5 个类别 ID，按概率从高到低排序
+---@field top1conf number|nil top1 对应的概率；分类失败时为 nil
+---@field top5conf number[] top5 对应的概率，顺序与 top5 一致
+
+--- 加载 YOLO 分类模型
 ---@param paramPath string
 ---@param binPath string
 ---@param nc integer|nil
@@ -10,14 +17,17 @@ local _YoloCls = {}
 ---@return string|nil
 function _YoloCls.load(paramPath, binPath, nc, useGpu) return nil end
 
---- classify
+--- 图像分类
 ---@param modelId string
 ---@param img string
 ---@param targetSize integer|nil
----@return table
-function _YoloCls.classify(modelId, img, targetSize) return { data = {}, top1 = nil, top5 = {}, top1conf = nil, top5conf = {} } end
+---@return YoloClsProbs
+function _YoloCls.classify(modelId, img, targetSize)
+    ---@type YoloClsProbs
+    return { data = {}, top1 = nil, top5 = {}, top1conf = nil, top5conf = {} }
+end
 
---- classifyRegion
+--- 对指定区域执行图像分类
 ---@param modelId string
 ---@param img string
 ---@param x integer|nil
@@ -25,15 +35,17 @@ function _YoloCls.classify(modelId, img, targetSize) return { data = {}, top1 =
 ---@param ex integer|nil
 ---@param ey integer|nil
 ---@param targetSize integer|nil
----@return table
-function _YoloCls.classifyRegion(modelId, img, x, y, ex, ey, targetSize) return { data = {}, top1 = nil, top5 = {}, top1conf = nil, top5conf = {} } end
+---@return YoloClsProbs
+function _YoloCls.classifyRegion(modelId, img, x, y, ex, ey, targetSize)
+    ---@type YoloClsProbs
+    return { data = {}, top1 = nil, top5 = {}, top1conf = nil, top5conf = {} }
+end
 
---- free
+--- 释放指定模型
 ---@param modelId string
 function _YoloCls.free(modelId) end
 
---- freeAll
-
+--- 释放全部模型
 function _YoloCls.freeAll() end
 
 ---@type YoloCls

package/types/opencv.d.ts

@@ -4,7 +4,7 @@
  *
  * @example
  * const src = cv.capture()
- * const gray = cv.cvtColor(src, { code: cv.COLOR_BGR2GRAY })
+ * const gray = cv.cvtColor(src, cv.COLOR_BGR2GRAY)
  * const edges = cv.Canny(gray, { threshold1: 100, threshold2: 200 })
  * cv.imwrite('/tmp/e.png', edges)
  * cv.release(src); cv.release(gray); cv.release(edges)