zhamao-robot/zhamao-framework
1
0
Fork 0
mirror of https://github.com/zhamao-robot/zhamao-framework.git synced 2026-07-22 08:05:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

update to 2.5.0-b1 (build 408)

Browse Source
This commit is contained in:
jerry
2021-06-16 00:17:30 +08:00
parent 59d614a24e
commit 4ee16d4fc6
92 changed files with 2286 additions and 1342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/component/bot/access-token.md Normal file
View File

@@ -0,0 +1,59 @@
# Token 验证
为了保障安全，框架支持给接入的 WebSocket 连接验证 Token，如果不设置 Token 同时又将框架的端口暴露在公网将会非常危险。
炸毛框架兼容 OneBot 标准的机器人客户端，所以自带一个 Token 验证器。
关于 Access Token 方面的标准规范，请参考下面内容：
- [OneBot - 鉴权](https://github.com/howmanybots/onebot/blob/master/v11/specs/communication/authorization.md)
- [go-cqhttp - 配置](https://github.com/Mrs4s/go-cqhttp/blob/master/docs/config.md)
> 以 go-cqhttp 举例，如果要设置验证，则将 go-cqhttp 配置文件中的 `access_token` 项填入内容即可。
## 验证位置
框架对 Token 的验证是内置的，在事件 `open`（WebSocket 连接接入时）触发。
如果是兼容 OneBot 标准的客户端接入，则一切都是兼容的。
如果是自定义的其他 WebSocket 客户端也想接入框架，那么其他 WebSocket 客户端也需要进行相应的设置才能利用此 Token 验证。
如果验证成功（Token 符合要求）则分发事件 `@OnOpenEvent`，否则此事件不触发，同时断开 WebSocket 连接。
## 标准验证（字符串形式）
默认的情况下，在框架的全局配置文件 `global.php` 中，对配置项 `access_token` 填入与 OneBot 客户端相同的 `access_token` 即可实现鉴权。下面是一个最基本的和 go-cqhttp 设置鉴权配置：
go-cqhttp 的配置段：
```hjson
// 访问密钥, 强烈推荐在公网的服务器设置
access_token: "emhhbWFvLXJvYm90"
```
框架的配置文件配置段：
```php
/** onebot连接约定的token */
$config["access_token"] = 'emhhbWFvLXJvYm90';
```
然后重启框架和 go-cqhttp 即可。（其他 OneBot 客户端同理）
## 自定义验证（Token 验证）
有些情况下，使用一个单一的字符串可能无法满足你对 Token 验证的安全需求，需要自定义一些判断模式才能满足，所以框架的 `access_token` 配置项支持动态的闭包函数自行编写判断逻辑，例如下面的一个例子，我可以让框架同时允许接入多个不同 token 的 WebSocket 连接：
```php
/** onebot连接约定的token */
$config["access_token"] = function($token){
$allow = ['emhhbWFvLXJvYm90','aXMtdmVyeS1nb29k'];
if (in_array($token, $allow)) return true;
else return false;
};
```
## 自定义验证（open 事件）
当然，这里设置了自定义方式，其实你也可以在下一层的 `@OnOpenEvent` 注解事件中进行自定义内容和判断，具体见 `@OnOpenEvent` 的相关章节。

539
docs/component/bot/cqcode.md Normal file
View File

@@ -0,0 +1,539 @@
# CQ 码（多媒体消息）
消息中的多媒体内容使用 CQ 码来表示，形如 `[CQ:face,id=178]`。其中，`[CQ:]` 是固定格式；`face` 是「功能名」，除了 `face` 还有许多不同的功能名；`id=178` 是「参数」，某些功能不需要参数，而另一些需要多个参数，当有多个参数时，参数间使用逗号分隔。
## 格式
一些 CQ 码的例子如下：
```
[CQ:shake]
[CQ:face,id=178]
[CQ:share,title=标题,url=http://baidu.com]
```
更多 CQ 码功能请参考 [消息段类型](https://github.com/howmanybots/onebot/blob/master/v11/specs/message/segment.md)。
!!! warning "注意"
CQ 码中不应有多余的空格，例如不应该使用 `[CQ:face, id=178]`。
CQ 码的参数值可以包含空格、换行、除 `[],&` 之外的特殊符号等。在解析时，应直接取 `[CQ:` 后、第一个 `,` 或 `]` 前的部分为功能名，第一个 `,` 之后到 `]` 之间的部分为参数，按 `,` 分割后，每个部分第一个 `=` 前的内容为参数名，之后的部分为参数值。例如 `[CQ:share,title=标题中有=等号,url=http://baidu.com]` 中，功能名为 `share`，`title` 参数值为 `标题中有=等号`，`url` 参数值为 `http://baidu.com`。
## 转义
CQ 码中包含一些特殊字符：`[`、`]`、`,` 等，而 CQ 码又是可能混杂在纯文本内容之中的，因此消息中的纯文本内容需要对特殊字符进行转义，以避免歧义。具体的转义规则如下：
| 转义前 | 转义后 |
| ------ | ------- |
| `&` | `&` |
| `[` | `[` |
| `]` | `]` |
另一方面，CQ 码内部的参数值也可能出现特殊字符，也是需要转义的。由于 `,`（半角逗号）在 CQ 码中用于分隔参数，因此除了上面的转义规则，还需要对 `,` 进行转义，如下：
| 转义前 | 转义后 |
| ------ | ------- |
| `&` | `&` |
| `[` | `[` |
| `]` | `]` |
| `,` | `,` |
例如，一个链接分享消息的 CQ 码可能如下：
```
[CQ:share,title=震惊,小伙睡觉前居然...,url=http://baidu.com/?a=1&b=2]
```
## 封装调用
框架提供了 CQ 码的封装，你可以在任何位置使用封装好的 CQ 码生成器。
生成器是一个静态类，里面的方法全部是静态调用，命名空间是：`ZM\API\CQ`。
例如，给用户发送图片这样写就好啦！只需要将添加图片的地方拼到回复用户的字符串里。如果只发图片，整个字符串里只能有 CQ 码。
```php
<?php
namespace Module\Example;
use ZM\API\CQ;
use ZM\Annotation\CQ\CQCommand;
class Hello {
/**
* @CQCommand("发送图片")
*/
public function msgRecv() {
return CQ::image("https://zhamao.xin/file/hello.jpg");
// 相当于返回："[CQ:image,file=https://zhamao.xin/file/hello.jpg]"
}
}
```
效果
<chat-box>
) 发送图片
[ https://zhamao.xin/file/hello.jpg
</chat-box>
## CQ 码操作
### CQ::decode()
CQ 码字符反转义。
定义：`CQ::encode($msg, $is_content = false)`
当 `$is_content` 为 true 时，会将 `&#44;` 转义为 `,`。
| 反转义前 | 反转义后 |
| -------- | -------- |
| `&amp;` | `&` |
| `&#91;` | `[` |
| `&#93;` | `]` |
| `&#44;` | `,` |
```php
$str = CQ::decode("&#91;CQ:at,qq=我只是一条普通的文本&#93;");
// 转换为 "[CQ:at,qq=我只是一条普通的文本]"
```
### CQ::encode()
转义 CQ 码的敏感符号，防止 酷Q 把不该解析为 CQ 码的消息内容当作 CQ 码处理。
```php
$str = CQ::encode("[CQ:我只是一条普通的文本]");
// $str: "&#91;CQ:我只是一条普通的文本&#93;"
```
定义：`CQ::encode($msg, $is_content = false)`
当 `$is_content` 为 true 时，会将 `,` 转义为 `&#44;`。
### CQ::escape()
同 `CQ::encode()`。
### CQ::removeCQ()
去除字符串中所有的 CQ 码。
```php
$str = CQ::removeCQ("[CQ:at,qq=all]这是带表情的全体消息[CQ:face,id=8]");
// $str: "这是带表情的全体消息"
```
### CQ::getCQ()
解析 CQ 码。
- 定义：`getCQ($msg, $is_object = false)`
- 参数 `$is_object` 为 true 时，返回一个 `\ZM\Entity\CQObject` 对象，此对象的属性和下表相同。（2.3.0+ 版本可用）
- 返回：`数组 | CQObject | null`，见下表。
| 键名 | 说明 |
| ------ | ------------------------------------------------------------ |
| type | CQ码类型，比如 `[CQ:at]` 中的 `at` |
| params | 参数列表，比如 `[CQ:image,file=123.jpg,url=http://a.com/a.jpg]`，params 为 `["file" => "123","url" => "http://a.com/a.jpg"]` |
| start | 此 CQ 码在字符串中的起始位置 |
| end | 此 CQ 码在字符串中的结束位置 |
### CQ::getAllCQ()
定义：`CQ::getAllCQ($msg, $is_object = false)`
参数 `$is_object` 为 true 时，返回一个 `\ZM\Entity\CQObject[]` 对象数组，此对象的属性和上面的表格内相同。（2.3.0+ 版本可用）
解析 CQ 码，和 `getCQ()` 的区别是，这个会将字符串中的所有 CQ 码都解析出来，并以同样上方解析出来的数组格式返回。
```php
CQ::getAllCQ("[CQ:at,qq=123]你好啊[CQ:at,qq=456]");
/*
[
[
"type" => "at",
"params" => [
"qq" => "123",
],
"start" => 0,
"end" => 13,
],
[
"type" => "at",
"params" => [
"qq" => "456",
],
"start" => 17,
"end" => 30,
],
]
*/
```
## CQ 码列表
### CQ::face() - 发送 QQ 表情
发送 QQ 原生表情。
定义：`CQ::face($id)`
参数：`$id` 为 QQ 表情对应的 ID 号，一些常见的表情 ID 对应的表情样式见 [QQ 对应表情ID表](https://static.zhamao.me/face_id.html)。
```php
/**
* @CQCommand("打盹")
*/
public function faceTest() {
ctx()->reply("正在打盹...");
ctx()->reply(CQ::face(8));
}
```
<chat-box>
) 打盹
( 正在打盹...
[ https://docs-v1.zhamao.xin/face/8.gif
</chat-box>
!!! note "提示"
对于不断更新的 QQ 版本下，可能会持续扩充新的 QQ 表情，如果上表没有新的表情的话，也可以使用消息接收的方式，让机器人收到表情后解析出来对应的 id 然后再发送。
### CQ::image() - 发送图片
发送图片。
定义：`image($file, $cache = true, $flash = false, $proxy = true, $timeout = -1)`
参数
| 参数名 | 收 | 发 | 默认值 | 说明 |
| --------- | ---- | ---- | ------- | ------------------------------------------------------------ |
| `file` | ✓ | ✓ | 必填 | 图片文件名 |
| `flash` | ✓ | ✓ | `false` | 图片类型，当参数为 true 时代表发送闪照 |
| `cache` | | ✓ | `true` | 只在通过网络 URL 发送时有效，表示是否使用已缓存的文件，默认 `true` |
| `proxy` | | ✓ | `true` | 只在通过网络 URL 发送时有效，表示是否通过代理下载文件（需通过环境变量或配置文件配置代理），默认 `true` |
| `timeout` | | ✓ | `-1` | 只在通过网络 URL 发送时有效，单位秒，表示下载网络文件的超时时间，默认 -1 不超时 |
发送时，`file` 参数除了支持使用收到的图片文件名直接发送外，还支持：
- 绝对路径，例如 `file:///root/imagetest/1.png`，格式使用 [`file` URI](https://tools.ietf.org/html/rfc8089)
- 网络 URL，例如 `http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg`
- Base64 编码，例如 `base64://iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAKElEQVQ4EWPk5+RmIBcwkasRpG9UM4mhNxpgowFGMARGEwnBIEJVAAAdBgBNAZf+QAAAAABJRU5ErkJggg==`
### CQ::record() - 发送语音
发送语音消息。
定义：`CQ::record($file, $magic = false, $cache = true, $proxy = true, $timeout = -1)`
参数
| 参数名 | 收 | 发 | 默认值 | 说明 |
| --------- | ---- | ---- | ------- | ------------------------------------------------------------ |
| `file` | ✓ | ✓ | 必填 | 音频文件名 |
| `flash` | ✓ | ✓ | `false` | 图片类型，当参数为 true 时代表发送闪照 |
| `cache` | | ✓ | `true` | 只在通过网络 URL 发送时有效，表示是否使用已缓存的文件，默认 `true` |
| `proxy` | | ✓ | `true` | 只在通过网络 URL 发送时有效，表示是否通过代理下载文件（需通过环境变量或配置文件配置代理），默认 `true` |
| `timeout` | | ✓ | `-1` | 只在通过网络 URL 发送时有效，单位秒，表示下载网络文件的超时时间，默认 -1 不超时 |
发送时，`file` 参数除了支持使用收到的语音文件名直接发送外，还支持其它形式，参考上方发送图片。
```php
/**
* @CQCommand("说你好")
*/
public function say() {
ctx()->reply(CQ::record("https://zhamao.xin/file/hello.mp3"));
}
```
<chat-box>
) 说你好
( [语音消息，点击收听] 2'' )))
</chat-box>
> 此 CQ 码只能用于单独一条文本消息中，如果混有其他字符串，则会吞掉其他字符串内容。
### CQ::at() - 群里@某人或全体
在群里 at 某个人或全体成员（全体成员需要有管理员权限）。
定义：`CQ::at($qq)`
参数：`$qq` 参数必填，如果填的是 QQ 号，则是单独 at 某人，如果是 `all`，则是 at 全体成员。
```php
/**
* @CQCommand("at测试")
*/
public function atTest() {
ctx()->reply(CQ::at(627577391)." 你好啊！");
}
```
<chat-box>
) at测试
( @鲸鱼 你好啊！
</chat-box>
### CQ::video() - 发送短视频
发送短视频。
定义：`CQ::video($file, $cache = true, $proxy = true, $timeout = -1)`
参数
| 参数名 | 收 | 发 | 默认值 | 说明 |
| --------- | ---- | ---- | ------ | ------------------------------------------------------------ |
| `file` | ✓ | ✓ | 必填 | 短视频文件名 |
| `cache` | | ✓ | `true` | 只在通过网络 URL 发送时有效，表示是否使用已缓存的文件，默认 `true` |
| `proxy` | | ✓ | `true` | 只在通过网络 URL 发送时有效，表示是否通过代理下载文件（需通过环境变量或配置文件配置代理），默认 `true` |
| `timeout` | | ✓ | `-1` | 只在通过网络 URL 发送时有效，单位秒，表示下载网络文件的超时时间，默认 -1 不超时 |
发送时，`file` 参数除了支持使用收到的视频文件名直接发送外，还支持其它形式，参考上方发送图片。
> 此 CQ 码只能用于单独一条文本消息中，如果混有其他字符串，则会吞掉其他字符串内容。
### CQ::rps() - 猜拳
定义：`CQ::rps()`
用法：`CQ::rps()`
> 此 CQ 码只能用于单独一条文本消息中，如果混有其他字符串，则会吞掉其他字符串内容。
### CQ::dice() - 掷骰子
定义：`CQ::dice()`
用法：`CQ::dice()`
> 此 CQ 码只能用于单独一条文本消息中，如果混有其他字符串，则会吞掉其他字符串内容。
### CQ::shake() - 窗口抖动
定义：`CQ::shake()`
用法：`CQ::shake()`
> 此 CQ 码只能用于单独一条文本消息中，如果混有其他字符串，则会吞掉其他字符串内容。
### CQ::poke() - 戳一戳
发送戳一戳。
定义：`CQ::poke($type, $id, $name = "")`
参数
| 参数名 | 收 | 发 | 可能的值 | 说明 |
| ------ | ---- | ---- | ------------------------------------------------------------ | ------ |
| `type` | ✓ | ✓ | 见 [Mirai 的 PokeMessage 类](https://github.com/mamoe/mirai/blob/f5eefae7ecee84d18a66afce3f89b89fe1584b78/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/HummerMessage.kt#L49) | 类型 |
| `id` | ✓ | ✓ | 同上 | ID |
| `name` | ✓ | | 同上 | 表情名 |
例子：`CQ::poke(6,-1)`
效果：放大招
> 此 CQ 码只能用于单独一条文本消息中，如果混有其他字符串，则会吞掉其他字符串内容。
### CQ::anonymous() - 匿名发消息
匿名发消息。需要在允许匿名发消息的群里发。
!!! tip "提示"
当收到匿名消息时，需要通过 [消息事件的群消息](https://github.com/howmanybots/onebot/blob/master/v11/specs/event/message.md#群消息) 的 `anonymous` 字段判断。
定义：`CQ::anonymous($ignore = 1)`
```php
/**
* @CQCommand("匿名测试")
*/
public function anonymousTest() {
ctx()->reply(CQ::anonymous()."匿名测试");
}
```
### CQ::share() - 链接分享
发送链接分享卡片，可自定义内容。
定义：`CQ::share($url, $title, $content = null, $image = null)`
参数
| 参数名 | 收 | 发 | 可能的值 | 说明 |
| --------- | ---- | ---- | -------- | -------------- |
| `url` | ✓ | ✓ | - | URL |
| `title` | ✓ | ✓ | - | 标题 |
| `content` | ✓ | ✓ | - | 可选，内容描述 |
| `image` | ✓ | ✓ | - | 可选，图片 URL |
```php
/**
* @CQCommand("链接分享测试")
*/
public function shareTest() {
ctx()->reply(CQ::share("https://baidu.com", "UC忽悠部", "震惊！我市一男子在光天化日之下..."));
}
```
### CQ::contact() - 推荐好友
发送推荐好友的卡片。
定义：`CQ::contact($type, $id)`
参数
| 参数名 | 收 | 发 | 可能的值 | 说明 |
| ------ | ---- | ---- | ------------- | ---------------------- |
| `type` | ✓ | ✓ | `qq`，`group` | 推荐好友或群 |
| `id` | ✓ | ✓ | - | 被推荐人的 QQ 号或群号 |
```php
/**
* @CQCommand("我的名片")
*/
public function myCard() {
ctx()->reply(CQ::contact("qq", ctx()->getUserId()));
}
```
### CQ::location() - 发送位置
发送位置，基于经纬度坐标发的。
定义：`CQ::location($lat, $lon, $title = "", $content = "")`
参数
| 参数名 | 收 | 发 | 可能的值 | 说明 |
| --------- | ---- | ---- | -------- | -------------- |
| `lat` | ✓ | ✓ | - | 纬度 |
| `lon` | ✓ | ✓ | - | 经度 |
| `title` | ✓ | ✓ | - | 可选，标题 |
| `content` | ✓ | ✓ | - | 可选，内容描述 |
### CQ::music() - 音乐分享
分享音乐，通过卡片。
发送音乐分享卡片。此 CQ 码如果伴随着其他文字，则文字内容会被丢弃。
定义：`CQ::music($type, $id_or_url, $audio = null, $title = null, $content = null, $image = null)`
- `$type`: 发送类型
- `$id_or_url`: 音乐的 id 或 音乐卡片点进去打开的链接
- `$audio`: 音频文件的 HTTP 地址
- `$title`: 音乐卡片的标题，建议 12 字以内
- `$content`: 音乐卡片的简介内容（可选）
- `$image`: 音乐卡片的图片的链接地址（可选）
如果 `$type` 参数为 `qq` 或 `163` 或 `xiami`，则必须且只和第二个参数 `$id_or_url` 配合使用。这三个为内置分享，需要先通过搜索功能获取对应平台歌曲的 id 后使用。
如果 `$type` 参数为 `custom`，则表明此音乐卡片为用户自定义，你可以根据自己的需要自定义卡片内容和音频。此时必须填写 `$id_or_url`, `$audio`, `$title` 三个参数。
```php
ctx()->reply(CQ::music("163", "730806")); //一首我喜欢的歌
// 以内置的发送类型发送音乐卡片，我这里挑了网易云音乐的一首歌。
ctx()->reply("custom", "https://baidu.com/", "https://zhamao.xin/file/hello.mp3", "我是Siri说出来的Hello", "不服来打我呀！", "https://zhamao.xin/file/hello.jpg");
// 自定义整个卡片的每个内容
```
### CQ::forward() - 合并转发
合并转发消息。
定义：`CQ::forward($id)`
参数
```
[CQ:forward,id=123456]
```
| 参数名 | 收 | 发 | 可能的值 | 说明 |
| ------ | ---- | ---- | -------- | ------------------------------------------------------------ |
| `id` | ✓ | | 必填 | 合并转发 ID，需通过 [`get_forward_msg` API](https://github.com/howmanybots/onebot/blob/master/v11/specs/api/public.md#get_forward_msg-获取合并转发消息) 获取具体内容 |
### CQ::node() - 合并转发自定义节点
接收时，此消息段不会直接出现在消息事件的 `message` 中，需通过 [`get_forward_msg` API](https://github.com/howmanybots/onebot/blob/master/v11/specs/api/public.md#get_forward_msg-获取合并转发消息) 获取。发送时，通过获取回来的 API 节点信息进行发送。
定义：`CQ::node($user_id, $nickname, $content)`
参数
| 参数名 | 收 | 发 | 可能的值 | 说明 |
| ---------- | ---- | ---- | -------- | ------------------------------------------------------------ |
| `user_id` | ✓ | ✓ | - | 发送者 QQ 号 |
| `nickname` | ✓ | ✓ | - | 发送者昵称 |
| `content` | ✓ | ✓ | - | 消息内容，支持发送消息时的 `message` 数据类型，见 [API 的参数](https://github.com/howmanybots/onebot/blob/master/v11/specs/api/#参数) |
```php
/**
* @CQCommand("node测试")
*/
public function nodeTest() {
ctx()->reply(CQ::node(123456, "Jack", "[CQ:face,id=123]哈喽～"));
}
```
### CQ::xml() - XML 消息
发送 QQ 兼容的 XML 多媒体消息。
定义：`CQ::xml($data)`
参数：`$data` 为 xml 字符串
```php
/**
* @CQCommand("xml测试")
*/
public function xmlTest() {
ctx()->reply(CQ::xml("<?xml ..."));
}
```
### CQ::json() - JSON 消息
发送 QQ 兼容的 JSON 多媒体消息。
定义：`CQ::json($data, $resid = 0)`
参数同上，内含 JSON 字符串即可。
其中 `$resid` 是面向 go-cqhttp 扩展的参数，默认不填为 0，走小程序通道，填了走富文本通道发送。
!!! tip "提示"
因为某些众所周知的原因，XML 和 JSON 的返回不提供实例，有兴趣的可以自行研究如何编写，文档不含任何相关教程。
### CQ::_custom() - 扩展自定义 CQ 码
用于兼容各类含有被支持的扩展 CQ 码，比如 go-cqhttp 的 `[CQ:gift]` 礼物类型。
定义：`CQ::_custom(string $type_name, array $params)`
| 参数名 | 说明 |
| ----------- | --------------------------------------------------- |
| `type_name` | CQ 码类型，如 `music`，`at` |
| `params` | 发送的 CQ 码中的参数数组，例如 `["qq" => "123456"]` |
下面是一个例子：
```php
CQ::_custom("at",["qq" => "123456","qwe" => "asd"]);
// 返回：[CQ:at,qq=123456,qwe=asd]
```

115
docs/component/bot/message-util.md Normal file
View File

@@ -0,0 +1,115 @@
# MessageUtil 消息处理工具类
类定义：`\ZM\Utils\MessageUtil`
> 2.3.0 版本起可用。
这里放置一些机器人聊天消息处理的便捷静态方法，例如下载图片等。
## 方法
### downloadCQImage()
下载用户消息中所带的所有图片，并返回文件路径。
定义：`downloadCQImage($msg, $path = null)`
参数 `$msg` 为带图片的用户消息，例如 `你好啊！\n[CQ:image,file=a.jpg,url=https://zhamao.xin/file/hello.jpg]`
参数 `$path` 为图片下载的路径，如果不填（默认 null）则指定为 `zm_data/images/` 目录，且不存在会自动创建。
```php
$r = MessageUtil::downloadCQImage("你好啊！\n[CQ:image,file=a.jpg,url=https://zhamao.xin/file/hello.jpg]");
/*
$r == [
"/path-to/zhamao-framework/zm_data/images/a.jpg"
];
*/
```
如果返回的是空数组 `[ ]`，则表明消息中没有图片。如果返回的是 `false`，则表明其中至少一张下载失败或路径有误。
### containsImage()
检查消息中是否含有图片。
定义：`containsImage($msg)`
返回：`bool`，你懂的，true 就是有，false 就没有。
```php
MessageUtil::containsImage("[CQ:image,file=a.jpg,url=http://xxx]"); // true
MessageUtil::containsImage("[CQ:face,id=140] 咦，这是一条带表情的消息"); // false
```
### getImageCQFromLocal()
通过文件路径获取图片的发送 CQ 码。
定义：`getImageCQFromLocal($file, $type = 0)`
参数 `$file` 为图片的绝对路径。
返回：图片的 CQ 码，如 `[CQ:image,file=xxxxx]`
参数 `$type`：
- `0`：以 base64 的方式发送图片，返回结果如 `[CQ:image,file=base64://xxxxxx]`
- `1`：以 `file://` 本地文件的方式发送图片，返回结果如 `[CQ:image,file=file:///path-to/images/a.jpg]`
- `2`：返回图片的 http:// CQ 码（默认为 /images/ 路径就是文件对应所在的目录），如 `[CQ:image,file=http://127.0.0.1:20001/images/a.jpg]`
### splitCommand()
切割用户消息为数组形式（`@CQCommand` 就是使用此方式切割的）
定义：`splitCommand($msg): array`
返回：数组，切分后的。
!!! tip "为什么不直接使用 explode 呢"
因为 `explode()` 只会简单粗暴的切割字符串，假设用户输入的消息中两个词中间有多个空格，则会有空的词出现。例如 `你好 我是一个长空格`。此函数会将多个空格当作一个空格来对待。
```php
MessageUtil::splitCommand("你好 我是傻瓜\n我是傻瓜二号"); // ["你好","我是傻瓜","我是傻瓜二号"]
MessageUtil::splitCommand("我有 三个空格"); // ["我有","三个空格"]
```
### matchCommand()
匹配一条消息到 `@CQCommand` 规则的注解事件，返回要执行的类和函数位置。
定义：`matchCommand($msg, $obj)`
参数 `$msg` 为消息内容。
参数 `$obj` 为事件的对象，可使用 `ctx()->getData()` 获取原先的事件体（仅限 OneBot 消息类型事件中使用）
返回：`\ZM\Entity\MatchObject` 对象，含有匹配成功与否，匹配到的注解对象，匹配到的分割词等，见 []
### addShortCommand()
快速添加一条静态消息回复命令。
定义：`addShortCommand($command, string $reply)`
参数 `$command` 为问的内容，如 `炸毛不聪明`。
参数 `$reply` 为回复的内容，如 `其实还是很聪明的！`。
这个命令推荐在 `@OnStart` 注解下使用，可以用这个来做一个动态的词库，从文件加载后使用。
```php
/**
* @OnStart()
*/
public function onStart() {
MessageUtil::addShortCommand("炸毛不聪明", "其实还是很聪明的！");
}
```
<chat-box>
) 炸毛不聪明
( 其实还是很聪明的！
</chat-box>

790
docs/component/bot/robot-api.md Normal file
View File

@@ -0,0 +1,790 @@
# 机器人 API（ZMRobot）
ZMRobot 类是封装好的 OneBot 标准的 API 接口调用类，可以在机器人连接后通过连接或者机器人 QQ 号获取对象并调用接口（如发送群消息、获取群列表等操作）。
| 属性项 | 属性值 | 备注 |
| -------- | ---------------- | ------------------------------ |
| 名称 | ZMRobot | |
| 类型 | 实例化类 | `$r = new ZMRobot($conn)` |
| 命名空间 | `ZM\API\ZMRobot` | 使用前先 `use ZM\API\ZMRobot;` |
## 属性
对象属性方法是对 API 的调整，例如是否以 `_async`、`_rate_limited` 后缀发送 API、设置协程返回还是异步返回结果等。
### ZMRobot::API_NORMAL
以默认（无后缀）方式请求 API。
### ZMRobot::API_ASYNC
以后缀 `_async` 方式异步请求 API。
### ZMRobot::API_RATE_LIMITED
以后缀 `_rate_limited` 方式请求 API。
## 方法
### setPrefix()
设置后缀。目前支持 `_async`、`_rate_limited`。
- **prefix**: `int` `默认:API_NORMAL`，可选 `ZMRobot::API_NORMAL`、`ZMRobot::API_ASYNC`、`ZMRobot::API_RATE_LIMITED`
设置后缀后，请求的 API 会发生变化。例如发送私聊消息：`sendPrivateMsg()`，请求的 API 为 `send_private_msg_async`，详见 [OneBot 文档](https://github.com/howmanybots/onebot/blob/master/v11/specs/api/README.md)。
### setCallback()
设置 API 结果返回方式。默认为 true，就是直接通过框架处理后接收回包直接返回给结果。如果为 false，则 API 请求后只返回是否成功推送出 WS 数据包。
### getSelfId()
获取当前对象的机器人 QQ 或 OneBot 实例的 ID。
```php
$bot = ZMRobot::get(123456);
echo $bot->getSelfId(); //123456
```
### ZMRobot::get()
静态方法，用来通过机器人 QQ 或 OneBot 实例的 ID 获取 ZMRobot 对象。
参数：`$robot_id`，必填。
```php
$r = ZMRobot::get(123456);
$r->sendPrivateMsg(55555, "hello");
```
### ZMRobot::getRandom()
静态方法，随机获取一个连接到框架的机器人（多个机器人实例连接到框架时适用）。
如果框架没有连接到任何机器人实例，则会抛出一个异常：`ZM\Exception\RobotNotFoundException`。
```php
try {
$bot = ZMRobot::getRandom();
$bot->sendPrivateMsg(55555, "foo");
} catch (\ZM\Exception\RobotNotFoundException $e) {
echo "还没有机器人连接到框架！\n";
}
```
### ZMRobot::getAllRobot()
获取所有连接到框架的机器人的 ZMRobot 对象。
返回值：`ZMRobot[]`。
```php
$all = ZMRobot::getAllRobot();
foreach($all as $v) {
$v->sendPrivateMsg(55555, "机器人轮流给一个人发消息啦！");
}
```
### __construct()
构造方法。
参数：`$connection`：炸毛框架内部的连接对象，必填参数。
```php
//从上下文获取 Websocket 连接对象
$conn = ctx()->getConnection();
$bot = new ZMRobot($conn);
```
## 返回结果处理
因为框架的机器人是兼容 OneBot 标准的（原 CQHTTP），所以每次接收发送 API 请求的结果都是大体一样的结构。我们以 `sendPrivateMsg()` 为例，因为发送出去的每一条消息都会在 OneBot 实例（如 CQHTTP 插件、go-cqhttp 等）中对应一个消息 ID，以供我们核查消息和后续撤回等操作需要。
```php
$bot = ZMRobot::get("123456"); // 机器人QQ号
$obj = $bot->sendGroupMsg("234567", "你好");
echo json_encode($obj, 128|256);
```
```json
// 输出结果
{
"status": "ok",
"retcode": 0,
"data": {
"message_id": 1243
}
}
```
如上，`$obj` 就是我们的回包内容，我们通过调用 `sendPrivateMsg()` 这个 API 后，会拿到机器人发送此条消息的消息 ID，然后可以通过它来进行其他操作（例如撤回）。
```php
$result = $bot->deleteMsg($obj["data"]["message_id"]);
vardump($result["retcode"]); //如果成功撤回，输出 int(0)
```
### 状态码和 Data
状态码一般情况成功都是 0 或者 200，在过去，炸毛框架兼容 CQHTTP 插件时，错误码的标准按照 CYKU 给出的标准编写，不同的 OneBot 标准的实现，可能有不同的数值，需要根据你对接的机器人客户端进行适配。
结果中返回的 `data` 字段根据下方不同 API 的调用而不同，具体查看每个 API 写明的 `响应数据` 表格。
### response 表
| 字段名 | 数据类型 | 默认值 | 说明 |
| --------- | -------- | ---------- | ----------------------- |
| `status` | String | "ok" | 状态码说明 |
| `retcode` | number | 0 | 返回状态码 |
| `data` | array | 见 data 表 | 根据不同的 API 返回不同 |
## 机器人 API 方法
### sendPrivateMsg()
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------------- | -------- | ------- | ------------------------------------------------------------ |
| `user_id` | number | - | 对方 QQ 号 |
| `message` | message | - | 要发送的内容 |
| `auto_escape` | boolean | `false` | 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 `message` 字段是字符串时有效 |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------ | -------------- | ------- |
| `message_id` | number (int32) | 消息 ID |
例子
=== "代码"
```php
$bot = ZMRobot::get(123456); // 123456是你的机器人QQ
$bot->sendPrivateMsg("627577391", "你好啊！你好你好！");
```
=== "效果"
<chat-box>
( 你好啊！你好你好！
</chat-box>
### sendGroupMsg()
发送群组消息。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------------- | -------- | ------- | ------------------------------------------------------------ |
| `group_id` | number | - | 群号 |
| `message` | message | - | 要发送的内容 |
| `auto_escape` | boolean | `false` | 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 `message` 字段是字符串时有效 |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------ | -------------- | ------- |
| `message_id` | number (int32) | 消息 ID |
### sendMsg()
发送消息。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| -------------- | -------- | ------- | ------------------------------------------------------------ |
| `message_type` | string | - | 消息类型，支持 `private`、`group`、`discuss`，分别对应私聊、群组、讨论组，如不传入，则根据传入的 `*_id` 参数判断 |
| `target_id` | number | - | 目标号码，如 QQ 号，群号，讨论组号 |
| `message` | message | - | 要发送的内容 |
| `auto_escape` | boolean | `false` | 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 `message` 字段是字符串时有效 |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------ | -------------- | ------- |
| `message_id` | number (int32) | 消息 ID |
### deleteMsg()
撤回消息。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------------ | -------------- | ------ | ------- |
| `message_id` | number (int32) | - | 消息 ID |
响应数据：无
### getMsg()
获取消息。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| --------- | -------- | ------ | -------------------------------- |
| `message_id` | number | - | 消息 ID |
响应数据
| 字段名 | 数据类型 | 说明 |
| -------------- | -------------- | ------------------------------------------------------------ |
| `time` | number (int32) | 发送时间 |
| `message_type` | string | 消息类型，同 [消息事件](https://github.com/howmanybots/onebot/blob/master/v11/specs/event/message.md) |
| `message_id` | number (int32) | 消息 ID |
| `real_id` | number (int32) | 消息真实 ID |
| `sender` | object | 发送人信息，同 [消息事件](https://github.com/howmanybots/onebot/blob/master/v11/specs/event/message.md) |
| `message` | message | 消息内容 |
### getForwardMsg()
获取合并转发消息。
参数
| 字段名 | 数据类型 | 说明 |
| ------ | -------- | ----------- |
| `id` | string | 合并转发 ID |
响应数据
| 字段名 | 类型 | 说明 |
| --------- | ------- | ------------------------------------------------------------ |
| `message` | message | 消息内容，使用 [消息的数组格式](https://github.com/howmanybots/onebot/blob/master/v11/specs/message/array.md) 表示，数组中的消息段全部为 [`node` 消息段](https://github.com/howmanybots/onebot/blob/master/v11/specs/message/segment.md#合并转发自定义节点) |
### sendLike()
发送好友赞。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| --------- | -------- | ------ | -------------------------------- |
| `user_id` | number | - | 对方 QQ 号 |
| `times` | number | 1 | 赞的次数，每个好友每天最多 10 次 |
响应数据
无
### setGroupKick()
群组踢人。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| -------------------- | -------- | ------- | ------------------ |
| `group_id` | number | - | 群号 |
| `user_id` | number | - | 要踢的 QQ 号 |
| `reject_add_request` | boolean | `false` | 拒绝此人的加群请求 |
响应数据：无
### setGroupBan()
群组单人禁言。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | --------- | -------------------------------- |
| `group_id` | number | - | 群号 |
| `user_id` | number | - | 要禁言的 QQ 号 |
| `duration` | number | `30 * 60` | 禁言时长，单位秒，0 表示取消禁言 |
响应数据：无
### setGroupAnonymousBan()
群组匿名用户禁言。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------------------- | ---------------- | --------- | ------------------------------------------------------------ |
| `group_id` | number | - | 群号 |
| `anonymous_or_flag` | object 或 string | - | 要禁言的匿名用户对象（群消息上报的 `anonymous` 字段）或用户的 flag |
| `duration` | number | `30 * 60` | 禁言时长，单位秒，无法取消匿名用户禁言 |
上面的 `anonymous_or_flag` 两者任选其一传入即可。
响应数据：无
### setGroupWholeBan()
群组全员禁言
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | -------- |
| `group_id` | number | - | 群号 |
| `enable` | boolean | `true` | 是否禁言 |
响应数据：无
### setGroupAdmin()
群组设置管理员
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | ------------------------- |
| `group_id` | number | - | 群号 |
| `user_id` | number | - | 要设置管理员的 QQ 号 |
| `enable` | boolean | `true` | true 为设置，false 为取消 |
响应数据：无
### setGroupAnonymous()
群组匿名
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | ---------------- |
| `group_id` | number | - | 群号 |
| `enable` | boolean | `true` | 是否允许匿名聊天 |
响应数据：无
### setGroupCard()
设置群名片（群备注）
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | ---------------------------------------- |
| `group_id` | number | - | 群号 |
| `user_id` | number | - | 要设置的 QQ 号 |
| `card` | string | 空 | 群名片内容，不填或空字符串表示删除群名片 |
响应数据：无
### setGroupName()
设置群名。
参数
| 字段名 | 数据类型 | 说明 |
| ------------ | -------------- | ------ |
| `group_id` | number (int64) | 群号 |
| `group_name` | string | 新群名 |
响应数据：无
### setGroupLeave()
退出群组
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------------ | -------- | ------- | -------------------------------------------------------- |
| `group_id` | number | - | 群号 |
| `is_dismiss` | boolean | `false` | 是否解散，如果登录号是群主，则仅在此项为 true 时能够解散 |
响应数据：无
### setGroupSpecialTitle()
设置群组专属头衔
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| --------------- | -------- | ------ | ------------------------------------------------------------ |
| `group_id` | number | - | 群号 |
| `user_id` | number | - | 要设置的 QQ 号 |
| `special_title` | string | 空 | 专属头衔，不填或空字符串表示删除专属头衔 |
| `duration` | number | `-1` | 专属头衔有效期，单位秒，-1 表示永久，不过此项似乎没有效果，可能是只有某些特殊的时间长度有效，有待测试 |
响应数据：无
### setFriendAddRequest()
处理加好友请求
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| --------- | -------- | ------ | ----------------------------------------- |
| `flag` | string | - | 加好友请求的 flag（需从上报的数据中获得） |
| `approve` | boolean | `true` | 是否同意请求 |
| `remark` | string | 空 | 添加后的好友备注（仅在同意时有效） |
响应数据：无
### setGroupAddRequest()
处理加群请求 / 邀请
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | ------------------------------------------------------------ |
| `flag` | string | - | 加群请求的 flag（需从上报的数据中获得） |
| `sub_type` | string | - | `add` 或 `invite`，请求类型（需要和上报消息中的 `sub_type` 字段相符） |
| `approve` | boolean | `true` | 是否同意请求／邀请 |
| `reason` | string | 空 | 拒绝理由（仅在拒绝时有效） |
响应数据无
### getLoginInfo()
获取登录号信息
参数：无
响应数据
| 字段名 | 数据类型 | 说明 |
| ---------- | -------------- | ------- |
| `user_id` | number (int64) | QQ 号 |
| `nickname` | string | QQ 昵称 |
### getStrangerInfo()
获取陌生人信息
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------- | ---------------------------------------------------- |
| `user_id` | number | - | QQ 号 |
| `no_cache` | boolean | `false` | 是否不使用缓存（使用缓存可能更新不及时，但响应更快） |
响应数据
| 字段名 | 数据类型 | 说明 |
| ---------- | -------------- | ------------------------------------- |
| `user_id` | number (int64) | QQ 号 |
| `nickname` | string | 昵称 |
| `sex` | string | 性别，`male` 或 `female` 或 `unknown` |
| `age` | number (int32) | 年龄 |
### getFriendList()
获取好友列表
参数：无
响应数据
响应内容为 JSON 数组，每个元素如下：
| 字段名 | 数据类型 | 说明 |
| ---------- | -------------- | ------ |
| `user_id` | number (int64) | QQ 号 |
| `nickname` | string | 昵称 |
| `remark` | string | 备注名 |
### getGroupInfo()
获取群信息
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------- | ---------------------------------------------------- |
| `group_id` | number | - | 群号 |
| `no_cache` | boolean | `false` | 是否不使用缓存（使用缓存可能更新不及时，但响应更快） |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------------ | -------------- | -------------------- |
| `group_id` | number (int64) | 群号 |
| `group_name` | string | 群名称 |
| `member_count` | number (int32) | 成员数 |
| `max_member_count` | number (int32) | 最大成员数（群容量） |
### getGroupList()
获取群列表
参数：无
响应数据
响应内容为 JSON 数组，每个元素如下：
| 字段名 | 数据类型 | 说明 |
| ------------ | -------------- | ------ |
| `group_id` | number (int64) | 群号 |
| `group_name` | string | 群名称 |
### getGroupMemberInfo()
获取群成员信息
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------- | ---------------------------------------------------- |
| `group_id` | number | - | 群号 |
| `user_id` | number | - | QQ 号 |
| `no_cache` | boolean | `false` | 是否不使用缓存（使用缓存可能更新不及时，但响应更快） |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------------- | -------------- | ------------------------------------- |
| `group_id` | number (int64) | 群号 |
| `user_id` | number (int64) | QQ 号 |
| `nickname` | string | 昵称 |
| `card` | string | 群名片／备注 |
| `sex` | string | 性别，`male` 或 `female` 或 `unknown` |
| `age` | number (int32) | 年龄 |
| `area` | string | 地区 |
| `join_time` | number (int32) | 加群时间戳 |
| `last_sent_time` | number (int32) | 最后发言时间戳 |
| `level` | string | 成员等级 |
| `role` | string | 角色，`owner` 或 `admin` 或 `member` |
| `unfriendly` | boolean | 是否不良记录成员 |
| `title` | string | 专属头衔 |
| `title_expire_time` | number (int32) | 专属头衔过期时间戳 |
| `card_changeable` | boolean | 是否允许修改群名片 |
### getGroupMemberList()
获取群成员列表
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | ---- |
| `group_id` | number | - | 群号 |
响应数据
响应内容为 JSON 数组，每个元素的内容和上面的 `/get_group_member_info` 接口相同，但对于同一个群组的同一个成员，获取列表时和获取单独的成员信息时，某些字段可能有所不同，例如 `area`、`title` 等字段在获取列表时无法获得，具体应以单独的成员信息为准。
### getGroupHonorInfo()
获取群荣誉信息。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ---------- | -------------- | ------ | ------------------------------------------------------------ |
| `group_id` | number (int64) | - | 群号 |
| `type` | string | - | 要获取的群荣誉类型，可传入 `talkative` `performer` `legend` `strong_newbie` `emotion` 以分别获取单个类型的群荣誉数据，或传入 `all` 获取所有数据 |
响应数据
| 字段名 | 数据类型 | 说明 |
| -------------------- | -------------- | ---------------------------------------------------------- |
| `group_id` | number (int64) | 群号 |
| `current_talkative` | object | 当前龙王，仅 `type` 为 `talkative` 或 `all` 时有数据 |
| `talkative_list` | array | 历史龙王，仅 `type` 为 `talkative` 或 `all` 时有数据 |
| `performer_list` | array | 群聊之火，仅 `type` 为 `performer` 或 `all` 时有数据 |
| `legend_list` | array | 群聊炽焰，仅 `type` 为 `legend` 或 `all` 时有数据 |
| `strong_newbie_list` | array | 冒尖小春笋，仅 `type` 为 `strong_newbie` 或 `all` 时有数据 |
| `emotion_list` | array | 快乐之源，仅 `type` 为 `emotion` 或 `all` 时有数据 |
其中 `current_talkative` 字段的内容如下：
| 字段名 | 数据类型 | 说明 |
| ----------- | -------------- | -------- |
| `user_id` | number (int64) | QQ 号 |
| `nickname` | string | 昵称 |
| `avatar` | string | 头像 URL |
| `day_count` | number (int32) | 持续天数 |
其它各 `*_list` 的每个元素是一个 JSON 对象，内容如下：
| 字段名 | 数据类型 | 说明 |
| ------------- | -------------- | -------- |
| `user_id` | number (int64) | QQ 号 |
| `nickname` | string | 昵称 |
| `avatar` | string | 头像 URL |
| `description` | string | 荣誉描述 |
### getCookies()
获取 Cookies。
!!! warning "注意"
目前开源的 mirai 为底层的机器人客户端均不支持获取 Cookies 和 CSRF Token，包括 go-cqhttp。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| -------- | -------- | ------ | ----------------------- |
| `domain` | string | 空 | 需要获取 cookies 的域名 |
响应数据
| 字段名 | 数据类型 | 说明 |
| --------- | -------- | ------- |
| `cookies` | string | Cookies |
### getCsrfToken()
获取 CSRF Token
参数：无
响应数据
| 字段名 | 数据类型 | 说明 |
| ------- | -------------- | ---------- |
| `token` | number (int32) | CSRF Token |
### getCredentials()
获取 QQ 相关接口凭证，即上面两个合并。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| -------- | -------- | ------ | ----------------------- |
| `domain` | string | 空 | 需要获取 cookies 的域名 |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------ | -------------- | ---------- |
| `cookies` | string | Cookies |
| `csrf_token` | number (int32) | CSRF Token |
### getRecord()
获取语音。其实并不是真的获取语音，而是转换语音到指定的格式。
> **提示**：要使用此接口，通常需要安装 ffmpeg，请参考 OneBot 实现的相关说明。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------------ | -------- | ------ | ------------------------------------------------------------ |
| `file` | string | - | 收到的语音文件名（CQ 码的 `file` 参数），如 `0B38145AA44505000B38145AA4450500.silk` |
| `out_format` | string | - | 要转换到的格式，目前支持 `mp3`、`amr`、`wma`、`m4a`、`spx`、`ogg`、`wav`、`flac` |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------ | -------- | ------------------------------------------------------------ |
| `file` | string | 转换后的语音文件路径，如 `/home/somebody/cqhttp/data/record/0B38145AA44505000B38145AA4450500.mp3` |
### getImage()
获取图片。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------ | -------- | ------ | ------------------------------------------------------------ |
| `file` | string | - | 收到的图片文件名（CQ 码的 `file` 参数），如 `6B4DE3DFD1BD271E3297859D41C530F5.jpg` |
响应数据
| 字段名 | 数据类型 | 说明 |
| ------ | -------- | ------------------------------------------------------------ |
| `file` | string | 下载后的图片文件路径，如 `/home/somebody/cqhttp/data/image/6B4DE3DFD1BD271E3297859D41C530F5.jpg` |
### canSendImage()
检查是否可以发送图片。
参数：无
响应数据
| 字段名 | 数据类型 | 说明 |
| ------ | -------- | ------ |
| `yes` | boolean | 是或否 |
### canSendRecord()
检查是否可以发送语音，返回同上。
### getStatus()
获取插件运行状态。
参数：无
响应数据
| 字段名 | 数据类型 | 说明 |
| -------- | -------- | -------------------------------------------------------- |
| `online` | boolean | 当前 QQ 在线，`null` 表示无法查询到在线状态 |
| `good` | boolean | 状态符合预期，意味着各模块正常运行、功能正常，且 QQ 在线 |
| ...... | - | OneBot 实例自行添加的其他内容 |
通常情况下建议只使用 `online` 和 `good` 这两个字段来判断运行状态，因为根据 OneBot 实现的不同，其它字段可能完全不同。
### getVersionInfo()
获取版本信息
响应数据
| 字段名 | 数据类型 | 说明 |
| ------------------ | -------- | ----------------------------- |
| `app_name` | string | 应用标识，如 `mirai-native` |
| `app_version` | string | 应用版本，如 `1.2.3` |
| `protocol_version` | string | OneBot 标准版本，如 `v11` |
| …… | - | OneBot 实现自行添加的其它内容 |
### setRestartPlugin()
重启 OneBot 客户端
由于重启 OneBot 实现同时需要重启 API 服务，这意味着当前的 API 请求会被中断，因此需要异步地重启，接口返回的 `status` 是 `async`。
参数
| 字段名 | 数据类型 | 默认值 | 说明 |
| ------- | -------- | ------ | ------------------------------------------------------------ |
| `delay` | number | `0` | 要延迟的毫秒数，如果默认情况下无法重启，可以尝试设置延迟为 2000 左右 |
响应数据：无
### cleanCache()
清理 OneBot 客户端的缓存。
参数：无
响应数据：无
### callExtendedAPI() （扩充 API）
用来调用 OneBot 标准之外扩展出来的自定义 API。
使用不同 OneBot 客户端时，可能有一些 API 不在上方的 OneBot 标准里，这时可以使用此方法进行额外调用。
参数
| 字段名 | 数据类型 | 默认值 |
| -------- | -------- | ------ |
| `action` | string | 必填 |
| `params` | array | `[]` |
例子
```php
$result = $bot->callExtendedAPI("get_group_root_files", ["group_id" => 123456]);
//这里以 go-cqhttp 扩展的一个获取群文件的 API 为例
var_dump($result["data"]);
// 输出群文件列表
```

86
docs/component/bot/turing-api.md Normal file
View File

@@ -0,0 +1,86 @@
# 图灵机器人 API（TuringAPI）
类定义：`\ZM\API\TuringAPI`
## 方法
### TuringAPI::getTuringMsg()
请求图灵接口，返回回复的消息。
定义：`getTuringMsg($msg, $user_id, $api)`
参数 `$msg` 为用户的消息内容，如果含有图片 CQ 码，则自动转换为图灵兼容的接口模式。
参数 `$user_id` 为用户 ID，一般默认给 QQ 号码就可以了，注意最好不要有特殊字符（如 `./\<>*` 等），否则会间断性调用失败。
参数 `$api` 为图灵机器人的 `apikey`，可以到 <http://www.turingapi.com/> 申请免费或付费的 API key。
在框架的示例模块中，已经写好了一个正常机器人响应图灵回复的命令，如下：
```php
class Hello {
/**
* 图灵机器人的内置实现，在www.turingapi.com申请一个apikey填入下方变量即可。
* @CQCommand(start_with="机器人",end_with="机器人",message_type="group")
* @CQMessage(message_type="private",level=1)
*/
public function turingAPI() {
$user_id = ctx()->getUserId();
$api = ""; // 请在这里填入你的图灵机器人的apikey
if ($api === "") return false; //如果没有填入apikey则此功能关闭
if (($this->_running_annotation ?? null) instanceof CQCommand) {
$msg = ctx()->getFullArg("我在！有什么事吗？");
} else {
$msg = ctx()->getMessage();
}
ctx()->setMessage($msg);
if (MessageUtil::matchCommand($msg, ctx()->getData())->status === false) {
return TuringAPI::getTuringMsg($msg, $user_id, $api);
} else {
QQBot::getInstance()->handle(ctx()->getData(), ctx()->getCache("level") + 1);
return true;
}
}
/**
* 响应at机器人的消息
* @CQBefore("message")
*/
public function changeAt() {
if (MessageUtil::isAtMe(ctx()->getMessage(), ctx()->getRobotId())) {
$msg = str_replace(CQ::at(ctx()->getRobotId()), "", ctx()->getMessage());
ctx()->setMessage("机器人" . $msg);
Console::info(ctx()->getMessage());
}
return true;
}
}
```
如上述代码，我们将申请的 apikey 填入变量 `$api` 中，启动机器人即可使用，以下是实测消息（我用自己申请的 key 做测试回复的消息）。
<chat-box>
) 你咋了
( 我没事哦，谢谢您的关心。
) 上海天气
( 上海:周一 03月29日,小雨 东南风转东风,最低气温14度，最高气温24度。
^ 切换为群内
) 机器人
( 我在！有什么事吗？
) 你叫啥
( 我的名字叫炸毛，认识你很高兴呢！
</chat-box>
在默认示例模块中的例子是直接可以拿来用的，这段代码同时做了对 at 的处理、以及兼容用户自定义写的其他命令的方式，下面是默认模块填好 apikey 后可以用的各种方式提问：
<chat-box>
^ 切换为群内
) 我是一条普通消息，这条机器人不会回复我
) @机器人 你叫啥
( 我是聪明可爱的炸毛，认识你很高兴。
) 机器人
( 我在！有什么事吗？
) 一言
( 多少事，从来急，天地转，光阴迫，一万年太久，只争朝夕。
</chat-box>