# wise-robot **Repository Path**: blps/wise-robot ## Basic Information - **Project Name**: wise-robot - **Description**: 一个基于 Spring Boot 的 QQ/CoolQ wechat 微信机器人系统，支持多平台消息处理与业务功能扩展。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-18 - **Last Updated**: 2026-03-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # WiseRobot 智能机器人系统 一个基于 Spring Boot 的 QQ/CoolQ 机器人系统，支持多平台消息处理与业务功能扩展。 ## 技术栈 - **Spring Boot 3.4.1** - 核心框架 - **Spring Web** - Web 服务 - **Spring WebSocket** - WebSocket 通信 - **Jackson** - JSON 处理 - **Lombok** - 代码简化 ## 项目结构 ``` src/main/java/com/eul/web/ ├── SpringWebfluxApplication.java # 启动类 ├── Global.java # 全局变量 ├── bot/ # 机器人插件 │ ├── entity/ # 示例实体 │ └── plugin/ # 插件实现 │ ├── example/ # 示例插件 │ ├── export/ # 导出插件 │ ├── file/ # 文件处理插件 │ ├── prefix/ # 前缀插件 │ └── status/ # 状态插件 ├── config/ # 配置类 │ └── RestTemplateConfig.java # HTTP 客户端配置 ├── controller/ # 控制器 │ ├── IndexController.java # 首页控制器 │ └── MessageController.java # 消息接收 ├── cq/ # CoolQ 机器人核心 │ ├── entity/ # 实体类 │ │ ├── CQFile.java │ │ ├── CQGroupAnonymous.java │ │ ├── CQGroupUser.java │ │ ├── CQStatus.java │ │ └── CQUser.java │ ├── event/ # 事件定义 │ │ ├── message/ # 消息事件 │ │ ├── meta/ # 元事件 │ │ ├── notice/ # 通知事件 │ │ └── request/ # 请求事件 │ ├── retdata/ # API 返回数据 │ ├── robot/ # 机器人核心 │ │ ├── CoolQ.java # CoolQ 核心类 │ │ ├── EventHandler.java # 事件处理器 │ │ ├── ApiEnum.java # API 枚举 │ │ └── ApiSender.java # API 发送器 │ └── websocket/ # WebSocket 处理 ├── domain/ # 领域模型 │ ├── Message.java # 消息实体 │ └── tire/ # 敏感词匹配树 ├── enums/ # 枚举类 │ ├── ClientTypeEnum.java # 客户端类型 │ └── EventMessageTypeEnum.java # 消息事件类型 ├── factory/ # 工厂模式 │ ├── MessageSender.java # 消息发送接口 │ ├── MessageSenderFactory.java # 发送器工厂 │ ├── QQMessageSender.java # QQ 消息发送 │ ├── UnifiedMessageService.java # 统一消息服务 │ └── WeChatMessageSender.java # 微信消息发送 ├── plugin/ # 业务插件系统 │ ├── BusinessPluginRegistry.java # 业务插件注册 │ ├── Plugin.java # 插件注解 │ ├── PluginRegistry.java # 插件注册中心 │ └── PluginStrategy.java # 插件策略接口 └── service/ # 业务服务 ├── WeChatService.java # 微信服务接口 ├── WechatMsgService.java # 消息服务接口 └── impl/ # 服务实现 ├── WeChatServiceImpl.java └── WechatMsgServiceImpl.java ``` ## 快速开始 ### 环境要求 - JDK 17+ - Maven 3.6+ ### 配置说明 在 `application.yml` 中配置： ```yaml server: port: 8080 ``` ### 启动项目 ```bash mvn spring-boot:run ``` ## 核心功能 ### 1. 消息接收 通过 `MessageController` 接收外部消息： ```java @PostMapping(value = "msg") public void msg(@RequestBody Message message) { wechatMessageService.process(message); } ``` ### 2. 微信服务 `WeChatService` 提供微信消息发送能力： ```java public interface WeChatService { void sendMessage(Integer msgType, String weChatId, String msg); void sendFile(Integer msgType, String weChatId, String msg); void chatRoomSendImage(Integer msgType, String weChatId, String imagePath); String getSelfWxId(); boolean checkWxLoginStatus(); } ``` ### 3. 消息发送 统一消息发送服务，支持微信和 QQ： ```java @Service public class UnifiedMessageService { public void sendMessage(ClientTypeEnum clientType, String receiverId, String content); public void sendFile(ClientTypeEnum clientType, String receiverId, EventMessageTypeEnum typeEnum, String filePath); } ``` ### 4. CoolQ 机器人 `CoolQ` 类提供 QQ 机器人 API： ```java // 发送私聊消息 robot.sendPrivateMsg(userId, message, false); // 发送群消息 robot.sendGroupMsg(groupId, message, false); // 获取群列表 robot.getGroupList(); // 获取登录信息 robot.getLoginInfo(); ``` ### 5. 敏感词过滤 系统内置基于 Trie 树的敏感词匹配功能： ```java Trie trie = new Trie(); trie.addKeywords(Set.of("敏感词1", "敏感词2")); Emits emits = trie.findAll(text); ``` ## 插件系统 ### CQ 插件 系统支持 CQ 风格的插件，继承 `CQPlugin` 类： ```java public class MyPlugin extends CQPlugin { @Override public int onPrivateMessage(CoolQ cq, CQPrivateMessageEvent event) { // 处理私聊消息 return MESSAGE_IGNORE; } @Override public int onGroupMessage(CoolQ cq, CQGroupMessageEvent event) { // 处理群消息 return MESSAGE_IGNORE; } } ``` ### 插件列表 | 插件 | 说明 | |------|------| | ExamplePlugin | 示例插件 | | ExportPlugin | 导出插件 | | FilePlugin | 文件处理插件 | | PrefixPlugin | 前缀处理插件 | | StatusPlugin | 状态监控插件 | ### 业务插件注册 `BusinessPluginRegistry` 管理业务插件： ```java @Component public class BusinessPluginRegistry { public void registerPlugins() { } public PluginStrategy getPlugin(String command) { } public void process(Message message) { } } ``` ### 自定义业务插件 实现 `PluginStrategy` 接口并使用 `@Plugin` 注解： ```java @Plugin public class MyPlugin implements PluginStrategy { @Override public String getCommand() { return "命令关键词"; } @Override public String getDescription() { return "插件描述"; } @Override public void process(Message message) { /* 处理逻辑 */ } @Override public boolean isEnabled() { return true; } } ``` ## 消息类型 | 类型码 | 说明 | |--------|------| | 1 | 文本消息 | | 3 | 图片消息 | | 49 | 文件/公众号消息 | ## API 接口 ### 接收消息 ```http POST /msg Content-Type: application/json { "wechatId": "wxid_xxx", "content": "消息内容", "messageType": 1, "sender": "sender_xxx", "groupId": "群ID" } ``` ### 首页 ```http GET / GET /index ``` ## WebSocket 连接 CoolQ 通过 WebSocket 连接到本系统： ``` ws://localhost:8080/cq?x-self-id=QQ号 ``` 系统通过 `WebSocketHandler` 处理： - 接收 CoolQ 上报的事件消息 - 转发 API 调用响应 - 管理机器人实例 ## 常见问题 ### 1. 编译报错 确保 JDK 版本为 17+： ```bash mvn clean compile ``` ### 2. 微信消息发送失败 - 检查微信 hook 服务 (127.0.0.1:9999) 是否正常运行 - 确认微信已登录 ## 扩展开发 ### 添加新的消息处理器 1. 在 `WechatMsgServiceImpl` 中扩展处理逻辑 2. 重启服务 ### 添加新的 CQ 插件 1. 继承 `CQPlugin` 类 2. 实现相应的事件处理方法 3. 在 `PluginRegistry` 中自动注册 ## 依赖关系 ``` spring-boot-starter ├── spring-boot-starter-web # Web MVC ├── spring-boot-starter-websocket # WebSocket └── lombok # 代码生成 ``` ### 微信版本 3.9.0.22 hook工具 https://www.alipan.com/s/6oBiKYFQg2n ## 许可证 MIT License