ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/system.md

@@ -0,0 +1,572 @@
+# 系统模块 (System)
+
+系统模块提供了与操作系统交互的核心功能，包括应用管理、锁屏控制、剪贴板操作、URL 打开和系统通知等功能。
+
+## 功能概览
+
+- **应用管理**: 启动、停止、激活应用，获取前台应用信息
+- **锁屏控制**: 检查锁屏状态、锁屏和解锁操作
+- **剪贴板**: 读取和设置系统剪贴板内容
+- **URL 操作**: 打开网页链接或应用 URL Scheme
+- **系统通知**: 发送系统通知消息
+- **内存管理**: 获取内存使用信息
+- **Agent 服务**: 启动 快点 Agent 服务
+
+## API 参考
+
+### 应用管理
+
+**注意事项:**
+
+- 仅支持 快点 Agent 模式使用
+
+#### startApp - 启动指定的应用程序。
+
+```typescript
+function startApp(bundleId: string): boolean;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
+| ---------- | ------ | -------- | ------ | ---------------- |
+| `bundleId` | string | 是       |        | 应用的 Bundle ID |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否启动成功 |
+
+**示例:**
+
+```javascript
+// 启动应用
+const started = system.startApp("com.example.app");
+if (started) {
+  logi("应用启动成功");
+}
+```
+
+#### stopApp - 关闭指定的应用程序。
+
+```typescript
+function stopApp(bundleId: string): boolean;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
+| ---------- | ------ | -------- | ------ | ---------------- |
+| `bundleId` | string | 是       |        | 应用的 Bundle ID |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否关闭成功 |
+
+**示例:**
+
+```javascript
+const stopped = system.stopApp("com.example.app");
+if (stopped) {
+  logi("应用关闭成功");
+} else {
+  logi("应用关闭失败或应用未运行");
+}
+```
+
+#### activateApp - 激活应用（如果未启动则启动，如果已启动则切换到前台）。
+
+```typescript
+function activateApp(bundleId: string): boolean;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
+| ---------- | ------ | -------- | ------ | ---------------- |
+| `bundleId` | string | 是       |        | 应用的 Bundle ID |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否激活成功 |
+
+**示例:**
+
+```javascript
+const activated = system.activateApp("com.apple.Safari");
+if (activated) {
+  logi("Safari 已激活");
+}
+```
+
+#### activateAppInfo - 获取当前前台应用的详细信息。
+
+```typescript
+function activateAppInfo(): {
+  bundleId: string;
+  name: string;
+  pid: number;
+} | null;
+```
+
+**返回值:**
+
+| 字段名     | 类型     | 描述                     |
+| ---------- | -------- | ------------------------ |
+| `bundleId` | `string` | 应用 Bundle ID           |
+| `name`     | `string` | 应用名称（不一定能取到） |
+| `pid`      | `number` | 进程 ID                  |
+
+**示例:**
+
+```javascript
+const appInfo = system.activateAppInfo();
+if (appInfo) {
+  logi(`当前前台应用: ${appInfo.name}`);
+  logi(`Bundle ID: ${appInfo.bundleId}`);
+  logi(`进程 ID: ${appInfo.pid}`);
+  logi("无法获取前台应用信息");
+}
+```
+
+### 锁屏控制
+
+**注意事项:**
+
+- 仅支持 快点 Agent 模式使用
+
+#### isLocked - 检查系统是否处于锁屏状态。
+
+```typescript
+function isLocked(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述     |
+| --------- | -------- |
+| `boolean` | 是否锁屏 |
+
+**示例:**
+
+```javascript
+if (system.isLocked()) {
+  logi("系统已锁屏");
+} else {
+  logi("系统未锁屏");
+}
+```
+
+#### lock - 锁定系统屏幕。
+
+```typescript
+function lock(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否锁屏成功 |
+
+**示例:**
+
+```javascript
+const locked = system.lock();
+if (locked) {
+  logi("系统已锁屏");
+} else {
+  logi("锁屏失败");
+}
+```
+
+#### unlock - 解锁系统屏幕（如果设置了密码，会停在解锁界面）。
+
+```typescript
+function unlock(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否解锁成功 |
+
+**示例:**
+
+```javascript
+const unlocked = system.unlock();
+if (unlocked) {
+  logi("系统已解锁");
+} else {
+  logi("解锁失败");
+}
+```
+
+### 剪贴板操作
+
+#### setClipboard - 设置系统剪贴板内容（需要应用在前台运行）。
+
+```typescript
+function setClipboard(text: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述             |
+| ------ | ------ | -------- | ------ | ---------------- |
+| `text` | string | 是       |        | 要设置的文本内容 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否设置成功 |
+
+**示例:**
+
+```javascript
+const set = system.setClipboard("Hello, World!");
+if (set) {
+  logi("剪贴板内容已设置");
+} else {
+  logi("设置剪贴板失败（可能应用不在前台）");
+}
+```
+
+#### getClipboard - 获取系统剪贴板内容（需要应用在前台运行）。
+
+```typescript
+function getClipboard(): string;
+```
+
+**返回值:**
+
+| 类型     | 描述                                    |
+| -------- | --------------------------------------- |
+| `string` | 剪贴板文本内容 `""`剪贴板为空或获取失败 |
+
+**示例:**
+
+```javascript
+const clipboardText = system.getClipboard();
+if (clipboardText) {
+  logi(`剪贴板内容: ${clipboardText}`);
+} else {
+  logi("剪贴板为空或获取失败");
+}
+```
+
+### URL 操作
+
+**注意事项:**
+
+- 仅支持 快点 Agent 模式使用
+
+#### openURL - 打开指定的 URL（可以是网页链接或应用的 URL Scheme）。
+
+```typescript
+function openURL(url: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `url`  | string | 是       |        | 要打开的 URL |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否打开成功 |
+
+**示例:**
+
+```javascript
+// 打开网页
+const webOpened = system.openURL("https://www.apple.com");
+if (webOpened) {
+  logi("网页已打开");
+}
+
+// 打开应用（URL Scheme）
+const appOpened = system.openURL("tel://10086");
+if (appOpened) {
+  logi("电话应用已打开");
+}
+
+// 打开邮件
+const mailOpened = system.openURL("mailto:example@example.com");
+if (mailOpened) {
+  logi("邮件应用已打开");
+}
+```
+
+### 系统通知
+
+#### notify - 发送系统通知。
+
+```typescript
+function notify(msg: string, title?: string, id?: string): void;
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                              |
+| ------- | ------ | -------- | ------ | --------------------------------- |
+| `msg`   | string | 是       |        | 通知内容                          |
+| `title` | string | 否       |        | 通知标题                          |
+| `id`    | string | 否       |        | 通知 ID（相同 ID 的通知会被覆盖） |
+
+**示例:**
+
+```javascript
+// 发送基础通知
+system.notify("任务已完成", "提醒", "task_complete");
+
+// 发送进度通知（会覆盖之前的通知）
+system.notify("进度: 50%", "下载中", "download_progress");
+system.notify("进度: 100%", "下载完成", "download_progress");
+```
+
+### 内存管理
+
+#### getMemoryInfo - 获取内存使用信息。
+
+```typescript
+function getMemoryInfo(): {
+  used: number;
+  available: number;
+  total: number;
+  usagePercentage: number;
+};
+```
+
+**返回值:**
+
+| 类型              | 描述                   |
+| ----------------- | ---------------------- |
+| `used`            | 已使用内存（单位：MB） |
+| `available`       | 可用内存（单位：MB）   |
+| `total`           | 总内存（单位：MB）     |
+| `usagePercentage` | 内存使用率（百分比）   |
+
+**说明:**
+
+该方法返回设备的完整内存使用信息，包括已使用内存、可用内存、总内存和使用率。
+
+**示例:**
+
+```javascript
+// 获取完整内存信息
+const memInfo = system.getMemoryInfo();
+logi(`内存使用情况:`);
+logi(`已使用: ${memInfo.used}MB`);
+logi(`可用: ${memInfo.available}MB`);
+logi(`总计: ${memInfo.total}MB`);
+logi(`使用率: ${memInfo.usagePercentage}%`);
+
+// 检查内存使用率
+if (memInfo.usagePercentage > 80) {
+  logw("内存使用率过高，建议清理内存");
+}
+```
+
+#### getUsedMemory - 获取已使用内存。
+
+```typescript
+function getUsedMemory(): number;
+```
+
+**返回值:**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `number` | 已使用内存大小（单位：MB） |
+
+**说明:**
+
+该方法返回当前应用已使用的内存大小。
+
+**示例:**
+
+```javascript
+// 获取已使用内存
+const usedMemory = system.getUsedMemory();
+logi(`已使用内存: ${usedMemory}MB`);
+
+// 检查内存使用情况
+if (usedMemory > 500) {
+  logw("内存使用较高，可能需要优化");
+}
+```
+
+#### getAvailableMemory - 获取可用内存。
+
+```typescript
+function getAvailableMemory(): number;
+```
+
+**返回值:**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `number` | 可用内存大小（单位：MB） |
+
+**说明:**
+
+该方法返回系统当前可用的内存大小，包括空闲内存和非活跃内存。
+
+**示例:**
+
+```javascript
+// 获取可用内存
+const availableMemory = system.getAvailableMemory();
+logi(`可用内存: ${availableMemory}MB`);
+
+// 检查可用内存是否充足
+if (availableMemory < 100) {
+  logw("可用内存不足，可能影响应用性能");
+}
+```
+
+#### getTotalMemory - 获取系统总内存。
+
+```typescript
+function getTotalMemory(): number;
+```
+
+**返回值:**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `number` | 系统总内存大小（单位：MB） |
+
+**说明:**
+
+该方法返回设备的物理内存总大小，这是设备硬件规格中的内存容量。
+
+**示例:**
+
+```javascript
+// 获取系统总内存
+const totalMemory = system.getTotalMemory();
+logi(`系统总内存: ${totalMemory}MB`);
+
+// 计算内存使用率
+const usedMemory = system.getUsedMemory();
+const usagePercentage = (usedMemory / totalMemory) * 100;
+logi(`内存使用率: ${usagePercentage.toFixed(1)}%`);
+
+// 获取完整的内存信息
+const memoryInfo = system.getMemoryInfo();
+logi(`内存信息: 已使用 ${memoryInfo.used}MB / 总计 ${memoryInfo.total}MB`);
+```
+
+### 快点 Agent 服务
+
+#### startAgent - 启动 快点 Agent 服务。
+
+**注意事项:**
+
+- 该方法仅前台可用。
+
+```typescript
+function startAgent(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否启动成功 |
+
+**说明:**
+
+该方法通过调用 `kuaijsagent://` URL Scheme 来启动 Agent 服务。
+
+内置 Agent 可以直接后台启动
+
+**示例:**
+
+```javascript
+// 启动 Agent 服务
+const started = system.startAgent();
+if (started) {
+  logi("快点 Agent 服务启动成功");
+} else {
+  logi("快点 Agent 服务启动失败");
+}
+```
+
+#### stopAgent - 停止 快点 Agent 服务。
+
+```typescript
+function stopAgent(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否关闭成功 |
+
+**说明:**
+
+该方法只支持内置 Agent 服务关闭。
+
+**示例:**
+
+```javascript
+// 关闭 Agent 服务
+const stopped = system.stopAgent();
+if (stopped) {
+  logi("快点 Agent 服务关闭成功");
+} else {
+  logi("快点 Agent 服务关闭失败");
+}
+```
+
+#### getAgentStatus - 获取 快点 Agent 服务状态。
+
+```typescript
+function getAgentStatus(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述                    |
+| --------- | ----------------------- |
+| `boolean` | 快点 Agent 是否正在运行 |
+
+**说明:**
+
+该方法检查 快点 Agent 服务的当前运行状态，通过向 快点 Agent 服务发送状态检查请求来判断服务是否可用。
+
+**示例:**
+
+```javascript
+// 检查 快点 Agent 服务状态
+const isRunning = system.getAgentStatus();
+if (isRunning) {
+  logi("快点 Agent 服务正在运行");
+} else {
+  logi("快点 Agent 服务未运行");
+}
+
+// 在执行自动化操作前检查 快点 Agent 服务状态
+if (system.getAgentStatus()) {
+  // 执行点击操作
+  action.click(100, 200);
+} else {
+  loge("快点 Agent 服务未运行，无法执行自动化操作");
+  // 尝试启动 Agent 服务
+  system.startAgent();
+}
+```