Skip to content
This repository was archived by the owner on Aug 2, 2020. It is now read-only.

Commit 4b1e4bb

Browse files
stdrcstdrc
committed
Update docs for v4.5.0
1 parent e1a7e76 commit 4b1e4bb

File tree

16 files changed

+1965
-1
lines changed

16 files changed

+1965
-1
lines changed

‎docs/4.5/API.md‎

Lines changed: 718 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/4.5/CQCode.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# CQ 码
2+
3+
CQ 码的使用方式和酷 Q 原生的 CQ 码兼容（关于原生 CQ 码的使用，请看 [Pro/CQ码](https://d.cqp.me/Pro/CQ%E7%A0%81)），在要发送的消息中插入相应的代码即可，例如：
4+
5+
```
6+
[CQ:face,id=14] [CQ:image,file=1.jpg]
7+
```
8+
9+
对于字符串格式表示的消息，使用方式和原生 CQ 码完全兼容**意味着需要对特殊字符字符进行转义**，由于很多时候我们不需要使用 CQ 码，只需要发送文字消息就行了，这种情况下可以在请求 API 时加入 `auto_escape` 参数，这将会自动对整个消息的特殊字符进行转义，具体请看 [API 描述](/API)。
10+
11+
而使用数组格式的消息段来表示 CQ 码，则无需进行转义。
12+
13+
除了原生的 CQ 码，CoolQ HTTP API 还提供了一些实用的增强功能（对字符串和数组格式的消息均有效，下面将以字符串为例），称之为「增强 CQ 码」。
14+
15+
## 增强功能列表
16+
17+
### 发送
18+
19+
#### 发送网络图片或语音
20+
21+
酷 Q 原生的 CQ 码只能发送 `data\image` 文件夹里的图片、`data\record` 里的语音，增强 CQ 码支持设置 `file` 为网络链接，内部会首先把图片或语音下载到 `data` 中相应的文件夹，然后把 `file` 替换成下载好的本地文件名。例如：
22+
23+
```
24+
[CQ:image,file=http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg]
25+
[CQ:record,file=http://doora.qiniudn.com/35aIm.silk]
26+
```
27+
28+
由于从网络下载可能比较耗时，插件默认情况下会在第二次发送同一链接时，直接采用本地缓存，如果要发送的图片或语音的链接内容有变，不宜使用缓存，则可以在 CQ 码中加入参数 `cache=0` 来禁用缓存（仅本次有效），例如：
29+
30+
```
31+
[CQ:image,cache=0,file=http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg]
32+
```
33+
34+
另外，插一个题外话，如果要发送非 SILK 格式的音频文件，需要安装酷 Q 的 [语音组件](https://cqp.cc/t/21132)，否则会出现错误码 -11。
35+
36+
#### 发送文件系统中另一个地方的图片或语音
37+
38+
除了发送网络上的图片、语音，还可以发送本地文件系统中其它地方的图片、语音，使用 [`file` URI](https://tools.ietf.org/html/rfc8089) 格式，例如：
39+
40+
```
41+
[CQ:image,file=file:///C:\Users\richard\Pictures\1.png]
42+
[CQ:record,file=file:///C:\Users\richard\Music\1.mp3]
43+
```
44+
45+
#### 发送 base64 编码的图片或语音
46+
47+
除了指定实体文件，也可以直接将文件用 base64 编码后放在 CQ 码参数中传递，使用 `base64://` 加 base64 编码，例如：
48+
49+
```
50+
[CQ:image,file=base64://iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAKElEQVQ4EWPk5+RmIBcwkasRpG9UM4mhNxpgowFGMARGEwnBIEJVAAAdBgBNAZf+QAAAAABJRU5ErkJggg==]
51+
```
52+
53+
### 接收
54+
55+
#### 提取 cqimg 文件中的实际图片 URL
56+
57+
酷 Q 收到的图片会放在 `data\image` 中，并且以文件名加 `.cqimg` 扩展名的形式存储为纯文本文件，实际的图片 URL 就在里面的 `url` 字段，增强 CQ 码会自动提取这个 URL，并添加到 CQ 码的 `url` 参数中。
58+
59+
例如，假设原 CQ 码如下：
60+
61+
```
62+
[CQ:image,file=AE3062186A2073B33AB1F2BB2F58F3A4.jpg]
63+
```
64+
65+
提取 URL 后，会更改为：
66+
67+
```
68+
[CQ:image,file=AE3062186A2073B33AB1F2BB2F58F3A4.jpg,url=http://183.232.95.26/offpic_new/1002647525//8102132e-4ab0-46cf-a8e1-2f62185232cb/0]
69+
```
70+
71+
如果提取不成功（读取文件失败），则不变。
72+
73+
**另外请注意，这个 URL 会在一定时间后过期（不确定多久），但酷 Q 在收到以前收过的图之后，仍然会返回同样的文件名，因此建议定期清理 `data\image` 目录以防止 URL 失效。**
74+
75+
## 原生 CQ 码的非官方补充
76+
77+
CQ 码虽然在一定程度上具有较强的消息表达能力，但由于 QQ 的经常更新以及酷 Q 协议的更新不及时，导致 CQ 码的使用中会遇到很多坑。要重新整理一份完整的 CQ 码列表比较麻烦，因此这里只给出一条一条的坑的记录，见 [CQ 码的坑](https://github.com/richardchien/coolq-http-api/wiki/CQ-%E7%A0%81%E7%9A%84%E5%9D%91)。

‎docs/4.5/CommunicationMethods.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# 通信方式
2+
3+
目前支持三种通信方式：
4+
5+
- 插件作为 HTTP 服务端，提供 API 和数据文件获取服务
6+
- 插件作为 WebSocket 服务端，通过 `/api/` 和 `/event/` 两个接口分别提供 API 调用和事件推送服务
7+
- 插件作为 WebSocket 客户端（称为「反向 WebSocket」），主动连接给定的 API 和事件上报地址，分别提供 API 调用服务和事件上报服务
8+
9+
上面三种通信方式分别使用 `use_http`、`use_ws`、`use_ws_reverse` 三个配置项来开关。
10+
11+
除了上述通信方式，还有通过 HTTP 上报事件，这是永远可用的，**不受上面三个 `use_*` 配置控制**，只要配置了 `post_url`，就会上报，并且处理响应数据。
12+
13+
下面详细介绍上面的三种通信方式的适用场景和使用方法，你可以根据需要选择其一或者适当组合使用。
14+
15+
## 插件作为 HTTP 服务端
16+
17+
### 适用场景
18+
19+
这是本插件最初支持的通信方式，也是使用起来最方便快捷的方式，适用于以下情况：
20+
21+
- 在本地初步测试使用酷 Q 和本插件，需要快速测试接口、查看接口返回的数据
22+
- 运行酷 Q 的机器有公网 IP，或酷 Q 和业务代码运行在同一机器上
23+
- 对于数据文件访问有需求
24+
- ...
25+
26+
### 使用方法
27+
28+
将 `use_http` 配置为 `yes`（默认即 `yes`），然后通过 `host`、`port` 来配置要监听的 IP 和端口（默认为 `0.0.0.0:5700`），启用插件后即可通过形如 `http://host:port/send_private_msg?user_id=1234567&message=hello` 的 URL 来调用 API。
29+
30+
具体的 API 调用方法和 API 列表见 [API 描述](/API)。
31+
32+
## 插件作为 WebSocket 服务端
33+
34+
### 适用场景
35+
36+
- 运行酷 Q 的机器有公网 IP，或酷 Q 和业务代码运行在同一机器上
37+
- 业务代码运行环境无法通过 HTTP 上报获得事件（例如浏览器中）
38+
- ...
39+
40+
### 使用方法
41+
42+
将 `use_ws` 配置为 `yes`（默认 `no`），然后通过 `ws_host`、`ws_port` 来配置要监听的 IP 和端口（默认为 `0.0.0.0:6700`），启用插件后即可通过 `ws://ws_host:ws_port/api/` 接口来调用 API，通过 `ws://ws_host:ws_port/event/` 来接收事件推送。
43+
44+
这两个接口的具体用法见 [WebSocket API 描述](/WebSocketAPI)。
45+
46+
## 插件作为 WebSocket 客户端（反向 WebSocket）
47+
48+
### 适用场景
49+
50+
- 运行酷 Q 的机器没有公网 IP，且业务代码有公网 IP，或两者运行在同一机器上
51+
- ...
52+
53+
### 使用方法
54+
55+
在业务代码中启动 WebSocket 服务端，开启两个接口，分别用于 API 调用和事件上报（如果只需要一个功能，也可以只开一个），然后分别配置 `ws_reverse_api_url`、`ws_reverse_event_url` 为上述两个接口的完整地址，例如 `ws://127.0.0.1:8765/api/`。再将 `use_ws_reverse` 配置为 `yes`（默认为 `no`），重启插件即可开启反向 WebSocket 服务。
56+
57+
插件会在特定的时候向指定的 URL 建立连接，并且在请求头中通过 `X-Self-ID` 来表示当前正在建立连接的机器人 QQ 号，以及通过 `X-Client-Role` 来表示当前正在建立连接的客户端类型，如：
58+
59+
```http
60+
X-Self-ID: 123456
61+
X-Client-Role: Event
62+
```
63+
64+
其中，`X-Client-Role` 可能为 `Event` 和 `API`，分别对应事件上报和 API 的两个连接。`X-Client-Role` 头的存在意味着你可以将 `ws_reverse_api_url` 和 `ws_reverse_event_url` 设置为相同的地址，或简单地使用 `ws_reverse_url` 来配置共用地址即可，然后只需要在 WebSocket 后端对请求头进行判断即可知道是哪个账号的哪个客户端在连接。
65+
66+
如果配置了 `access_token`，则在建立连接时，还会加入 `Authorization` 请求头，例如：
67+
68+
```http
69+
Authorization: Token kSLuTF2GC2Q4q4ugm3
70+
X-Self-ID: 123456
71+
```
72+
73+
#### API 调用
74+
75+
首先插件启用时会启动一个**保持连接**的客户端用于连接 API 调用接口，即 `ws_reverse_api_url` 指定的接口，一旦收到服务端发来的消息就会调用相应的 API 并返回调用结果。
76+
77+
API 的调用方式和插件作为 WebSocket 服务端的 `/api/` 接口使用方式相同，见 [WebSocket API 描述的 `/api/`](/WebSocketAPI#api)，不同在于你的服务端必须在调用 API 后保持连接，以便下次调用。
78+
79+
#### 事件上报
80+
81+
插件启动时会启动一个**保持连接**的客户端用于连接事件上报接口，即 `ws_reverse_event_url` 指定的接口，在后续接收到酷 Q 的事件时，会通过这个连接发送事件数据。发送事件数据格式和 HTTP POST 方式上报的完全一致，见 [上报数据格式](/Post#上报数据格式)，事件列表见 [事件列表](/Post#事件列表)。
82+
83+
与 HTTP 上报不同的是，这里上报不会对数据进行签名（即 HTTP 上报中的 `X-Signature` 请求头在这里没有等价的东西），并且也不会处理响应数据。
84+
85+
### 断线重连
86+
87+
可通过配置项 `ws_reverse_reconnect_interval` 和 `ws_reverse_reconnect_on_code_1000` 来配置反向 WebSocket 的断线重连机制，分别设置尝试重连的时间间隔，和是否在关闭码 1000 的情况下进行重连。
88+
89+
如果你的服务器重启时插件没有自动重连，建议尝试设置 `ws_reverse_reconnect_on_code_1000 = yes`。
90+
91+
## WebSocket 的 API 调用响应顺序问题
92+
93+
由于 WebSocket 的通信不像 HTTP 那样是固定的一来一回，而是一直保持连接，大多 WebSocket 框架都采用事件驱动的方式来提供接口。这就导致，在通过 WebSocket 进行**连续** API 调用时，很多情况下无法确切地知道插件返回的响应是对应哪次调用。因此插件现加入了 echo 机制，允许用户在调用 API 时在调用数据（JSON 对象）中加入一个 `echo` 字段（数据类型任意），以标记此次调用，插件会在该调用的响应数据中将其原样返回。
94+
95+
### 调用示例
96+
97+
```json
98+
{
99+
"action": "send_private_msg",
100+
"params": {
101+
"user_id": 123456,
102+
"message": "你好"
103+
},
104+
"echo": 1648451782
105+
}
106+
```
107+
108+
### 响应示例
109+
110+
```json
111+
{
112+
"status": "ok",
113+
"retcode": 0,
114+
"data": null,
115+
"echo": 1648451782
116+
}
117+
```

‎docs/4.5/Configuration.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# 配置
2+
3+
配置文件支持 INI 和 JSON 两种格式，并支持单个文件配置多个账号，或每个账号对应一个配置文件。
4+
5+
插件启动时（或重启时）按如下顺序依次尝试加载配置文件，一旦有一条加载成功，则停止加载（所有路径均为相对于 `app\io.github.richardchien.coolqhttpapi` 的相对路径）：
6+
7+
- `config.(cfg|ini)`（扩展名的括号和竖线表示优先加载 `.cfg`，若没有，则加载 `.ini`，下同），文件中通用配置需要放在 `[general]` 下，QQ 号特定配置放在 `[<user_id>]` 下
8+
- `config\general.(cfg|ini)` + `config\<user_id>.(cfg|ini)`，前者是通用配置，全部放在 `[general]` 下，后者是 QQ 号特定配置，全部放在 `[<user_id>]` 下，后者覆盖前者中已存在的内容
9+
- `config.json`，通用配置需放在根对象的 `general` 字段，QQ 号特定配置放在 QQ 号对应字段，例如 `{"general": {"host": "0.0.0.0"}, "123456": {"port": 6666}}`
10+
- `config\general.json` + `config\<user_id>.json`，配置项均直接放在根对象，后者覆盖前者中已存在的内容
11+
12+
**重要：如果配置文件中需要使用中文或其它非 ASCII 字符，则必须使用 UTF-8 without BOM 编码保存文件！**
13+
14+
## 几种典型的配置文件安排方式
15+
16+
### 使用 INI 格式，在单个文件中存放多个账号的配置
17+
18+
- `app\io.github.richardchien.coolqhttpapi\config.ini`
19+
20+
```ini
21+
[general]
22+
host = 0.0.0.0
23+
post_url = http://192.168.0.11:8888
24+
25+
[12345678]
26+
access_token = Mgep4rV49rM8Jf
27+
port = 5700
28+
29+
[87654321]
30+
port = 5701
31+
```
32+
33+
### 使用 JSON 格式，在单个文件中存放多个账号的配置
34+
35+
- `app\io.github.richardchien.coolqhttpapi\config.json`
36+
37+
```json
38+
{
39+
"general": {
40+
"host": "0.0.0.0",
41+
"post_url": "http://127.0.0.1:8080"
42+
},
43+
"12345678": {
44+
"access_token": "Mgep4rV49rM8Jf",
45+
"port": 5700
46+
},
47+
"87654321": {
48+
"port": 5701
49+
}
50+
}
51+
```
52+
53+
### 使用 JSON 格式，每个账号对应一个配置文件
54+
55+
- `app\io.github.richardchien.coolqhttpapi\config\general.json`
56+
57+
```json
58+
{
59+
"host": "0.0.0.0",
60+
"post_url": "http://127.0.0.1:8080"
61+
}
62+
```
63+
64+
- `app\io.github.richardchien.coolqhttpapi\config\12345678.json`
65+
66+
```json
67+
{
68+
"access_token": "Mgep4rV49rM8Jf",
69+
"port": 5700
70+
}
71+
```
72+
73+
- `app\io.github.richardchien.coolqhttpapi\config\87654321.json`
74+
75+
```json
76+
{
77+
"port": 5701
78+
}
79+
```
80+
81+
## 配置项
82+
83+
| 配置项名称 | 默认值 | 说明 |
84+
| -------- | ------ | --- |
85+
| `host` | `0.0.0.0` | HTTP 服务器监听的 IP |
86+
| `port` | `5700` | HTTP 服务器监听的端口 |
87+
| `use_http` | `true` | 是否开启 HTTP 接口，即通过 HTTP 调用 API，见 [通信方式的第一种](/CommunicationMethods#插件作为-http-服务端) |
88+
| `ws_host` | `0.0.0.0` | WebSocket 服务器监听的 IP |
89+
| `ws_port` | `6700` | WebSocket 服务器监听的端口 |
90+
| `use_ws` | `false` | 是否开启 WebSocket 服务器，可用于调用 API 和推送事件，见 [通信方式的第二种](/CommunicationMethods#插件作为-websocket-服务端) |
91+
| `ws_reverse_url` | 空 | 反向 WebSocket Event 和事件上报的共用地址 |
92+
| `ws_reverse_api_url` | 空 | 反向 WebSocket API 地址，如果为空，则使用 `ws_reverse_url` 指定的值 |
93+
| `ws_reverse_event_url` | 空 | 反向 WebSocket 事件上报地址，如果为空，则使用 `ws_reverse_url` 指定的值 |
94+
| `ws_reverse_reconnect_interval` | `3000` | 反向 WebSocket 客户端断线重连间隔，单位毫秒 |
95+
| `ws_reverse_reconnect_on_code_1000` | `true` | 是否在关闭状态码为 1000 的时候重连 |
96+
| `use_ws_reverse` | `false` | 是否使用反向 WebSocket 服务，即插件作为 WebSocket 客户端主动连接指定的 API 和事件上报地址，见 [通信方式的第三种](/CommunicationMethods#插件作为-websocket-客户端（反向-websocket）) |
97+
| `post_url` | 空 | 消息和事件的上报地址，通过 POST 方式请求，数据以 JSON 格式发送 |
98+
| `post_timeout` | `0` | HTTP 上报（即访问 `post_url`）的超时时间（单位：秒），0 表示不设置超时 |
99+
| `access_token` | 空 | API 访问 token，如果不为空，则会在接收到请求时验证 `Authorization` 请求头是否为 `Token xxxxxxxx`，`xxxxxxxx` 为 access token |
100+
| `secret` | 空 | 上报数据签名密钥，如果不为空，则会在 HTTP 上报时对 HTTP 正文进行 HMAC SHA1 哈希，使用 `secret` 的值作为密钥，计算出的哈希值放在上报的 `X-Signature` 请求头，例如 `X-Signature: sha1=f9ddd4863ace61e64f462d41ca311e3d2c1176e2` |
101+
| `post_message_format` | `string` | 上报消息格式，`string` 为字符串格式，`array` 为数组格式，具体见 [消息格式](/Message) |
102+
| `serve_data_files` | `false` | 是否提供请求 `data` 目录的文件的功能 |
103+
| `update_source` | `github` | 更新源，默认使用托管在 GitHub 的 [richardchien/coolq-http-api-release](https://github.com/richardchien/coolq-http-api-release) 仓库，对于酷 Q 运行在国内的情况，可以换成 `gitee` |
104+
| `update_channel` | `stable` | 更新通道，目前有 `stable`、`beta`、`alpha` 三个 |
105+
| `auto_check_update` | `false` | 是否自动检查更新（每次启用插件时检查），不启用的情况下，仍然可以在酷 Q 应用菜单中手动检查更新 |
106+
| `auto_perform_update` | `false` | 是否自动执行更新，仅在 `auto_check_update` 启用时有效，若启用，则插件将在自动检查到更新后，自动下载新版本并重启酷 Q 生效 |
107+
| `thread_pool_size` | `4` | 工作线程池大小，用于异步发送消息和一些其它小的异步任务，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |
108+
| `server_thread_pool_size` | `4` | API 服务器线程池大小，用于异步处理请求，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |
109+
| `convert_unicode_emoji` | `true` | 是否在 CQ:emoji 和实际的 Unicode 之间进行转换，转换可能耗更多时间，但日常情况下影响不大，如果你的机器人需要处理非常大段的消息（上千字），且对性能有要求，可以考虑关闭转换 |
110+
| `event_filter` | 空 | 指定事件过滤规则文件，见 [事件过滤器](/EventFilter)，留空将不开启事件过滤器 |
111+
| `enable_backward_compatibility` | `false` | 是否启用旧版兼容性，启用时**事件上报**的数据将和 3.x 版本保持兼容 |
112+
| `show_log_console` | `false` | 是否显示日志输出控制台 |
113+
| `max_log_file_size` | `6291456` | 最大单日志文件大小，默认 6 MB |
114+
| `max_log_files` | `1` | 最大日志文件备份数量（采用日志轮替机制） |
115+
| `log_level` | `info` | 日志文件和日志控制台的日志等级，可选 `debug`、`info`、`warning`、`error`、`fatal` |
116+
| `use_extension` | `false` | 是否启用扩展机制，见 [扩展](/Extension) |
117+
| `disable_coolq_log` | `true` | 是否禁用酷 Q 原生日志，由于使用酷 Q 原生日志可能会导致快速重启时插件卡死，所以默认禁用，如果你不在乎重启时卡死，并且需要在酷 Q 原生日志窗口查看插件的日志，可以将此项设为 false |
118+
| `online_status_detection_method` | `log_db` | QQ 在线状态检测方式，默认（`log_db`）从酷 Q 的日志数据库判断，设为 `get_stranger_info` 可切换成通过查询陌生人接口判断（频繁请求可能导致结果不准） |
119+
| `enable_heartbeat` | `false` | 是否启用心跳机制，启用时会产生类型为 `heartbeat` 的元事件，见 [元事件](/Post#元事件) |
120+
| `heartbeat_interval` | `15000` | 产生心跳元事件的时间间隔，默认 15 秒 |

0 commit comments

Comments
 (0)