ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/utils.md

@@ -0,0 +1,222 @@
+# 工具模块 (Utils)
+
+工具模块提供了一系列实用的工具函数，包括时间格式化、随机数生成、应用前台切换等常用功能。
+
+## 功能概览
+
+- **时间处理**: 时间格式化功能
+- **随机数生成**: 生成指定范围的随机数
+- **应用控制**: 将应用切换到前台
+- **编码转换**: 字符串编码与解码工具
+
+## API 参考
+
+### 时间处理
+
+#### timeFormat - 格式化当前时间为指定格式的字符串。
+
+```lua
+---@param format string
+---@return string
+function timeFormat(format) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                      |
+| -------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `format` | string | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `HH` - 两位小时（24 小时制）<br> `hh` - 两位小时（12 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
+
+**返回值:**
+
+| 类型     | 描述                 |
+| -------- | -------------------- |
+| `string` | 格式化后的时间字符串 |
+
+**示例:**
+
+```lua
+local utils = require("utils")
+
+-- 标准日期时间格式
+local dateTime = utils.timeFormat("yyyy-MM-dd HH:mm:ss")
+print(dateTime) -- 输出: 2024-01-15 14:30:25
+
+-- 仅日期格式
+local date = utils.timeFormat("yyyy-MM-dd")
+print(date) -- 输出: 2024-01-15
+
+-- 仅时间格式
+local time = utils.timeFormat("HH:mm:ss")
+print(time) -- 输出: 14:30:25
+
+-- 自定义分隔符
+local customFormat = utils.timeFormat("yyyy/MM/dd HH:mm")
+print(customFormat) -- 输出: 2024/01/15 14:30
+
+-- 紧凑格式
+local compact = utils.timeFormat("yyyyMMddHHmmss")
+print(compact) -- 输出: 20240115143025
+```
+
+### 随机数生成
+
+#### random - 生成指定范围内的随机整数。
+
+```lua
+---@param min number
+---@param max number
+---@return number
+function random(min, max) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述           |
+| ------ | ------ | -------- | ------ | -------------- |
+| `min`  | number | 是       |        | 最小值（包含） |
+| `max`  | number | 是       |        | 最大值（包含） |
+
+**返回值:**
+
+| 类型     | 描述                 |
+| -------- | -------------------- |
+| `number` | 指定范围内的随机整数 |
+
+**示例:**
+
+```lua
+local utils = require("utils")
+
+-- 生成1-10之间的随机数
+local randomNum = utils.random(1, 10)
+print("随机数: " .. tostring(randomNum))
+
+-- 生成0-100之间的随机数
+local percentage = utils.random(0, 100)
+print("随机百分比: " .. tostring(percentage))
+
+-- 生成随机延迟时间（毫秒）
+local delay = utils.random(1000, 5000)
+print("随机延迟: " .. tostring(delay) .. " 毫秒")
+Sleep(delay)
+
+-- 生成随机索引
+local array = { "apple", "banana", "orange", "grape" }
+local randomIndex = utils.random(1, #array)
+print("随机选择: " .. array[randomIndex])
+```
+
+### 应用控制
+
+#### takeMeToFront - 将快点 JS 应用切换到前台显示。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+
+```lua
+---@return boolean
+function takeMeToFront() end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+
+-- 将应用切换到前台
+utils.takeMeToFront()
+print("应用已切换到前台")
+```
+
+### 编码转换
+
+#### randomUUID - 生成随机 UUID。
+
+```lua
+---@return string
+function randomUUID() end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+print(utils.randomUUID())
+```
+
+#### hexString - 字符串转 Hex 字符串。
+
+```lua
+---@param source string
+---@return string
+function hexString(source) end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+print(utils.hexString("hello"))
+```
+
+#### base64Encoded - 字符串转 Base64。
+
+```lua
+---@param source string
+---@return string
+function base64Encoded(source) end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+print(utils.base64Encoded("hello"))
+```
+
+#### base64Decoded - Base64 转字符串。
+
+```lua
+---@param source string
+---@return string
+function base64Decoded(source) end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+print(utils.base64Decoded("aGVsbG8="))
+```
+
+#### hexStringBase64Encoded - 16 进制字符串转 Base64。
+
+```lua
+---@param hexString string
+---@return string
+function hexStringBase64Encoded(hexString) end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+print(utils.hexStringBase64Encoded("68656c6c6f"))
+```
+
+#### hexStringBase64Decoded - Base64 转 16 进制字符串。
+
+```lua
+---@param base64HexString string
+---@return string
+function hexStringBase64Decoded(base64HexString) end
+```
+
+**示例:**
+
+```lua
+local utils = require("utils")
+print(utils.hexStringBase64Decoded("aGVsbG8="))
+```

package/docs/apilua/yolo.md

@@ -0,0 +1,324 @@
+# YOLO 目标检测模块 (YOLO)
+
+YOLO 模块基于 YOLOV8/YOLO11/YOLO26 算法和 NCNN 框架，提供高性能的实时目标检测功能，支持多种输入源和自定义模型，可用于物体识别、位置定位等应用场景。
+
+## 数据标注
+
+查看 [快点 Label](../label/dataAnnotation.md) 了解如何进行数据标注
+
+## 功能概览
+
+- **模型管理**: YOLO 模型加载和资源管理
+- **目标检测**: 实时物体检测和位置识别
+- **多源输入**: 支持屏幕截图、图片文件、URL 等多种输入源
+- **结果处理**: 完整的检测结果信息和坐标数据
+- **资源控制**: 完整的模型生命周期管理
+
+## 测试结果
+
+| 设备型号   | 模型类型         | 检测耗时  |
+| ---------- | ---------------- | --------- |
+| iPhoneX    | yolov8n(80 类别) | 70-100ms  |
+| iPhoneX    | yolov8s(80 类别) | 160-200ms |
+| iPhone SE3 | yolov8n(80 类别) | 30-50ms   |
+| iPhone SE3 | yolov8s(80 类别) | 70-100ms  |
+
+## 数据类型
+
+### YoloResult
+
+YOLO 检测结果接口，包含检测到的物体的完整信息。
+
+```lua
+---@class YoloResult
+---@field x number 检测框的左上角x坐标
+---@field y number 检测框的左上角y坐标
+---@field ex number 检测框的右下角x坐标
+---@field ey number 检测框的右下角y坐标
+---@field centerX number 检测框的中心点x坐标
+---@field centerY number 检测框的中心点y坐标
+---@field width number 检测框的宽度
+---@field height number 检测框的高度
+---@field confidence number 检测框的置信度 (0-1)
+---@field classId number 检测框的类别ID
+```
+
+**字段说明:**
+
+| 字段名             | 类型   | 描述                                       |
+| ------------------ | ------ | ------------------------------------------ |
+| `x, y`             | number | 检测框左上角坐标                           |
+| `ex, ey`           | number | 检测框右下角坐标                           |
+| `centerX, centerY` | number | 检测框中心点坐标                           |
+| `width, height`    | number | 检测框尺寸                                 |
+| `confidence`       | number | 检测置信度，范围 0-1，值越高表示检测越可靠 |
+| `classId`          | number | 物体类别 ID，对应训练模型的类别标签        |
+
+## API 参考
+
+### 模型管理
+
+#### load - 加载 YOLO 模型（支持版本 8/11/26）。
+
+加载模型是使用目标检测功能的前提。
+
+```lua
+---@param paramPath string
+---@param binPath string
+---@param nc number?
+---@param version number?
+---@param useGpu boolean?
+---@return string|nil
+function load(paramPath, binPath, nc, version, useGpu) end
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                                                        |
+| ----------- | ------- | -------- | ------ | --------------------------------------------------------------------------- |
+| `paramPath` | string  | 是       |        | NCNN 模型的 param 文件绝对路径                                              |
+| `binPath`   | string  | 是       |        | NCNN 模型的 bin 文件绝对路径                                                |
+| `nc`        | number  | 否       | 0      | 模型的标签数量；传 `0` 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空数组 |
+| `version`   | number  | 否       | 0      | 模型版本；传 `0` 或省略时按 v11 处理，显式传入支持 8/11/26                  |
+| `useGpu`    | boolean | 否       | false  | 是否启用 GPU 加速                                                           |
+
+**返回值:**
+
+| 类型            | 描述                                      |
+| --------------- | ----------------------------------------- |
+| `string \| nil` | 加载成功返回模型 ID 字符串，失败返回 nil  |
+
+**示例:**
+
+```lua
+local yolo = require("yolo")
+local modelId = yolo.load(
+  "yolov8n_ncnn_model/model.ncnn.param",
+  "yolov8n_ncnn_model/model.ncnn.bin",
+  0,
+  8,
+  false
+)
+```
+
+#### loadV11 - 加载 YOLO 模型。
+
+加载模型是使用目标检测功能的前提。兼容 YOLOV8 / YOLO11 的 NCNN 模型。
+
+```lua
+---@param paramPath string
+---@param binPath string
+---@param nc number?
+---@param useGpu boolean?
+---@return string|nil
+function loadV11(paramPath, binPath, nc, useGpu) end
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                                                        |
+| ----------- | ------- | -------- | ------ | --------------------------------------------------------------------------- |
+| `paramPath` | string  | 是       |        | NCNN 模型的 param 文件绝对路径                                              |
+| `binPath`   | string  | 是       |        | NCNN 模型的 bin 文件绝对路径                                                |
+| `nc`        | number  | 否       | 0      | 模型的标签数量；传 `0` 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空数组 |
+| `useGpu`    | boolean | 否       | false  | 是否启用 GPU 加速                                                           |
+
+**返回值:**
+
+| 类型            | 描述                                      |
+| --------------- | ----------------------------------------- |
+| `string \| nil` | 加载成功返回模型 ID 字符串，失败返回 nil  |
+
+**示例:**
+
+```lua
+local yolo = require("yolo")
+
+-- 加载 YOLO 模型
+local modelId = yolo.loadV11(
+  "yolo11n_ncnn_model/model.ncnn.param",
+  "yolo11n_ncnn_model/model.ncnn.bin",
+  0,
+  false
+)
+```
+
+### 目标检测
+
+#### detect - 对输入图像执行目标检测。
+
+执行目标检测，识别图像中的物体并返回检测结果。
+
+```lua
+---@param modelId string
+---@param img string
+---@param targetSize number?
+---@param threshold number?
+---@param nmsThreshold number?
+---@return YoloResult[]
+function detect(modelId, img, targetSize, threshold, nmsThreshold) end
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                               |
+| -------------- | ------ | -------- | ------ | ------------------------------------------------------------------ |
+| `modelId`      | string | 是       |        | 模型 ID，通过 `loadV11` 获取                                       |
+| `img`          | string | 是       |        | 图像输入源，支持 `"screen"`、图片文件路径、HTTP 图片地址或 imageId |
+| `targetSize`   | number | 否       | 640    | 模型推理输入边长，通常为 640（与模型训练时一致）                   |
+| `threshold`    | number | 否       | 0.4    | 置信度阈值，低于此值的检测结果会被过滤                             |
+| `nmsThreshold` | number | 否       | 0.5    | 非极大值抑制阈值，用于去除重叠检测框                               |
+
+**返回值:**
+
+| 类型           | 描述           |
+| -------------- | -------------- |
+| `YoloResult[]` | 检测结果数组   |
+
+**示例:**
+
+```lua
+local yolo = require("yolo")
+
+-- 首先加载模型
+local modelId = yolo.loadV11(
+  "/yolo11n_ncnn_model/model.ncnn.param",
+  "/yolo11n_ncnn_model/model.ncnn.bin",
+  0,
+  false
+)
+
+if not modelId then
+  print("模型加载失败")
+  return
+end
+
+-- 检测当前屏幕
+local screenResults = yolo.detect(modelId, "screen", 640, 0.4, 0.5)
+print("屏幕检测到 " .. tostring(#screenResults) .. " 个物体")
+
+for index, result in ipairs(screenResults) do
+  print("物体 " .. tostring(index) .. ":")
+  print("  类别ID: " .. tostring(result.classId))
+  print("  置信度: " .. tostring(result.confidence * 100) .. "%")
+  print("  边界框: (" .. tostring(result.x) .. ", " .. tostring(result.y) .. ", " .. tostring(result.ex) .. ", " .. tostring(result.ey) .. ")")
+  print("  中心点: (" .. tostring(result.centerX) .. ", " .. tostring(result.centerY) .. ")")
+  print("  尺寸: " .. tostring(result.width) .. " x " .. tostring(result.height))
+end
+
+-- 检测图片文件
+local imageResults = yolo.detect(modelId, "/path/to/test_image.jpg", 640, 0.3, 0.5)
+if #imageResults > 0 then
+  print("图片中检测到 " .. tostring(#imageResults) .. " 个物体")
+  for _, result in ipairs(imageResults) do
+    print("检测到类别 " .. tostring(result.classId) .. "，置信度: " .. tostring(result.confidence))
+  end
+else
+  print("图片中未检测到任何物体")
+end
+
+-- 检测网络图片
+local urlResults = yolo.detect(modelId, "https://example.com/test_image.jpg", 640, 0.5, 0.4)
+print("网络图片检测结果: " .. tostring(#urlResults) .. " 个物体")
+
+yolo.free(modelId)
+```
+
+#### detectAbs - 对指定区域执行目标检测，并将结果坐标映射为原图/全屏绝对坐标。
+
+传入裁剪区域时，结果坐标会映射回原图或全屏坐标，可直接用于点击；全屏检测时 `x/y/ex/ey` 传 `0`。
+
+```lua
+---@param modelId string
+---@param img string
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@param targetSize number?
+---@param threshold number?
+---@param nmsThreshold number?
+---@return YoloResult[]
+function detectAbs(modelId, img, x, y, ex, ey, targetSize, threshold, nmsThreshold) end
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                               |
+| -------------- | ------ | -------- | ------ | ------------------------------------------------------------------ |
+| `modelId`      | string | 是       |        | 模型 ID，通过 `load` 或 `loadV11` 获取                             |
+| `img`          | string | 是       |        | 图像输入源，支持 `"screen"`、图片文件路径、HTTP 图片地址或 imageId |
+| `x`            | number | 是       |        | 裁剪区域左上角 x 坐标；全屏检测传 0                                |
+| `y`            | number | 是       |        | 裁剪区域左上角 y 坐标；全屏检测传 0                                |
+| `ex`           | number | 是       |        | 裁剪区域右下角 x 坐标；全屏检测传 0                                |
+| `ey`           | number | 是       |        | 裁剪区域右下角 y 坐标；全屏检测传 0                                |
+| `targetSize`   | number | 否       | 640    | 模型推理输入边长，通常为 640（与模型训练时一致）                   |
+| `threshold`    | number | 否       | 0.4    | 置信度阈值，低于此值的检测结果会被过滤                             |
+| `nmsThreshold` | number | 否       | 0.5    | 非极大值抑制阈值，用于去除重叠检测框                               |
+
+**返回值:**
+
+| 类型           | 描述                                   |
+| -------------- | -------------------------------------- |
+| `YoloResult[]` | 检测结果数组，坐标为原图或全屏绝对坐标 |
+
+**示例:**
+
+```lua
+local yolo = require("yolo")
+local modelId = yolo.load(
+  "/yolo11n_ncnn_model/model.ncnn.param",
+  "/yolo11n_ncnn_model/model.ncnn.bin",
+  0,
+  11,
+  false
+)
+local results = yolo.detectAbs(modelId, "screen", 0, 0, 0, 0, 640, 0.4, 0.5)
+if #results > 0 then
+  print(results[1].classId, results[1].centerX, results[1].centerY)
+end
+yolo.free(modelId)
+```
+
+### 资源管理
+
+#### free - 释放指定模型的资源。
+
+```lua
+---@param modelId string
+function free(modelId) end
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述            |
+| --------- | ------ | -------- | ------ | --------------- |
+| `modelId` | string | 是       |        | 要释放的模型 ID |
+
+**示例:**
+
+```lua
+local yolo = require("yolo")
+
+-- 释放特定模型
+if modelId then
+  yolo.free(modelId)
+  print("模型 " .. tostring(modelId) .. " 资源已释放")
+end
+```
+
+#### freeAll - 释放所有已加载模型的资源。
+
+```lua
+function freeAll() end
+```
+
+**示例:**
+
+```lua
+local yolo = require("yolo")
+
+-- 释放所有模型资源
+yolo.freeAll()
+print("所有 YOLO 模型资源已释放")
+```