插件形态

Saukko Core 通过插件自定义处理聊天平台的事件与消息，插件系统由 plugin 服务实现。

不稳定的 API

Saukko Core 的插件 API 尚处于开发阶段，可能会发生重大变化。

模块形态（主路径）

export const inject = []; // 声明所依赖的服务或插件
export const name = 'my-plugin';
export default function (context: Context) {}

{ name, default } 模块形态是插件的主路径：Daemon 的包加载（plugin.files 与 plugin.scopes）只接受该形态，插件包也应以该形态发布。

注意

Saukko Core 的插件仅支持 ESM 模块。如果你使用 CommonJS 写法，你需要将其转换为 ESM 写法。

其他形态

程序化安装（plugin 服务的 install 方法）另支持三种形态，内部会统一归一化为模块形态：

// 函数形态：函数名即插件名，inject 作为函数属性声明
pluginService.install(async function myPlugin(context) {});

// 类形态：类名即插件名，实例化即完成挂载
pluginService.install(class MyPlugin {
    constructor(context) {}
});

// 对象形态：提供 name 与 apply 方法
pluginService.install({ name: 'my-plugin', apply(context) {} });

名称解析规则：模块/对象形态取 name 属性，函数形态取函数名，类形态取类名。匿名函数、匿名类、缺少 name 的对象都无法解析出名称，安装时会抛出错误。

安装与启用

install 即执行主体，enable/disable 是纯开关：

• install：派生子作用域并执行插件主体（注册钩子、监听、share 服务都在此刻完成）。依赖未就绪时主体挂起，插件进入"等待依赖"状态，依赖补齐后自动执行。主体执行失败会清理子作用域且不留记录，重试即重新 install。
• enable：触发 onStart 钩子。依赖未就绪时不拒绝——标记为"期望启用"，依赖就绪后自动启动。
• disable：触发 onStop 钩子；子作用域不销毁，再次 enable 时钩子重新触发，主体不会重复执行。
• uninstall：终态销毁子作用域（onDispose），从插件表移除。

其他事项：

• Daemon 启动时会自动安装并启用配置中的所有插件；
• 运行中可通过 saukko plugin install / enable / disable / uninstall 动态管理，见 CLI 与 Daemon；
• 依赖判定与等待语义详见 依赖与诊断。

插件示例

export const inject = ['storage'];
export const name = 'my-plugin';

export default function (context: Context) {
  const storage = context.get('storage');

  context.on('message.private', (event) => {
    // 处理消息事件
  });

  context.lifecycle.onStop(async () => {
    // 禁用时清理，框架会等待完成
  });
}