shkong/go-cqhttp
1
0
Fork 0
mirror of https://github.com/Mrs4s/go-cqhttp.git synced 2025-05-05 03:23:49 +08:00
Code Issues Projects Releases Wiki Activity

improve doc

Browse Source
This commit is contained in:
Yiwen-Chan 2020-12-08 20:24:48 +08:00
parent de1cd8b314
commit e6de0c33cd
1 changed files with 132 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
docs/cqhttp.md
View File

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