improve doc

2025-05-04 19:17:37 +08:00 · 2020-12-08 20:24:48 +08:00 · 2020-12-08 20:24:48 +08:00 · e6de0c33cd
commit e6de0c33cd
parent de1cd8b314
1 changed files with 132 additions and 75 deletions
--- a/docs/cqhttp.md
+++ b/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,8 @@
 | 40004 | 爱你 |
 | 40005 | 征友 |

+示例: `[CQ:image,file=http://baidu.com/1.jpg,type=show,id=40004]`
+

 ### 回复

@ -36,7 +92,7 @@ Type : `reply`

 | 参数名 | 类型 | 说明                                  |
 | ------ | ---- | ------------------------------------- |
-| id     | int  | 回复时所引用的消息id, 必须为本群消息. |
+| `id`   | int  | 回复时所引用的消息id, 必须为本群消息. |

 示例: `[CQ:reply,id=123456]`

@ -49,8 +105,8 @@ Type: `redbag`
 参数:

 | 参数名  | 类型   | 说明        |
-| ------ | ------ | ----------- |
-| title  | string | 祝福语/口令 |
+| ------- | ------ | ----------- |
+| `title` | string | 祝福语/口令 |

 示例: `[CQ:redbag,title=恭喜发财]`

@ -66,7 +122,7 @@ Type: `poke`

 | 参数名 | 类型  | 说明         |
 | ------ | ----- | ------------ |
-| qq     | int64 | 需要戳的成员 |
+| `qq`   | int64 | 需要戳的成员 |

 示例: `[CQ:poke,qq=123456]`

@ -82,8 +138,8 @@ Type: `gift`

 | 参数名 | 类型  | 说明           |
 | ------ | ----- | -------------- |
-| qq     | int64 | 接收礼物的成员 |
-| id     | int   | 礼物的类型     |
+| `qq`   | int64 | 接收礼物的成员 |
+| `id`   | int   | 礼物的类型     |

 目前支持的礼物ID:

@ -117,8 +173,8 @@ Type: `forward`
 参数:

 | 参数名 | 类型   | 说明                                                         |
-| ------ | ------ | ------------------------------------------------------------- |
-| id     | string | 合并转发ID, 需要通过 `/get_forward_msg` API获取转发的具体内容 |
+| ------ | ------ | ------------------------------------------------------------ |
+| `id`   | string | 合并转发ID, 需要通过 `/get_forward_msg` API获取转发的具体内容 |

 示例: `[CQ:forward,id=xxxx]`

@ -131,11 +187,11 @@ 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套娃**

@ -209,7 +265,7 @@ Type: `node`
 ]
 ````

-### xml支持
+### xml 消息

 Type: `xml`

@ -218,9 +274,9 @@ Type: `xml`
 参数:

 | 参数名  | 类型   | 说明                                      |
-| ------ | ------ | ----------------------------------------- |
-| data   | string | xml内容，xml中的value部分，记得实体化处理 |
-| resid  | int32  | 可以不填                                  |
+| ------- | ------ | ----------------------------------------- |
+| `data`  | string | xml内容，xml中的value部分，记得实体化处理 |
+| `resid` | int32  | 可以不填                                  |

 示例: `[CQ:xml,data=xxxx]`

@ -258,7 +314,7 @@ Type: `xml`
 </msg>
 ```

-### json消息支持
+### JSON 消息

 Type: `json`

@ -267,19 +323,19 @@ 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;`

 否则无法正确得到解析

@ -289,7 +345,8 @@ json中的字符串需要进行转义：
 ```


-### cardimage 一种xml的图片消息（装逼大图）
+### cardimage
+一种xml的图片消息（装逼大图）

 ps: xml 接口的消息都存在风控风险，请自行兼容发送失败后的处理（可以失败后走普通图片模式）

@ -300,14 +357,14 @@ 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码：
@ -327,7 +384,7 @@ Type: `tts`

 | 参数名 | 类型   | 说明 |
 | ------ | ------ | ---- |
-| text   | string | 内容 |
+| `text` | string | 内容 |

 示例: `[CQ:tts,text=这是一条测试消息]`

@ -340,9 +397,9 @@ Type: `tts`
 **参数** 

 | 字段         | 类型   | 说明 |
-| ---------- | ------ | ---- |
-| group_id   | int64  | 群号 |
-| group_name | string | 新名 |
+| ------------ | ------ | ---- |
+| `group_id`   | int64  | 群号 |
+| `group_name` | string | 新名 |

 ### 设置群头像

@ -351,10 +408,10 @@ Type: `tts`
 **参数** 

 | 字段       | 类型   | 说明                     |
-| -------- | ------ | ------------------------ |
-| group_id | int64  | 群号                     |
-| file     | string | 图片文件名               |
-| cache    | int    | 表示是否使用已缓存的文件 |
+| ---------- | ------ | ------------------------ |
+| `group_id` | int64  | 群号                     |
+| `file`     | string | 图片文件名               |
+| `cache`    | int    | 表示是否使用已缓存的文件 |

 [1]`file` 参数支持以下几种格式：

@ -655,33 +712,33 @@ 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 | 账号掉线次数     |

 > 注意: 所有统计信息都将在重启后重制

 ## 事件

-#### 群消息撤回
+### 群消息撤回

 **上报数据**

@ -694,7 +751,7 @@ Type: `tts`
 | `operator_id` | int64  |                | 操作者id       |
 | `message_id`  | int64  |                | 被撤回的消息id |

-#### 好友消息撤回
+### 好友消息撤回

 **上报数据**

@ -705,7 +762,7 @@ Type: `tts`
 | `user_id`     | int64  |                 | 好友id         |
 | `message_id`  | int64  |                 | 被撤回的消息id |

-#### 群内戳一戳
+### 群内戳一戳

 > 注意：此事件无法在平板和手表协议上触发

@ -720,7 +777,7 @@ Type: `tts`
 | `user_id`     | int64  |          | 发送者id |
 | `target_id`   | int64  |          | 被戳者id |

-#### 群红包运气王提示
+### 群红包运气王提示

 > 注意：此事件无法在平板和手表协议上触发

@ -735,7 +792,7 @@ Type: `tts`
 | `user_id`     | int64  |              | 红包发送者id |
 | `target_id`   | int64  |              | 运气王id     |

-#### 群成员荣誉变更提示
+### 群成员荣誉变更提示

 > 注意：此事件无法在平板和手表协议上触发

@ -750,7 +807,7 @@ Type: `tts`
 | `user_id`     | int64  |                                                          | 成员id   |
 | `honor_type`  | string | `talkative:龙王` `performer:群聊之火` `emotion:快乐源泉` | 荣誉类型 |

-#### 群成员名片更新
+### 群成员名片更新

 > 注意: 此事件不保证时效性，仅在收到消息时校验卡片

@ -767,7 +824,7 @@ Type: `tts`

 > PS: 当名片为空时 `card_xx` 字段为空字符串, 并不是昵称

-#### 接收到离线文件
+### 接收到离线文件

 **上报数据**