ms-vite-plugin 1.4.8 → 1.4.10

package/docs/apicn/pip.md

@@ -1,81 +1,15 @@
 # 悬浮窗模块 ($悬浮窗)
 
-悬浮窗模块提供了画中画（Picture in Picture）功能，允许在应用中显示悬浮的日志窗口，支持自定义样式。
+悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
 
 ## 功能特性
 
-- 🖼️ **悬浮窗显示** - 支持在屏幕上显示悬浮的日志窗口
-- 🎨 **自定义样式** - 可配置窗口大小、字体、颜色等
-- 🎮 **脚本控制配置** - 保留脚本控制配置接口，Video Call PiP 链路不再提供播放/暂停按钮回调
-
-## 接口定义
-
-### 日志窗口参数
-
-```typescript
-interface 日志窗口参数 {
-  /**
-   * 悬浮窗内容宽度，默认 300
-   */
-  width: 数字;
-  /**
-   * 悬浮窗内容高度，支持最低 0.1pt，实际显示由 iOS Video Call PiP 决定
-   */
-  height: 数字;
-  /**
-   * 日志的字体大小
-   */
-  textSize: 数字;
-  /**
-   * 日志的文字颜色，格式如 #FFFFFF
-   */
-  textColor: 字符串;
-  /**
-   * 日志的背景颜色，格式如 #000000
-   */
-  backgroundColor: 字符串;
-}
-```
-
-**参数说明：**
-
-| 参数              | 类型   | 是否必填 | 默认值 | 描述                                    |
-| ----------------- | ------ | -------- | ------ | --------------------------------------- |
-| `width`           | 数字   | 是       |        | 悬浮窗内容宽度，默认 300                |
-| `height`          | 数字   | 是       |        | 悬浮窗内容高度，支持最低 0.1pt          |
-| `textSize`        | 数字   | 是       |        | 日志文字大小（像素）                    |
-| `textColor`       | 字符串 | 是       |        | 文字颜色，十六进制格式（如：`#FFFFFF`） |
-| `backgroundColor` | 字符串 | 是       |        | 背景颜色，十六进制格式（如：`#000000`） |
+- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **状态查询**：判断悬浮窗是否正在显示
+- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
 
 ## API 方法
 
-### 设置日志视图参数
-
-```typescript
-function 设置日志视图参数(参数: 日志窗口参数): 无返回值;
-```
-
-设置悬浮窗日志窗口的显示参数。显示前调用会影响首次高度；显示后再次调用会同步更新当前 Video Call PiP 内容尺寸。
-
-**参数：**
-
-| 参数名 | 类型         | 是否必填 | 默认值 | 描述                   |
-| ------ | ------------ | -------- | ------ | ---------------------- |
-| `参数` | 日志窗口参数 | 是       |        | 包含显示参数的配置对象 |
-
-**示例：**
-
-```typescript
-// 配置悬浮窗参数
-$悬浮窗.设置日志视图参数({
-  width: 300,
-  height: 400,
-  textSize: 14,
-  textColor: "#FFFFFF",
-  backgroundColor: "#000000",
-});
-```
-
 ### 是否显示 - 判断悬浮窗是否打开
 
 ```typescript
@@ -93,133 +27,87 @@ function 是否显示(): 布尔值;
 **示例：**
 
 ```typescript
-// 检查悬浮窗是否打开
 const 是否显示 = $悬浮窗.是否显示();
 if (是否显示) {
   $打印信息日志("悬浮窗当前已打开");
-} else {
-  $打印信息日志("悬浮窗当前未打开");
 }
 ```
 
-### 显示日志窗口
+### 切换到日志模式
 
 ```typescript
-function 显示日志窗口(): 布尔值;
+function 切换到日志模式(): 布尔值;
 ```
 
-显示悬浮窗日志窗口。应用必须在前台才可调用
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
 
 **返回值：**
 
-| 类型     | 描述                              |
-| -------- | --------------------------------- |
-| `布尔值` | `true` 代表成功，`false` 代表失败 |
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 将应用切入前台
 $APP切入前台();
-// 显示悬浮窗
-const 是否成功 = $悬浮窗.显示日志窗口();
-if (是否成功) {
-  $打印信息日志("悬浮窗显示成功");
-} else {
-  $打印信息日志("悬浮窗显示失败，请检查权限设置");
-}
+const 是否成功 = $悬浮窗.切换到日志模式();
 ```
 
-### 关闭日志窗口
+### 切换到保活模式
 
 ```typescript
-function 关闭日志窗口(): 布尔值;
+function 切换到保活模式(): 布尔值;
 ```
 
-关闭悬浮窗日志窗口。应用必须在前台才可调用。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
 
 **返回值：**
 
-| 类型     | 描述                              |
-| -------- | --------------------------------- |
-| `布尔值` | `true` 代表成功，`false` 代表失败 |
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 将应用切入前台
 $APP切入前台();
-// 关闭悬浮窗
-const 是否成功 = $悬浮窗.关闭日志窗口();
-if (是否成功) {
-  $打印信息日志("悬浮窗关闭成功");
-} else {
-  $打印信息日志("悬浮窗关闭失败");
-}
+const 是否成功 = $悬浮窗.切换到保活模式();
 ```
 
-### 设置是否允许控制脚本启停
+### 切换到关闭模式
 
 ```typescript
-function 设置是否允许控制脚本启停(是否允许: 布尔值): 布尔值;
+function 切换到关闭模式(): 布尔值;
 ```
 
-设置是否允许悬浮窗控制脚本的启停。当前 Video Call PiP 链路仅保存配置，不再提供播放/暂停按钮回调。
-
-**参数：**
-
-| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                        |
-| ---------- | ------ | -------- | ------ | ------------------------------------------- |
-| `是否允许` | 布尔值 | 是       |        | `true` 代表允许控制，`false` 代表不允许控制 |
-
-**示例：**
+切换到关闭模式并关闭悬浮窗。
 
 **返回值：**
 
-| 类型     | 描述                              |
-| -------- | --------------------------------- |
-| `布尔值` | `true` 代表成功，`false` 代表失败 |
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 允许悬浮窗控制脚本
-const 是否成功1 = $悬浮窗.设置是否允许控制脚本启停(true);
-// 禁止悬浮窗控制脚本
-const 是否成功2 = $悬浮窗.设置是否允许控制脚本启停(false);
+const 是否成功 = $悬浮窗.切换到关闭模式();
 ```
 
 ## 完整使用示例
 
 ```typescript
-// 将应用切入前台
 $APP切入前台();
-// 1. 配置悬浮窗参数
-$悬浮窗.设置日志视图参数({
-  width: 350,
-  height: 500,
-  textSize: 16,
-  textColor: "#00FF00", // 绿色文字
-  backgroundColor: "#1A1A1A", // 深灰色背景
-});
-
-// 2. 保存悬浮窗控制脚本配置
-$悬浮窗.设置是否允许控制脚本启停(true);
-
-// 3. 显示悬浮窗
-const showResult = $悬浮窗.显示日志窗口();
+$悬浮窗.切换到日志模式();
 ```
 
 ## 注意事项
 
-1. **前台限制**：所有悬浮窗操作都必须在应用前台状态下进行
+1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **尺寸限制**：`height` 支持最低 0.1pt，内部最高限制为 220pt；实际悬浮窗显示仍由 iOS Video Call PiP 决定
-4. **配置时机**：`设置日志视图参数()` 可在显示前或显示后调用，显示后会同步更新当前内容尺寸
-5. **颜色格式**：颜色值必须使用十六进制格式（如：`#FFFFFF`）
-6. **尺寸适配**：iOS 系统会对画中画窗口的尺寸进行限制和自动调整，实际显示的画中画窗口大小可能与设置的 `width` 和 `height` 参数不完全一致
-7. **内容渲染**：画中画内容渲染会自动适配系统分配的实际窗口尺寸，而不是使用配置的尺寸参数
-8. **脚本控制**：Video Call PiP 链路不再提供播放/暂停按钮回调，`设置是否允许控制脚本启停(true)` 当前仅保存配置
+3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
 
 ## 故障排除
 
@@ -227,15 +115,4 @@ const showResult = $悬浮窗.显示日志窗口();
 
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
-- 确认参数配置是否正确（高度不低于 0.1pt）
-
-### 悬浮窗显示异常
-
-- 检查颜色值格式是否正确
-- 确认字体大小设置是否合理
-- 验证窗口尺寸是否在有效范围内
-
-### 脚本控制无效
-
-- 当前 Video Call PiP 链路不再提供播放/暂停按钮回调
-- `设置是否允许控制脚本启停(true)` 仅保存配置，不会直接驱动脚本启停
+- 确认应用当前在前台

package/docs/apicn/system.md

@@ -10,6 +10,7 @@
 - **URL 操作**: 打开网页链接或应用 URL Scheme
 - **系统通知**: 发送系统通知消息
 - **内存管理**: 获取内存使用信息
+- **CPU 管理**: 获取 CPU 使用率
 - **快点 Agent 服务**: 启动 Agent 服务
 
 ## API 参考
@@ -427,37 +428,35 @@ function 获取内存使用信息(): {
   used: 数字;
   available: 数字;
   total: 数字;
+  systemUsed: 数字;
   usagePercentage: 数字;
 };
 ```
 
 **返回值:**
 
-| 参数名            | 类型 | 描述                   |
-| ----------------- | ---- | ---------------------- |
-| `used`            | 数字 | 已使用内存（单位：MB） |
-| `available`       | 数字 | 可用内存（单位：MB）   |
-| `total`           | 数字 | 总内存（单位：MB）     |
-| `usagePercentage` | 数字 | 内存使用率（百分比）   |
+| 参数名            | 类型 | 描述                         |
+| ----------------- | ---- | ---------------------------- |
+| `used`            | 数字 | 当前应用占用（单位：MB）     |
+| `available`       | 数字 | 系统可用内存（单位：MB）     |
+| `total`           | 数字 | 系统总内存（单位：MB）       |
+| `systemUsed`      | 数字 | 系统已用内存（单位：MB）     |
+| `usagePercentage` | 数字 | 系统内存占用率（百分比）     |
 
 **说明:**
 
-该方法返回设备的完整内存使用信息，包括已使用内存、可用内存、总内存和使用率。
+该方法返回当前应用占用和系统内存概况。`usagePercentage` 表示系统整体占用率。
 
 **示例:**
 
 ```javascript
-// 获取完整内存信息
 const memInfo = $系统.获取内存使用信息();
-$打印信息日志(`内存使用情况:`);
-$打印信息日志(`已使用: ${memInfo.used}MB`);
-$打印信息日志(`可用: ${memInfo.available}MB`);
-$打印信息日志(`总计: ${memInfo.total}MB`);
-$打印信息日志(`使用率: ${memInfo.usagePercentage}%`);
+$打印信息日志(`应用占用: ${memInfo.used}MB`);
+$打印信息日志(`系统内存: ${memInfo.systemUsed}/${memInfo.total}MB`);
+$打印信息日志(`系统占用: ${memInfo.usagePercentage}%`);
 
-// 检查内存使用率
 if (memInfo.usagePercentage > 80) {
-  $打印警告日志("内存使用率过高，建议清理内存");
+  $打印警告日志("系统内存占用较高");
 }
 ```
 
@@ -554,6 +553,61 @@ $打印信息日志(
 );
 ```
 
+#### 获取系统已用内存 - 获取系统物理内存已使用量。
+
+```typescript
+function 获取系统已用内存(): 数字;
+```
+
+**返回值:**
+
+| 参数名       | 类型 | 描述                       |
+| ------------ | ---- | -------------------------- |
+| `systemUsed` | 数字 | 系统已用内存大小（单位：MB） |
+
+**说明:**
+
+该方法返回系统物理内存的已使用量，计算方式为系统总内存减去可用内存，与 `获取内存使用信息()` 返回的 `systemUsed` 一致。
+
+**示例:**
+
+```javascript
+// 获取系统已用内存
+const 系统已用内存 = $系统.获取系统已用内存();
+$打印信息日志(`系统已用内存: ${系统已用内存}MB`);
+
+// 与 获取内存使用信息 对比
+const 内存信息 = $系统.获取内存使用信息();
+$打印信息日志(
+  `系统已用: ${系统已用内存}MB, 内存信息: ${内存信息.systemUsed}MB`,
+);
+```
+
+### CPU 管理
+
+#### 获取CPU使用率 - 获取 CPU 使用率。
+
+```typescript
+function 获取CPU使用率(): 数字;
+```
+
+**返回值:**
+
+| 类型   | 描述                         |
+| ------ | ---------------------------- |
+| `数字` | 当前应用 CPU 使用率（百分比） |
+
+**示例:**
+
+```javascript
+const CPU使用率 = $系统.获取CPU使用率();
+$打印信息日志(`CPU 使用率: ${CPU使用率}%`);
+
+if (CPU使用率 > 80) {
+  $打印警告日志("CPU 使用率较高，建议降低脚本负载");
+}
+```
+
 ### 快点 Agent 服务
 
 #### 启动 快点 Agent 服务

package/docs/apipython/g.md

@@ -101,6 +101,58 @@ if g.getAgentFastMode():
     print("Agent 快速模式已开启")
 ```
 
+#### `setCpuAutoThrottle` - 设置脚本 CPU 自动限流
+
+默认开启。开启后，脚本 API 在 CPU 占用接近系统杀进程阈值时会轻微让步，降低被系统终止的风险。
+
+```python
+def setCpuAutoThrottle(enabled: bool) -> bool
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述             |
+| --------- | ------ | -------- | ------ | ---------------- |
+| `enabled` | `bool` | 是       | -      | 是否开启自动限流 |
+
+**返回值:**
+
+| 类型   | 描述                 |
+| ------ | -------------------- |
+| `bool` | 实际是否开启自动限流 |
+
+**示例:**
+
+```python
+from kuaijs import g
+
+enabled = g.setCpuAutoThrottle(True)
+print(f"CPU 自动限流: {enabled}")
+```
+
+#### `getCpuAutoThrottle` - 获取脚本 CPU 自动限流
+
+默认开启。
+
+```python
+def getCpuAutoThrottle() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述                 |
+| ------ | -------------------- |
+| `bool` | 当前是否开启自动限流 |
+
+**示例:**
+
+```python
+from kuaijs import g
+
+if g.getCpuAutoThrottle():
+    print("CPU 自动限流已开启")
+```
+
 #### `restartScript` - 重启脚本
 
 ```python

package/docs/apipython/ime.md

@@ -36,32 +36,6 @@ else:
     # 可能需要重新初始化或检查权限
 ```
 
-### autoSwitchApiKeyboard - 自动切换到 API 键盘
-
-```python
-def autoSwitchApiKeyboard() -> bool
-```
-
-**返回值：**
-
-| 类型   | 描述                                       |
-| ------ | ------------------------------------------ |
-| `bool` | 是否成功切换并连接到 API 键盘，成功为 True |
-
-- 该方法仅在系统设置中添加了快点JS API键盘 并且已授权完全访问权限时有效。
-
-**示例：**
-
-```python
-from kuaijs import ime
-
-# 自动切换到 API 键盘（如未弹出会尝试切换）
-if ime.autoSwitchApiKeyboard():
-    print("已切换到 API 键盘")
-else:
-    print("切换失败，请检查键盘设置和完全访问权限")
-```
-
 ## 文本获取和清除
 
 ### getText - 获取当前输入框的文本内容