ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/system.md

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