ms-vite-plugin 1.1.2 → 1.1.4

package/docs/apipython/utils.md

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

package/docs/apipython/yolo.md

@@ -0,0 +1,281 @@
+# 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 检测结果字典，包含检测到的物体的完整信息。
+
+```python
+from typing import TypedDict
+
+class YoloResult(TypedDict):
+    x: int          # 检测框的左上角x坐标
+    y: int          # 检测框的左上角y坐标
+    ex: int         # 检测框的右下角x坐标
+    ey: int         # 检测框的右下角y坐标
+    centerX: int    # 检测框的中心点x坐标
+    centerY: int    # 检测框的中心点y坐标
+    width: int      # 检测框的宽度
+    height: int     # 检测框的高度
+    confidence: float # 检测框的置信度 (0-1)
+    classId: int    # 检测框的类别ID
+```
+
+**字段说明:**
+
+| 字段名             | 类型  | 描述                                       |
+| ------------------ | ----- | ------------------------------------------ |
+| `x, y`             | int   | 检测框左上角坐标                           |
+| `ex, ey`           | int   | 检测框右下角坐标                           |
+| `centerX, centerY` | int   | 检测框中心点坐标                           |
+| `width, height`    | int   | 检测框尺寸                                 |
+| `confidence`       | float | 检测置信度，范围 0-1，值越高表示检测越可靠 |
+| `classId`          | int   | 物体类别 ID，对应训练模型的类别标签        |
+
+## API 参考
+
+### 模型管理
+
+#### load - 加载 YOLO 模型（支持版本 8/11/26）
+
+加载模型是使用目标检测功能的前提。
+
+```python
+def load(paramPath: str, binPath: str, nc: int, version: int = 11) -> Optional[str]
+```
+
+**参数:**
+
+| 参数名      | 类型 | 是否必填 | 默认值 | 描述                                        |
+| ----------- | ---- | -------- | ------ | ------------------------------------------- |
+| `paramPath` | str  | 是       | -      | NCNN 模型的 param 文件绝对路径              |
+| `binPath`   | str  | 是       | -      | NCNN 模型的 bin 文件绝对路径                |
+| `nc`        | int  | 是       | -      | 模型的标签数量（在标签集 data.yaml 中查看） |
+| `version`   | int  | 否       | 11     | YOLO 模型版本号（仅支持 8/11/26）           |
+
+**返回值:**
+
+| 类型          | 描述                                 |
+| ------------- | ------------------------------------ |
+| `str \| None` | 加载成功返回模型 ID，失败返回 `None` |
+
+**示例:**
+
+```python
+from kuaijs import yolo
+
+# 加载 YOLOv8 模型
+model_id = yolo.load(
+    "yolov8n_ncnn_model/model.ncnn.param",
+    "yolov8n_ncnn_model/model.ncnn.bin",
+    80,
+    8,
+)
+```
+
+#### loadV11 - 加载 YOLOv11 模型（兼容 yolov8）
+
+加载模型是使用目标检测功能的前提。
+
+```python
+def loadV11(paramPath: str, binPath: str, nc: int) -> Optional[str]
+```
+
+**参数:**
+
+| 参数名      | 类型 | 是否必填 | 默认值 | 描述                                        |
+| ----------- | ---- | -------- | ------ | ------------------------------------------- |
+| `paramPath` | str  | 是       | -      | NCNN 模型的 param 文件绝对路径              |
+| `binPath`   | str  | 是       | -      | NCNN 模型的 bin 文件绝对路径                |
+| `nc`        | int  | 是       | -      | 模型的标签数量（在标签集 data.yaml 中查看） |
+
+**返回值:**
+
+| 类型          | 描述                                 |
+| ------------- | ------------------------------------ |
+| `str \| None` | 加载成功返回模型 ID，失败返回 `None` |
+
+**示例:**
+
+```python
+from kuaijs import yolo
+
+# 加载 YOLOv11 模型
+# 模型放在res目录
+model_id = yolo.loadV11(
+    "yolo11n_ncnn_model/model.ncnn.param",
+    "yolo11n_ncnn_model/model.ncnn.bin",
+    80 # COCO 数据集有 80 个类别
+)
+
+if model_id:
+    print(f"模型加载成功，ID: {model_id}")
+else:
+    print("模型加载失败，请检查文件路径和格式")
+```
+
+### 目标检测
+
+#### detect - 执行目标检测
+
+识别图像中的物体并返回检测结果。
+
+```python
+def detect(
+    modelId: str,
+    img: str,
+    targetSize: int = 640,
+    threshold: float = 0.4,
+    nmsThreshold: float = 0.5
+) -> List[YoloResult]
+```
+
+**参数:**
+
+| 参数名         | 类型  | 是否必填 | 默认值 | 描述                                                                                                                                      |
+| -------------- | ----- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelId`      | str   | 是       | -      | 模型 ID（通过 `loadV11` 获取）                                                                                                            |
+| `img`          | str   | 是       | -      | 图像输入源：<br>- `"screen"` - 使用当前屏幕截图<br>- `str` - 图片文件路径或 HTTP 图片地址<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `targetSize`   | int   | 否       | 640    | 图像缩放的检测大小，通常为 640（与模型训练时一致）                                                                                        |
+| `threshold`    | float | 否       | 0.4    | 置信度阈值，默认 0.4，低于此值的检测结果会被过滤                                                                                          |
+| `nmsThreshold` | float | 否       | 0.5    | 非极大值抑制阈值，默认 0.5，用于去除重叠检测框                                                                                            |
+
+**返回值:**
+
+| 类型               | 描述                                           |
+| ------------------ | ---------------------------------------------- |
+| `List[YoloResult]` | 检测结果数组，每个元素包含一个检测到的物体信息 |
+
+**示例:**
+
+```python
+from kuaijs import yolo
+
+# 首先加载模型
+mid = yolo.loadV11("yolo11n_ncnn_model/model.ncnn.param", "yolo11n_ncnn_model/model.ncnn.bin", 80)
+
+if not mid:
+    print("模型加载失败")
+else:
+    # 检测当前屏幕
+    screen_results = yolo.detect(
+        mid,
+        "screen", # 使用当前屏幕
+        640,      # 标准检测尺寸
+        0.4,      # 置信度阈值
+        0.5       # NMS 阈值
+    )
+
+    print(f"屏幕检测到 {len(screen_results)} 个物体")
+
+    for i, r in enumerate(screen_results):
+        print(f"物体 {i + 1}:")
+        print(f"  类别ID: {r.classId}")
+        print(f"  置信度: {round(r.confidence * 100, 2)}%")
+        print(f"  边界框: ({r.x}, {r.y}, {r.ex}, {r.ey})")
+        print(f"  中心点: ({r.centerX}, {r.centerY})")
+        print(f"  尺寸: {r.width} x {r.height}")
+
+    # 检测图片文件
+    image_results = yolo.detect(
+        mid,
+        "/path/to/test_image.jpg",
+        640,
+        0.3, # 降低置信度阈值以检测更多物体
+        0.5
+    )
+
+    if image_results:
+        print(f"图片中检测到 {len(image_results)} 个物体")
+        for r in image_results:
+            print(f"检测到类别 {r.classId}，置信度: {round(r.confidence, 3)}")
+    else:
+        print("图片中未检测到任何物体")
+
+    # 检测网络图片
+    url_results = yolo.detect(
+        mid,
+        "https://example.com/test_image.jpg",
+        640,
+        0.5, # 提高置信度阈值以获得更可靠的结果
+        0.4
+    )
+    print(f"网络图片检测结果: {len(url_results)} 个物体")
+```
+
+### 资源管理
+
+#### free - 释放指定模型
+
+释放指定模型的资源。
+
+```python
+def free(modelId: str) -> None
+```
+
+**参数:**
+
+| 参数名    | 类型 | 是否必填 | 默认值 | 描述            |
+| --------- | ---- | -------- | ------ | --------------- |
+| `modelId` | str  | 是       | -      | 要释放的模型 ID |
+
+**示例:**
+
+```python
+from kuaijs import yolo
+
+# 释放特定模型
+if model_id:
+    yolo.free(model_id)
+    print(f"模型 {model_id} 资源已释放")
+
+# 使用完毕后释放资源
+def cleanup_model(mid):
+    if mid:
+        yolo.free(mid)
+        print("模型资源已清理")
+
+cleanup_model(model_id)
+```
+
+#### freeAll - 释放所有模型
+
+释放所有已加载模型的资源。
+
+```python
+def freeAll() -> None
+```
+
+**示例:**
+
+```python
+from kuaijs import yolo
+
+# 释放所有模型资源
+yolo.freeAll()
+print("所有 YOLO 模型资源已释放")
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {
@@ -8,17 +8,20 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "docs"
   ],
   "bin": {
     "ms-cli": "dist/cli.js",
-    "ms": "dist/cli.js"
+    "ms": "dist/cli.js",
+    "ms-mcp": "dist/mcp-server.js"
   },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.1",
     "archiver": "^7.0.1",
     "commander": "^14.0.3",
     "crc": "^4.3.2",
@@ -26,7 +29,8 @@
     "uuid": "^14.0.0",
     "vite": "^8.0.9",
     "vite-plugin-bundle-obfuscator": "^1.11.0",
-    "ws": "^8.20.0"
+    "ws": "^8.20.0",
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@types/archiver": "^7.0.0",