feat: 添加 OneBot v11 QQ 机器人插件

功能:
- WebSocket 正向/反向连接 OneBot 实现
- 接收私聊和群消息,转发给 AI 处理
- AI 回复自动发回 QQ
- 支持 @机器人 / 前缀 / 全部消息 三种触发模式
- 群白名单、管理员配置
- 手动发消息命令
- 支持 go-cqhttp / Lagrange / LLOneBot / NapCat 等

文件:
- onebot/onebot.py - 插件代码
- onebot/README.md - 使用教程
- plugin_registry.json - 注册表更新
This commit is contained in:
xiaoli-cli bot committed 2026-04-30 02:50:31 +08:00
1 parent 040e90eb0d
commit bdf1d1a29a
4 files changed
+726 -29

No files matched your search

+159
View File
@@ -0,0 +1,159 @@
# OneBot v11 QQ 机器人插件
> 让 xiaoli-cli 成为 QQ 机器人,通过 OneBot 协议连接 QQ 消息平台
## 什么是 OneBot
[OneBot](https://github.com/botuniverse/onebot) 是一个聊天机器人应用标准,支持 QQ、微信等平台。常见的 OneBot 实现:
| 实现 | 语言 | 说明 |
|------|------|------|
| [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) | Go | 最流行,功能全 |
| [Lagrange.Core](https://github.com/LagrangeDev/Lagrange.Core) | C# | 轻量,NTQQ 协议 |
| [LLOneBot](https://github.com/LLOneBot/LLOneBot) | TypeScript | QQNT 插件形式 |
| [NapCat](https://github.com/NapNeko/NapCatQQ) | TypeScript | 另一个 QQNT 方案 |
## 前置准备
### 1. 安装依赖
```bash
pip install websocket-client
```
### 2. 安装 OneBot 实现
以 Lagrange 为例:
```bash
# 下载 Lagrange
# https://github.com/LagrangeDev/Lagrange.Core/releases
# 编辑配置 appsettings.json,设置正向 WebSocket
{
"Implementations": [{
"Type": "ForwardWebSocket",
"Host": "0.0.0.0",
"Port": 8080
}]
}
# 启动,扫码登录
./Lagrange.Core
```
### 3. 安装插件
```bash
# 方式1: 通过插件码安装
/plugin install onebot
# 方式2: 手动复制
cp onebot/onebot.py /path/to/xiaoli-cli/plugins/
```
## 使用教程
### 方式一:正向 WebSocket(推荐)
xiaoli-cli 主动连接 OneBot 服务:
```
# 连接
/onebot connect ws://127.0.0.1:8080
# 查看状态
/onebot status
```
### 方式二:反向 WebSocket
xiaoli-cli 监听端口,等 OneBot 主动连接:
```
# 启动监听(默认 8765 端口)
/onebot listen 8765
```
然后在 OneBot 配置中设置反向 WebSocket 地址为 `ws://你的IP:8765`。
### 配置触发方式
```
# 只响应 @机器人 的消息(默认)
/onebot config trigger_mode at
# 响应所有消息
/onebot config trigger_mode all
# 响应以特定前缀开头的消息
/onebot config trigger_mode prefix
/onebot config trigger_prefix !
```
### 群白名单
```
# 只在指定群响应
/onebot config group_whitelist 123456789
/onebot config group_whitelist 987654321
```
### 手动发消息
```
# 发私聊
/onebot send private 123456 你好
# 发群聊
/onebot send group 123456789 大家好
```
## 命令速查
| 命令 | 说明 |
|------|------|
| `/onebot connect <ws_url>` | 正向 WebSocket 连接 |
| `/onebot listen [port]` | 反向 WebSocket 监听 |
| `/onebot disconnect` | 断开连接 |
| `/onebot status` | 查看状态 |
| `/onebot config <key> <val>` | 配置参数 |
| `/onebot send <type> <id> <msg>` | 手动发消息 |
| `/onebot help` | 显示帮助 |
## 工作原理
```
QQ 用户发消息
↓
OneBot 实现 (Lagrange/go-cqhttp)
↓ WebSocket 推送
onebot 插件 (接收消息)
↓ 注入上下文
xiaoli-cli AI 引擎 (处理消息)
↓ 生成回复
onebot 插件 (发送回复)
↓ OneBot API
QQ 用户收到回复
```
## 常见问题
**Q: 连接不上怎么办?**
A: 检查 OneBot 实现是否启动,端口是否正确,防火墙是否放行。
**Q: 群里不回复?**
A: 检查 trigger_mode 设置,以及是否在群白名单中。
**Q: 支持图片/语音吗?**
A: 当前版本只处理文本消息。图片消息会提取文本部分处理。
**Q: 安全性如何?**
A: 建议设置群白名单,不要在公开群暴露。管理员功能可后续扩展。
## 参考
- [OneBot 标准文档](https://github.com/botuniverse/onebot)
- [OneBot v11 接口文档](https://github.com/botuniverse/onebot-11)
- [Lagrange.Core](https://github.com/LagrangeDev/Lagrange.Core)
- [go-cqhttp](https://github.com/Mrs4s/go-cqhttp)