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:
1 parent
040e90eb0d
commit
bdf1d1a29a
4 files changed
+726
-29
No files matched your search
@@ -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)
|
||||
Reference in new issue
Block a user