ms-vite-plugin 1.4.8 → 1.4.10

package/docs/apipython/pip.md

@@ -1,61 +1,15 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供了画中画（Picture in Picture）功能，允许在应用中显示悬浮的日志窗口，支持自定义样式。
+悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
 
 ## 功能特性
 
-- **悬浮窗显示**: 支持在屏幕上显示悬浮的日志窗口
-- **自定义样式**: 可配置窗口大小、字体、颜色等
-- **脚本控制配置**: 保留脚本控制配置接口，Video Call PiP 链路不再提供播放/暂停按钮回调
-
-## 类型定义
-
-### LogViewParams
-
-悬浮窗参数配置。
-
-```python
-from typing import TypedDict
-
-class LogViewParams(TypedDict):
-    width: float          # 悬浮窗内容宽度，默认 300
-    height: float         # 悬浮窗内容高度，支持最低 0.1pt
-    textSize: int         # 日志的字体大小
-    textColor: str        # 日志的文字颜色，格式如 #FFFFFF
-    backgroundColor: str  # 日志的背景颜色，格式如 #000000
-```
+- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **状态查询**：判断悬浮窗是否正在显示
+- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
 
 ## API 参考
 
-### setLogViewParams - 设置悬浮窗显示参数
-
-设置悬浮窗日志窗口的显示参数。显示前调用会影响首次高度；显示后再次调用会同步更新当前 Video Call PiP 内容尺寸。
-
-```python
-def setLogViewParams(params: LogViewParams) -> None
-```
-
-**参数：**
-
-| 参数名   | 类型            | 是否必填 | 默认值 | 描述                   |
-| -------- | --------------- | -------- | ------ | ---------------------- |
-| `params` | `LogViewParams` | 是       | -      | 包含显示参数的配置对象 |
-
-**示例：**
-
-```python
-from kuaijs import pip
-
-# 配置悬浮窗参数
-pip.setLogViewParams({
-    "width": 300,
-    "height": 400,
-    "textSize": 14,
-    "textColor": "#FFFFFF",
-    "backgroundColor": "#000000"
-})
-```
-
 ### isPipActive - 判断悬浮窗是否打开
 
 判断悬浮窗是否当前打开。
@@ -75,104 +29,76 @@ def isPipActive() -> bool
 ```python
 from kuaijs import pip
 
-# 检查悬浮窗是否打开
-is_active = pip.isPipActive()
-if is_active:
+if pip.isPipActive():
     print("悬浮窗当前已打开")
-else:
-    print("悬浮窗当前未打开")
 ```
 
-### showLogWindow - 显示日志窗口
+### switchToLogMode - 切换到日志模式
 
-显示悬浮窗日志窗口。应用必须在前台才可调用。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
 
 ```python
-def showLogWindow() -> bool
+def switchToLogMode() -> bool
 ```
 
 **返回值：**
 
-| 类型   | 描述                              |
-| ------ | --------------------------------- |
-| `bool` | `True` 代表成功，`False` 代表失败 |
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
 
 **示例：**
 
 ```python
 from kuaijs import pip, utils
 
-# 将应用切入前台
 utils.takeMeToFront()
-
-# 显示悬浮窗
-success = pip.showLogWindow()
-if success:
-    print("悬浮窗显示成功")
-else:
-    print("悬浮窗显示失败，请检查权限设置")
+success = pip.switchToLogMode()
 ```
 
-### closeLogWindow - 关闭日志窗口
+### switchToKeepAliveMode - 切换到保活模式
 
-关闭悬浮窗日志窗口。应用必须在前台才可调用。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
 
 ```python
-def closeLogWindow() -> bool
+def switchToKeepAliveMode() -> bool
 ```
 
 **返回值：**
 
-| 类型   | 描述                              |
-| ------ | --------------------------------- |
-| `bool` | `True` 代表成功，`False` 代表失败 |
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
 
 **示例：**
 
 ```python
 from kuaijs import pip, utils
 
-# 将应用切入前台
 utils.takeMeToFront()
-
-# 关闭悬浮窗
-success = pip.closeLogWindow()
-if success:
-    print("悬浮窗关闭成功")
-else:
-    print("悬浮窗关闭失败")
+success = pip.switchToKeepAliveMode()
 ```
 
-### setPipCtrlScript - 设置脚本控制权限
+### switchToOffMode - 切换到关闭模式
 
-设置是否允许悬浮窗控制脚本的启停。当前 Video Call PiP 链路仅保存配置，不再提供播放/暂停按钮回调。
+切换到关闭模式并关闭悬浮窗。
 
 ```python
-def setPipCtrlScript(ctrl: bool) -> bool
+def switchToOffMode() -> bool
 ```
 
-**参数：**
-
-| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                        |
-| ------ | ------ | -------- | ------ | ------------------------------------------- |
-| `ctrl` | `bool` | 是       | -      | `True` 代表允许控制，`False` 代表不允许控制 |
-
 **返回值：**
 
-| 类型   | 描述                              |
-| ------ | --------------------------------- |
-| `bool` | `True` 代表成功，`False` 代表失败 |
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
 
 **示例：**
 
 ```python
 from kuaijs import pip
 
-# 允许悬浮窗控制脚本
-ok1 = pip.setPipCtrlScript(True)
-
-# 禁止悬浮窗控制脚本
-ok2 = pip.setPipCtrlScript(False)
+success = pip.switchToOffMode()
 ```
 
 ## 完整使用示例
@@ -180,35 +106,16 @@ ok2 = pip.setPipCtrlScript(False)
 ```python
 from kuaijs import pip, utils
 
-# 将应用切入前台
 utils.takeMeToFront()
-
-# 1. 配置悬浮窗参数
-pip.setLogViewParams({
-    "width": 350,
-    "height": 500,
-    "textSize": 16,
-    "textColor": "#00FF00",      # 绿色文字
-    "backgroundColor": "#1A1A1A" # 深灰色背景
-})
-
-# 2. 保存悬浮窗控制脚本配置
-pip.setPipCtrlScript(True)
-
-# 3. 显示悬浮窗
-pip.showLogWindow()
+pip.switchToLogMode()
 ```
 
 ## 注意事项
 
-1. **前台限制**：所有悬浮窗操作都必须在应用前台状态下进行
+1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **尺寸限制**：`height` 支持最低 0.1pt，内部最高限制为 220pt；实际悬浮窗显示仍由 iOS Video Call PiP 决定
-4. **配置时机**：`setLogViewParams()` 可在显示前或显示后调用，显示后会同步更新当前内容尺寸
-5. **颜色格式**：颜色值必须使用十六进制格式（如：`#FFFFFF`）
-6. **尺寸适配**：iOS 系统会对画中画窗口的尺寸进行限制和自动调整，实际显示的画中画窗口大小可能与设置的 `width` 和 `height` 参数不完全一致
-7. **内容渲染**：画中画内容渲染会自动适配系统分配的实际窗口尺寸，而不是使用配置的尺寸参数
-8. **脚本控制**：Video Call PiP 链路不再提供播放/暂停按钮回调，`setPipCtrlScript(True)` 当前仅保存配置
+3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
 
 ## 故障排除
 
@@ -216,15 +123,4 @@ pip.showLogWindow()
 
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
-- 确认参数配置是否正确（高度不低于 0.1pt）
-
-### 悬浮窗显示异常
-
-- 检查颜色值格式是否正确
-- 确认字体大小设置是否合理
-- 验证窗口尺寸是否在有效范围内
-
-### 脚本控制无效
-
-- 当前 Video Call PiP 链路不再提供播放/暂停按钮回调
-- `setPipCtrlScript(True)` 仅保存配置，不会直接驱动脚本启停
+- 确认应用当前在前台

package/docs/apipython/system.md

@@ -10,6 +10,7 @@
 - **URL 操作**: 打开网页链接或应用 URL Scheme
 - **系统通知**: 发送系统通知消息
 - **内存管理**: 获取内存使用信息
+- **CPU 管理**: 获取 CPU 使用率
 - **快点 Agent 服务**: 启动 快点 Agent 服务
 
 ## 类型定义
@@ -42,10 +43,11 @@ class InstalledAppInfo(TypedDict):
 
 ```python
 class MemoryInfo(TypedDict):
-    used: int            # 已使用内存（MB）
-    available: int       # 可用内存（MB）
-    total: int           # 总内存（MB）
-    usagePercentage: float # 内存使用率（百分比）
+    used: int            # 当前应用占用（MB）
+    available: int       # 系统可用内存（MB）
+    total: int           # 系统总内存（MB）
+    systemUsed: int      # 系统已用内存（MB）
+    usagePercentage: float # 系统占用率（百分比）
 ```
 
 ## API 参考
@@ -387,25 +389,26 @@ def getMemoryInfo() -> MemoryInfo
 
 **返回值:**
 | 类型 | 描述 |
-| ----------------- | ---------------------- |
-| `used` | 已使用内存（单位：MB） |
-| `available` | 可用内存（单位：MB） |
-| `total` | 总内存（单位：MB） |
-| `usagePercentage` | 内存使用率（百分比） |
+| ----------------- | ---------------------------- |
+| `used` | 当前应用占用（单位：MB） |
+| `available` | 系统可用内存（单位：MB） |
+| `total` | 系统总内存（单位：MB） |
+| `systemUsed` | 系统已用内存（单位：MB） |
+| `usagePercentage` | 系统内存占用率（百分比） |
 
 **说明:**
 
-该方法返回设备的完整内存使用信息，包括已使用内存、可用内存、总内存和使用率。
+该方法返回当前应用占用和系统内存概况。`usagePercentage` 表示系统整体占用率。
 
 **示例:**
 
 ```python
 from kuaijs import system
 mem = system.getMemoryInfo()
-print(mem.used, mem.available, mem.total, mem.usagePercentage)
+print(f"应用: {mem.used}MB, 系统: {mem.systemUsed}/{mem.total}MB, 占用: {mem.usagePercentage}%")
 
 if mem.usagePercentage > 80:
-    print("内存使用率过高，建议清理内存")
+    print("系统内存占用较高")
 ```
 
 #### getUsedMemory - 获取已使用内存。
@@ -465,6 +468,58 @@ usage = (used / total) * 100 if total else 0
 print(f"使用率: {usage:.1f}%")
 ```
 
+#### getSystemUsedMemory - 获取系统已用内存。
+
+```python
+def getSystemUsedMemory() -> int
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | ------------ |
+| `int`| 系统已用内存（MB） |
+
+**说明:**
+
+该方法返回系统物理内存的已使用量，计算方式为系统总内存减去可用内存，与 `getMemoryInfo()` 返回的 `systemUsed` 一致。
+
+**示例：**
+
+```python
+from kuaijs import system
+
+system_used = system.getSystemUsedMemory()
+print(f"系统已用内存: {system_used}MB")
+
+mem = system.getMemoryInfo()
+print(f"getMemoryInfo systemUsed: {mem['systemUsed']}MB")
+```
+
+### CPU 管理
+
+#### getCpuUsage - 获取 CPU 使用率。
+
+```python
+def getCpuUsage() -> float
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | ---- |
+| `float` | 当前应用 CPU 使用率（百分比） |
+
+**示例:**
+
+```python
+from kuaijs import system
+
+cpu_usage = system.getCpuUsage()
+print(f"CPU 使用率: {cpu_usage}%")
+
+if cpu_usage > 80:
+    print("CPU 使用率较高，建议降低脚本负载")
+```
+
 ### 快点 Agent 服务
 
 #### startAgent - 启动 快点 Agent 服务。