ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apipython/system.md

@@ -0,0 +1,458 @@
+# 系统模块 (System)
+
+系统模块提供了与操作系统交互的核心功能，包括应用管理、锁屏控制、剪贴板操作、URL 打开和系统通知等功能。
+
+## 功能概览
+
+- **应用管理**: 启动、停止、激活应用，获取前台应用信息
+- **锁屏控制**: 检查锁屏状态、锁屏和解锁操作
+- **剪贴板**: 读取和设置系统剪贴板内容
+- **URL 操作**: 打开网页链接或应用 URL Scheme
+- **系统通知**: 发送系统通知消息
+- **内存管理**: 获取内存使用信息
+- **快点 Agent 服务**: 启动 快点 Agent 服务
+
+## 类型定义
+
+### ActivateAppInfo
+
+前台应用信息结构。
+
+```python
+class ActivateAppInfo(TypedDict):
+    bundleId: str
+    name: str
+    pid: int
+```
+
+### MemoryInfo
+
+内存信息结构。
+
+```python
+class MemoryInfo(TypedDict):
+    used: int            # 已使用内存（MB）
+    available: int       # 可用内存（MB）
+    total: int           # 总内存（MB）
+    usagePercentage: float # 内存使用率（百分比）
+```
+
+## API 参考
+
+### 应用管理
+
+**注意事项:**
+
+- 此模块仅支持 快点 Agent 模式使用
+
+#### startApp - 启动指定的应用程序。
+
+```python
+def startApp(bundle_id: str) -> bool
+```
+
+**参数:**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ------ | ---- | ------- | ------ | ---- |
+| `bundle_id` | str | 是 | - | 应用 Bundle ID |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否启动成功 |
+
+**示例:**
+
+```python
+from kuaijs import system
+# 启动应用
+ok = system.startApp("com.example.app")
+print("应用启动成功" if ok else "应用启动失败")
+```
+
+#### stopApp - 关闭指定的应用程序。
+
+```python
+def stopApp(bundle_id: str) -> bool
+```
+
+**参数：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+|-------------|------|----------|--------|-----------------|
+| `bundle_id` | str | 是 | - | 应用 Bundle ID |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否停止成功 |
+
+**示例:**
+
+```python
+from kuaijs import system
+system.stopApp("com.apple.Safari")
+```
+
+#### activateApp - 激活应用（如果未启动则启动，如果已启动则切换到前台）。
+
+```python
+def activateApp(bundle_id: str) -> bool
+```
+
+**参数：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+|-------------|------|----------|--------|-----------------|
+| `bundle_id` | str | 是 | - | 应用 Bundle ID |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否激活成功 |
+
+**示例:**
+
+```python
+from kuaijs import system
+system.activateApp("com.apple.Safari")
+```
+
+#### activateAppInfo - 获取当前前台应用的详细信息。
+
+```python
+def activateAppInfo() -> Optional[ActivateAppInfo]
+```
+
+**返回值：**
+
+| 字段名     | 类型 | 描述                     |
+| ---------- | ---- | ------------------------ |
+| `bundleId` | str  | 应用 Bundle ID           |
+| `name`     | str  | 应用名称（不一定能取到） |
+| `pid`      | int  | 进程 ID                  |
+
+**示例：**
+
+```python
+from kuaijs import system
+info = system.activateAppInfo()
+if info:
+    print(info.name, info.bundleId, info.pid)
+```
+
+### 锁屏控制
+
+**注意事项:**
+
+- 此模块仅支持 快点 Agent 模式使用
+
+#### isLocked - 检查系统是否处于锁屏状态。
+
+```python
+def isLocked() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 当前是否锁屏 |
+
+#### lock - 锁定系统屏幕
+
+```python
+def lock() -> bool
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | ---- |
+| `bool` | 操作是否成功 |
+
+#### unlock - 解锁系统屏幕（如果设置了密码，会停在解锁界面）
+
+```python
+def unlock() -> bool
+```
+
+**返回值：**
+| 类型 | 描述 |
+| ---- | ---- |
+| `bool` | 操作是否成功 |
+
+### 剪贴板操作
+
+#### setClipboard - 设置系统剪贴板内容（需要应用在前台运行）。
+
+```python
+def setClipboard(text: str) -> bool
+```
+
+**参数:**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `text` | str | 是 | | 要设置的文本内容 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 设置是否成功 |
+
+**示例:**
+
+```python
+from kuaijs import system
+system.setClipboard("Hello, World!")
+```
+
+```python
+from kuaijs import system
+text = system.getClipboard()
+print(text if text else "剪贴板为空或获取失败")
+```
+
+#### getClipboard - 获取系统剪贴板内容。
+
+```python
+def getClipboard() -> str
+```
+
+**返回值:**
+
+| 类型  | 描述                                       |
+| ----- | ------------------------------------------ |
+| `str` | 剪贴板文本内容；空字符串表示获取失败或为空 |
+
+**示例:**
+
+```python
+from kuaijs import system
+print(system.getClipboard())
+```
+
+### URL 操作
+
+**注意事项:**
+
+- 此模块仅支持 快点 Agent 模式使用
+
+#### openURL - 打开 URL（网页或 URL Scheme）
+
+```python
+def openURL(url: str) -> bool
+```
+
+**参数：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+|--------|------|----------|--------|--------------|
+| `url` | str | 是 | - | URL 或 Scheme |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 打开是否成功 |
+
+**示例:**
+
+```python
+from kuaijs import system
+system.openURL("https://www.apple.com")
+system.openURL("tel://10086")
+```
+
+### 系统通知
+
+#### notify - 发送系统通知。
+
+```python
+def notify(msg: str, title: str = ..., id: str = ...) -> None
+```
+
+**参数:**
+
+| 参数名  | 类型 | 是否必填 | 默认值   | 描述                    |
+| ------- | ---- | -------- | -------- | ----------------------- |
+| `msg`   | str  | 是       | -        | 通知内容                |
+| `title` | str  | 否       | 应用名称 | 通知标题                |
+| `id`    | str  | 否       | -        | 通知 ID（相同 ID 覆盖） |
+
+**示例:**
+
+```python
+from kuaijs import system
+system.notify("任务完成", title="提示", id="task-1")
+system.notify("进度: 50%", title="下载中", id="download")
+system.notify("进度: 100%", title="下载完成", id="download")
+```
+
+### 内存管理
+
+#### getMemoryInfo - 获取内存使用信息。
+
+```python
+def getMemoryInfo() -> MemoryInfo
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ----------------- | ---------------------- |
+| `used` | 已使用内存（单位：MB） |
+| `available` | 可用内存（单位：MB） |
+| `total` | 总内存（单位：MB） |
+| `usagePercentage` | 内存使用率（百分比） |
+
+**说明:**
+
+该方法返回设备的完整内存使用信息，包括已使用内存、可用内存、总内存和使用率。
+
+**示例:**
+
+```python
+from kuaijs import system
+mem = system.getMemoryInfo()
+print(mem.used, mem.available, mem.total, mem.usagePercentage)
+
+if mem.usagePercentage > 80:
+    print("内存使用率过高，建议清理内存")
+```
+
+#### getUsedMemory - 获取已使用内存。
+
+```python
+def getUsedMemory() -> int
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | -------------- |
+| `int`| 已使用内存（MB） |
+
+**说明:**
+
+该方法返回当前应用已使用的内存大小。
+
+#### getAvailableMemory - 获取可用内存。
+
+```python
+def getAvailableMemory() -> int
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | -------------- |
+| `int`| 可用内存（MB） |
+
+**说明:**
+
+该方法返回系统当前可用的内存大小，包括空闲内存和非活跃内存。
+
+#### getTotalMemory - 获取系统总内存。
+
+```python
+def getTotalMemory() -> int
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | ------------ |
+| `int`| 总内存（MB） |
+
+**说明:**
+
+该方法返回设备的物理内存总大小，这是设备硬件规格中的内存容量。
+
+**示例：**
+
+```python
+from kuaijs import system
+used = system.getUsedMemory()
+available = system.getAvailableMemory()
+total = system.getTotalMemory()
+print(f"已用: {used}MB, 可用: {available}MB, 总计: {total}MB")
+usage = (used / total) * 100 if total else 0
+print(f"使用率: {usage:.1f}%")
+```
+
+### 快点 Agent 服务
+
+#### startAgent - 启动 快点 Agent 服务。
+
+**注意事项:**
+
+- 该方法仅前台可用。
+
+```python
+def startAgent() -> bool
+```
+
+**返回值:**
+| 类型 | 描述 |
+| ---- | ---- |
+| `bool` | 启动是否成功 |
+
+**说明:**
+
+该方法通过调用 `kuaijsagent://` URL Scheme 来启动 快点 Agent 服务。
+
+内置 Agent 可以直接后台启动
+
+**示例:**
+
+```python
+from kuaijs import system
+system.startAgent()
+```
+
+#### stopAgent - 关闭 快点 Agent 服务。
+
+```python
+def stopAgent() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否关闭成功 |
+
+**说明:**
+
+该方法只支持内置 Agent 服务关闭。
+
+**示例:**
+
+```python
+from kuaijs import system
+stopped = system.stopAgent()
+if stopped:
+    print("Agent 服务关闭成功")
+else:
+    print("Agent 服务关闭失败")
+```
+
+#### getAgentStatus - 获取 快点 Agent 服务状态。
+
+```python
+def getAgentStatus() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述                         |
+| ------ | ---------------------------- |
+| `bool` | 当前 快点 Agent 服务是否可用 |
+
+**说明:**
+
+该方法检查 快点 Agent 服务的当前运行状态，通过向 快点 Agent 服务发送状态检查请求来判断服务是否可用。
+
+**示例：**
+
+```python
+from kuaijs import system
+print(system.getAgentStatus())
+```