插件类型

PyriteSDK 提供三种插件基类，每种对应不同的运行模式和可用 API。

类型对比

激活与常驻

插件不是默认启动的。是否启动由清单中的激活事件（activationEvents）决定：

• 声明 onStartup 的 UiPlugin / ServicePlugin 会在 IDE 启动时激活。
• 声明 onView:<viewId> / onCommand:<commandId> / onLanguage:<languageId> 的插件，在对应事件首次发生时按需激活，之后保持 active。
• DataPlugin 无条件在 IDE 启动时自动运行（原因 data-startup），贡献完成后立即退出，不占用常驻进程。

三种类型都会经历同样的激活流程：创建会话 → 协议握手 → on_start() → 进入 active。停用时 IDE 发送 dispose 钩子并回收会话。完整的时序与状态机见 生命周期。

对 UiPlugin 来说，常驻指进入 active 后持续处理视图事件，而非每次打开视图都创建会话。视图隐藏或关闭不会停用插件，只有禁用插件、关闭 IDE 等显式停用操作才触发 on_dispose()。

公共 API（BasePlugin）

三种插件共享 BasePlugin 提供的 API：

• self.path — 插件目录路径
• self.settings — IDE 设置读写
• self.message — 消息通知
• self.clipboard — 剪贴板写入
• self.dialog — 文件夹选择对话框
• self.resources — 只读资源（assets/）
• self.events — 事件订阅
• self.commands — 命令注册与分发
• self.configuration — 清单声明的配置读写
• self.context — 当前插件会话上下文（ID、目录、能力集）

UiPlugin

UiPlugin 用于开发带界面的插件。界面由 IDE 渲染器驱动：你在 plugin.toml 中声明视图贡献（指定 renderer），然后在代码中通过 self.views 创建视图模型并推送数据。

UiPlugin 可用的 API：

• self.file — 本地文件读写
• self.board — 设备文件读写
• self.editor — 编辑器内容和光标操作
• self.persistence — 键值存储
• self.serial — 串口通信
• self.documents — 编辑器文档查询与订阅
• self.runtime — 设备运行时检查
• self.env — 运行环境信息
• self.tabs — 创建视图标签页
• self.views — 原生视图模型

ServicePlugin

ServicePlugin 用于执行后台任务，不渲染 UI。适合文件监听、设备数据采集、定时同步等场景。

ServicePlugin 可用的 API：file、board、persistence、serial、documents、runtime、env，以及公共 API。

DataPlugin

DataPlugin 用于向 IDE 贡献数据（主题、语言包、类型存根）。调用 start() 后执行 on_contribute()，完成贡献后自动退出。

DataPlugin 可用的 API：theme、i18n、stubs，以及公共 API。

选择建议

• 需要渲染界面 → UiPlugin（使用 self.views / self.tabs）
• 需要在后台持续执行任务，且无需界面 → ServicePlugin（文件监听、数据采集、定时同步）
• 仅贡献主题、语言包或类型存根 → DataPlugin

三个问题辅助判断：

1. 要不要给用户看界面？ 要 → UiPlugin；不要 → 看下一个问题。
2. 要不要持续运行（监听、轮询、订阅）？ 要 → ServicePlugin；不要 → 看下一个问题。
3. 是否只做一次性数据贡献（主题 / i18n / stubs）？ 是 → DataPlugin。

如果插件既需要界面又需要在后台做设备监听，以 UiPlugin 为主，把后台逻辑放进 on_start() 启动的异步任务即可——三种插件共享同一套 file / board / serial / runtime API（DataPlugin 除外，它只有 theme / i18n / stubs）。