ms-vite-plugin 1.4.29 → 1.4.30

package/docs/api/cloud.md

@@ -0,0 +1,154 @@
+# 云控模块 (Cloud)
+
+云控模块用于在主脚本中使用内置云控 WebSocket 连接。脚本可以主动连接云控服务器、判断连接状态、断开连接、上报事件数据，并监听服务器事件数据。
+
+## 注意事项
+
+- `cloud` 只在主脚本上下文注册，不支持在线程脚本里调用。
+- 服务器事件只有一个主脚本监听槽位，多次调用 `onEvent` 会覆盖旧监听。
+
+## 协议
+
+脚本上报数据时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptReport",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+服务器下发脚本事件时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptEvent",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+`event` 是脚本和服务器约定的自定义事件名。`data` 在 JS 中是普通 Object，必须能被 JSON 序列化。
+
+## API 参考
+
+### connect - 连接云控服务器
+
+```typescript
+function connect(url: string, deviceNo?: string): boolean;
+```
+
+**参数**
+
+| 参数名     | 类型   | 是否必填 | 默认值         | 描述 |
+| ---------- | ------ | -------- | -------------- | ---- |
+| `url`      | string | 是       | -              | 完整 `ws://` 或 `wss://` 云控地址 |
+| `deviceNo` | string | 否       | 已保存设备编号 | 连接时追加到 query 的设备编号 |
+
+**返回值**
+
+| 类型    | 描述 |
+| ------- | ---- |
+| boolean | URL 校验通过且连接请求已提交时返回 true |
+
+**说明**
+
+- `connect` 只能在主脚本上下文调用。
+- `connect` 只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+
+**示例**
+
+```javascript
+const accepted = cloud.connect("wss://example.com/control", "device-001");
+logi("云控连接请求:", accepted);
+```
+
+### isConnected - 判断是否已连接
+
+```typescript
+function isConnected(): boolean;
+```
+
+**返回值**
+
+| 类型    | 描述 |
+| ------- | ---- |
+| boolean | WebSocket 已连接时返回 true |
+
+**示例**
+
+```javascript
+if (cloud.isConnected()) {
+  cloud.report("status", { value: "ready" });
+}
+```
+
+### disconnect - 断开连接
+
+```typescript
+function disconnect(): void;
+```
+
+断开云控 WebSocket 并停止自动重连。
+
+**示例**
+
+```javascript
+cloud.disconnect();
+```
+
+### report - 上报数据
+
+```typescript
+function report(event: string, data: Record<string, any>): boolean;
+```
+
+**参数**
+
+| 参数名  | 类型      | 是否必填 | 默认值 | 描述 |
+| ------- | --------- | -------- | ------ | ---- |
+| `event` | string    | 是       | -      | 自定义事件名 |
+| `data`  | Record<string, any> | 是 | - | 要上报的普通 Object 参数 |
+
+**返回值**
+
+| 类型    | 描述 |
+| ------- | ---- |
+| boolean | 已连接且 JSON 文本帧已提交写出时返回 true |
+
+**示例**
+
+```javascript
+const ok = cloud.report("taskFinished", {
+  taskId: "A-1001",
+  success: true,
+  costMs: 1280,
+});
+logi("上报结果:", ok);
+```
+
+### onEvent - 监听服务器事件
+
+```typescript
+function onEvent(callback: ((event: string, data: Record<string, any>) => void) | null): void;
+```
+
+监听服务器发送的 `scriptEvent` 协议帧。传入 `null` 会取消主脚本监听。
+此回调注册接口只能在主线程调用，不能在线程脚本中调用。
+
+**参数**
+
+| 参数名     | 类型                          | 是否必填 | 描述 |
+| ---------- | ----------------------------- | -------- | ---- |
+| `callback` | `(event, data) => void` 或 `null` | 是    | 事件处理函数，或传 `null` 取消监听 |
+
+**示例**
+
+```javascript
+cloud.onEvent((event, data) => {
+  if (event === "startTask") {
+    logi("任务参数:", data);
+  }
+});
+```

package/docs/api/global.md

@@ -456,7 +456,7 @@ logi(`CPU 限流延迟: ${delay.minMs}~${delay.maxMs}ms`);
 
 ### setStopCallback
 
-设置停止回调函数（仅主线程调用）。
+设置停止回调函数。此回调注册接口只能在主线程调用，不能在线程脚本中调用。
 
 ```typescript
 function setStopCallback(callback: () => void): void;
@@ -483,7 +483,7 @@ setStopCallback(() => {
 
 ### setExceptionCallback
 
-设置异常停止回调函数（仅主线程调用）。
+设置异常停止回调函数。此回调注册接口只能在主线程调用，不能在线程脚本中调用。
 
 ```typescript
 function setExceptionCallback(callback: () => void): void;

package/docs/api/ui.md

@@ -74,15 +74,17 @@ UI 模块提供了 WebView 相关功能，支持事件通信和 JavaScript 交
 
 ```typescript
 function onEvent(
-  onEvent: (event: string, data: Record<string, any>) => void
+  onEvent: ((event: string, data: Record<string, any>) => void) | null
 ): void;
 ```
 
+此回调注册接口只能在主线程调用，不能在线程脚本中调用。传入 `null` 会取消监听。
+
 **参数：**
 
 | 参数名    | 类型                                               | 是否必填 | 默认值 | 描述                                 |
 | --------- | -------------------------------------------------- | -------- | ------ | ------------------------------------ |
-| `onEvent` | (event: string, data: Record<string, any>) => void | 是       |        | 事件回调函数，用于处理来自网页的事件 |
+| `onEvent` | ((event: string, data: Record<string, any>) => void) 或 null | 是 | | 事件回调函数，用于处理来自网页的事件，传 `null` 取消监听 |
 
 **示例：**
 

package/docs/apicn/cloud.md

@@ -0,0 +1,154 @@
+# 云控模块 ($云控)
+
+云控模块用于在主脚本中使用内置云控 WebSocket 连接。脚本可以连接服务器、判断连接状态、断开连接、上报事件数据，并监听服务器事件数据。
+
+## 注意事项
+
+- `$云控` 只在主脚本上下文注册，不支持在线程脚本里调用。
+- 服务器事件只有一个主脚本监听槽位，多次调用 `监听事件回调` 会覆盖旧监听。
+
+## 协议
+
+脚本上报数据时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptReport",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+服务器下发脚本事件时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptEvent",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+`event` 是脚本和服务器约定的自定义事件名。`data` 在 JS 中是普通 Object，必须能被 JSON 序列化。
+
+## API 参考
+
+### 连接
+
+```typescript
+function 连接(地址: 字符串, 设备编号?: 字符串): 布尔值;
+```
+
+**参数**
+
+| 参数名     | 类型   | 是否必填 | 默认值         | 描述 |
+| ---------- | ------ | -------- | -------------- | ---- |
+| `地址`     | 字符串 | 是       | -              | 完整 `ws://` 或 `wss://` 云控地址 |
+| `设备编号` | 字符串 | 否       | 已保存设备编号 | 连接时追加到 query 的设备编号 |
+
+**返回值**
+
+| 类型   | 描述 |
+| ------ | ---- |
+| 布尔值 | URL 校验通过且连接请求已提交时返回 true |
+
+**说明**
+
+- `连接` 只能在主脚本上下文调用。
+- `连接` 只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+
+**示例**
+
+```javascript
+const 已提交 = $云控.连接("wss://example.com/control", "device-001");
+$打印信息日志("云控连接请求:", 已提交);
+```
+
+### 是否已连接
+
+```typescript
+function 是否已连接(): 布尔值;
+```
+
+**返回值**
+
+| 类型   | 描述 |
+| ------ | ---- |
+| 布尔值 | WebSocket 已连接时返回 true |
+
+**示例**
+
+```javascript
+if ($云控.是否已连接()) {
+  $云控.上报数据("status", { value: "ready" });
+}
+```
+
+### 断开连接
+
+```typescript
+function 断开连接(): 无返回值;
+```
+
+断开云控 WebSocket 并停止自动重连。
+
+**示例**
+
+```javascript
+$云控.断开连接();
+```
+
+### 上报数据
+
+```typescript
+function 上报数据(事件: 字符串, 数据: 字典<任意类型>): 布尔值;
+```
+
+**参数**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述 |
+| ------ | -------- | -------- | ------ | ---- |
+| `事件` | 字符串   | 是       | -      | 自定义事件名 |
+| `数据` | 字典<任意类型> | 是 | - | 要上报的普通 Object 参数 |
+
+**返回值**
+
+| 类型   | 描述 |
+| ------ | ---- |
+| 布尔值 | 已连接且 JSON 文本帧已提交写出时返回 true |
+
+**示例**
+
+```javascript
+const 成功 = $云控.上报数据("taskFinished", {
+  taskId: "A-1001",
+  success: true,
+  costMs: 1280,
+});
+$打印信息日志("上报结果:", 成功);
+```
+
+### 监听事件回调
+
+```typescript
+function 监听事件回调(回调: ((事件: 字符串, 数据: 字典<任意类型>) => 无返回值) | null): 无返回值;
+```
+
+监听服务器发送的 `scriptEvent` 协议帧。传入 `null` 会取消主脚本监听。
+该回调注册接口只能在主线程调用，不能在线程脚本中调用。
+
+**参数**
+
+| 参数名 | 类型                    | 是否必填 | 描述 |
+| ------ | ----------------------- | -------- | ---- |
+| `回调` | `(事件, 数据) => 无返回值` 或 `null` | 是 | 事件处理函数，或传 `null` 取消监听 |
+
+**示例**
+
+```javascript
+$云控.监听事件回调((事件, 数据) => {
+  if (事件 === "startTask") {
+    $打印信息日志("任务参数:", 数据);
+  }
+});
+```

package/docs/apicn/global.md

@@ -457,7 +457,7 @@ $打印信息日志(`CPU 限流延迟: ${延迟.minMs}~${延迟.maxMs}ms`);
 
 ### $设置停止回调
 
-设置停止回调函数（仅主线程调用）。
+设置停止回调函数。该回调注册接口只能在主线程调用，不能在线程脚本中调用。
 
 ```typescript
 declare const $设置停止回调: (回调: () => 无返回值) => 无返回值;
@@ -484,7 +484,7 @@ $设置停止回调(() => {
 
 ### $设置异常停止回调
 
-设置异常停止回调函数（仅主线程调用）。
+设置异常停止回调函数。该回调注册接口只能在主线程调用，不能在线程脚本中调用。
 
 ```typescript
 declare const $设置异常停止回调: (回调: () => 无返回值) => 无返回值;

package/docs/apicn/ui.md

@@ -62,15 +62,17 @@ UI 模块提供了 WebView 相关功能，支持事件通信和 JavaScript 交
 
 ```typescript
 function 监听事件回调(
-  回调函数: (事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值
+  回调函数: ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) | null
 ): 无返回值;
 ```
 
+该回调注册接口只能在主线程调用，不能在线程脚本中调用。传入 `null` 会取消监听。
+
 **参数：**
 
 | 参数名     | 类型                                                 | 是否必填 | 默认值 | 描述                                 |
 | ---------- | ---------------------------------------------------- | -------- | ------ | ------------------------------------ |
-| `回调函数` | (事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值 | 是       |        | 事件回调函数，用于处理来自网页的事件 |
+| `回调函数` | ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) 或 null | 是 | | 事件回调函数，用于处理来自网页的事件，传 `null` 取消监听 |
 
 **示例：**
 

package/docs/apipython/cloud.md

@@ -0,0 +1,175 @@
+# 云控模块 (Cloud)
+
+云控模块用于在 Python 主脚本中使用内置云控 WebSocket 连接。脚本可以连接云控服务器、判断连接状态、断开连接、上报事件数据，并监听服务器事件数据。
+
+## 注意事项
+
+- Python 云控模块只支持英文方法，不提供中文方法。
+- `cloud` 只能在主脚本中调用，不支持在线程脚本里调用。
+- 服务器事件只有一个主脚本监听槽位，多次调用 `onEvent` 会覆盖旧监听。
+
+## 协议
+
+脚本上报数据时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptReport",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+服务器下发脚本事件时发送 JSON 文本帧：
+
+```json
+{
+  "type": "scriptEvent",
+  "event": "eventName",
+  "data": {}
+}
+```
+
+`event` 是脚本和服务器约定的自定义事件名。`data` 在 Python 中是普通 `dict`，必须能被 JSON 序列化。
+
+## API 参考
+
+### connect - 连接云控服务器
+
+```python
+def connect(url: str, deviceNo: str | None = None) -> bool
+```
+
+**参数**
+
+| 参数名     | 类型         | 是否必填 | 默认值         | 描述 |
+| ---------- | ------------ | -------- | -------------- | ---- |
+| `url`      | str          | 是       | -              | 完整 `ws://` 或 `wss://` 云控地址 |
+| `deviceNo` | str 或 `None` | 否       | 已保存设备编号 | 连接时追加到 query 的设备编号 |
+
+**返回值**
+
+| 类型 | 描述 |
+| ---- | ---- |
+| bool | URL 校验通过且连接请求已提交时返回 `True` |
+
+**说明**
+
+- `connect` 只能在主脚本中调用。
+- `connect` 只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+
+**示例**
+
+```python
+from kuaijs import cloud, logger
+
+accepted = cloud.connect("wss://example.com/control", "device-001")
+logger.info(f"云控连接请求: {accepted}")
+```
+
+### isConnected - 判断是否已连接
+
+```python
+def isConnected() -> bool
+```
+
+**返回值**
+
+| 类型 | 描述 |
+| ---- | ---- |
+| bool | WebSocket 已连接时返回 `True` |
+
+**示例**
+
+```python
+from kuaijs import cloud
+
+if cloud.isConnected():
+    cloud.report("status", {"value": "ready"})
+```
+
+### disconnect - 断开连接
+
+```python
+def disconnect() -> None
+```
+
+断开云控 WebSocket 并停止自动重连。
+
+**示例**
+
+```python
+from kuaijs import cloud
+
+cloud.disconnect()
+```
+
+### report - 上报数据
+
+```python
+from typing import Any, Dict
+
+def report(event: str, data: Dict[str, Any]) -> bool
+```
+
+**参数**
+
+| 参数名  | 类型             | 是否必填 | 默认值 | 描述 |
+| ------- | ---------------- | -------- | ------ | ---- |
+| `event` | str              | 是       | -      | 自定义事件名 |
+| `data`  | `Dict[str, Any]` | 是       | -      | 要上报的普通 dict 参数 |
+
+**返回值**
+
+| 类型 | 描述 |
+| ---- | ---- |
+| bool | 已连接且 JSON 文本帧已提交写出时返回 `True` |
+
+**示例**
+
+```python
+from kuaijs import cloud, logger
+
+ok = cloud.report("taskFinished", {
+    "taskId": "A-1001",
+    "success": True,
+    "costMs": 1280,
+})
+logger.info(f"上报结果: {ok}")
+```
+
+### onEvent - 监听服务器事件
+
+```python
+from typing import Any, Callable, Dict
+
+def onEvent(callback: Callable[[str, Dict[str, Any]], None] | None) -> None
+```
+
+监听服务器发送的 `scriptEvent` 协议帧。传入 `None` 会取消主脚本监听。
+该回调注册接口只能在 Python 主脚本中调用，不能在线程脚本中调用。
+
+**参数**
+
+| 参数名     | 类型                              | 是否必填 | 描述 |
+| ---------- | --------------------------------- | -------- | ---- |
+| `callback` | `Callable[[str, Dict[str, Any]], None]` 或 `None` | 是 | 事件处理函数，或传 `None` 取消监听 |
+
+事件处理函数参数：
+
+| 字段 | 类型 | 描述 |
+| ---- | ---- | ---- |
+| `event` | str | 自定义事件名称 |
+| `data` | dict | 服务端事件数据，普通 `dict` |
+
+**示例**
+
+```python
+from kuaijs import cloud, logger
+
+def handle_event(event: str, data: dict):
+    if event == "startTask":
+        logger.info(f"任务参数: {data}")
+
+cloud.onEvent(handle_event)
+```

package/docs/apipython/overview.md

@@ -5,7 +5,7 @@
 - 导入方式：
 
 ```python
-from kuaijs import action, hid, image, appleocr, paddleocr, yolo, yolocls, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
+from kuaijs import action, cloud, hid, image, appleocr, paddleocr, yolo, yolocls, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
 ```
 
 ## 下载资源

package/docs/apipython/ui.md

@@ -75,14 +75,16 @@ UI 模块提供 WebView 相关功能，支持事件通信与 JavaScript 交互
 ```python
 from typing import Callable, Any
 
-def onEvent(callback: Callable[[str, Any], None]) -> None
+def onEvent(callback: Callable[[str, Any], None] | None) -> None
 ```
 
+该回调注册接口只能在 Python 主脚本中调用，不能在线程脚本中调用。传入 `None` 会取消监听。
+
 **参数：**
 
 | 参数名     | 类型                         | 是否必填 | 默认值 | 描述                                 |
 | ---------- | ---------------------------- | -------- | ------ | ------------------------------------ |
-| `callback` | `Callable[[str, Any], None]` | 是       |        | 事件回调函数，用于处理来自网页的事件 |
+| `callback` | `Callable[[str, Any], None]` 或 `None` | 是 | | 事件回调函数，用于处理来自网页的事件，传 `None` 取消监听 |
 
 **示例：**
 

package/package.json

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