ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apicn/utils.md

@@ -0,0 +1,265 @@
+# 工具模块 ($工具)
+
+工具模块提供了一系列实用的工具函数，包括时间格式化、资源文件读取、随机数生成、应用前台切换等常用功能。
+
+## 功能概览
+
+- **时间处理**: 时间格式化功能
+- **随机数生成**: 生成指定范围的随机数
+- **应用控制**: 将应用切换到前台
+- **编码转换**: 字符串编码与解码工具
+
+## API 参考
+
+### 时间处理
+
+#### 获取当前时间字符串 - 格式化当前时间为指定格式的字符串。
+
+```typescript
+function 获取当前时间字符串(格式化字符串: 字符串): 字符串;
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                      |
+| -------------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `格式化字符串` | string | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `hh` - 两位小时（24 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
+
+**返回值:**
+
+| 类型     | 描述                 |
+| -------- | -------------------- |
+| `字符串` | 格式化后的时间字符串 |
+
+**示例:**
+
+```javascript
+// 标准日期时间格式
+const dateTime = $工具.获取当前时间字符串("yyyy-MM-dd hh:mm:ss");
+$打印信息日志(dateTime); // 输出: 2024-01-15 14:30:25
+
+// 仅日期格式
+const date = $工具.获取当前时间字符串("yyyy-MM-dd");
+$打印信息日志(date); // 输出: 2024-01-15
+
+// 仅时间格式
+const time = $工具.获取当前时间字符串("hh:mm:ss");
+$打印信息日志(time); // 输出: 14:30:25
+
+// 自定义分隔符
+const customFormat = $工具.获取当前时间字符串("yyyy/MM/dd hh:mm");
+$打印信息日志(customFormat); // 输出: 2024/01/15 14:30
+
+// 紧凑格式
+const compact = $工具.获取当前时间字符串("yyyyMMddhhmmss");
+$打印信息日志(compact); // 输出: 20240115143025
+```
+
+### 随机数生成
+
+#### 生成随机数 - 生成指定范围内的随机整数。
+
+```typescript
+function 生成随机数(最小值: 数字, 最大值: 数字): 数字;
+```
+
+**参数:**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述           |
+| -------- | ---- | -------- | ------ | -------------- |
+| `最小值` | 数字 | 是       |        | 最小值（包含） |
+| `最大值` | 数字 | 是       |        | 最大值（包含） |
+
+**返回值:**
+
+| 类型   | 描述                 |
+| ------ | -------------------- |
+| `数字` | 指定范围内的随机整数 |
+
+**示例:**
+
+```javascript
+// 生成1-10之间的随机数
+const randomNum = $工具.生成随机数(1, 10);
+$打印信息日志(`随机数: ${randomNum}`);
+
+// 生成0-100之间的随机数
+const percentage = $工具.生成随机数(0, 100);
+$打印信息日志(`随机百分比: ${percentage}`);
+
+// 生成随机延迟时间（毫秒）
+const delay = $工具.生成随机数(1000, 5000);
+$打印信息日志(`随机延迟: ${delay} 毫秒`);
+sleep(delay);
+
+// 生成随机索引
+const array = ["apple", "banana", "orange", "grape"];
+const randomIndex = $工具.生成随机数(0, array.length - 1);
+$打印信息日志(`随机选择: ${array[randomIndex]}`);
+```
+
+#### 生成随机 UUID - 生成随机 UUID。
+
+```typescript
+function 生成随机UUID(): 字符串;
+```
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `字符串` | 随机 UUID 字符串 |
+
+**示例:**
+
+```javascript
+const uuid = $工具.生成随机UUID();
+$打印信息日志(uuid);
+```
+
+### 应用控制
+
+#### APP 切入前台 - 将快点 JS 应用切换到前台显示。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+
+```typescript
+function APP切入前台(): void;
+```
+
+**示例:**
+
+```javascript
+// 将应用切换到前台
+$工具.APP切入前台();
+$打印信息日志("应用已切换到前台");
+```
+
+### 编码转换
+
+#### 字符串转 hex - 字符串转 Hex 字符串。
+
+```typescript
+function 字符串转hex(source: string): string;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述     |
+| -------- | ------ | -------- | ------ | -------- |
+| `source` | string | 是       |        | 源字符串 |
+
+**返回值:**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `string` | Hex 字符串 |
+
+**示例:**
+
+```javascript
+const hex = $工具.字符串转hex("hello");
+$打印信息日志(hex);
+```
+
+#### 字符串转 base64 - 字符串转 Base64。
+
+```typescript
+function 字符串转base64(源字符串: 字符串): 字符串;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `源字符串` | 字符串 | 是       |        | 源字符串 |
+
+**返回值:**
+
+| 类型     | 描述          |
+| -------- | ------------- |
+| `字符串` | Base64 字符串 |
+
+**示例:**
+
+```javascript
+const b64 = $工具.字符串转base64("hello");
+$打印信息日志(b64);
+```
+
+#### base64 转字符串 - Base64 转字符串。
+
+```typescript
+function base64转字符串(源base64字符串: 字符串): 字符串;
+```
+
+**参数:**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述          |
+| ---------------- | ------ | -------- | ------ | ------------- |
+| `源base64字符串` | 字符串 | 是       |        | Base64 字符串 |
+
+**返回值:**
+
+| 类型     | 描述           |
+| -------- | -------------- |
+| `字符串` | 解码后的字符串 |
+
+**示例:**
+
+```javascript
+const str = $工具.base64转字符串("aGVsbG8=");
+$打印信息日志(str);
+```
+
+#### hex 字符串转 base64 - 16 进制字符串转 Base64。
+
+```typescript
+function hex字符串转base64(源16进制字符串: 字符串): 字符串;
+```
+
+**参数:**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述          |
+| ---------------- | ------ | -------- | ------ | ------------- |
+| `源16进制字符串` | 字符串 | 是       |        | 16 进制字符串 |
+
+**返回值:**
+
+| 类型     | 描述          |
+| -------- | ------------- |
+| `字符串` | Base64 字符串 |
+
+**示例:**
+
+```javascript
+const b64 = $工具.hex字符串转base64("68656c6c6f");
+$打印信息日志(b64);
+```
+
+#### base64 转 hex 字符串 - Base64 转 16 进制字符串。
+
+```typescript
+function base64转hex字符串(源base64字符串: 字符串): 字符串;
+```
+
+**参数:**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述          |
+| ---------------- | ------ | -------- | ------ | ------------- |
+| `源base64字符串` | 字符串 | 是       |        | Base64 字符串 |
+
+**返回值:**
+
+| 类型     | 描述          |
+| -------- | ------------- |
+| `字符串` | 16 进制字符串 |
+
+**示例:**
+
+```javascript
+const hex = $工具.base64转hex字符串("aGVsbG8=");
+$打印信息日志(hex);
+```

package/docs/apicn/yolo.md

@@ -0,0 +1,314 @@
+# YOLO 目标检测模块 ($YOLO)
+
+YOLO 模块基于 YOLOV8/YOLO11/YOLO26 算法和 NCNN 框架，提供高性能的实时目标检测功能，支持多种输入源和自定义模型，可用于物体识别、位置定位等应用场景。
+
+## 数据标注
+
+查看 [快点 Label](../label/dataAnnotation.md) 了解如何进行数据标注
+
+## 功能概览
+
+- **模型管理**: YOLOV8/YOLOV11/YOLOV26 模型加载和资源管理
+- **目标检测**: 实时物体检测和位置识别
+- **多源输入**: 支持屏幕截图、图片文件、URL 等多种输入源
+- **结果处理**: 完整的检测结果信息和坐标数据
+- **资源控制**: 完整的模型生命周期管理
+
+## 测试结果
+
+| 设备型号   | 模型类型         | 检测耗时  |
+| ---------- | ---------------- | --------- |
+| iPhoneX    | yolov8n(80 类别) | 70-100ms  |
+| iPhoneX    | yolov8s(80 类别) | 160-200ms |
+| iPhone SE3 | yolov8n(80 类别) | 30-50ms   |
+| iPhone SE3 | yolov8s(80 类别) | 70-100ms  |
+
+## 数据结构
+
+### Yolo 检测结果
+
+YOLO 检测结果接口，包含检测到的物体的完整信息。
+
+```typescript
+interface Yolo检测结果 {
+  x: 数字; // 检测框的左上角x坐标
+  y: 数字; // 检测框的左上角y坐标
+  ex: 数字; // 检测框的右下角x坐标
+  ey: 数字; // 检测框的右下角y坐标
+  centerX: 数字; // 检测框的中心点x坐标
+  centerY: 数字; // 检测框的中心点y坐标
+  width: 数字; // 检测框的宽度
+  height: 数字; // 检测框的高度
+  confidence: 数字; // 检测框的置信度 (0-1)
+  classId: 数字; // 检测框的类别ID
+}
+```
+
+**字段说明:**
+
+| 字段名             | 类型 | 描述                                       |
+| ------------------ | ---- | ------------------------------------------ |
+| `x, y`             | 数字 | 检测框左上角坐标                           |
+| `ex, ey`           | 数字 | 检测框右下角坐标                           |
+| `centerX, centerY` | 数字 | 检测框中心点坐标                           |
+| `width, height`    | 数字 | 检测框尺寸                                 |
+| `confidence`       | 数字 | 检测置信度，范围 0-1，值越高表示检测越可靠 |
+| `classId`          | 数字 | 物体类别 ID，对应训练模型的类别标签        |
+
+## API 参考
+
+### 模型管理
+
+#### 加载模型 - 加载 YOLO 模型（支持版本 8/11/26）
+
+加载模型是使用目标检测功能的前提。
+
+```typescript
+function 加载模型(
+  ncnn模型的param文件路径: 字符串,
+  ncnn模型的bin文件路径: 字符串,
+  标签数量: 数字,
+  模型版本?: 数字
+): 字符串 | null;
+```
+
+**参数:**
+
+| 参数名                    | 类型   | 是否必填 | 默认值 | 描述                                        |
+| ------------------------- | ------ | -------- | ------ | ------------------------------------------- |
+| `ncnn模型的param文件路径` | 字符串 | 是       |        | NCNN 模型的 param 文件绝对路径              |
+| `ncnn模型的bin文件路径`   | 字符串 | 是       |        | NCNN 模型的 bin 文件绝对路径                |
+| `标签数量`                | 数字   | 是       |        | 模型的标签数量，可在标签集 data.yaml 中查看 |
+| `模型版本`                | 数字   | 否       | 11     | YOLO 模型版本号（仅支持 8/11/26）           |
+
+**返回值:**
+
+| 类型             | 描述                                      |
+| ---------------- | ----------------------------------------- |
+| `字符串 \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+
+**示例:**
+
+```javascript
+// 加载 YOLOv8 模型
+const 模型ID = $YOLO.加载模型(
+  "yolov8n_ncnn_model/model.ncnn.param",
+  "yolov8n_ncnn_model/model.ncnn.bin",
+  80,
+  8
+);
+```
+
+#### 加载 YOLOv11 模型 - 加载 YOLOv11 模型（兼容 yolov8 模型），这是使用目标检测功能的前提。
+
+```typescript
+function 加载YOLOv11模型(
+  ncnn模型的param文件路径: 字符串,
+  ncnn模型的bin文件路径: 字符串,
+  标签数量: 数字
+): 字符串 | null;
+```
+
+**参数:**
+
+| 参数名                    | 类型   | 是否必填 | 默认值 | 描述                                        |
+| ------------------------- | ------ | -------- | ------ | ------------------------------------------- |
+| `ncnn模型的param文件路径` | 字符串 | 是       |        | NCNN 模型的 param 文件绝对路径              |
+| `ncnn模型的bin文件路径`   | 字符串 | 是       |        | NCNN 模型的 bin 文件绝对路径                |
+| `标签数量`                | 数字   | 是       |        | 模型的标签数量，可在标签集 data.yaml 中查看 |
+
+**返回值:**
+
+| 类型             | 描述                                      |
+| ---------------- | ----------------------------------------- |
+| `字符串 \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+
+**示例:**
+
+```javascript
+// 加载 YOLOv11 模型
+// 模型放在res目录
+const 模型ID = $YOLO.加载YOLOv11模型(
+  "yolo11n_ncnn_model/model.ncnn.param",
+  "yolo11n_ncnn_model/model.ncnn.bin",
+  80 // COCO 数据集有 80 个类别
+);
+
+if (模型ID) {
+  $打印信息日志(`模型加载成功，ID: ${模型ID}`);
+} else {
+  $打印错误日志("模型加载失败，请检查文件路径和格式");
+}
+```
+
+### 目标检测
+
+#### detect - 执行目标检测，识别图像中的物体并返回检测结果。
+
+```typescript
+function 目标检测(
+  模型ID: 字符串,
+  图片ID: 字符串,
+  目标检测输入大小?: 数字,
+  置信度?: 数字,
+  重叠阈值?: 数字
+): 数组<Yolo检测结果>;
+```
+
+**参数:**
+
+| 参数名             | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                         |
+| ------------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `模型ID`           | 字符串 | 是       |        | 模型 ID（通过 loadV11 获取）                                                                                                                 |
+| `图片ID`           | 字符串 | 是       |        | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `string` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `目标检测输入大小` | 数字   | 否       | 640    | 图像缩放的检测大小，通常为 640（与模型训练时一致）                                                                                           |
+| `置信度`           | 数字   | 否       | 0.4    | 置信度阈值，默认 0.4，低于此值的检测结果会被过滤                                                                                             |
+
+- `重叠阈值` - 非极大值抑制阈值，默认 0.5，用于去除重叠检测框
+
+**返回值:**
+
+| 类型                 | 描述                                           |
+| -------------------- | ---------------------------------------------- |
+| `数组<Yolo检测结果>` | 检测结果数组，每个元素包含一个检测到的物体信息 |
+
+**示例:**
+
+```javascript
+// 首先加载模型
+const 模型ID = $YOLO.加载YOLOv11模型(
+  "/yolo11n_ncnn_model/model.ncnn.param",
+  "/yolo11n_ncnn_model/model.ncnn.bin",
+  80
+);
+
+if (!模型ID) {
+  $打印信息日志("模型加载失败");
+  return;
+}
+
+// 检测当前屏幕
+const screenResults = $YOLO.目标检测(
+  模型ID,
+  "screen", // 使用当前屏幕
+  640, // 标准检测尺寸
+  0.4, // 置信度阈值
+  0.5 // NMS 阈值
+);
+
+$打印信息日志(`屏幕检测到 ${screenResults.length} 个物体`);
+
+screenResults.forEach((result, index) => {
+  $打印信息日志(`物体 ${index + 1}:`);
+  $打印信息日志(`  类别ID: ${result.classId}`);
+  $打印信息日志(`  置信度: ${(result.confidence * 100).toFixed(2)}%`);
+  $打印信息日志(
+    `  边界框: (${result.x}, ${result.y}, ${result.x + result.width}, ${
+      result.y + result.height
+    })`
+  );
+  $打印信息日志(`  中心点: (${result.centerX}, ${result.centerY})`);
+  $打印信息日志(`  尺寸: ${result.width} x ${result.height}`);
+});
+
+// 检测图片文件
+const imageResults = $YOLO.目标检测(
+  模型ID,
+  "/path/to/test_image.jpg",
+  640,
+  0.3, // 降低置信度阈值以检测更多物体
+  0.5
+);
+
+if (imageResults.length > 0) {
+  $打印信息日志(`图片中检测到 ${imageResults.length} 个物体`);
+  imageResults.forEach((result) => {
+    $打印信息日志(
+      `检测到类别 ${result.classId}，置信度: ${result.confidence.toFixed(3)}`
+    );
+  });
+} else {
+  $打印信息日志("图片中未检测到任何物体");
+}
+
+// 检测网络图片
+const urlResults = $YOLO.目标检测(
+  模型ID,
+  "https://example.com/test_image.jpg",
+  640,
+  0.5, // 提高置信度阈值以获得更可靠的结果
+  0.4
+);
+
+$打印信息日志(`网络图片检测结果: ${urlResults.length} 个物体`);
+
+// 高精度检测（降低阈值）
+const highPrecisionResults = $YOLO.目标检测(
+  模型ID,
+  null,
+  640,
+  0.2, // 更低的置信度阈值
+  0.3 // 更低的 NMS 阈值
+);
+
+$打印信息日志(`高精度检测结果: ${highPrecisionResults.length} 个物体`);
+
+// 快速检测（提高阈值）
+const fastResults = $YOLO.目标检测(
+  模型ID,
+  null,
+  416, // 更小的检测尺寸以提高速度
+  0.6, // 更高的置信度阈值
+  0.6 // 更高的 NMS 阈值
+);
+
+$打印信息日志(`快速检测结果: ${fastResults.length} 个物体`);
+```
+
+### 资源管理
+
+#### 释放模型资源
+
+```typescript
+function 释放模型资源(模型ID: 字符串): 无返回值;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述            |
+| -------- | ------ | -------- | ------ | --------------- |
+| `模型ID` | 字符串 | 是       |        | 要释放的模型 ID |
+
+**示例:**
+
+```javascript
+// 释放特定模型
+if (模型ID) {
+  $YOLO.释放模型资源(模型ID);
+  $打印信息日志(`模型 ${模型ID} 资源已释放`);
+}
+
+// 使用完毕后释放资源
+function 清理模型资源(模型ID: 字符串) {
+  if (模型ID) {
+    $YOLO.释放模型资源(模型ID);
+    $打印信息日志("模型资源已清理");
+  }
+}
+
+清理模型资源(模型ID);
+```
+
+#### 释放所有模型资源
+
+```typescript
+function 释放所有模型资源(): 无返回值;
+```
+
+**示例:**
+
+```javascript
+// 释放所有模型资源
+$YOLO.释放所有模型资源();
+$打印信息日志("所有 YOLO 模型资源已释放");
+```