ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/yolocls.md

@@ -0,0 +1,276 @@
+# YOLO 图像分类模块 (YoloCls)
+
+YOLO 图像分类模块基于 YOLOv8-cls / YOLO11-cls / YOLO26-cls 分类模型和 NCNN 框架，提供整图分类、区域分类和模型资源管理能力。
+
+## 功能概览
+
+- **模型管理**: 加载和释放 YOLOv8-cls / YOLO11-cls / YOLO26-cls NCNN 模型
+- **图像分类**: 对屏幕截图、图片文件、HTTP 图片或图片 ID 执行整图分类
+- **区域分类**: 先裁剪指定区域，再对裁剪结果执行分类
+- **结果处理**: 返回 Ultralytics `Probs` 风格的完整概率、top1、top5 和对应置信度
+- **资源控制**: 支持释放单个模型或释放全部已加载模型
+
+## 适用场景
+
+- 判断当前屏幕或图片属于哪个业务类别
+- 对截图中的固定区域进行状态识别
+- 对自定义 YOLO-cls 模型导出的 NCNN 模型执行端侧推理
+
+## 数据结构
+
+### YoloClsProbs
+
+YOLO 分类概率结果，字段命名与 Ultralytics `Probs` 保持一致。
+
+```lua
+---@class YoloClsProbs
+---@field data number[]
+---@field top1 number | nil
+---@field top5 number[]
+---@field top1conf number | nil
+---@field top5conf number[]
+```
+
+**字段说明:**
+
+| 字段名     | 类型             | 描述                                                       |
+| ---------- | ---------------- | ---------------------------------------------------------- |
+| `data`     | `number[]`       | 所有类别概率数组，下标即类别 ID                            |
+| `top1`     | `number \| nil` | 概率最高的类别 ID；分类失败时为 `nil`                     |
+| `top5`     | `number[]`       | 概率最高的 5 个类别 ID，按概率从高到低排序                 |
+| `top1conf` | `number \| nil` | `top1` 对应的概率；分类失败时为 `nil`                     |
+| `top5conf` | `number[]`       | `top5` 对应的概率，顺序与 `top5` 一致                      |
+
+**结果说明:**
+
+- `top1` 等于 `top5[0]`，`top1conf` 等于 `data[top1]`。
+- 当模型类别数少于 5 时，`top5` 和 `top5conf` 的长度会小于 5。
+- 分类失败时返回空结果：`data`、`top5`、`top5conf` 为空数组，`top1` 和 `top1conf` 为 `nil`。
+
+## API 参考
+
+### 模型管理
+
+#### load - 加载 YOLO 分类模型（支持 YOLOv8-cls / YOLO11-cls / YOLO26-cls）
+
+加载模型是使用图像分类能力的前提。支持 Ultralytics 官方 YOLOv8-cls、YOLO11-cls、YOLO26-cls 导出的 NCNN 分类模型，常见模型名使用 `-cls` 后缀，例如 `yolov8n-cls`、`yolo11n-cls`、`yolo26n-cls`。
+
+```lua
+---@param paramPath string
+---@param binPath string
+---@param nc number?
+---@param useGpu boolean?
+---@return string | nil
+function load(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 yoloCls = require("yoloCls")
+-- 模型文件通常放在 res 目录
+local modelId = yoloCls.load(
+  "yolo11n_cls_ncnn_model/model.ncnn.param",
+  "yolo11n_cls_ncnn_model/model.ncnn.bin",
+  1000, -- ImageNet 分类模型通常为 1000 类
+  false
+)
+
+if modelId then
+  print("YOLO 分类模型加载成功，ID = " .. tostring(modelId))
+else
+  print("YOLO 分类模型加载失败，请检查模型文件路径和格式")
+end
+```
+
+### 图像分类
+
+#### classify - 对输入图像执行分类
+
+对整张输入图像执行分类，返回完整概率数组和 top1/top5 结果。
+
+```lua
+---@param modelId string
+---@param img string
+---@param targetSize number?
+---@return YoloClsProbs
+function classify(modelId, img, targetSize) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelId`    | string | 是       |        | 模型 ID（通过 `load` 获取）                                                                                                                  |
+| `img`        | string | 是       |        | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `string` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `targetSize` | number | 否       | 224    | 分类输入大小，应与模型训练或导出时的输入尺寸一致                                                                                             |
+
+**返回值:**
+
+| 类型           | 描述                                                |
+| -------------- | --------------------------------------------------- |
+| `YoloClsProbs` | Ultralytics `Probs` 风格分类结果，包含 top1/top5 等 |
+
+**示例:**
+
+```lua
+local yoloCls = require("yoloCls")
+local modelId = yoloCls.load(
+  "yolo11n_cls_ncnn_model/model.ncnn.param",
+  "yolo11n_cls_ncnn_model/model.ncnn.bin",
+  1000,
+  false
+)
+
+if not modelId then
+  print("模型加载失败")
+  return
+end
+
+local probs = yoloCls.classify(
+  modelId,
+  "screen", -- 使用当前屏幕
+  224 -- 分类模型常用输入尺寸
+)
+
+if probs.top1 ~= nil then
+  print("top1 类别ID = " .. tostring(probs.top1))
+  print("top1 置信度: " .. tostring((probs.top1conf * 100).toFixed(2)) .. "%")
+else
+  print("分类失败或无有效结果")
+end
+
+for i = 1, #probs.top5 do
+  print(
+    "top[" .. tostring(i + 1) .. "] = 类别ID=" .. tostring(probs.top5[i]) .. ", 置信度=" .. tostring(probs.top5conf[i].toFixed(4))
+  )
+end
+-- 如需读取某个类别的原始概率，可直接访问 data[classId]
+local classId = 0
+if #probs.data > classId then
+  print("类别 " .. tostring(classId) .. " 概率: " .. tostring(probs.data[classId].toFixed(4)))
+end
+
+yoloCls.free(modelId)
+```
+
+#### classifyRegion - 对指定区域执行分类
+
+先从输入图像中裁剪指定区域，再对裁剪结果执行分类。适合只关心屏幕某个固定区域状态的场景。
+
+```lua
+---@param modelId string
+---@param img string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param targetSize number?
+---@return YoloClsProbs
+function classifyRegion(modelId, img, x, y, ex, ey, targetSize) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelId`    | string | 是       |        | 模型 ID（通过 `load` 获取）                                                                                                                  |
+| `img`        | string | 是       |        | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `string` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `x`          | number | 否       | 0      | 裁剪区域左上角 x 坐标                                                                                                                        |
+| `y`          | number | 否       | 0      | 裁剪区域左上角 y 坐标                                                                                                                        |
+| `ex`         | number | 否       | 0      | 裁剪区域右下角 x 坐标                                                                                                                        |
+| `ey`         | number | 否       | 0      | 裁剪区域右下角 y 坐标                                                                                                                        |
+| `targetSize` | number | 否       | 224    | 分类输入大小，应与模型训练或导出时的输入尺寸一致                                                                                             |
+
+**返回值:**
+
+| 类型           | 描述                                                |
+| -------------- | --------------------------------------------------- |
+| `YoloClsProbs` | Ultralytics `Probs` 风格分类结果，包含 top1/top5 等 |
+
+**示例:**
+
+```lua
+local yoloCls = require("yoloCls")
+local regionProbs = yoloCls.classifyRegion(
+  modelId,
+  "screen",
+  100,
+  100,
+  500,
+  400,
+  224
+)
+
+if regionProbs.top1 ~= nil then
+  print(
+    "区域分类 top1=" .. tostring(regionProbs.top1) .. ", 置信度=" .. tostring(regionProbs.top1conf.toFixed(4))
+  )
+end
+```
+
+### 资源管理
+
+#### free - 释放指定模型资源
+
+释放指定分类模型占用的资源。
+
+```lua
+---@param modelId string
+function free(modelId) end
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述            |
+| --------- | ------ | -------- | ------ | --------------- |
+| `modelId` | string | 是       |        | 要释放的模型 ID |
+
+**示例:**
+
+```lua
+local yoloCls = require("yoloCls")
+if modelId then
+  yoloCls.free(modelId)
+  print("YOLO 分类模型 " .. tostring(modelId) .. " 资源已释放")
+end
+```
+
+#### freeAll - 释放所有模型资源
+
+释放所有已加载的 YOLO 分类模型资源。
+
+```lua
+function freeAll() end
+```
+
+**示例:**
+
+```lua
+local yoloCls = require("yoloCls")
+yoloCls.freeAll()
+print("所有 YOLO 分类模型资源已释放")
+```
+
+## 使用注意事项
+
+- `targetSize` 默认值为 224，常见 YOLO-cls 模型使用该尺寸；自定义模型请填写训练或导出时使用的输入尺寸。
+- `nc` 传 `0` 或省略时会根据模型输出自动推断类别数量；显式传入但和模型输出不匹配时返回空结果。
+- `classifyRegion` 中 `x/y/ex/ey` 全部为 `0` 时表示不裁剪，直接对整张图分类。
+- 裁剪区域必须位于图像范围内，并且 `ex > x`、`ey > y`。
+- 分类结果中的类别 ID 需要结合训练时的类别列表解释；本模块只返回类别 ID 和概率。

package/docs/mcp-agent-description.md

@@ -10,7 +10,8 @@
 
 - JavaScript 项目使用 JavaScript 文档与写法。
 - Python 项目使用 Python 文档与写法。
-- 不要混用 JavaScript 与 Python API。
+- Lua 项目使用 Lua 文档与写法。
+- 不要混用 JavaScript、Python 与 Lua API。
 - 不要把快点JS Python 脚本当成普通 CPython 脚本。
 - 不要对快点JS Python 脚本运行 `python -m py_compile`、`py_compile` 或类似 CPython 编译校验。
 - 不要创建、保留或同步 `__pycache__`、`.pyc` 作为项目改动。
@@ -60,12 +61,12 @@ npx ms package
 
 文档入口：
 
-- MCP：使用 `get_docs_paths` 获取文档根目录、JS 文档目录、中文 JS 文档目录、Python 文档目录和 HTTP API 文档路径。
+- MCP：使用 `get_docs_paths` 获取文档根目录、JS 文档目录、中文 JS 文档目录、Python 文档目录、Lua 文档目录和 HTTP API 文档路径。
 - CLI：使用 `npx ms docs paths` 输出同一组文档路径。
 
 读取规则：
 
-1. 先根据项目语言选择 `docs/api`、`docs/apicn` 或 `docs/apipython`。
+1. 先根据项目语言选择 `docs/api`、`docs/apicn`、`docs/apipython` 或 `docs/apilua`。
 2. 直接读取对应目录下的 markdown 文件。
 3. 调用 HTTP API 前，直接读取 `docs/httpapi/api.md`。
 4. 只依据已读取的本地文档内容回答或编写代码。
@@ -203,7 +204,7 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 
 - 不要在没有读取本地文档的情况下回答 API 用法或编写 API 调用代码。
 - 不要臆造快点JS API、对象、参数、返回值或运行机制。
-- 不要混用 JavaScript 与 Python API。
+- 不要混用 JavaScript、Python 与 Lua API。
 - 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
 - 不要对快点JS Python 脚本运行 `py_compile` 或其他 CPython 编译校验。
 - 不要在没有读取本地 HTTP API 文档的情况下调用 `http_api_call` 或 `ms http-call`。

package/docs/quick/vscode/createProject.md

@@ -0,0 +1,84 @@
+# 创建项目
+
+**前置条件**
+
+- 已安装 Visual Studio Code 和 快点 JS 开发工具插件
+- 快点 JS 开发工具插件需要登录`快点JS 开发者账号`，才能创建项目，请点击顶部菜单`开发者后台`注册账号
+- 快点 JS APP 也需要注册账号才能使用，注意`快点JS APP的账号`和 `快点JS 开发工具插件`的账号是不同的
+- 快点 JS APP 需要从`快点JS APP` 上<span style="color: red;">注册账号</span>，注册完成后，需要登录`快点JS APP`，才能使用
+
+## 创建项目
+
+- 快点 JS 使用 `javascript`/`python`/`lua` 编写脚本，入口文件为 `main.js` 或 `main.py` 或 `main.lua`
+
+- 在创建`快点JS`项目之前，请确保你拥有 js 基础，了解 js 的语法，才能正常使用`快点JS`
+- 可以查找`快点JS`的文档，了解`快点JS`的语法，如[点此进入 JS 基础教程](../js-tutorial/introduction.md)
+- 点击`创建快点JS项目`，如没有安装`快点JS开发工具插件`，是不会有这个按钮的
+- 选择一个文件目录，输入项目名称，回车创建项目
+- 快点 JS-JS 引擎使用 `ES6` 语法，支持 import 别的 js 文件
+- 快点 JS-Python 引擎使用 `Python3.14`, 打包需要安装 `Python3.14`
+- 快点 JS-Lua 引擎入口为 `scripts/main.lua`，模块通过 `require("device")` 加载，全局函数如 `Sleep` 可直接调用
+- 项目创建完成后，会自动打开项目，项目结构如下：
+
+### 项目结构
+
+```
+项目名称/
+├─ scripts/                 ← 脚本存放目录
+│  └─ main.js               ← JS引擎程序入口（文件名不可改变，仅js项目）
+|  └─ main.py               ← Python程序入口（文件名不可改变，仅python项目）
+|  └─ main.lua              ← Lua程序入口（文件名不可改变，仅lua项目）
+├─ res/                     ← 资源存放目录
+├─ ui/                      ← UI 界面存放目录
+│  ├─ fonts/
+│  ├─ htmljs/
+│  └─ index.html
+├─ .gitignore               ← Git 忽略文件
+├─ .npmrc                   ← npm 配置文件
+├─ .prettierignore          ← 代码格式化忽略文件（仅js项目）
+├─ .prettierrc.yaml         ← 代码格式化配置（需安装 Prettier 插件，仅js项目）
+├─ obfuscator.json          ← 代码混淆配置（javascript-obfuscator，仅js项目）
+├─ package.json             ← 项目依赖配置文件
+└─ tsconfig.json            ← TypeScript 配置文件（用于js提示和网页提示）
+```
+
+### 创建项目
+
+<img src="/img/Project/createProject.jpg" width="800" alt="创建项目">
+
+### 项目类型
+
+<img src="/img/Project/项目类型.jpg" width="800" alt="创建项目">
+
+## 安装依赖
+
+- 项目第一次创建打开时，可能会提示环境不满足，跟随提示自动配置环境，点击一键安装即可
+
+<img src="/img/Project/installDeps.jpg" width="800" alt="安装依赖">
+
+## 运行项目
+
+**使用说明**
+
+- 点击运行项目，会执行编译同步到设备上运行，同时运行会变成停止按钮
+- 点击停止项目，会停止设备上运行的项目，如果项目没有写死循环，会自动退出
+- 点击运行 UI，设备会打开项目的 UI 界面，打开配置的 html
+- 点击图色按钮，会打开图色工具
+- 点击节点查找按钮，会打开节点查找工具
+- 点击实时画面，会打开手机实时画面
+- 点击打包，会打包项目为msbundle脚本包，打包完成后，会在项目目录下生成msbundle文件
+
+**注意事项**
+
+- 当你的 VisualStudioCode 安装其他的插件时，编辑器右侧顶部工具栏，可能图标不显示，因为被其他插件占用了
+- 你可以通过编辑器右键菜单->`快点JS`->的下级菜单，来使用所有功能
+
+<img src="/img/Project/devloper.png" width="800" alt="运行项目">
+
+## 常见问题
+
+### 无法显示`debug`或`warn`级别的日志
+
+- VisualStudioCode 日志控制台默认是信息也就是 INFO 请设置为跟踪，并点击设置为默认值，否则可能看不到 `debug` 或 `warn` 级别的日志
+
+<img src="/img/Project/log.png" width="800" alt="日志控制台">

package/docs/quick/vscode/packProject.md

@@ -0,0 +1,17 @@
+# 打包脚本包
+
+**前置条件**
+
+- 需要在项目配置 `AppId` 字段
+- `AppId` 从开发者后台->网络验证管理->软件列表 中获取
+
+**操作步骤**
+
+- 打开主脚本 `main.js | main.py | main.lua`，右键编辑器，选择 `快点JS` -> `打包应用`
+- 输入在开发者后台->网络验证管理->软件列表 中获取的 `AppId` 字段
+- 注意：上传到快点JS热更新服务后，可通过开发者后台->网络验证管理->软件列表的软件编号进行分发
+- 注意：快点JS上可通过软件面板，输入软件编号进行搜索加载应用
+
+<img src="/img/PackProject/打包菜单.png" width="800" alt="打包菜单">
+
+<img src="/img/PackProject/packageIPA.png" width="800" alt="打包IPA">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.49",
+  "version": "1.4.51",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {
@@ -21,6 +21,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@gamely/prometheus-cli": "^0.0.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "acorn": "8.15.0",
     "archiver": "^7.0.1",