插件开发概览

Skydimo 的插件系统允许你扩展自定义硬件驱动、灯光效果和后台服务。当前生产可用运行时为 Lua 5.4 与 native-c。

版本说明

本页所述工作流在 3.0.0-dev.4 及之后版本可用。

插件类型

类型	目录命名	用途
Controller（控制器）	`controller.<id>/`	硬件设备驱动（串口、HID、mDNS）
Effect（灯效）	`effect.<id>/`	视觉灯光图案与动画
Extension（扩展）	`extension.<id>/`	后台服务、协议网桥、自定义 UI

运行时选择

运行时	`language`	适合场景
Lua	`"lua"`	快速迭代、小型集成、设备协议胶水
Native C ABI	`"native-c"`	基于公开 C、Rust、C#、C++、Zig 等 C ABI SDK 包构建的高性能灯效/控制器/扩展

native-c 插件是加载到 Core 进程内的共享库。需要原生性能或公开 SDK 语言包时，请参阅 Native-C 插件运行时。

插件源码包结构

源码包建议保持标准目录结构：

<type>.<id>/
├── manifest.json
├── main.lua / init.lua      # Lua 插件
├── native/<platform>/       # native-c 共享库
├── lib/            # 可选
├── data/           # 可选初始化数据
└── page/           # 仅 extension 可选

开发阶段 native-c 源码工程可以与源码包放在一起，但可安装/分发的插件包必须包含 entry 指向的已编译共享库。

插件包组（Pack）

一个包目录也可以是 "type": "pack" 的包组 manifest，并通过 plugins 列表引用子插件目录。包组自身不加载运行时，只用于组织多个子插件：

{
  "id": "my_effect_pack",
  "version": "1.0.0",
  "name": "My Effect Pack",
  "publisher": "Example",
  "type": "pack",
  "plugins": [
    "Rainbow",
    { "path": "Audio/Bars" }
  ]
}

包组条目必须指向包组目录内的子目录。不支持嵌套包组。

运行时存储（由 Core 管理）

插件运行时目录与数据目录由 Core 管理，可通过插件管理功能直接打开。

建议将运行时路径视为内部实现，不要依赖其命名规则，也不要在插件逻辑中手工拼接目录。

对于扩展插件，请优先使用宿主 API（例如 ext.data_dir）访问数据目录。

高层加载流程

Core 解析插件来源（应用打包 + 用户安装）
Core 读取 manifest 与插件元数据
Core 按插件类型初始化运行时
UI 通过 get_plugins 获取插件元数据
刷新/删除/重置/安装操作后触发运行时刷新

安装来源（UI / API）

每个插件会带有安装来源：

来源	含义
`bundled`	应用打包插件
`import`	来自导入队列
`import-dev`	来自开发导入队列（保留源码）
`package`	包导入安装流程
`manual`	手动引入 / 兼容来源

该信息可用于排障、迁移和运维决策（例如应“删除”还是“重置”）。

“重置”含义

若插件存在打包默认版本，重置会移除用户覆盖并回到默认版本。
可选择是否同时清理插件数据。
打包插件通常走重置流程，而不是直接删除。

“删除”含义

删除当前已安装插件副本。
可选择是否同时删除插件数据。
对于 import-dev 来源，删除安装副本并不会删除开发源码包。

下一步

快速入门 —— 创建并迭代你的第一个插件
插件管理 —— 导入、刷新、删除、重置与排障
Manifest 参考 —— 完整的 manifest.json 规格说明
控制器插件指南 —— 构建硬件驱动
灯效插件指南 —— 创建灯光效果
扩展插件指南 —— 构建集成方案和后台服务
Native-C 插件运行时
Native-C API 参考

兼容说明

旧文档中基于 plugins/<type>.<id>/ 直接运维的描述可用于历史理解，但在 3.0.0-dev.4 之后不再是推荐生产工作流。

插件类型​

运行时选择​

推荐工作流（3.0.0-dev.4+）​

插件源码包结构​

插件包组（Pack）​

运行时存储（由 Core 管理）​

高层加载流程​

安装来源（UI / API）​

“重置”含义​

“删除”含义​

下一步​

兼容说明​