ms-types 0.9.6 → 0.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-types",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/types/appleocr.d.ts

@@ -37,11 +37,10 @@ declare namespace appleOcr {
    * @param ey 边界框右下角y坐标 默认 0
    * @param languages 识别语言数组，默认为["zh-Hans", "en-US"]
    * @returns 识别结果数组，包含文本、置信度、坐标等信息
+   * @deprecated 请改用 recognizeAbs，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const results = appleOcr.recognize("screen", 0, 0, 100, 100, ["zh-Hans", "en-US"])
-   * results.forEach(result => {
-   *   logi(`文本: ${result.text}, 置信度: ${result.confidence}`)
-   * })
+   * const results = appleOcr.recognizeAbs("screen", 0, 0, 100, 100, ["zh-Hans", "en-US"])
+   * logi(`识别数量: ${results.length}`)
    */
   function recognize(
     input: string,
@@ -84,11 +83,10 @@ declare namespace appleOcr {
    * @param ex 边界框右下角x坐标
    * @param ey 边界框右下角y坐标
    * @returns 识别结果数组，包含文本、置信度、坐标等信息
+   * @deprecated 请改用 recognizeNumbersAbs，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const results = appleOcr.recognizeNumbers("screen", 0, 0, 100, 100)
-   * results.forEach(result => {
-   *   logi(`文本: ${result.text}, 置信度: ${result.confidence}`)
-   * })
+   * const results = appleOcr.recognizeNumbersAbs("screen", 0, 0, 100, 100)
+   * logi(`数字识别数量: ${results.length}`)
    */
   function recognizeNumbers(
     input: string,
@@ -131,11 +129,10 @@ declare namespace appleOcr {
    * @param languages 识别语言数组，默认为["zh-Hans", "en-US"]
    * @param exactMatch 是否完整匹配，默认 false 表示包含匹配；传 true 时要求整条 OCR 识别结果文本等于目标文本
    * @returns 命中子串的识别结果数组，坐标对应目标子串区域
+   * @deprecated 请改用 findTextAbs，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const results = appleOcr.findText("screen", ["开始"], 0, 0, 100, 100, ["zh-Hans", "en-US"])
-   * results.forEach(result => {
-   *   logi(`文本: ${result.text}, 置信度: ${result.confidence}`)
-   * })
+   * const results = appleOcr.findTextAbs("screen", ["开始"], 0, 0, 100, 100, ["zh-Hans", "en-US"])
+   * logi(`命中数量: ${results.length}`)
    */
   function findText(
     input: string,

package/types/image.d.ts

@@ -21,14 +21,15 @@ declare namespace image {
     ex?: number,
     ey?: number,
   ): string | null;
-  /**
-   * 截图
-   * @returns 截图的imageId ，如果截图失败则返回null
-   * @example
-   * const imageId = image.captureFullScreen()
-   * if (imageId) {
-   *   image.saveTo(imageId, "screen.jpg")
-   * }
+  /**
+   * 截图
+   * @returns 截图的imageId ，如果截图失败则返回null
+   * @deprecated 请改用 captureScreen()。
+   * @example
+   * const imageId = image.captureScreen()
+   * if (imageId) {
+   *   image.saveTo(imageId, "screen.jpg")
+   * }
    */
   function captureFullScreen(): string | null;
   /**
@@ -36,13 +37,14 @@ declare namespace image {
    * @param x 截图区域左上角x坐标
    * @param y 截图区域左上角y坐标
    * @param ex 截图区域右下角x坐标
-   * @param ey 截图区域右下角y坐标
-   * @returns 截图的imageId ，如果截图失败则返回null
-   * @example
-   * const imageId = image.captureRect(0, 0, 100, 100)
-   * if (imageId) {
-   *   image.saveTo(imageId, "screen.jpg")
-   * }
+   * @param ey 截图区域右下角y坐标
+   * @returns 截图的imageId ，如果截图失败则返回null
+   * @deprecated 请改用 captureScreen(x, y, ex, ey)。
+   * @example
+   * const imageId = image.captureScreen(0, 0, 100, 100)
+   * if (imageId) {
+   *   image.saveTo(imageId, "screen.jpg")
+   * }
    */
   function captureRect(
     x: number,
@@ -61,11 +63,11 @@ declare namespace image {
   /**
    * 图片是否已释放
    * @param imageId 图片id
-   * @returns true 已释放 false 未释放
-   * @example
-   * const imageId = image.captureFullScreen()
-   * if (imageId) {
-   *   image.saveTo(imageId, "screen.jpg")
+   * @returns true 已释放 false 未释放
+   * @example
+   * const imageId = image.captureScreen()
+   * if (imageId) {
+   *   image.saveTo(imageId, "screen.jpg")
    *   image.isRelease(imageId) // false
    *   image.release(imageId)
    *   image.isRelease(imageId) // true

package/types/media.d.ts

@@ -87,17 +87,16 @@ declare namespace media {
   function stopMp3(): boolean;
 
   /**
-   * 同步播放MP3音乐（等待结束）
+   * 同步播放MP3音乐（播放一次并等待结束）
    * @param path 文件路径
-   * @param loop 是否循环播放
    * @returns 是否播放成功
    * @example
-   * const played = media.playMp3WaitEnd("music.mp3", true)
+   * const played = media.playMp3WaitEnd("music.mp3")
    * if (played) {
    *   logi("播放成功")
    * }
    */
-  function playMp3WaitEnd(path: string, loop: boolean): boolean;
+  function playMp3WaitEnd(path: string): boolean;
 
   /**
    * 查询MP3音乐是否正在播放

package/types/paddleocr.d.ts

@@ -1,7 +1,12 @@
 /**
- * 飞桨OCR模块 包含OCR识别、OCR模型加载等功能
+ * 飞桨OCR模块 包含OCR识别、模型切换和资源释放等功能
  */
 declare namespace paddleOcr {
+  /**
+   * PaddleOCR 内置模型 ID。
+   */
+  type PaddleOCRModelId = "ppocr-v6-tiny" | "ppocr-v6-small" | "ppocr-v5";
+
   /**
    * OCR识别结果接口
    */
@@ -33,17 +38,38 @@ declare namespace paddleOcr {
   }
 
   /**
-   * 初始化PP-OCRv5模型
+   * 手动切换到 PP-OCRv5 模型。PaddleOCR 默认自动加载 PP-OCRv6 tiny；同一时间只保留一个 active 模型，加载成功后会替换已加载的 PP-OCRv6 模型。
    * @param maxSideLen 最大边长，默认640，可不传
    * @param useGpu 是否使用GPU，默认false，可不传
-   * @returns 初始化成功或模型已加载返回true
+   * @returns 加载成功或模型已加载返回true
+   * @deprecated 请改用 loadModel("ppocr-v5", useGpu)；检测长边请使用 setMaxSideLen 单独设置。
    * @example
-   * const loaded = paddleOcr.loadV5(640, true)
-   * if (loaded) {
-   *   logi("加载成功")
-   * }
+   * const results = paddleOcr.recognizeAbs("screen", 0, 0, 0, 0)
+   * logi(`识别数量: ${results.length}`)
    */
   function loadV5(maxSideLen?: number, useGpu?: boolean): boolean;
+  /**
+   * 按模型 ID 手动加载内置 PaddleOCR 模型。识别和查找方法默认自动加载 ppocr-v6-tiny；同一时间只保留一个 active 模型，加载成功后会替换已加载模型；检测长边请使用 setMaxSideLen 单独设置。
+   * @param modelId 模型 ID，必须传入，支持 "ppocr-v6-tiny"、"ppocr-v6-small"、"ppocr-v5"
+   * @param useGpu 是否使用GPU，默认false，可不传
+   * @returns 加载成功或目标模型已加载返回true
+   * @example
+   * const ok = paddleOcr.loadModel("ppocr-v6-small", false)
+   * logi(`PaddleOCR 模型加载结果: ${ok}`)
+   */
+  function loadModel(
+    modelId: PaddleOCRModelId,
+    useGpu?: boolean,
+  ): boolean;
+  /**
+   * 单独设置检测阶段输入最大边长，不重新加载已加载的 PP-OCRv5/v6 模型。可在首次识别前调用，后续默认自动加载 PP-OCRv6 tiny 时会沿用该设置。
+   * @param maxSideLen 最大边长，默认640；传 0 或负数时使用默认值 640
+   * @returns 设置成功返回true
+   * @example
+   * paddleOcr.setMaxSideLen(960)
+   * const results = paddleOcr.recognizeAbs("screen", 0, 0, 0, 0)
+   */
+  function setMaxSideLen(maxSideLen?: number): boolean;
   /**
    * 执行OCR识别
    * @param input 输入源（imageId、URL字符串、文件路径或"screen"，"screen"表示使用当前屏幕）
@@ -53,6 +79,7 @@ declare namespace paddleOcr {
    * @param ey 裁剪区域右下角 y 坐标，全屏传 0，默认 0
    * @param confidenceThreshold 置信度阈值，默认 0.6
    * @returns 识别结果数组，坐标相对于裁剪区域
+   * @deprecated 请改用 recognizeAbs，避免裁剪区域坐标和全屏坐标混用。
    * @example
    * const results = paddleOcr.recognize("screen", 100, 100, 500, 300)
    * if (results.length > 0) {
@@ -101,6 +128,7 @@ declare namespace paddleOcr {
    * @param confidenceThreshold 置信度阈值，默认 0.6
    * @param exactMatch 是否完整匹配，默认 false 表示包含匹配；传 true 时要求整条 OCR 识别结果文本等于目标文本
    * @returns 匹配到的子串结果数组，坐标相对于裁剪区域
+   * @deprecated 请改用 findTextAbs，避免裁剪区域坐标和全屏坐标混用。
    * @example
    * const results = paddleOcr.findText("screen", ["确定"], 100, 100, 500, 300, 0.6)
    * if (results.length > 0) {

package/types/yolo.d.ts

@@ -72,8 +72,9 @@ declare namespace yolo {
    * @param nc 模型的标签数量；传 0 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空数组
    * @param useGpu 是否使用 GPU 加载
    * @returns 加载成功返回模型ID字符串，失败返回null
+   * @deprecated 请改用 load(paramPath, binPath, nc, 11, useGpu)。
    * @example
-   * const modelId = yolo.loadV11("yolov11n.param", "yolov11n.bin", 0)
+   * const modelId = yolo.load("yolov11n.param", "yolov11n.bin", 0, 11, false)
    */
   function loadV11(
     paramPath: string,
@@ -90,8 +91,9 @@ declare namespace yolo {
    * @param threshold 置信度，默认0.4，小于这个值的会被过滤掉
    * @param nmsThreshold 重叠阈值，一般是0.5不需要更改
    * @returns 检测结果数组
+   * @deprecated 请改用 detectAbs，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const results = yolo.detect(modelId, "screen", 640, 0.4, 0.5)
+   * const results = yolo.detectAbs(modelId, "screen", 0, 0, 0, 0, 640, 0.4, 0.5)
    */
   function detect(
     modelId: string,

package/types/zh/PaddleOCR/346/250/241/345/235/227.d.ts

@@ -1,8 +1,13 @@
 /// <reference path="全局模块.d.ts" />
 /**
- * 飞桨OCR模块 包含OCR识别、OCR模型加载等功能
+ * 飞桨OCR模块 包含OCR识别、模型切换和资源释放等功能
  */
 declare namespace $PaddleOCR {
+  /**
+   * PaddleOCR 内置模型 ID。
+   */
+  type PaddleOCR模型ID = "ppocr-v6-tiny" | "ppocr-v6-small" | "ppocr-v5";
+
   /**
    * OCR识别结果接口
    */
@@ -34,17 +39,38 @@ declare namespace $PaddleOCR {
   }
 
   /**
-   * 初始化PP-OCRv5模型
+   * 手动切换到 PP-OCRv5 模型。PaddleOCR 默认自动加载 PP-OCRv6 tiny；同一时间只保留一个 active 模型，加载成功后会替换已加载的 PP-OCRv6 模型。
    * @param 最大边长 最大边长，默认640，可不传
    * @param useGpu 是否使用GPU，默认false，可不传
-   * @returns 初始化成功或模型已加载返回true
+   * @returns 加载成功或模型已加载返回true
+   * @deprecated 请改用 加载模型("ppocr-v5", useGpu)；检测长边请使用 设置最大边长 单独设置。
    * @example
-   * const 是否加载成功 = $PaddleOCR.加载V5模型(640, true)
-   * if (是否加载成功) {
-   *   $打印信息日志("加载成功")
-   * }
+   * const 识别结果数组 = $PaddleOCR.识别绝对坐标("screen", 0, 0, 0, 0)
+   * $打印信息日志(`识别数量: ${识别结果数组.length}`)
    */
   function 加载V5模型(最大边长?: 数字, useGpu?: 布尔值): 布尔值;
+  /**
+   * 按模型 ID 手动加载内置 PaddleOCR 模型。识别和查找方法默认自动加载 ppocr-v6-tiny；同一时间只保留一个 active 模型，加载成功后会替换已加载模型；检测长边请使用 设置最大边长 单独设置。
+   * @param 模型ID 模型 ID，必须传入，支持 "ppocr-v6-tiny"、"ppocr-v6-small"、"ppocr-v5"
+   * @param useGpu 是否使用GPU，默认false，可不传
+   * @returns 加载成功或目标模型已加载返回true
+   * @example
+   * const 加载成功 = $PaddleOCR.加载模型("ppocr-v6-small", false)
+   * $打印信息日志(`PaddleOCR 模型加载结果: ${加载成功}`)
+   */
+  function 加载模型(
+    模型ID: PaddleOCR模型ID,
+    useGpu?: 布尔值,
+  ): 布尔值;
+  /**
+   * 单独设置检测阶段输入最大边长，不重新加载已加载的 PP-OCRv5/v6 模型。可在首次识别前调用，后续默认自动加载 PP-OCRv6 tiny 时会沿用该设置。
+   * @param 最大边长 最大边长，默认640；传 0 或负数时使用默认值 640
+   * @returns 设置成功返回true
+   * @example
+   * $PaddleOCR.设置最大边长(960)
+   * const 识别结果数组 = $PaddleOCR.识别绝对坐标("screen", 0, 0, 0, 0)
+   */
+  function 设置最大边长(最大边长?: 数字): 布尔值;
   /**
    * 执行OCR识别
    * @param 输入源（imageId、URL字符串、文件路径或"screen"，"screen"表示使用当前屏幕）
@@ -54,6 +80,7 @@ declare namespace $PaddleOCR {
    * @param 图片边界框右下角y坐标 裁剪区域右下角 y，全屏传 0，默认 0
    * @param 置信度阈值 置信度阈值，默认 0.6
    * @returns 识别结果数组，坐标相对于裁剪区域
+   * @deprecated 请改用 识别绝对坐标，避免裁剪区域坐标和全屏坐标混用。
    * @example
    * const 识别结果数组 = $PaddleOCR.识别("screen", 100, 100, 500, 300)
    * if (识别结果数组.length > 0) {
@@ -102,6 +129,7 @@ declare namespace $PaddleOCR {
    * @param 置信度阈值 置信度阈值，默认 0.6
    * @param 是否完整匹配 默认 false 表示包含匹配；传 true 时要求整条 OCR 识别结果文本等于目标文本
    * @returns 匹配到的子串结果数组，坐标相对于裁剪区域
+   * @deprecated 请改用 查找文本绝对坐标，避免裁剪区域坐标和全屏坐标混用。
    * @example
    * const 结果 = $PaddleOCR.查找文本("screen", ["确定"], 100, 100, 500, 300, 0.6)
    * if (结果.length > 0) {

package/types/zh/YOLO/346/250/241/345/235/227.d.ts

@@ -76,8 +76,9 @@ declare namespace $YOLO {
    * @param 标签数量 模型的标签数量；传 0 或省略时根据模型输出自动推断，显式传入但不匹配时检测返回空数组
    * @param useGpu 是否使用 GPU 加载
    * @returns 加载成功返回模型ID字符串，失败返回null
+   * @deprecated 请改用 加载模型(paramPath, binPath, 标签数量, 11, useGpu)。
    * @example
-   * const 模型ID = $YOLO.加载YOLOv11模型("yolov11n.param", "yolov11n.bin", 0)
+   * const 模型ID = $YOLO.加载模型("yolov11n.param", "yolov11n.bin", 0, 11, false)
    */
   function 加载YOLOv11模型(
     ncnn模型的param文件路径: 字符串,
@@ -94,8 +95,9 @@ declare namespace $YOLO {
    * @param 置信度 置信度，默认0.4，小于这个值的会被过滤掉
    * @param 重叠阈值 一般是0.5不需要更改
    * @returns 检测结果数组
+   * @deprecated 请改用 目标检测绝对坐标，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const 结果数组 = $YOLO.目标检测(模型ID, "screen", 640, 0.4, 0.5)
+   * const 结果数组 = $YOLO.目标检测绝对坐标(模型ID, "screen", 0, 0, 0, 0, 640, 0.4, 0.5)
    */
   function 目标检测(
     模型ID: 字符串,

package/types/zh//345/233/276/347/211/207/346/250/241/345/235/227.d.ts

@@ -22,14 +22,15 @@ declare namespace $图片 {
     区域右下角X坐标?: 数字,
     区域右下角Y坐标?: 数字,
   ): 字符串 | null;
-  /**
-   * 截图
-   * @returns 截图的imageId ，如果截图失败则返回null
-   * @example
-   * const 图片ID = $图片.截取全屏()
-   * if (图片ID) {
-   *   $图片.保存图片(图片ID, "screen.jpg")
-   * }
+  /**
+   * 截图
+   * @returns 截图的imageId ，如果截图失败则返回null
+   * @deprecated 请改用 截取屏幕()。
+   * @example
+   * const 图片ID = $图片.截取屏幕()
+   * if (图片ID) {
+   *   $图片.保存图片(图片ID, "screen.jpg")
+   * }
    */
   function 截取全屏(): 字符串 | null;
   /**
@@ -37,13 +38,14 @@ declare namespace $图片 {
    * @param 区域左上角X坐标
    * @param 区域左上角Y坐标
    * @param 区域右下角X坐标
-   * @param 区域右下角Y坐标
-   * @returns 截图的imageId ，如果截图失败则返回null
-   * @example
-   * const 图片ID = $图片.截取区域(0, 0, 100, 100)
-   * if (图片ID) {
-   *   $图片.保存图片(图片ID, "screen.jpg")
-   * }
+   * @param 区域右下角Y坐标
+   * @returns 截图的imageId ，如果截图失败则返回null
+   * @deprecated 请改用 截取屏幕(区域左上角X坐标, 区域左上角Y坐标, 区域右下角X坐标, 区域右下角Y坐标)。
+   * @example
+   * const 图片ID = $图片.截取屏幕(0, 0, 100, 100)
+   * if (图片ID) {
+   *   $图片.保存图片(图片ID, "screen.jpg")
+   * }
    */
   function 截取区域(
     区域左上角X坐标: 数字,
@@ -62,11 +64,11 @@ declare namespace $图片 {
   /**
    * 图片是否已释放
    * @param imageId 图片id
-   * @returns true 已释放 false 未释放
-   * @example
-   * const 图片ID = $图片.截取全屏()
-   * if (图片ID) {
-   *   $图片.保存图片(图片ID, "screen.jpg")
+   * @returns true 已释放 false 未释放
+   * @example
+   * const 图片ID = $图片.截取屏幕()
+   * if (图片ID) {
+   *   $图片.保存图片(图片ID, "screen.jpg")
    *   $图片.图片是否被释放(图片ID) // false
    *   $图片.释放图片(图片ID)
    *   $图片.图片是否被释放(图片ID) // true

package/types/zh//345/252/222/344/275/223/346/250/241/345/235/227.d.ts

@@ -88,17 +88,16 @@ declare namespace $媒体 {
   function 停止播放MP3音乐(): 布尔值;
 
   /**
-   * 同步播放MP3音乐（等待结束）
+   * 同步播放MP3音乐（播放一次并等待结束）
    * @param 文件路径
-   * @param 是否循环播放
    * @returns 是否播放成功
    * @example
-   * const 是否播放成功 = $媒体.同步播放MP3音乐("music.mp3", true)
+   * const 是否播放成功 = $媒体.同步播放MP3音乐("music.mp3")
    * if (是否播放成功) {
    *   $打印信息日志("播放成功")
    * }
    */
-  function 同步播放MP3音乐(文件路径: 字符串, 是否循环播放: 布尔值): 布尔值;
+  function 同步播放MP3音乐(文件路径: 字符串): 布尔值;
 
   /**
    * 查询MP3音乐是否正在播放

package/types/zh//350/213/271/346/236/234OCR.d.ts

@@ -39,11 +39,10 @@ declare namespace $苹果OCR {
    * @param 图片边界框右下角y坐标 默认 0
    * @param 识别语言数组 识别语言数组，默认为["zh-Hans", "en-US"]
    * @returns 识别结果数组，包含文本、置信度、坐标等信息
+   * @deprecated 请改用 识别绝对坐标，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const 检查结果数组 = $苹果OCR.识别("screen", 0, 0, 100, 100, ["zh-Hans", "en-US"])
-   * 检查结果数组.forEach(目标 => {
-   *   $打印信息日志(`文本: ${目标.text}, 置信度: ${目标.confidence}`)
-   * })
+   * const 检查结果数组 = $苹果OCR.识别绝对坐标("screen", 0, 0, 100, 100, ["zh-Hans", "en-US"])
+   * $打印信息日志(`识别数量: ${检查结果数组.length}`)
    */
   function 识别(
     输入源: 字符串,
@@ -86,11 +85,10 @@ declare namespace $苹果OCR {
    * @param 图片边界框右下角x坐标 默认 0
    * @param 图片边界框右下角y坐标 默认 0
    * @returns 识别结果数组，包含文本、置信度、坐标等信息
+   * @deprecated 请改用 识别数字绝对坐标，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const 检查结果数组 = $苹果OCR.识别数字("screen", 0, 0, 100, 100)
-   * 检查结果数组.forEach(目标 => {
-   *   $打印信息日志(`文本: ${目标.text}, 置信度: ${目标.confidence}`)
-   * })
+   * const 检查结果数组 = $苹果OCR.识别数字绝对坐标("screen", 0, 0, 100, 100)
+   * $打印信息日志(`数字识别数量: ${检查结果数组.length}`)
    */
   function 识别数字(
     输入源: 字符串,
@@ -133,11 +131,10 @@ declare namespace $苹果OCR {
    * @param 识别语言数组 识别语言数组，默认为["zh-Hans", "en-US"]
    * @param 是否完整匹配 默认 false 表示包含匹配；传 true 时要求整条 OCR 识别结果文本等于目标文本
    * @returns 命中子串的识别结果数组，坐标对应目标子串区域
+   * @deprecated 请改用 查找文本绝对坐标，避免裁剪区域坐标和全屏坐标混用。
    * @example
-   * const 检查结果数组 = $苹果OCR.查找文本("screen", ["开始"], 0, 0, 100, 100, ["zh-Hans", "en-US"])
-   * 检查结果数组.forEach(目标 => {
-   *   $打印信息日志(`文本: ${目标.text}, 置信度: ${目标.confidence}`)
-   * })
+   * const 检查结果数组 = $苹果OCR.查找文本绝对坐标("screen", ["开始"], 0, 0, 100, 100, ["zh-Hans", "en-US"])
+   * $打印信息日志(`命中数量: ${检查结果数组.length}`)
    */
   function 查找文本(
     输入源: 字符串,