# 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)