# QQ 官方机器人接入说明

本项目基于 `Cucko-main` 的 `QQ` 适配器接入 QQ 开放平台官方机器人。

## 1. 配置 Adapter.json

在 `Adapter.json` 中增加一个 `type` 为 `QQ` 的适配器：

```json
{
    "id": "official",
    "type": "QQ",
    "QQ": "机器人QQ号",
    "appid": "机器人ID",
    "token": "机器人令牌",
    "appsecret": "机器人密钥"
}
```

兼容字段：

- `appid`：QQ 开放平台的机器人 ID。
- `token`：QQ 开放平台的机器人令牌，当前代码保留该字段用于配置完整性。
- `appsecret`：QQ 开放平台的机器人密钥。
- `appsecert`：兼容常见拼写错误。
- `secret`：兼容原项目字段名。
- `QQ`：机器人 QQ 号，用于标识和记录。

## 2. 配置回调地址

本地测试地址：

```text
http://127.0.0.1:8002/
```

线上部署时，把 QQ 开放平台后台的事件回调地址设置为：

```text
https://你的域名/
```

QQ 开放平台会带 `X-Bot-Appid` 请求头，`index.php` 会用它匹配 `Adapter.json` 里的 `appid`。

## 3. 事件验证

QQ 开放平台首次验证会发送 `op = 13` 的回调。`QQ.php` 会使用 `appsecret` 生成签名并返回：

```json
{
    "plain_token": "...",
    "signature": "..."
}
```

## 4. 插件目录

推荐使用全局插件目录，上传一次即可被多个机器人共用：

```text
plugin/php/global/plugin-name/main.php
plugin/php/global/plugin-name/info.json
plugin/python/global/plugin-name/main.py
plugin/python/global/plugin-name/info.json
```

示例：

```text
plugin/php/global/menu/main.php
plugin/php/global/menu/info.json
```

PHP/Python 插件必须分别放在 `plugin/php/` 和 `plugin/python/`。旧目录 `plugin/global/`、`plugin/adapter-id/` 仍兼容运行，后台可将其迁移到对应运行时目录。

基础插件示例：

```php
<?php
if (defined("事件") && 事件 === "群聊" && 消息 === "menu") {
    文字("Menu\n1. ping");
}

if (defined("事件") && 事件 === "私聊" && 消息 === "menu") {
    文字("Private menu");
}
```

## 5. 事件覆盖

当前 `QQ.php` 会识别并分类 botpy 当前暴露的事件：

| 类型 | 事件 |
| --- | --- |
| 消息 | `AT_MESSAGE_CREATE`、`MESSAGE_CREATE`、`GROUP_AT_MESSAGE_CREATE`、`GROUP_MESSAGE_CREATE`、`C2C_MESSAGE_CREATE`、`DIRECT_MESSAGE_CREATE` |
| 删除 | `PUBLIC_MESSAGE_DELETE`、`MESSAGE_DELETE`、`DIRECT_MESSAGE_DELETE` |
| 管理 | `GROUP_ADD_ROBOT`、`GROUP_DEL_ROBOT`、`GROUP_MSG_REJECT`、`GROUP_MSG_RECEIVE`、`FRIEND_ADD`、`FRIEND_DEL`、`C2C_MSG_REJECT`、`C2C_MSG_RECEIVE` |
| 互动 | `INTERACTION_CREATE` |
| 频道 | `GUILD_CREATE`、`GUILD_UPDATE`、`GUILD_DELETE`、`CHANNEL_CREATE`、`CHANNEL_UPDATE`、`CHANNEL_DELETE` |
| 成员 | `GUILD_MEMBER_ADD`、`GUILD_MEMBER_UPDATE`、`GUILD_MEMBER_REMOVE` |
| 扩展 | 表态、审核、论坛、开放论坛、音频、音视频/直播成员进出 |

未知事件不会丢弃，会以 `unknown_event` 进入日志和插件。

## 6. 群机器人开关

项目会自动记录已接触的群 `group_openid`，新群默认开启机器人功能。

进入后台：

```text
/admin/?page=contacts
```

群消息会直接执行 PHP / Python 插件并回复，不需要在后台逐群开启。后台“群列表”用于查看群状态；插件自己的群消息自动撤回开关仍然有效。

QQ 平台的 `GROUP_MSG_RECEIVE` / `GROUP_MSG_REJECT` 只作为平台主动消息状态展示，不会自动开启 Cucko 的群机器人功能。

QQ 官方机器人不是登录 QQ 账号的客户端，后台不能主动拉取“当前已加入的全部群/全部好友”。列表会在收到 QQ 官方回调事件后实时更新；如果服务器已经产生过运行日志，可以点击“从日志重建列表”把历史事件里的群和私聊用户补回后台。

## 7. 常用常量

- `事件`：中文事件名，例如 `群聊`、`私聊`、`频道`、`加群`、`回调`。
- `事件类型`：QQ 官方原始事件名，例如 `GROUP_AT_MESSAGE_CREATE`。
- `事件分类`：`message`、`manage`、`interaction`、`guild`、`audit` 等。
- `消息`：消息内容。
- `消息ID`：回复消息需要的 ID。
- `群号`：群 openid。
- `QQ`：用户 openid。
- `事件ID`：事件类回调使用。
- `原始事件`：完整事件数组。

## 8. 常用发送函数

- `文字("内容")`
- `图片($urlOrBinary, "可选文字")`
- `语音($urlOrBinary)`
- `视频($urlOrBinary)`
- `文件($binary, "文件名")`

完整 PHP 插件示例见：

```text
plugin/php/global/sdk_demo/main.php
```

实用 PHP 插件示例见：

```text
plugin/php/global/sign_weather/main.php
```

支持：

- `签到` / `signin`
- `排行` / `rank`
- `天气 北京` / `weather Beijing`

完整 Python SDK 示例见：

```text
examples/python_sign_weather_plugin.py
```

可上传的插件 zip 模板见：

```text
examples/packages/cucko_php_plugin_example.zip
examples/packages/cucko_python_plugin_example.zip
```