Merge branch 'master' into dev.

docs/cqhttp.md

@@ -2,10 +2,64 @@
 
 由于部分 api 原版 CQHTTP 并未实现，go-cqhttp 修改并增加了一些拓展 api .
 
+<details>
+<summary>目录</summary>
+<p>
+
+##### CQCode
+- [图片](#图片)
+- [回复](#回复)
+- [红包](#红包)
+- [戳一戳](#戳一戳)
+- [礼物](#礼物)
+- [合并转发](#合并转发)
+- [合并转发消息节点](#合并转发消息节点)
+- [XML 消息](#xml-消息)
+- [JSON 消息](#json-消息)
+- [cardimage](#cardimage)
+- [文本转语音](#文本转语音)
+- [图片](#图片)
+
+##### API
+- [设置群名](#设置群名)
+- [设置群头像](#设置群头像)
+- [获取图片信息](#获取图片信息)
+- [获取消息](#获取消息)
+- [获取合并转发内容](#获取合并转发内容)
+- [发送合并转发(群)](#发送合并转发(群))
+- [获取中文分词](#获取中文分词)
+- [图片OCR](#图片OCR)
+- [获取中文分词](#获取中文分词)
+- [获取群系统消息](#获取群文件系统信息)
+- [获取群文件系统信息](#获取群文件系统信息)
+- [获取群根目录文件列表](#获取群根目录文件列表)
+- [获取群子目录文件列表](#获取群子目录文件列表)
+- [获取群文件资源链接](#获取群文件资源链接)
+- [获取状态](#获取状态)
+- [获取群子目录文件列表](#设置群名)
+
+##### 事件
+- [群消息撤回](#群消息撤回)
+- [好友消息撤回](#好友消息撤回)
+- [群内戳一戳](#群内戳一戳)
+- [群红包运气王提示](#群红包运气王提示)
+- [群成员荣誉变更提示](#群成员荣誉变更提示)
+- [群成员名片更新](#群成员名片更新)
+- [接收到离线文件](#接收到离线文件)
+
+</p>
+</details>
+
 ## CQCode
 
 ### 图片
 
+Type : `image`
+
+范围: **发送/接收**
+
+参数:
+
 | 参数名  | 可能的值        | 说明                                                            |
 | ------- | --------------- | --------------------------------------------------------------- |
 | `file`  | -               | 图片文件名                                                      |
@@ -25,6 +79,23 @@
 | 40004 | 爱你 |
 | 40005 | 征友 |
 
+示例: `[CQ:image,file=http://baidu.com/1.jpg,type=show,id=40004]`
+
+
+### 回复
+
+Type : `reply`
+
+范围: **发送/接收**
+
+参数:
+
+| 参数名 | 类型 | 说明                                  |
+| ------ | ---- | ------------------------------------- |
+| `id`   | int  | 回复时所引用的消息id, 必须为本群消息. |
+
+示例: `[CQ:reply,id=123456]`
+
 ### 红包
 
 Type: `redbag`
@@ -33,9 +104,9 @@ Type: `redbag`
 
 参数:
 
-| 参数名 | 类型   | 说明        |
-| ------ | ------ | ----------- |
-| title  | string | 祝福语/口令 |
+| 参数名  | 类型   | 说明        |
+| ------- | ------ | ----------- |
+| `title` | string | 祝福语/口令 |
 
 示例: `[CQ:redbag,title=恭喜发财]`
 
@@ -51,7 +122,7 @@ Type: `poke`
 
 | 参数名 | 类型  | 说明         |
 | ------ | ----- | ------------ |
-| qq     | int64 | 需要戳的成员 |
+| `qq`   | int64 | 需要戳的成员 |
 
 示例: `[CQ:poke,qq=123456]`
 
@@ -67,8 +138,8 @@ Type: `gift`
 
 | 参数名 | 类型  | 说明           |
 | ------ | ----- | -------------- |
-| qq     | int64 | 接收礼物的成员 |
-| id     | int   | 礼物的类型     |
+| `qq`   | int64 | 接收礼物的成员 |
+| `id`   | int   | 礼物的类型     |
 
 目前支持的礼物ID:
 
@@ -93,6 +164,20 @@ Type: `gift`
 
 示例: `[CQ:gift,qq=123456,id=8]`
 
+ ### 合并转发
+
+Type: `forward`
+
+范围: **接收**
+
+参数:
+
+| 参数名 | 类型   | 说明                                                         |
+| ------ | ------ | ------------------------------------------------------------ |
+| `id`   | string | 合并转发ID, 需要通过 `/get_forward_msg` API获取转发的具体内容 |
+
+示例: `[CQ:forward,id=xxxx]`
+
 ### 合并转发消息节点
 
 Type: `node`
@@ -101,12 +186,12 @@ Type: `node`
 
 参数:
 
-| 参数名  | 类型    | 说明           | 特殊说明                                                                               |
-| ------- | ------- | -------------- | -------------------------------------------------------------------------------------- |
-| id      | int32   | 转发消息id     | 直接引用他人的消息合并转发,  实际查看顺序为原消息发送顺序 **与下面的自定义消息二选一** |
-| name    | string  | 发送者显示名字 | 用于自定义消息 (自定义消息并合并转发，实际查看顺序为自定义消息段顺序)                  |
-| uin     | int64   | 发送者QQ号     | 用于自定义消息                                                                         |
-| content | message | 具体消息       | 用于自定义消息 **不支持转发套娃，不支持引用回复**                                      |
+| 参数名    | 类型    | 说明           | 特殊说明                                                     |
+| --------- | ------- | -------------- | ------------------------------------------------------------ |
+| `id`      | int32   | 转发消息id     | 直接引用他人的消息合并转发,  实际查看顺序为原消息发送顺序 **与下面的自定义消息二选一** |
+| `name`    | string  | 发送者显示名字 | 用于自定义消息 (自定义消息并合并转发，实际查看顺序为自定义消息段顺序) |
+| `uin`     | int64   | 发送者QQ号     | 用于自定义消息                                               |
+| `content` | message | 具体消息       | 用于自定义消息 **不支持转发套娃，不支持引用回复**            |
 
 特殊说明: **需要使用单独的API `/send_group_forward_msg` 发送，并且由于消息段较为复杂，仅支持Array形式入参。 如果引用消息和自定义消息同时出现，实际查看顺序将取消息段顺序.  另外按 [CQHTTP](https://cqhttp.cc/docs/4.15/#/Message?id=格式) 文档说明, `data` 应全为字符串, 但由于需要接收`message` 类型的消息, 所以 *仅限此Type的content字段* 支持Array套娃**
 
@@ -180,7 +265,7 @@ Type: `node`
 ]
 ````
 
-### xml支持
+### XML 消息
 
 Type: `xml`
 
@@ -188,10 +273,10 @@ Type: `xml`
 
 参数:
 
-| 参数名 | 类型   | 说明                                      |
-| ------ | ------ | ----------------------------------------- |
-| data   | string | xml内容，xml中的value部分，记得实体化处理 |
-| resid  | int32  | 可以不填                                  |
+| 参数名  | 类型   | 说明                                      |
+| ------- | ------ | ----------------------------------------- |
+| `data`  | string | xml内容，xml中的value部分，记得实体化处理 |
+| `resid` | int32  | 可以不填                                  |
 
 示例: `[CQ:xml,data=xxxx]`
 
@@ -229,7 +314,7 @@ Type: `xml`
 </msg>
 ```
 
-### json消息支持
+### JSON 消息
 
 Type: `json`
 
@@ -237,20 +322,20 @@ Type: `json`
 
 参数:
 
-| 参数名 | 类型   | 说明                                            |
-| ------ | ------ | ----------------------------------------------- |
-| data   | string | json内容，json的所有字符串记得实体化处理        |
-| resid  | int32  | 默认不填为0，走小程序通道，填了走富文本通道发送 |
+| 参数名  | 类型   | 说明                                            |
+| ------- | ------ | ----------------------------------------------- |
+| `data`  | string | json内容，json的所有字符串记得实体化处理        |
+| `resid` | int32  | 默认不填为0，走小程序通道，填了走富文本通道发送 |
 
 json中的字符串需要进行转义：
 
->","=>`&#44;`、
+>","=> `&#44;`
 
->"&"=> `&amp;`、
+>"&"=> `&amp;`
 
->"["=>`&#91;`、
+>"["=> `&#91;`
 
->"]"=>`&#93;`、
+>"]"=> `&#93;`
 
 否则无法正确得到解析
 
@@ -260,7 +345,8 @@ json中的字符串需要进行转义：
 ```
 
 
-### cardimage 一种xml的图片消息（装逼大图）
+### cardimage
+一种xml的图片消息（装逼大图）
 
 ps: xml 接口的消息都存在风控风险，请自行兼容发送失败后的处理（可以失败后走普通图片模式）
 
@@ -270,15 +356,15 @@ Type: `cardimage`
 
 参数:
 
-| 参数名    | 类型   | 说明                                  |
-| --------- | ------ | ------------------------------------- |
-| file      | string | 和image的file字段对齐，支持也是一样的 |
-| minwidth  | int64  | 默认不填为400，最小width              |
-| minheight | int64  | 默认不填为400，最小height             |
-| maxwidth  | int64  | 默认不填为500，最大width              |
-| maxheight | int64  | 默认不填为1000，最大height            |
-| source    | string | 分享来源的名称，可以留空              |
-| icon      | string | 分享来源的icon图标url，可以留空       |
+| 参数名      | 类型   | 说明                                  |
+| ----------- | ------ | ------------------------------------- |
+| `file`      | string | 和image的file字段对齐，支持也是一样的 |
+| `minwidth`  | int64  | 默认不填为400，最小width              |
+| `minheight` | int64  | 默认不填为400，最小height             |
+| `maxwidth`  | int64  | 默认不填为500，最大width              |
+| `maxheight` | int64  | 默认不填为1000，最大height            |
+| `source`    | string | 分享来源的名称，可以留空              |
+| `icon`      | string | 分享来源的icon图标url，可以留空       |
 
 
 示例cardimage 的cq码：
@@ -298,23 +384,34 @@ Type: `tts`
 
 | 参数名 | 类型   | 说明 |
 | ------ | ------ | ---- |
-| text   | string | 内容 |
+| `text` | string | 内容 |
 
 示例: `[CQ:tts,text=这是一条测试消息]`
 
 ## API
 
+### 设置群名
+
+终结点: `/set_group_name`  
+
+**参数** 
+
+| 字段         | 类型   | 说明 |
+| ------------ | ------ | ---- |
+| `group_id`   | int64  | 群号 |
+| `group_name` | string | 新名 |
+
 ### 设置群头像
 
 终结点: `/set_group_portrait`  
 
 **参数** 
 
-| 字段     | 类型   | 说明                     |
-| -------- | ------ | ------------------------ |
-| group_id | int64  | 群号                     |
-| file     | string | 图片文件名               |
-| cache    | int    | 表示是否使用已缓存的文件 |
+| 字段       | 类型   | 说明                     |
+| ---------- | ------ | ------------------------ |
+| `group_id` | int64  | 群号                     |
+| `file`     | string | 图片文件名               |
+| `cache`    | int    | 表示是否使用已缓存的文件 |
 
 [1]`file` 参数支持以下几种格式：
 
@@ -614,78 +711,129 @@ Type: `tts`
 
 **响应数据**
 
-| 字段            | 类型       | 说明                            |
-| --------------- | ---------- | ------------------------------- |
-| app_initialized | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
-| app_enabled     | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
-| plugins_good    | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
-| app_good        | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
-| online          | bool       | 表示BOT是否在线                 |
-| goold           | bool       | 同 `online`                     |
-| stat            | Statistics | 运行统计                        |
+| 字段              | 类型       | 说明                            |
+| ----------------- | ---------- | ------------------------------- |
+| `app_initialized` | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
+| `app_enabled`     | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
+| `plugins_good`    | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
+| `app_good`        | bool       | 原 `CQHTTP` 字段, 恒定为 `true` |
+| `online`          | bool       | 表示BOT是否在线                 |
+| `goold`           | bool       | 同 `online`                     |
+| `stat`            | Statistics | 运行统计                        |
 
 **Statistics**
 
 
-| 字段             | 类型   | 说明             |
-| ---------------- | ------ | ---------------- |
-| packet_received  | uint64 | 收到的数据包总数 |
-| packet_sent      | uint64 | 发送的数据包总数 |
-| packet_lost      | uint32 | 数据包丢失总数   |
-| message_received | uint64 | 接受信息总数     |
-| message_sent     | uint64 | 发送信息总数     |
-| disconnect_times | uint32 | TCP链接断开次数  |
-| lost_times       | uint32 | 账号掉线次数     |
+| 字段               | 类型   | 说明             |
+| ------------------ | ------ | ---------------- |
+| `packet_received`  | uint64 | 收到的数据包总数 |
+| `packet_sent`      | uint64 | 发送的数据包总数 |
+| `packet_lost`      | uint32 | 数据包丢失总数   |
+| `message_received` | uint64 | 接受信息总数     |
+| `message_sent`     | uint64 | 发送信息总数     |
+| `disconnect_times` | uint32 | TCP链接断开次数  |
+| `lost_times`       | uint32 | 账号掉线次数     |
 
 > 注意: 所有统计信息都将在重启后重制
 
 ## 事件
 
-#### 好友戳一戳
+### 群消息撤回
 
 **上报数据**
 
-| 字段          | 类型   | 可能的值     | 说明                  |
-| ------------- | ------ | ------------ | --------------------- |
-| `post_type`   | string | `notice`     | 上报类型              |
-| `notice_type` | string | `group_card` | 通知类型              |
-| `sub_type`    | string | `poke`       | 事件子类型            |
-| `self_id`     | int64  |              | 收到事件的机器人QQ 号 |
-| `user_id`     | int64  |              | 发送者QQ号            |
-| `target_id`   | int64  |              | 被戳者QQ号            |
-| `time`        | int64  |              | 事件发生的时间戳      |
+| 字段          | 类型   | 可能的值       | 说明           |
+| ------------- | ------ | -------------- | -------------- |
+| `post_type`   | string | `notice`       | 上报类型       |
+| `notice_type` | string | `group_recall` | 消息类型       |
+| `group_id`    | int64  |                | 群号           |
+| `user_id`     | int64  |                | 消息发送者id   |
+| `operator_id` | int64  |                | 操作者id       |
+| `message_id`  | int64  |                | 被撤回的消息id |
 
-#### 群成员名片更新
+### 好友消息撤回
+
+**上报数据**
+
+| 字段          | 类型   | 可能的值        | 说明           |
+| ------------- | ------ | --------------- | -------------- |
+| `post_type`   | string | `notice`        | 上报类型       |
+| `notice_type` | string | `friend_recall` | 消息类型       |
+| `user_id`     | int64  |                 | 好友id         |
+| `message_id`  | int64  |                 | 被撤回的消息id |
+
+### 群内戳一戳
+
+> 注意：此事件无法在平板和手表协议上触发
+
+**上报数据**
+
+| 字段          | 类型   | 可能的值 | 说明     |
+| ------------- | ------ | -------- | -------- |
+| `post_type`   | string | `notice` | 上报类型 |
+| `notice_type` | string | `notify` | 消息类型 |
+| `group_id`    | int64  |          | 群号     |
+| `sub_type`    | string | `poke`   | 提示类型 |
+| `user_id`     | int64  |          | 发送者id |
+| `target_id`   | int64  |          | 被戳者id |
+
+### 群红包运气王提示
+
+> 注意：此事件无法在平板和手表协议上触发
+
+**上报数据**
+
+| 字段          | 类型   | 可能的值     | 说明         |
+| ------------- | ------ | ------------ | ------------ |
+| `post_type`   | string | `notice`     | 上报类型     |
+| `notice_type` | string | `notify`     | 消息类型     |
+| `group_id`    | int64  |              | 群号         |
+| `sub_type`    | string | `lucky_king` | 提示类型     |
+| `user_id`     | int64  |              | 红包发送者id |
+| `target_id`   | int64  |              | 运气王id     |
+
+### 群成员荣誉变更提示
+
+> 注意：此事件无法在平板和手表协议上触发
+
+**上报数据**
+
+| 字段          | 类型   | 可能的值                                                 | 说明     |
+| ------------- | ------ | -------------------------------------------------------- | -------- |
+| `post_type`   | string | `notice`                                                 | 上报类型 |
+| `notice_type` | string | `notify`                                                 | 消息类型 |
+| `group_id`    | int64  |                                                          | 群号     |
+| `sub_type`    | string | `honor`                                                  | 提示类型 |
+| `user_id`     | int64  |                                                          | 成员id   |
+| `honor_type`  | string | `talkative:龙王` `performer:群聊之火` `emotion:快乐源泉` | 荣誉类型 |
+
+### 群成员名片更新
 
 > 注意: 此事件不保证时效性，仅在收到消息时校验卡片
 
 **上报数据**
 
-| 字段          | 类型   | 可能的值     | 说明                  |
-| ------------- | ------ | ------------ | --------------------- |
-| `post_type`   | string | `notice`     | 上报类型              |
-| `notice_type` | string | `group_card` | 消息类型              |
-| `group_id`    | int64  |              | 群号                  |
-| `user_id`     | int64  |              | 成员id                |
-| `card_new`    | int64  |              | 新名片                |
-| `card_old`    | int64  |              | 旧名片                |
-| `self_id`     | int64  |              | 收到事件的机器人QQ 号 |
-| `time`        | int64  |              | 事件发生的时间戳      |
+| 字段          | 类型   | 可能的值     | 说明     |
+| ------------- | ------ | ------------ | -------- |
+| `post_type`   | string | `notice`     | 上报类型 |
+| `notice_type` | string | `group_card` | 消息类型 |
+| `group_id`    | int64  |              | 群号     |
+| `user_id`     | int64  |              | 成员id   |
+| `card_new`    | int64  |              | 新名片   |
+| `card_old`    | int64  |              | 旧名片   |
 
 > PS: 当名片为空时 `card_xx` 字段为空字符串, 并不是昵称
 
-#### 接收到离线文件
+### 接收到离线文件
 
 **上报数据**
 
-| 字段          | 类型   | 可能的值       | 说明                  |
-| ------------- | ------ | -------------- | --------------------- |
-| `post_type`   | string | `notice`       | 上报类型              |
-| `notice_type` | string | `offline_file` | 消息类型              |
-| `user_id`     | int64  |                | 发送者id              |
-| `self_id`     | int64  |                | 收到事件的机器人QQ 号 |
-| `time`        | int64  |                | 事件发生的时间戳      |
-| `file`        | object |                | 文件数据              |
+| 字段          | 类型   | 可能的值       | 说明     |
+| ------------- | ------ | -------------- | -------- |
+| `post_type`   | string | `notice`       | 上报类型 |
+| `notice_type` | string | `offline_file` | 消息类型 |
+| `user_id`     | int64  |                | 发送者id |
+| `file`        | object |                | 文件数据 |
 
 **file object**
 
@@ -693,4 +841,4 @@ Type: `tts`
 | ------ | ------ | -------- | -------- |
 | `name` | string |          | 文件名   |
 | `size` | int64  |          | 文件大小 |
-| `url`  | string |          | 下载链接 |
+| `url`  | string |          | 下载链接 |