ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/utils.md

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

package/docs/api/yolo.md

@@ -0,0 +1,310 @@
+# 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  |
+
+## 数据结构
+
+### YoloResult
+
+YOLO 检测结果接口，包含检测到的物体的完整信息。
+
+```typescript
+interface YoloResult {
+  x: number; // 检测框的左上角x坐标
+  y: number; // 检测框的左上角y坐标
+  ex: number; // 检测框的右下角x坐标
+  ey: number; // 检测框的右下角y坐标
+  centerX: number; // 检测框的中心点x坐标
+  centerY: number; // 检测框的中心点y坐标
+  width: number; // 检测框的宽度
+  height: number; // 检测框的高度
+  confidence: number; // 检测框的置信度 (0-1)
+  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）
+
+加载模型是使用目标检测功能的前提。
+
+```typescript
+function load(
+  paramPath: string,
+  binPath: string,
+  nc: number,
+  version?: number
+): string | null;
+```
+
+**参数:**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                        |
+| ----------- | ------ | -------- | ------ | ------------------------------------------- |
+| `paramPath` | string | 是       |        | NCNN 模型的 param 文件绝对路径              |
+| `binPath`   | string | 是       |        | NCNN 模型的 bin 文件绝对路径                |
+| `nc`        | number | 是       |        | 模型的标签数量，可在标签集 data.yaml 中查看 |
+| `version`   | number | 否       | 11     | YOLO 模型版本号（仅支持 8/11/26）           |
+
+**返回值:**
+
+| 类型             | 描述                                      |
+| ---------------- | ----------------------------------------- |
+| `string \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+
+**示例:**
+
+```javascript
+// 加载 YOLOv8 模型
+const modelId = yolo.load(
+  "yolov8n_ncnn_model/model.ncnn.param",
+  "yolov8n_ncnn_model/model.ncnn.bin",
+  80,
+  8
+);
+```
+
+#### loadV11 - 加载 YOLOv11 模型（兼容 yolov8 模型），这是使用目标检测功能的前提。
+
+```typescript
+function loadV11(paramPath: string, binPath: string, nc: number): string | null;
+```
+
+**参数:**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                        |
+| ----------- | ------ | -------- | ------ | ------------------------------------------- |
+| `paramPath` | string | 是       |        | NCNN 模型的 param 文件绝对路径              |
+| `binPath`   | string | 是       |        | NCNN 模型的 bin 文件绝对路径                |
+| `nc`        | number | 是       |        | 模型的标签数量，可在标签集 data.yaml 中查看 |
+
+**返回值:**
+
+| 类型             | 描述                                      |
+| ---------------- | ----------------------------------------- |
+| `string \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+
+**示例:**
+
+```javascript
+// 加载 YOLOv11 模型
+// 模型放在res目录
+const modelId = yolo.loadV11(
+  "yolo11n_ncnn_model/model.ncnn.param",
+  "yolo11n_ncnn_model/model.ncnn.bin",
+  80 // COCO 数据集有 80 个类别
+);
+
+if (modelId) {
+  logi(`模型加载成功，ID: ${modelId}`);
+} else {
+  logi("模型加载失败，请检查文件路径和格式");
+}
+```
+
+### 目标检测
+
+#### detect - 执行目标检测，识别图像中的物体并返回检测结果。
+
+```typescript
+function detect(
+  modelId: string,
+  img: string,
+  targetSize?: number,
+  threshold?: number,
+  nmsThreshold?: number
+): YoloResult[];
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelId`    | string | 是       |        | 模型 ID（通过 loadV11 获取）                                                                                                                 |
+| `img`        | string | 是       |        | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `string` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `targetSize` | number | 否       | 640    | 图像缩放的检测大小，通常为 640（与模型训练时一致）                                                                                           |
+| `threshold`  | number | 否       | 0.4    | 置信度阈值，默认 0.4，低于此值的检测结果会被过滤                                                                                             |
+
+- `nmsThreshold` - 非极大值抑制阈值，默认 0.5，用于去除重叠检测框
+
+**返回值:**
+
+| 类型           | 描述                                           |
+| -------------- | ---------------------------------------------- |
+| `YoloResult[]` | 检测结果数组，每个元素包含一个检测到的物体信息 |
+
+**示例:**
+
+```javascript
+// 首先加载模型
+const modelId = yolo.loadV11(
+  "/yolo11n_ncnn_model/model.ncnn.param",
+  "/yolo11n_ncnn_model/model.ncnn.bin",
+  80
+);
+
+if (!modelId) {
+  logi("模型加载失败");
+  return;
+}
+
+// 检测当前屏幕
+const screenResults = yolo.detect(
+  modelId,
+  "screen", // 使用当前屏幕
+  640, // 标准检测尺寸
+  0.4, // 置信度阈值
+  0.5 // NMS 阈值
+);
+
+logi(`屏幕检测到 ${screenResults.length} 个物体`);
+
+screenResults.forEach((result, index) => {
+  logi(`物体 ${index + 1}:`);
+  logi(`  类别ID: ${result.classId}`);
+  logi(`  置信度: ${(result.confidence * 100).toFixed(2)}%`);
+  logi(
+    `  边界框: (${result.x}, ${result.y}, ${result.x + result.width}, ${
+      result.y + result.height
+    })`
+  );
+  logi(`  中心点: (${result.centerX}, ${result.centerY})`);
+  logi(`  尺寸: ${result.width} x ${result.height}`);
+});
+
+// 检测图片文件
+const imageResults = yolo.detect(
+  modelId,
+  "/path/to/test_image.jpg",
+  640,
+  0.3, // 降低置信度阈值以检测更多物体
+  0.5
+);
+
+if (imageResults.length > 0) {
+  logi(`图片中检测到 ${imageResults.length} 个物体`);
+  imageResults.forEach((result) => {
+    logi(
+      `检测到类别 ${result.classId}，置信度: ${result.confidence.toFixed(3)}`
+    );
+  });
+} else {
+  logi("图片中未检测到任何物体");
+}
+
+// 检测网络图片
+const urlResults = yolo.detect(
+  modelId,
+  "https://example.com/test_image.jpg",
+  640,
+  0.5, // 提高置信度阈值以获得更可靠的结果
+  0.4
+);
+
+logi(`网络图片检测结果: ${urlResults.length} 个物体`);
+
+// 高精度检测（降低阈值）
+const highPrecisionResults = yolo.detect(
+  modelId,
+  null,
+  640,
+  0.2, // 更低的置信度阈值
+  0.3 // 更低的 NMS 阈值
+);
+
+logi(`高精度检测结果: ${highPrecisionResults.length} 个物体`);
+
+// 快速检测（提高阈值）
+const fastResults = yolo.detect(
+  modelId,
+  null,
+  416, // 更小的检测尺寸以提高速度
+  0.6, // 更高的置信度阈值
+  0.6 // 更高的 NMS 阈值
+);
+
+logi(`快速检测结果: ${fastResults.length} 个物体`);
+```
+
+### 资源管理
+
+#### free - 释放指定模型的资源。
+
+```typescript
+function free(modelId: string): void;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述            |
+| --------- | ------ | -------- | ------ | --------------- |
+| `modelId` | string | 是       |        | 要释放的模型 ID |
+
+**示例:**
+
+```javascript
+// 释放特定模型
+if (modelId) {
+  yolo.free(modelId);
+  logi(`模型 ${modelId} 资源已释放`);
+}
+
+// 使用完毕后释放资源
+function cleanupModel(modelId) {
+  if (modelId) {
+    yolo.free(modelId);
+    logi("模型资源已清理");
+  }
+}
+
+cleanupModel(modelId);
+```
+
+#### freeAll - 释放所有已加载模型的资源。
+
+```typescript
+function freeAll(): void;
+```
+
+**示例:**
+
+```javascript
+// 释放所有模型资源
+yolo.freeAll();
+logi("所有 YOLO 模型资源已释放");
+```