ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/system.md

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