diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 891d753..52aaf37 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -117,10 +117,19 @@ export const sidebar: DefaultTheme.Sidebar = { { text: "消息", link: "/server/api/message" }, { text: "最近会话", link: "/server/api/conversation" }, { text: "Webhook", link: "/server/api/webhook" }, - { text: "Datasource", link: "/server/api/datasource" }, + // { text: "Datasource", link: "/server/api/datasource" }, { text: "API调用时机说明", link: "/server/api/instructions" }, ], }, + { + text: "插件", + items: [ + { text: "说明", link: "/server/plugin/intro" }, + { text: "市场", link: "/server/plugin/market" }, + { text: "使用", link: "/server/plugin/use" }, + { text: "开发", link: "/server/plugin/dev" }, + ], + }, { text: "进阶", items: [ diff --git a/src/server/plugin/ai-demo.png b/src/server/plugin/ai-demo.png new file mode 100644 index 0000000..d17312a Binary files /dev/null and b/src/server/plugin/ai-demo.png differ diff --git a/src/server/plugin/bind.png b/src/server/plugin/bind.png new file mode 100644 index 0000000..1fda73a Binary files /dev/null and b/src/server/plugin/bind.png differ diff --git a/src/server/plugin/dev.md b/src/server/plugin/dev.md new file mode 100644 index 0000000..ae7e323 --- /dev/null +++ b/src/server/plugin/dev.md @@ -0,0 +1,129 @@ +# 插件开发 + +目前插件开发只支持Go语言 + +开发插件需要依赖`WuKongIM`的插件库 [Go PDK](https://github.com/WuKongIM/go-pdk)。 + +## 开发插件 + +以下内容的完整源码:https://github.com/WuKongIM/plugins/blob/main/ai-example/main.go + +### 定义插件结构体 + +```go +// 定义插件的配置结构体 +type Config struct { + Name string `json:"name" label:"AI名字"` // json为配置项名称,label为WuKongIM后台显示的配置项名称 +} + +// 插件结构体 +type AIExample struct { + Config Config // 插件的配置,名字必须为Config, 声明了以后,可以在WuKongIM后台配置,WuKongIM后台配置后会自动填充Config的数据,从而在函数里可以直接使用Config里的属性 +} + +// 创建一个插件对象 +func New() interface{} { + return &AIExample{} +} +``` + +### 定义插件函数 + +```go +// 收到消息 +func (a *AIExample) Receive(c *pdk.Context) { + // 获取发送消息内容 + text := a.getText(c) + + // 编码消息 + data, _ := json.Marshal(map[string]interface{}{ + "type": 1, + "content": fmt.Sprintf("我是%s,收到您的消息:%s", a.Config.Name, text), + }) + + // 回复消息 + c.Reply(data) +} +``` +其他函数见下方的函数说明 + + +### 启动插件 + +```go +func main () { + pdk.RunServer(New, "wk.plugin.ai-example", pdk.WithVersion("0.0.1"), pdk.WithPriority(1)) +} +``` + +## 调试插件 + +### 源码启动单机WuKongIM + +下载`WuKongIM`源码 https://github.com/WuKongIM/WuKongIM + +进入源码根目录,执行: + +```go +go run main.go --config exampleconfig/single.yaml +``` + +### 启动插件 + +进入插件源码根目录,执行 + +```go +go run main.go +``` +插件出现如下日志说明与`WuKongIM`建立连接成功 + +![图片](plugin-connect.png) + +### 绑定用户(全局插件不需要此步骤) + +在`WuKongIM后台 --> AI --> 添加AI` 即可实现绑定。 + +![图片](bind.png) + +给绑定的uid发送消息即可调试插件的`Receive`方法 + +## 函数说明 + +### Setup() + +插件启动时调用 + +### Route(c *pdk.Route) + +路由函数,插件可以定义自己的http请求,比如 + +```go +func (s *Hello) Route(c *pdk.Route) { + // http://127.0.0.1:5001/plugins/[插件编号]/hello + c.GET("/hello", s.sayHello) +} +``` + +通过`http://127.0.0.1:5001/plugins/[插件编号]/hello` 就可以访问到插件提供的http服务 + +源码参考:https://github.com/WuKongIM/plugins/blob/main/hello/hello.go + +### Receive(c *pdk.Context) + +收到给插件发送的消息时,`WuKongIM`会调用插件此函数 (此函数只作用于绑定的用户) + +### Send(c *pdk.Context) + +消息发送前`WuKongIM`会调用插件此函数,可以在此函数里改变消息内容 (全局函数) + +### PersistAfter(c *pdk.Context) + +消息存储后在扩散前,`WuKongIM`会调用插件的此函数,可以在此函数内对消息做数据分析,比如实现消息搜索功能(全局函数) + +### ConfigUpdate() + + 配置发生变化时调用 + + ### Stop() + +插件停止时调用 diff --git a/src/server/plugin/intro.md b/src/server/plugin/intro.md new file mode 100644 index 0000000..6dec4b1 --- /dev/null +++ b/src/server/plugin/intro.md @@ -0,0 +1,22 @@ +# 说明 + +## 什么是插件? + +`WuKongIM`定义了一套规则,第三方可以实现这套规则,用于扩展或增强现有`WuKongIM`的消息处理逻辑。 + +比如可以通过插件实现:`敏感词过滤`,`消息搜索`,`AI`等功能 + +## 用户插件 + +用户插件可以收到插件绑定用户的所有消息,用户插件安装后需要绑定用户才能生效。 + +比如实现与大模型聊天,需要插件绑定指定用户的uid,然后给此用户发消息即给大模型发消息。 + +实现`Receive`函数的为用户插件 + + +## 全局插件 + +全局插件可以收到系统内的所有消息,全局插件安装后全局都会生效。 + +比如:敏感词过滤插件,消息搜索插件,都是全局插件,会监听每条发送消息。 \ No newline at end of file diff --git a/src/server/plugin/market.md b/src/server/plugin/market.md new file mode 100644 index 0000000..23aa69f --- /dev/null +++ b/src/server/plugin/market.md @@ -0,0 +1,12 @@ + +# 插件市场 + +插件列表地址: + +[Github](https://github.com/WuKongIM/plugins/releases/latest) + +[Gitee](https://gitee.com/WuKongDev/plugins/releases/latest) + +`插件格式:[插件名字]-[系统]-[CPU架构].wkp` + +`常见CPU架构为amd64` \ No newline at end of file diff --git a/src/server/plugin/plugin-config.png b/src/server/plugin/plugin-config.png new file mode 100644 index 0000000..dfe05c4 Binary files /dev/null and b/src/server/plugin/plugin-config.png differ diff --git a/src/server/plugin/plugin-config2.png b/src/server/plugin/plugin-config2.png new file mode 100644 index 0000000..b8ca6ed Binary files /dev/null and b/src/server/plugin/plugin-config2.png differ diff --git a/src/server/plugin/plugin-connect.png b/src/server/plugin/plugin-connect.png new file mode 100644 index 0000000..a17084e Binary files /dev/null and b/src/server/plugin/plugin-connect.png differ diff --git a/src/server/plugin/plugin-dir.png b/src/server/plugin/plugin-dir.png new file mode 100644 index 0000000..fa0a8ba Binary files /dev/null and b/src/server/plugin/plugin-dir.png differ diff --git a/src/server/plugin/uinstall.png b/src/server/plugin/uinstall.png new file mode 100644 index 0000000..89d32fd Binary files /dev/null and b/src/server/plugin/uinstall.png differ diff --git a/src/server/plugin/use.md b/src/server/plugin/use.md new file mode 100644 index 0000000..9cd0280 --- /dev/null +++ b/src/server/plugin/use.md @@ -0,0 +1,51 @@ + +# 插件使用 + +`插件在WuKongIM 2.1.3或以上版本才支持` + +## 安装插件 + +**下载插件** + +从插件市场下载:[链接](/server/plugin/market) + +**安装插件** + +复制插件到`WuKongIM`数据目录下的`plugins`目录下即可完成安装 + +![图片](plugin-dir.png) + +**配置插件** + +如果插件需要配置,在`WuKongIM`的管理后台插件列表里的操作将会显示配置按钮,点击按钮即可配置。 + +`配置内容根据插件不同而不同` + +![图片](plugin-config.png) + +![图片](plugin-config2.png) + + +## 调用插件 + +如果是全局插件,当系统中有消息发送时,插件就会被调用。 + +如果是AI插件,需要将AI插件绑定到用户UID上,所以主要讲AI插件怎么绑定用户UID。 + +在`WuKongIM后台 --> AI --> 添加AI` 即可实现绑定。 + +![图片](bind.png) + +插件绑定后,给此用户发消息也会将消息发送给插件,插件可以做出回应。 + +比如我们绑定,AI案例插件`wk.plugin.ai-example`到用户`robot`,给robot发消息,AI插件即可做出回应。 + +![图片](ai-demo.png) + + + +## 卸载插件 + +`WuKongIM --> 插件 --> 卸载` + +![图片](uinstall.png) \ No newline at end of file