app.system - 系统信息 API

获取系统、硬件和环境信息。

基础信息

app.system.osName()

获取操作系统名称。

返回值: string - 始终返回 “macOS”

local os = app.system.osName()  -- "macOS"

app.system.osVersion()

获取操作系统版本。

返回值: string - 版本号

local version = app.system.osVersion()  -- "14.1.0"

app.system.osBuild()

获取系统构建号。

返回值: string - 构建号

local build = app.system.osBuild()  -- "23B74"

app.system.hostName()

获取主机名。

返回值: string - 主机名

local host = app.system.hostName()  -- "MacBook-Pro.local"

app.system.userName()

获取当前用户名。

返回值: string - 用户名

local user = app.system.userName()  -- "username"

app.system.fullUserName()

获取用户全名。

返回值: string - 全名

local name = app.system.fullUserName()  -- "张三"

环境变量

app.system.env(name)

获取环境变量。

参数:

• name (string) - 变量名

返回值: string|nil - 变量值或 nil

local home = app.system.env("HOME")        -- "/Users/username"
local path = app.system.env("PATH")        -- "/usr/local/bin:..."
local custom = app.system.env("MY_VAR")    -- nil（如果不存在）

app.system.envAll()

获取所有环境变量。

返回值: table - 键值对表

local env = app.system.envAll()
for name, value in pairs(env) do
    app.log.info(name .. " = " .. value)
end

app.system.setEnv(name, value)

设置环境变量（仅当前进程有效）。

参数:

• name (string) - 变量名
• value (string) - 变量值

返回值: boolean - 是否成功

app.system.setEnv("MY_VAR", "my_value")

硬件信息

app.system.arch()

获取 CPU 架构。

返回值: string - “arm64” 或 “x86_64”

local arch = app.system.arch()  -- "arm64"

if arch == "arm64" then
    app.log.info("Apple Silicon Mac")
else
    app.log.info("Intel Mac")
end

app.system.cpuCount()

获取 CPU 核心数。

返回值: number - 核心数

local cores = app.system.cpuCount()  -- 8

app.system.memory()

获取内存信息。

返回值: table

• total (number) - 总内存（字节）
• available (number) - 可用内存（字节）
• used (number) - 已用内存（字节）

local mem = app.system.memory()
app.log.info("总内存: " .. (mem.total / 1024 / 1024 / 1024) .. " GB")
app.log.info("可用: " .. (mem.available / 1024 / 1024 / 1024) .. " GB")

app.system.diskSpace(path?)

获取磁盘空间信息。

参数:

• path (string, 可选) - 磁盘路径（默认 “/“）

返回值: table|nil

• total (number) - 总空间（字节）
• available (number) - 可用空间（字节）
• used (number) - 已用空间（字节）

local disk = app.system.diskSpace("/")
app.log.info("可用空间: " .. (disk.available / 1024 / 1024 / 1024) .. " GB")

-- 检查外置硬盘
local external = app.system.diskSpace("/Volumes/MyDrive")

app.system.deviceModel()

获取设备型号标识（since 1.3.0）。

返回值: string - 如 "MacBookPro18,3"、"Macmini9,1" 等

local model = app.system.deviceModel()
app.log.info("设备型号: " .. model)

硬件标识（PII）

以下 API 返回可唯一识别设备的信息，属于个人身份信息。插件需要在 plugin.json 中声明 hardware_id 权限，首次使用时会弹窗请求用户授权。

app.system.serialNumber()

获取 Mac 序列号（since 1.3.0，需要 hardware_id 权限）。

返回值: string|nil, err - 如 "C02XXXXXXXXX"

-- plugin.json: "permissions": ["system", "hardware_id"]
local sn, err = app.system.serialNumber()
if sn then
    app.log.info("序列号: " .. sn)
end

app.system.hardwareUUID()

获取硬件 UUID（since 1.3.0，需要 hardware_id 权限）。

返回值: string|nil, err - 如 "00000000-0000-0000-0000-000000000000" 格式的 UUID

local uuid, err = app.system.hardwareUUID()

app.system.diskSerial(path?)

获取磁盘序列号（since 1.3.0，需要 hardware_id 权限）。

参数:

• path (string, 可选) - 磁盘路径（默认 “/“）

返回值: string|nil, err - 磁盘的 UUID 或设备路径标识

local sn, err = app.system.diskSerial("/")

开机启动（1.3.0）

管理 iRightMenu Pro 自身的开机启动状态。修改需要 login_item 权限，读取无需声明。

app.system.isLoginItem()

查询 iRightMenu Pro 是否已设为开机启动（since 1.3.0）。

返回值: boolean

if app.system.isLoginItem() then
    app.log.info("已开启开机启动")
end

app.system.setLoginItem(enable)

设置 iRightMenu Pro 的开机启动状态（since 1.3.0，需要 login_item 权限，首次调用会弹窗确认）。

参数:

• enable (boolean) - true 启用，false 禁用

返回值: boolean, err

-- plugin.json: "permissions": ["system", "login_item"]
local ok, err = app.system.setLoginItem(true)

语言和区域

app.system.locale()

获取系统区域设置。

返回值: string - 区域代码

local locale = app.system.locale()  -- "zh_CN"

app.system.language()

获取系统首选语言。

返回值: string - 语言代码

local lang = app.system.language()  -- "zh-Hans"

app.system.timezone()

获取时区。

返回值: string - 时区标识符

local tz = app.system.timezone()  -- "Asia/Shanghai"

其他

app.system.uptime()

获取系统运行时间。

返回值: number - 秒数

local uptime = app.system.uptime()
local hours = math.floor(uptime / 3600)
app.log.info("系统已运行 " .. hours .. " 小时")

app.system.uuid()

生成新的 UUID。

返回值: string - UUID 字符串

local id = app.system.uuid()  -- "A1B2C3D4-E5F6-..."

app.system.timestamp()

获取当前 Unix 时间戳。

返回值: number - 时间戳（秒，带小数部分）

local ts = app.system.timestamp()  -- 1701234567.123

目录路径

目录路径请使用 app.path 模块：

app.path.home()         -- "/Users/username"
app.path.temp()         -- "/var/folders/.../T"
app.path.desktop()      -- "/Users/username/Desktop"
app.path.documents()    -- "/Users/username/Documents"
app.path.downloads()    -- "/Users/username/Downloads"
app.path.applications() -- "/Applications"

事件监听

app.system.watch(event, callback)

监听系统级事件。

参数:

• event (string) - 事件名称:
  • "sleep" - 系统即将进入休眠时触发
  • "wake" - 系统从休眠唤醒时触发
  • "screenLocked" - 屏幕锁定时触发
  • "screenUnlocked" - 屏幕解锁时触发
  • "volumeMount" - 卷宗挂载时触发，回调参数: {type, path, name}
  • "volumeUnmount" - 卷宗卸载时触发，回调参数: {type, path, name}
• callback (function) - 回调函数。sleep/wake/screenLocked/screenUnlocked 无参数；volumeMount/volumeUnmount 接收:
  • type (string) - 事件类型
  • path (string) - 挂载路径（如 “/Volumes/MyDisk”）
  • name (string) - 卷宗名称

返回值: string, error - watcher 句柄 ID

app.system.watch("sleep", function()
    app.log.info("系统即将休眠")
end)

app.system.watch("wake", function()
    app.log.info("系统已唤醒")
end)

app.system.watch("volumeMount", function(e)
    app.notification.show("磁盘已挂载", e.name .. " (" .. e.path .. ")")
end)

app.system.watch("volumeUnmount", function(e)
    app.log.info("磁盘已卸载: " .. e.name)
end)

app.system.stopAllWatchers()

停止当前插件注册的所有系统事件监听器。

返回值: boolean

app.system.stopAllWatchers()

app.system.listWatchers()

列出当前插件已注册的系统事件监听器。

返回值: array<table> - 每项包含:

• id (string) - watcher 句柄 ID
• event (string) - 监听的事件名称

local watchers = app.system.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

示例

检查系统要求

function MyPlugin:checkRequirements()
    -- 检查 macOS 版本
    local version = app.system.osVersion()
    local major = tonumber(version:match("^(%d+)"))

    if major < 12 then
        app.dialog.alert({
            title = "不支持",
            message = "需要 macOS 12 或更高版本"
        })
        return false
    end

    -- 检查架构
    if app.system.arch() ~= "arm64" then
        app.log.warning("在 Intel Mac 上运行，性能可能下降")
    end

    -- 检查磁盘空间
    local disk = app.system.diskSpace("/")
    local freeGB = disk.available / 1024 / 1024 / 1024

    if freeGB < 1 then
        app.dialog.alert({
            title = "空间不足",
            message = "需要至少 1GB 可用空间"
        })
        return false
    end

    return true
end

生成系统报告

function MyPlugin:handleSystemInfo(context)
    local mem = app.system.memory()
    local disk = app.system.diskSpace("/")

    local info = {
        "系统信息报告",
        "================",
        "",
        "操作系统: " .. app.system.osName() .. " " .. app.system.osVersion(),
        "构建号: " .. app.system.osBuild(),
        "架构: " .. app.system.arch(),
        "主机名: " .. app.system.hostName(),
        "用户: " .. app.system.fullUserName() .. " (" .. app.system.userName() .. ")",
        "",
        "CPU 核心: " .. app.system.cpuCount(),
        "内存: " .. string.format("%.1f GB", mem.total / 1024^3),
        "可用内存: " .. string.format("%.1f GB", mem.available / 1024^3),
        "",
        "磁盘总量: " .. string.format("%.1f GB", disk.total / 1024^3),
        "磁盘可用: " .. string.format("%.1f GB", disk.available / 1024^3),
        "",
        "语言: " .. app.system.language(),
        "区域: " .. app.system.locale(),
        "时区: " .. app.system.timezone(),
        "",
        "运行时间: " .. string.format("%.1f 小时", app.system.uptime() / 3600),
        "",
        "生成时间: " .. os.date("%Y-%m-%d %H:%M:%S")
    }

    local report = table.concat(info, "\n")

    -- 保存报告
    local path = app.path.join(context.currentDirectory, "system_info.txt")
    app.file.write(path, report)

    app.finder.reveal(path)
end

根据系统配置调整行为

function MyPlugin:getOptimalThreadCount()
    local cores = app.system.cpuCount()

    -- 保留一些核心给系统
    local threads = math.max(1, cores - 2)

    -- 检查可用内存
    local mem = app.system.memory()
    local freeGB = mem.available / 1024 / 1024 / 1024

    -- 如果内存不足，减少线程数
    if freeGB < 2 then
        threads = math.min(threads, 2)
    end

    return threads
end