权限

插件必须在 manifest.json 中声明所需权限。Core 会强制执行权限检查 —— 调用未声明权限的 API 将会失败。

可用权限

通用

权限	说明
log	向应用日志写入内容
system:info	访问宿主系统硬件信息（操作系统、CPU、GPU、内存等） （3.0.0-dev.2 起支持）

控制器插件

权限	说明
serial:read	从串口读取数据
serial:write	向串口写入数据
hid:read	从 HID 设备读取数据
hid:write	向 HID 设备写入数据

灯效插件

权限	说明
screen:capture	捕获屏幕内容
audio:capture	访问音频 FFT 数据
media:album_art	访问媒体专辑封面

扩展插件

权限	说明
media:session	访问当前系统媒体会话的元数据、播放状态、进度时间线与封面 （3.0.0-dev.3 起支持）
system:process	订阅运行中的应用程序进程变化并查询当前进程列表。仅支持 Windows。（3.0.0-dev.3 起支持）
system:window-focus	订阅前台窗口焦点变化并查询当前聚焦窗口。仅支持 Windows。（3.0.0-dev.3 起支持）
network	允许所有网络访问（TCP 和 HTTP）（3.0.0-dev.3 起支持）
network:tcp	建立 TCP 连接
network:http	发起 HTTP/HTTPS 请求 （3.0.0-dev.3 起支持）
process	启动和管理外部进程
hardware:hid	直接打开并与 HID 设备通信 （3.0.0-dev.2 起支持）
native	通过 require() 加载原生 C 模块（.dll/.so），并可使用 native 清单块进行精细化库搜索控制 （3.0.0-dev.2 起支持；native 清单配置自 3.0.0-dev.3 起支持）

native-c 运行时

native 权限用于 Lua 插件加载原生 Lua 模块。language 为 "native-c" 的插件本身就是原生共享库，不需要仅为了加载自身而声明 native 权限。但它仍然必须声明所调用宿主能力所需的权限，例如 audio:capture、screen:capture、network:http、process 或 hardware:hid。

声明权限

在 manifest.json 中添加 permissions 数组：

{
  "permissions": ["log", "network:tcp", "process"]
}

安全模型

• Lua 插件运行在沙箱化的 Lua 5.4 环境中
• native-c 插件作为可信进程内原生代码运行；仅加载自身不需要 native 权限
• 通过宿主 API 暴露的文件系统访问限制在插件自身目录内
• 网络访问需要显式声明 network:tcp 权限
• 进程启动需要显式声明 process 权限
• 每个 Lua 插件运行在独立的 Lua 状态中 —— 插件之间无法访问彼此的数据
• 系统信息访问需要显式声明 system:info 权限；控制器插件和扩展插件均可用 （3.0.0-dev.2 起支持）
• 媒体会话访问需要显式声明 media:session 权限；仅扩展插件可用 （3.0.0-dev.3 起支持）
• 系统进程监控需要显式声明 system:process 权限；仅扩展插件可用。目前仅支持 Windows。（3.0.0-dev.3 起支持）
• 窗口焦点监控需要显式声明 system:window-focus 权限；仅扩展插件可用。目前仅支持 Windows。（3.0.0-dev.3 起支持）
• HID 访问需要显式声明 hardware:hid 权限；仅扩展插件可用 （3.0.0-dev.2 起支持）
• 原生 Lua 模块加载需要显式声明 native 权限，并使用不安全 Lua VM —— 请谨慎使用 （3.0.0-dev.2 起支持）
• 通过 native 清单块进行高级 DLL 搜索路径控制与预加载需要 3.0.0-dev.3 或更高版本 （参见 Manifest 参考 — 原生库配置）
• native-c 插件运行在 Core 进程内并拥有原生代码权限。审查、签名和分发时应按应用二进制同等标准处理。