ms-vite-plugin 1.4.31 → 1.4.33

package/dist/build.js

@@ -220,10 +220,6 @@ const buildAll = async (isDev = true, workspacePath) => {
                                     disableConsoleOutput: false,
                                     domainLock: [],
                                     selfDefending: false,
-                                    // 注入到引擎的全局对象与方法（如 paddleOcr.recognizeAbs、ms、ui、http…）
-                                    // 由原生侧按“名称字符串”绑定，一旦被改名原生就找不到对应实现。
-                                    // 这里强制关闭全局名 / 属性名改写，避免任何 obfuscator.json 误开导致注入 API 被混淆。
-                                    // 如确需对自有属性做重命名，请改用 renamePropertiesMode + reservedNames 白名单。
                                     renameGlobals: false,
                                     renameProperties: false,
                                 },

package/docs/api/global.md

@@ -459,25 +459,32 @@ logi(`CPU 限流延迟: ${delay.minMs}~${delay.maxMs}ms`);
 设置停止回调函数。此回调注册接口只能在主线程调用，不能在线程脚本中调用。
 
 ```typescript
-function setStopCallback(callback: () => void): void;
+function setStopCallback(
+  callback: (status: "success" | "error" | "stopped") => void,
+): void;
 ```
 
 **参数:**
 
-| 参数名     | 类型       | 是否必填 | 默认值 | 描述         |
-| ---------- | ---------- | -------- | ------ | ------------ |
-| `callback` | () => void | 是       | -      | 停止回调函数 |
+| 参数名     | 类型                                                   | 是否必填 | 默认值 | 描述         |
+| ---------- | ------------------------------------------------------ | -------- | ------ | ------------ |
+| `callback` | (status: "success" \| "error" \| "stopped") => void | 是       | -      | 停止回调函数 |
 
 **说明:**
 
-脚本执行完成或异常停止时调用，`exit()` 退出不会触发此回调。
+脚本执行停止时调用，`status` 表示停止状态：`success` 为正常完成，`error` 为异常停止，`stopped` 为手动停止。
 
 **示例:**
 
 ```javascript
-setStopCallback(() => {
-  logi("脚本执行完成");
-  // 执行清理工作
+setStopCallback((status) => {
+  if (status === "success") {
+    logi("脚本执行完成");
+  } else if (status === "error") {
+    loge("脚本执行异常");
+  } else if (status === "stopped") {
+    logi("脚本手动停止");
+  }
 });
 ```
 

package/docs/api/media.md

@@ -229,9 +229,9 @@ function playMp3WaitEnd(path: string): boolean;
 
 **返回值:**
 
-| 类型      | 描述         |
-| --------- | ------------ |
-| `boolean` | 是否播放成功 |
+| 类型      | 描述                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `boolean` | 是否正常播放到结尾；系统音频中断、`stopMp3` 或新播放替换时返回 `false` |
 
 **示例:**
 
@@ -242,6 +242,6 @@ const played = media.playMp3WaitEnd("/path/to/notification.mp3");
 if (played) {
   logi("音频播放完成");
 } else {
-  logi("播放失败");
+  logi("播放失败或被系统音频中断");
 }
 ```

package/docs/api/utils.md

@@ -23,7 +23,7 @@ function timeFormat(format: string): string;
 
 | 参数名   | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                      |
 | -------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `format` | string | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `hh` - 两位小时（24 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
+| `format` | string | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `HH` - 两位小时（24 小时制）<br> `hh` - 两位小时（12 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
 
 **返回值:**
 
@@ -35,7 +35,7 @@ function timeFormat(format: string): string;
 
 ```javascript
 // 标准日期时间格式
-const dateTime = utils.timeFormat("yyyy-MM-dd hh:mm:ss");
+const dateTime = utils.timeFormat("yyyy-MM-dd HH:mm:ss");
 logi(dateTime); // 输出: 2024-01-15 14:30:25
 
 // 仅日期格式
@@ -43,15 +43,15 @@ const date = utils.timeFormat("yyyy-MM-dd");
 logi(date); // 输出: 2024-01-15
 
 // 仅时间格式
-const time = utils.timeFormat("hh:mm:ss");
+const time = utils.timeFormat("HH:mm:ss");
 logi(time); // 输出: 14:30:25
 
 // 自定义分隔符
-const customFormat = utils.timeFormat("yyyy/MM/dd hh:mm");
+const customFormat = utils.timeFormat("yyyy/MM/dd HH:mm");
 logi(customFormat); // 输出: 2024/01/15 14:30
 
 // 紧凑格式
-const compact = utils.timeFormat("yyyyMMddhhmmss");
+const compact = utils.timeFormat("yyyyMMddHHmmss");
 logi(compact); // 输出: 20240115143025
 ```
 

package/docs/apicn/global.md

@@ -460,25 +460,32 @@ $打印信息日志(`CPU 限流延迟: ${延迟.minMs}~${延迟.maxMs}ms`);
 设置停止回调函数。该回调注册接口只能在主线程调用，不能在线程脚本中调用。
 
 ```typescript
-declare const $设置停止回调: (回调: () => 无返回值) => 无返回值;
+declare const $设置停止回调: (
+  回调: (状态: "success" | "error" | "stopped") => 无返回值,
+) => 无返回值;
 ```
 
 **参数:**
 
-| 参数名 | 类型           | 是否必填 | 默认值 | 描述         |
-| ------ | -------------- | -------- | ------ | ------------ |
-| `回调` | () => 无返回值 | 是       | -      | 停止回调函数 |
+| 参数名 | 类型                                                       | 是否必填 | 默认值 | 描述         |
+| ------ | ---------------------------------------------------------- | -------- | ------ | ------------ |
+| `回调` | (状态: "success" \| "error" \| "stopped") => 无返回值 | 是       | -      | 停止回调函数 |
 
 **说明:**
 
-脚本执行完成或异常停止时调用，`$退出脚本()` 退出不会触发此回调。
+脚本执行停止时调用，`状态` 表示停止状态：`success` 为正常完成，`error` 为异常停止，`stopped` 为手动停止。
 
 **示例:**
 
 ```javascript
-$设置停止回调(() => {
-  $打印信息日志("脚本执行完成");
-  // 执行清理工作
+$设置停止回调((状态) => {
+  if (状态 === "success") {
+    $打印信息日志("脚本执行完成");
+  } else if (状态 === "error") {
+    $打印错误日志("脚本执行异常");
+  } else if (状态 === "stopped") {
+    $打印信息日志("脚本手动停止");
+  }
 });
 ```
 

package/docs/apicn/media.md

@@ -233,9 +233,9 @@ function 同步播放MP3音乐(文件路径: 字符串): 布尔值;
 
 **返回值:**
 
-| 类型     | 描述         |
-| -------- | ------------ |
-| `布尔值` | 是否播放成功 |
+| 类型     | 描述                                                                                  |
+| -------- | ------------------------------------------------------------------------------------- |
+| `布尔值` | 是否正常播放到结尾；系统音频中断、`停止播放MP3音乐` 或新播放替换时返回 `false` |
 
 **示例:**
 
@@ -246,6 +246,6 @@ const 是否播放成功 = $媒体.同步播放MP3音乐("/path/to/notification.
 if (是否播放成功) {
   $打印信息日志("音频播放完成");
 } else {
-  $打印错误日志("播放失败");
+  $打印错误日志("播放失败或被系统音频中断");
 }
 ```

package/docs/apicn/utils.md

@@ -23,7 +23,7 @@ function 获取当前时间字符串(格式化字符串: 字符串): 字符串;
 
 | 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                      |
 | -------------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `格式化字符串` | string | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `hh` - 两位小时（24 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
+| `格式化字符串` | string | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `HH` - 两位小时（24 小时制）<br> `hh` - 两位小时（12 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
 
 **返回值:**
 
@@ -35,7 +35,7 @@ function 获取当前时间字符串(格式化字符串: 字符串): 字符串;
 
 ```javascript
 // 标准日期时间格式
-const dateTime = $工具.获取当前时间字符串("yyyy-MM-dd hh:mm:ss");
+const dateTime = $工具.获取当前时间字符串("yyyy-MM-dd HH:mm:ss");
 $打印信息日志(dateTime); // 输出: 2024-01-15 14:30:25
 
 // 仅日期格式
@@ -43,15 +43,15 @@ const date = $工具.获取当前时间字符串("yyyy-MM-dd");
 $打印信息日志(date); // 输出: 2024-01-15
 
 // 仅时间格式
-const time = $工具.获取当前时间字符串("hh:mm:ss");
+const time = $工具.获取当前时间字符串("HH:mm:ss");
 $打印信息日志(time); // 输出: 14:30:25
 
 // 自定义分隔符
-const customFormat = $工具.获取当前时间字符串("yyyy/MM/dd hh:mm");
+const customFormat = $工具.获取当前时间字符串("yyyy/MM/dd HH:mm");
 $打印信息日志(customFormat); // 输出: 2024/01/15 14:30
 
 // 紧凑格式
-const compact = $工具.获取当前时间字符串("yyyyMMddhhmmss");
+const compact = $工具.获取当前时间字符串("yyyyMMddHHmmss");
 $打印信息日志(compact); // 输出: 20240115143025
 ```
 

package/docs/apipython/g.md

@@ -7,6 +7,7 @@
 - 应用信息常量：版本号/构建号/名称/包名
 - 前台切换：将宿主应用切到前台
 - Agent 设置：读取和设置 Agent 快速模式
+- 脚本生命周期：设置停止回调和异常停止回调
 
 ## 常量
 
@@ -226,6 +227,69 @@ from kuaijs import g
 g.restartScript()
 ```
 
+#### `setStopCallback` - 设置停止回调
+
+设置脚本停止回调函数。回调只在主脚本结束时调用，不能在线程脚本中分别注册。
+
+```python
+def setStopCallback(callback: Callable[[Literal["success", "error", "stopped"]], None] | None) -> None
+```
+
+**参数:**
+
+| 参数名     | 类型                                                      | 是否必填 | 默认值 | 描述 |
+| ---------- | --------------------------------------------------------- | -------- | ------ | ---- |
+| `callback` | `Callable[[Literal["success", "error", "stopped"]], None]` 或 `None` | 是 | - | 停止回调函数，传 `None` 取消回调 |
+
+**状态值:**
+
+| 状态 | 描述 |
+| ---- | ---- |
+| `success` | 脚本正常执行完成 |
+| `error` | 脚本发生未捕获异常 |
+| `stopped` | 脚本被手动停止或主动退出 |
+
+**示例:**
+
+```python
+from kuaijs import g
+
+def on_stop(status: str) -> None:
+    if status == "success":
+        print("脚本执行完成")
+    elif status == "error":
+        print("脚本执行异常")
+    elif status == "stopped":
+        print("脚本手动停止")
+
+g.setStopCallback(on_stop)
+```
+
+#### `setExceptionCallback` - 设置异常停止回调
+
+设置脚本异常停止回调函数。该回调只在主脚本发生未捕获异常时调用，并且会早于 `setStopCallback` 注册的停止回调执行。
+
+```python
+def setExceptionCallback(callback: Callable[[], None] | None) -> None
+```
+
+**参数:**
+
+| 参数名     | 类型                         | 是否必填 | 默认值 | 描述 |
+| ---------- | ---------------------------- | -------- | ------ | ---- |
+| `callback` | `Callable[[], None]` 或 `None` | 是 | - | 异常停止回调函数，传 `None` 取消回调 |
+
+**示例:**
+
+```python
+from kuaijs import g
+
+def on_exception() -> None:
+    print("脚本异常停止")
+
+g.setExceptionCallback(on_exception)
+```
+
 #### `loadDex` - 加载指定的 dex、apk 文件
 
 **注意:**

package/docs/apipython/media.md

@@ -205,9 +205,9 @@ def playMp3WaitEnd(path: str) -> bool
 
 **返回值:**
 
-| 类型   | 描述         |
-| ------ | ------------ |
-| `bool` | 是否播放成功 |
+| 类型   | 描述                                                                 |
+| ------ | -------------------------------------------------------------------- |
+| `bool` | 是否正常播放到结尾；系统音频中断、`stopMp3` 或新播放替换时返回 `False` |
 
 **示例:**
 
@@ -216,5 +216,5 @@ from kuaijs import media
 
 print("开始播放音频...")
 played = media.playMp3WaitEnd("/var/mobile/Media/notification.mp3")
-print("音频播放完成" if played else "播放失败")
+print("音频播放完成" if played else "播放失败或被系统音频中断")
 ```

package/docs/apipython/utils.md

@@ -23,7 +23,7 @@ def timeFormat(format: str) -> str
 
 | 参数名   | 类型 | 是否必填 | 默认值 | 描述                                                                                                                                                      |
 | -------- | ---- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `format` | str  | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `hh` - 两位小时（24 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
+| `format` | str  | 是       |        | 时间格式化字符串 <br> `yyyy` - 四位年份 <br> `MM` - 两位月份<br> `dd` - 两位日期<br> `HH` - 两位小时（24 小时制）<br> `hh` - 两位小时（12 小时制）<br> `mm` - 两位分钟<br> `ss` - 两位秒数 |
 
 **返回值:**
 
@@ -37,7 +37,7 @@ def timeFormat(format: str) -> str
 from kuaijs import utils, logger
 
 # 标准日期时间格式
-dateTime = utils.timeFormat("yyyy-MM-dd hh:mm:ss")
+dateTime = utils.timeFormat("yyyy-MM-dd HH:mm:ss")
 logger.info(dateTime) # 输出: 2024-01-15 14:30:25
 
 # 仅日期格式
@@ -45,15 +45,15 @@ date = utils.timeFormat("yyyy-MM-dd")
 logger.info(date) # 输出: 2024-01-15
 
 # 仅时间格式
-time = utils.timeFormat("hh:mm:ss")
+time = utils.timeFormat("HH:mm:ss")
 logger.info(time) # 输出: 14:30:25
 
 # 自定义分隔符
-customFormat = utils.timeFormat("yyyy/MM/dd hh:mm")
+customFormat = utils.timeFormat("yyyy/MM/dd HH:mm")
 logger.info(customFormat) # 输出: 2024/01/15 14:30
 
 # 紧凑格式
-compact = utils.timeFormat("yyyyMMddhhmmss")
+compact = utils.timeFormat("yyyyMMddHHmmss")
 logger.info(compact) # 输出: 20240115143025
 ```
 

package/docs/httpapi/api.md

@@ -299,6 +299,92 @@ GET /api/activeAppInfo
 | »» bundleId | string  | true | none | 应用包名 | none |
 | »» pid      | integer | true | none |          | none |
 
+## GET 获取锁屏状态
+
+GET /api/isLocked
+
+> 返回示例
+
+> 200 Response
+
+```json
+{
+  "success": true,
+  "data": false
+}
+```
+
+### 返回结果
+
+| 状态码 | 状态码含义                                              | 说明 | 数据模型 |
+| ------ | ------------------------------------------------------- | ---- | -------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | none | Inline   |
+
+### 返回数据结构
+
+状态码 **200**
+
+| 名称      | 类型    | 必选 | 约束 | 中文名   | 说明 |
+| --------- | ------- | ---- | ---- | -------- | ---- |
+| » success | boolean | true | none | 是否成功 | none |
+| » data    | boolean | true | none | 是否锁屏 | `true` 表示已锁屏，`false` 表示未锁屏 |
+
+## GET 锁屏
+
+GET /api/lock
+
+> 返回示例
+
+> 200 Response
+
+```json
+{
+  "success": true
+}
+```
+
+### 返回结果
+
+| 状态码 | 状态码含义                                              | 说明 | 数据模型 |
+| ------ | ------------------------------------------------------- | ---- | -------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | none | Inline   |
+
+### 返回数据结构
+
+状态码 **200**
+
+| 名称      | 类型    | 必选 | 约束 | 中文名   | 说明 |
+| --------- | ------- | ---- | ---- | -------- | ---- |
+| » success | boolean | true | none | 是否成功 | none |
+
+## GET 解锁
+
+GET /api/unlock
+
+> 返回示例
+
+> 200 Response
+
+```json
+{
+  "success": true
+}
+```
+
+### 返回结果
+
+| 状态码 | 状态码含义                                              | 说明 | 数据模型 |
+| ------ | ------------------------------------------------------- | ---- | -------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | none | Inline   |
+
+### 返回数据结构
+
+状态码 **200**
+
+| 名称      | 类型    | 必选 | 约束 | 中文名   | 说明 |
+| --------- | ------- | ---- | ---- | -------- | ---- |
+| » success | boolean | true | none | 是否成功 | none |
+
 ## GET 获取屏幕亮度
 
 GET /api/getScreenBrightness
@@ -789,7 +875,7 @@ WebSocket Upgrade /mirror/ws
 
 | 名称          | 位置  | 类型    | 必选 | 中文名 | 说明                         |
 | ------------- | ----- | ------- | ---- | ------ | ---------------------------- |
-| fps           | query | integer | 否   |        | 帧率，默认 10，范围 1-30     |
+| fps           | query | integer | 否   |        | 帧率，默认 10，范围 1-60     |
 | quality       | query | number  | 否   |        | 质量，默认 0.25，范围 0.1-1.0 |
 | scalingFactor | query | number  | 否   |        | 缩放比例，默认 1.0，范围 0.1-1.0 |
 
@@ -797,6 +883,40 @@ WebSocket Upgrade /mirror/ws
 
 连接成功后服务端持续发送 JPEG 二进制 WebSocket frame；客户端不需要发送业务消息。
 
+## HTTP-FLV 实时屏幕画面流
+
+GET /mirror/flv
+
+### 请求参数
+
+| 名称          | 位置  | 类型    | 必选 | 中文名 | 说明                                |
+| ------------- | ----- | ------- | ---- | ------ | ----------------------------------- |
+| fps           | query | integer | 否   |        | 帧率，默认 10，范围 1-60            |
+| quality       | query | number  | 否   |        | JPEG 源质量，默认 0.25，范围 0.1-1.0 |
+| scalingFactor | query | number  | 否   |        | 缩放比例，默认 1.0，范围 0.1-1.0    |
+| bitrate       | query | number  | 否   |        | H.264 目标码率，单位 Mbps，默认 4    |
+
+### 返回数据
+
+响应类型为 `video/x-flv`，服务端持续输出 FLV 容器内的 H.264 视频 tag。
+
+## WHEP 实时屏幕画面流
+
+POST /mirror/whep
+
+### 请求参数
+
+| 名称          | 位置  | 类型    | 必选 | 中文名 | 说明                                |
+| ------------- | ----- | ------- | ---- | ------ | ----------------------------------- |
+| fps           | query | integer | 否   |        | 帧率，默认 10，范围 1-60            |
+| quality       | query | number  | 否   |        | JPEG 源质量，默认 0.25，范围 0.1-1.0 |
+| scalingFactor | query | number  | 否   |        | 缩放比例，默认 1.0，范围 0.1-1.0    |
+| bitrate       | query | number  | 否   |        | WebRTC 发送码率，单位 Mbps，默认 4   |
+
+### 返回数据
+
+请求 body 为 `application/sdp` 的 WebRTC offer；响应类型为 `application/sdp`，内容为 WebRTC answer。
+
 ## POST 执行脚本（仅支持JS脚本）
 
 POST /api/runScript
@@ -2937,6 +3057,28 @@ GET /api/file/download
 | 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)  | 设备未授权 | Inline   |
 | 404    | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)   | 文件不存在 | Inline   |
 
+## GET MJPEG 镜像流
+
+GET /mirror/image
+
+返回 `multipart/x-mixed-replace` MJPEG 长连接，每个 part 都是一帧 JPEG。浏览器可直接用 `<img src="/mirror/image">` 预览。
+
+### 请求参数
+
+| 名称          | 位置  | 类型    | 必选 | 说明 |
+| ------------- | ----- | ------- | ---- | ---- |
+| fps           | query | integer | 否   | 目标帧率，范围 1-60，默认 10 |
+| quality       | query | number  | 否   | JPEG 质量，范围 0.1-1.0，默认 0.25 |
+| scalingFactor | query | number  | 否   | 截图缩放因子，范围 0.1-1.0，默认 1.0 |
+
+### 返回结果
+
+| 状态码 | 状态码含义                                                       | 说明 | 数据模型 |
+| ------ | ---------------------------------------------------------------- | ---- | -------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)          | `multipart/x-mixed-replace; boundary=kuaijs-mjpeg-boundary` 流 | file |
+| 429    | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | 镜像流客户端数量已满 | Inline |
+| 503    | [Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4) | HID 录屏链路未就绪 | Inline |
+
 # 数据模型
 
 <h2 id="tocS_软件状态">软件状态</h2>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.31",
+  "version": "1.4.33",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {