xiaoli-cli bot
bdf1d1a29a
功能: - WebSocket 正向/反向连接 OneBot 实现 - 接收私聊和群消息，转发给 AI 处理 - AI 回复自动发回 QQ - 支持 @机器人 / 前缀 / 全部消息 三种触发模式 - 群白名单、管理员配置 - 手动发消息命令 - 支持 go-cqhttp / Lagrange / LLOneBot / NapCat 等 文件: - onebot/onebot.py - 插件代码 - onebot/README.md - 使用教程 - plugin_registry.json - 注册表更新
160 lines
3.5 KiB
Markdown
160 lines
3.5 KiB
Markdown
# 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)
|