# wechat-bot-plugins

**Repository Path**: LeftJson/wechat-bot-plugins

## Basic Information

- **Project Name**: wechat-bot-plugins
- **Description**: 微信机器人插件合集
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: 2.2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 26
- **Created**: 2024-11-01
- **Last Updated**: 2024-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wechat-bot-plugins

## 介绍
微信机器人插件合集

## 软件架构

此模块以`wechat-bot-plugin-base`作为父模块，该模块依赖`wechat-bot-core`核心模块，同时依赖`maven-shade`插件进行打包操作。

## 插件说明

### AI插件

`wechat-bot-plugin-ai`模块，监听文本消息事件，基于ai接口对接大模型，实现对微信消息的回复及聊天记录总结等功能。

### 今日新闻插件

`wechat-bot-plugin-daily_news`模块，监听文本消息事件，基于第三方api，使用hutool-http下载每日新闻或每日吃瓜图片并进行回复。

**关键词**： `今日新闻`、`今日吃瓜`

### 表情包插件

`wechat-bot-plugin-emoticon`模块，监听文本消息事件，通过消息中存在的关键词触发，回复表情包。
该插件包括命令执行器，可通过命令动态添加、删除表情包及关键词，亦可手动管理配置文件。

**命令**：

- `/emoticon list`
- `/emoticon add <name> <emoticon_md5> <kerwords>`
- `/emoticon remove <name>`
- `/emoticon black <keywords>`

### 邀请入群插件

`wechat-bot-plugin-invite`模块通过监听好友请求事件或私聊消息事件，通过关键词触发，添加机器人好友时的验证信息或私聊机器人相应关键词，自动邀请好友进群。
通过配置文件配置关键词、对应群名称。

```yaml
keyword: group_name
# 例如通过`wechat-bot`关键词邀请好友加入`协议版机器人催更群`
wechat-bot: 协议版机器人催更群
```

### kfc插件

`wechat-bot-plugin-kfc`模块，监听消息事件，通过关键词触发，回复kfc文案。插件优先从api获取文案，失败后会从本地json文件中获取。

**关键词**： `kfc`、`KFC`、`肯德基`、`疯狂星期四`、`v我50`

### 内存插件

`wechat-bot-plugin-memory`模块，监听消息事件，通过命令执行器，查看bot程序当前占用内存及清理内存。

**命令**：

- `/memory [-s|--show]` 查看内存使用情况
- `/memory [-c|--clear]` 清理内存

### 复读机插件

`wechat-bot-plugin-reread`模块，~~人类的本质就是复读机~~。`RereadListener`监听群组文本消息事件，
如果同一个群组中的文本消息与上次的相同，那么进行复读，发送同一条消息给群组。

### 定时任务插件

`wechat-bot-plugin-schedule`模块，通过命令执行器或手动配置，添加、删除定时任务。

**命令**：

- `/scheduler list` 查看定时任务列表
- `scheduler add [-n|--name]=<name> [-c|--cron]=<cron> [-k|--kerword]=<keyword> [-t|--targets]=<targets...>`
  添加定时任务，name为任务名称，cron为cron表达式(因命令行解析原因，空格需要使用[-+|.]代替)
  ，keyword为触发关键词，targets为目标群组名称(使用空格分隔)
- `/scheduler remove <name>` 删除定时任务
- `/scheduler edit [-n|--name]=<name> [-c|--cron]=<cron> [-k|--kerword]=<keyword> [-t|--targets]=<targets...>`
  编辑定时任务，参考add命令

**配置文件示例**：

```yaml
daily-news:
  name: 今日新闻
  cron: 30 8 * * *
  keyword: 每日新闻
  targets:
    - 协议版机器人催更群
```

### 色图插件

`wechat-bot-plugin-setu`模块，监听文本消息事件，通过关键词触发，回复相应图片。
发送图片频率太高会被微信限制，请不要频繁使用。（考虑后续添加间隔限制）

**关键词**：

- `来点黑丝` 回复黑丝图片
- `来点白丝` 回复白丝图片
- `看看腿` 随机回复黑丝或白丝图片
- `plmm`、`漂亮妹妹`、`来点美女` 回复美女图片或视频
- `来点帅哥` 回复帅哥图片
- `来点**` 通过360图片搜索**，随机获取其中一张回复

### 群消息统计分析插件

`wechat-bot-plugin-statistics`模块，监听所有群组的消息事件，统计群组内消息发送情况，并根据关键词生成排行榜、词云、AI分析报告（依赖于ai插件）。
该插件依赖`hutool-db:5.8.29`进行数据库操作(6.0去除了nosql的操作)，依赖`sqlite-jdbc`连接sqlite数据库（存储聊天记录），
依赖`jedis`连接操作redis（统计发言数据、分词后的词频等），依赖`hanlp`进行分词，依赖`kumo-core`进行词云图片生成。

1. 每个群组的消息数量存放于redis字符串中，key为`statistics:total:count::{groupName}`，value为群组消息数量。
2. 每个群组内每位成员发言总数存放于redis哈希表中，key为`statistics:everone:count::{groupName}`，其中key为成员名称，value为成员发言总数。
3. 每个群组内每位成员每天发言总数存放于redis哈希表中，key为`statistics:everyday:count::{groupName}`
   ，其中key为日期，value为成员当天发言总数。
4. 每个群组内每位成员今日发言数量存放于redis哈希表中，key为`statistics:today:count::{groupName}:{date}`
   ，其中key为成员名称，value为成员今日发言总数，此哈希表保留31天。
5. 群组内消息类型统计的key为`statistics:analyze::{messageType}`，value为消息类型对应的数量。
6. 群组消息分词词频统计数据存放于redis排序集合中，key为`tokenizer::{groupName}:{date}`，value为关键词，score为词频。

**注**：

1. 分词词频统计仅统计词性为"n"、"v"、"a"、"g"，其他词性不纳入统计，且分词后关键词长度大于1才纳入统计。
2. 分词统计及词云生成需要在配置文件中配置启用的群组才会生效，未启用时不会进行分词，统计数据没有词云
3. AI分析报告依赖`ai`插件，需要确保ai插件可以正常使用，否则将不会生成AI分析报告。
4. AI分析报告需要在配置文件中配置启用的群组才会生效，未启用时不会生成AI分析报告。
5. 只有今日排行会生成AI分析报告。

**关键词**: `今日排行`、`昨日排行`、`本周排行`、`本月排行`、`历史排行`

**命令**：

- `/statistics|stat <groupName> [-a|--add]=<members>` 为群组添加可以查看排行的成员，支持添加多个成员，多个成员之间使用空格分隔。
- `/statistics|stat <groupName> [-r|--remove]=<members>` 为群组移除可以查看排行的成员，支持移除多个成员，多个成员之间使用空格分隔。

**配置文件示例**：

```yaml
wordcloud: # 启用词频统计及词云生成的群
  - 机器人测试群
ai-analyze: # 启用AI分析报告的群
  - 机器人测试群
```

### 群成员发言欢迎词插件

`wechat-bot-plugin-tips`模块，监听群组文本消息事件，当发送消息的成员配置了欢迎词，则发送欢迎词。

**命令**：

- `/tips add [-m|--member]=<member> [-t|--tip]=<tip>` 为成员添加欢迎词，member为成员名称，tip为欢迎词。
- `/tips edit [-m|--member]=<member> [-t|--tip]=<tip>` 编辑成员欢迎词，member为成员名称，tip为欢迎词。
- `/tips del [-m|--member]=<member>` 移除成员欢迎词，member为成员名称。

**配置文件示例**：

```yaml
tips::timeout: 10   # 超时时间，单位分钟，当成员发言间隔大于该值时，才发送成员欢迎词
member_nick_name: tips # 成员昵称及欢迎词
```

## 常见问题

#### 如何使用？

将打包好的jar文件拷贝到`plugins`目录下，重启bot或向bot发送指令`/pm load <plugin-name>`（前提是已经加载了`PluginManager`
插件）即可。

#### 如何管理插件？

确保你已经加载了`PluginManager`插件，该插件提供了插件管理的相关命令：

- `/pm list` 查看已加载的插件
- `/pm help` 查看插件帮助信息
- `/pm load <plugin-name>...` 加载插件
- `/pm unload <plugin-name>...` 卸载插件
- `/pm reload <plugin-name>...` 重新加载插件
- `/pm info <plugin-name>...` 查看插件信息
- `/pm enable <plugin-name>...` 启用插件，如果在群组中执行该命令，则是为该群组启用插件，否则为全局启用插件；
- `/pm disable <plugin-name>...` 禁用插件，如果在群组中执行该命令，则是为该群组禁用插件，否则为全局禁用插件；

#### 插件的调用权限如何设置？

1. 对于命令执行插件，默认bot owner拥有执行权限，其他用户无权限执行；owner可用过`/cm <command> [-a|--add] <user>`
   命令添加指定命令可执行的用户。
2. 对于插件监听器，则需要自行在`EventListener`类的`support`方法或者`onEvent`方法中添加权限判断。

#### 如何开发插件？

1. frok本仓库或直接拉取本仓库后，创建新的插件模块进行开发，本仓库的`pom.xml`中已配置了插件依赖，无需手动添加依赖；
2. 自行创建插件项目或模块，`pom.xml`中以`x.ovo.wechat.bot:wechat-bot-plugin-base`作为父模块，`wechat-bot-plugin-base`
   中引入了核心依赖并配置了打包方式；
3. 自行船舰插件项目或模块，`pom.xml`中引入`x.ovo.wechat.bot:wechat-bot-core`，并配置`maven shade`打包插件；

插件中至少需要包含以下内容：

1. 继承`Plugin`类，实现`onLoad`、`getEventListener`、`getCommandExcutor`方法，`onLoad`方法为插件加载时调用，一般用于向
   `plugin/{plugin-name}`目录下创建配置文件，
   `getEventListener`方法返回事件监听器（可返回null），`getCommandExcutor`方法返回命令执行器（可返回null）；
2. `resources`中创建`plugin.yml`文件，该文件为插件配置文件，插件加载时需要获取插件jar包中的该文件，必不可少：

```yaml
name: plugin-manager      # 插件名称
version: 2.0.0            # 插件版本
priority: 10              # 优先级，值越小优先级越高越先执行，默认为10
main: x.ovo.wechat.bot.plugin.PmPlugin    # 插件类
description: 插件管理器，用于插件管理，启用、禁用、加载、下载、重载插件  # 插件描述
authors: # 插件作者
  - Ooops
```

`Plugin`中的`getEventListener`方法返回一个事件监听器，该监听器需要继承`EventListener<E extends Event<S>, S>`并实现
`boolean support(@NonNull E event, S source)`方法和`boolean onEvent(@NonNull E event, S source)`。
泛型`E`为事件类型，`S`为事件源类型，事件监听器用于监听事件，当监听到事件时，会调用`support`方法判断是否支持该事件，如果支持，则调用
`onEvent`方法处理事件。

`onEvent`方法需要返回一个boolean值，如果返回true，则表示事件监听器监听到事件并处理成功，否则表示事件处理失败。同时可自行选择是否需要重写
`boolean executeNext()`方法，
如果`onEvent`返回`true`且`executeNext`返回`false`，则表示此监听器已正常处理某事件，不再执行后续的事件监听器，否则会继续执行后续监听器。

`getCommandExcutor`方法返回一个命令执行器，该执行器需要继承`CommandExecutor`。
`CommandExecutor`中没有方法需要强制你去实现，命令行解析采用picocli，可参考[**官方文档**](https://picocli.info/)进行开发。

`CommandExecutor`中包含两个方法，你可以根据自己需要进行重写：

1. `String noPermissionTip()` 当发送命令的联系人没有执行权限时，返回的提示语，默认为“你没有权限执行此命令，请不要调皮”；
2. `boolean hasPermission(String user)` 权限检查，根据发送命令的用户昵称判断该用户是否具有权限执行此命令。
   默认逻辑为bot所有者和指定用户具有权限（可通过`wecaht-bot-plugin-cm`插件提供的`/cm <command> [-a|--add] <users>...`
   命令添加或自行修改配置文件
   `command_permission.json`）。

在[**bot仓库**](https://gitee.com/ilooli/wechat-bot)中的`wechat-bot-plugin`模块下，基础插件`wechat-bot-plugin-cm`和
`wechat-bot-plugin-pm`中的命令执行器采用了两种不同的实现形式，你可以参考进行开发。

#### 配置文件映射为bean异常

因为获取配置文件的`getConfig`方法声明于`Plugin`类，该类位于`wechat-bot-core`
模块中，bot启动时由“app”类加载器加载该类，而配置类位于插件jar中，由插件对应的ClassLoader加载。
yaml配置文件在解析时会先解析为Java基础类或Map、List等类型，而在进行类型转换时，由于跨类加载器，导致出现
`ClassDefinerNotFoundException`异常。本人能力有限，未能解决此问题，如有解决方案，欢迎提交PR。
因此在插件中使用配置文件时，不能自定义配置类，只能通过`plugin.getConfig()`方法获取`Map<String, Object>`类型对象后，再从map中取值。

## 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request