概述
WuKongIM 定义了一套插件规则,第三方开发者可以实现这套规则来扩展或增强现有 WuKongIM 的消息处理逻辑。通过插件可以实现敏感词过滤、消息搜索、AI 聊天等功能。插件功能在 WuKongIM 2.1.3 或以上版本才支持
插件类型
用户插件
用户插件可以收到插件绑定用户的所有消息,安装后需要绑定用户才能生效。 特点:- 只处理绑定用户的消息
- 适用于 AI 聊天、个人助手等场景
- 实现
Receive函数
- 与大模型聊天:绑定指定用户 UID,给此用户发消息即给大模型发消息
- 个人助手:为特定用户提供定制化服务
全局插件
全局插件可以收到系统内的所有消息,安装后全局都会生效。 特点:- 监听系统所有消息
- 无需绑定用户
- 适用于系统级功能
- 敏感词过滤:监听每条发送消息进行过滤
- 消息搜索:对所有消息建立搜索索引
- 数据分析:统计和分析消息数据
开发环境搭建
前置要求
- Go 语言环境(目前插件开发只支持 Go 语言)
- WuKongIM 源码或运行实例
- Go PDK 插件开发库
环境准备
1. 下载 WuKongIM 源码插件开发
基础结构
以下是一个完整的插件开发示例:配置说明
Config 结构体:- 名字必须为
Config - 声明后可在 WuKongIM 后台配置
- 使用
json标签定义配置项名称 - 使用
label标签定义后台显示名称
- 第一个参数:插件构造函数
- 第二个参数:插件唯一标识符
WithVersion:插件版本号WithPriority:插件优先级
插件生命周期
核心函数
Setup()
Setup()
调用时机:插件启动时调用用途:初始化插件资源、建立数据库连接等
Receive(c *pdk.Context)
Receive(c *pdk.Context)
调用时机:收到给插件发送的消息时调用作用范围:只作用于绑定的用户用途:处理用户消息,实现 AI 对话等功能
Send(c *pdk.Context)
Send(c *pdk.Context)
调用时机:消息发送前调用作用范围:全局函数用途:修改消息内容、敏感词过滤等
PersistAfter(c *pdk.Context)
PersistAfter(c *pdk.Context)
调用时机:消息存储后在扩散前调用作用范围:全局函数用途:数据分析、消息搜索索引建立等
Route(c *pdk.Route)
Route(c *pdk.Route)
调用时机:插件启动时注册路由用途:定义插件的 HTTP 接口
ConfigUpdate()
ConfigUpdate()
调用时机:配置发生变化时调用用途:响应配置更新,重新加载配置等
Stop()
Stop()
调用时机:插件停止时调用用途:清理资源、关闭连接等
调试和测试
本地调试
1. 启动 WuKongIM
用户插件测试
1. 绑定用户 在 WuKongIM 后台 → AI → 添加 AI,将插件绑定到指定用户:
Receive 方法:

全局插件测试
全局插件无需绑定用户,当系统中有消息发送时,插件就会被调用。开发示例
AI 聊天插件
插件安装和使用
安装插件
1. 从插件市场下载 插件格式:[插件名字]-[系统]-[CPU架构].wkp
2. 安装到 WuKongIM
将插件复制到 WuKongIM 数据目录下的 plugins 目录:

配置插件
如果插件需要配置,在 WuKongIM 管理后台的插件列表中点击配置按钮:

guest 用户没有权限配置插件,需要管理员权限
卸载插件
在 WuKongIM 后台 → 插件 → 卸载:
打包和部署
构建插件
打包为 .wkp 文件
部署到生产环境
- 将
.wkp文件上传到服务器 - 复制到 WuKongIM 的
plugins目录 - 重启 WuKongIM 或在后台启用插件
- 在管理后台进行配置
最佳实践
开发建议
- 错误处理:妥善处理各种异常情况
- 性能优化:避免阻塞操作,使用异步处理
- 资源管理:及时释放资源,避免内存泄漏
- 日志记录:添加适当的日志便于调试
- 配置验证:验证配置参数的有效性
安全考虑
- 输入验证:对所有输入进行严格验证
- 权限控制:确保插件只访问必要的资源
- 敏感信息:妥善保护 API 密钥等敏感配置
- 网络安全:使用 HTTPS 进行外部 API 调用
性能优化
- 缓存机制:对频繁访问的数据进行缓存
- 批量处理:合并多个操作减少开销
- 异步处理:使用 goroutine 处理耗时操作
- 连接池:复用数据库和网络连接

