Add docs for v4.7

kyubotics · Dec 11, 2018 · edf4355 · edf4355
1 parent 2229d81
commit edf4355
Show file tree

Hide file tree

Showing 16 changed files with 1,993 additions and 1 deletion.
diff --git a/docs/4.7/API.md b/docs/4.7/API.md
diff --git a/docs/4.7/CQCode.md b/docs/4.7/CQCode.md
@@ -0,0 +1,77 @@
+# CQ 码
+
+CQ 码的使用方式和酷 Q 原生的 CQ 码兼容（关于原生 CQ 码的使用，请看 [Pro/CQ码](https://d.cqp.me/Pro/CQ%E7%A0%81)），在要发送的消息中插入相应的代码即可，例如：
+
+```
+[CQ:face,id=14] [CQ:image,file=1.jpg]
+```
+
+对于字符串格式表示的消息，使用方式和原生 CQ 码完全兼容**意味着需要对特殊字符字符进行转义**，由于很多时候我们不需要使用 CQ 码，只需要发送文字消息就行了，这种情况下可以在请求 API 时加入 `auto_escape` 参数，这将会自动对整个消息的特殊字符进行转义，具体请看 [API 描述](/API)。
+
+而使用数组格式的消息段来表示 CQ 码，则无需进行转义。
+
+除了原生的 CQ 码，CoolQ HTTP API 还提供了一些实用的增强功能（对字符串和数组格式的消息均有效，下面将以字符串为例），称之为「增强 CQ 码」。
+
+## 增强功能列表
+
+### 发送
+
+#### 发送网络图片或语音
+
+酷 Q 原生的 CQ 码只能发送 `data\image` 文件夹里的图片、`data\record` 里的语音，增强 CQ 码支持设置 `file` 为网络链接，内部会首先把图片或语音下载到 `data` 中相应的文件夹，然后把 `file` 替换成下载好的本地文件名。例如：
+
+```
+[CQ:image,file=http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg]
+[CQ:record,file=http://doora.qiniudn.com/35aIm.silk]
+```
+
+由于从网络下载可能比较耗时，插件默认情况下会在第二次发送同一链接时，直接采用本地缓存，如果要发送的图片或语音的链接内容有变，不宜使用缓存，则可以在 CQ 码中加入参数 `cache=0` 来禁用缓存（仅本次有效），例如：
+
+```
+[CQ:image,cache=0,file=http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg]
+```
+
+另外，插一个题外话，如果要发送非 SILK 格式的音频文件，需要安装酷 Q 的 [语音组件](https://cqp.cc/t/21132)，否则会出现错误码 -11。
+
+#### 发送文件系统中另一个地方的图片或语音
+
+除了发送网络上的图片、语音，还可以发送本地文件系统中其它地方的图片、语音，使用 [`file` URI](https://tools.ietf.org/html/rfc8089) 格式，例如：
+
+```
+[CQ:image,file=file:///C:\Users\richard\Pictures\1.png]
+[CQ:record,file=file:///C:\Users\richard\Music\1.mp3]
+```
+
+#### 发送 base64 编码的图片或语音
+
+除了指定实体文件，也可以直接将文件用 base64 编码后放在 CQ 码参数中传递，使用 `base64://` 加 base64 编码，例如：
+
+```
+[CQ:image,file=base64://iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAKElEQVQ4EWPk5+RmIBcwkasRpG9UM4mhNxpgowFGMARGEwnBIEJVAAAdBgBNAZf+QAAAAABJRU5ErkJggg==]
+```
+
+### 接收
+
+#### 提取 cqimg 文件中的实际图片 URL
+
+酷 Q 收到的图片会放在 `data\image` 中，并且以文件名加 `.cqimg` 扩展名的形式存储为纯文本文件，实际的图片 URL 就在里面的 `url` 字段，增强 CQ 码会自动提取这个 URL，并添加到 CQ 码的 `url` 参数中。
+
+例如，假设原 CQ 码如下：
+
+```
+[CQ:image,file=AE3062186A2073B33AB1F2BB2F58F3A4.jpg]
+```
+
+提取 URL 后，会更改为：
+
+```
+[CQ:image,file=AE3062186A2073B33AB1F2BB2F58F3A4.jpg,url=http://183.232.95.26/offpic_new/1002647525//8102132e-4ab0-46cf-a8e1-2f62185232cb/0]
+```
+
+如果提取不成功（读取文件失败），则不变。
+
+**另外请注意，这个 URL 会在一定时间后过期（不确定多久），但酷 Q 在收到以前收过的图之后，仍然会返回同样的文件名，因此建议定期清理 `data\image` 目录以防止 URL 失效。**
+
+## 原生 CQ 码的非官方补充
+
+CQ 码虽然在一定程度上具有较强的消息表达能力，但由于 QQ 的经常更新以及酷 Q 协议的更新不及时，导致 CQ 码的使用中会遇到很多坑。要重新整理一份完整的 CQ 码列表比较麻烦，因此这里只给出一条一条的坑的记录，见 [CQ 码的坑](https://github.com/richardchien/coolq-http-api/wiki/CQ-%E7%A0%81%E7%9A%84%E5%9D%91)。
diff --git a/docs/4.7/CommunicationMethods.md b/docs/4.7/CommunicationMethods.md
@@ -0,0 +1,119 @@
+# 通信方式
+
+目前支持三种通信方式：
+
+- 插件作为 HTTP 服务端，提供 API 和数据文件获取服务
+- 插件作为 WebSocket 服务端，通过 `/api/` 和 `/event/` 两个接口分别提供 API 调用和事件推送服务
+- 插件作为 WebSocket 客户端（称为「反向 WebSocket」），主动连接给定的 API 和事件上报地址，分别提供 API 调用服务和事件上报服务
+
+上面三种通信方式分别使用 `use_http`、`use_ws`、`use_ws_reverse` 三个配置项来开关。
+
+除了上述通信方式，还有通过 HTTP 上报事件，这是永远可用的，**不受上面三个 `use_*` 配置控制**，只要配置了 `post_url`，就会上报，并且处理响应数据。
+
+下面详细介绍上面的三种通信方式的适用场景和使用方法，你可以根据需要选择其一或者适当组合使用。
+
+## 插件作为 HTTP 服务端
+
+### 适用场景
+
+这是本插件最初支持的通信方式，也是使用起来最方便快捷的方式，适用于以下情况：
+
+- 在本地初步测试使用酷 Q 和本插件，需要快速测试接口、查看接口返回的数据
+- 运行酷 Q 的机器有公网 IP，或酷 Q 和业务代码运行在同一机器上
+- 对于数据文件访问有需求
+- ...
+
+### 使用方法
+
+将 `use_http` 配置为 `true`（默认即 `true`），然后通过 `host`、`port` 来配置要监听的 IP 和端口（默认为 `0.0.0.0:5700`），启用插件后即可通过形如 `http://host:port/send_private_msg?user_id=1234567&message=hello` 的 URL 来调用 API。
+
+具体的 API 调用方法和 API 列表见 [API 描述](/API)。
+
+## 插件作为 WebSocket 服务端
+
+### 适用场景
+
+- 运行酷 Q 的机器有公网 IP，或酷 Q 和业务代码运行在同一机器上
+- 业务代码运行环境无法通过 HTTP 上报获得事件（例如浏览器中）
+- ...
+
+### 使用方法
+
+将 `use_ws` 配置为 `true`（默认 `false`），然后通过 `ws_host`、`ws_port` 来配置要监听的 IP 和端口（默认为 `0.0.0.0:6700`），启用插件后即可通过 `ws://ws_host:ws_port/api/` 接口来调用 API，通过 `ws://ws_host:ws_port/event/` 来接收事件推送，通过 `ws://ws_host:ws_port/` 接口来在同一条连接上调用 API 和接收事件推送（相当于 `/api/` 和 `/event/` 接口的合并，对接收到的数据可通过 `post_type` 字段来判断是 API 响应还是事件）。
+
+这两个接口的具体用法见 [WebSocket API 描述](/WebSocketAPI)。
+
+## 插件作为 WebSocket 客户端（反向 WebSocket）
+
+### 适用场景
+
+- 运行酷 Q 的机器没有公网 IP，且业务代码有公网 IP，或两者运行在同一机器上
+- ...
+
+### 使用方法
+
+在业务代码中启动 WebSocket 服务端，开启两个接口，分别用于 API 调用和事件上报（如果只需要一个功能，也可以只开一个），然后分别配置 `ws_reverse_api_url`、`ws_reverse_event_url` 为上述两个接口的完整地址，例如 `ws://127.0.0.1:8765/api/`。再将 `use_ws_reverse` 配置为 `true`（默认为 `false`），重启插件即可开启反向 WebSocket 服务。
+
+插件会在特定的时候向指定的 URL 建立连接，并且在请求头中通过 `X-Self-ID` 来表示当前正在建立连接的机器人 QQ 号，以及通过 `X-Client-Role` 来表示当前正在建立连接的客户端类型，如：
+
+```http
+X-Self-ID: 123456
+X-Client-Role: Event
+```
+
+其中，`X-Client-Role` 可能为 `Event` 和 `API`，分别对应事件上报和 API 的两个连接。`X-Client-Role` 头的存在意味着你可以将 `ws_reverse_api_url` 和 `ws_reverse_event_url` 设置为相同的地址，或简单地使用 `ws_reverse_url` 来配置共用地址即可，然后只需要在 WebSocket 后端对请求头进行判断即可知道是哪个账号的哪个客户端在连接。
+
+除了使用 API 和 Event 双连接的方式，还可以通过将配置项 `ws_reverse_use_universal_client` 设为 `true`（默认 `false`）来让插件**只向 `ws_reverse_url` 建立一条连接**，`X-Client-Role` 为 `Universal`，API 和 Event 的数据均从这条连接上传输（相当于 API 和 Event 客户端的合并，对接收到的数据可通过 `post_type` 字段来判断是 API 响应还是事件）。Universal 客户端单连接的使用方式和分开的 API 和 Event 完全一致，下面不在单独说明。
+
+如果配置了 `access_token`，则在建立连接时，还会加入 `Authorization` 请求头，例如：
+
+```http
+Authorization: Token kSLuTF2GC2Q4q4ugm3
+X-Self-ID: 123456
+```
+
+#### API 调用
+
+首先插件启用时会启动一个**保持连接**的客户端用于连接 API 调用接口，即 `ws_reverse_api_url` 指定的接口，一旦收到服务端发来的消息就会调用相应的 API 并返回调用结果。
+
+API 的调用方式和插件作为 WebSocket 服务端的 `/api/` 接口使用方式相同，见 [WebSocket API 描述的 `/api/`](/WebSocketAPI#api)，不同在于你的服务端必须在调用 API 后保持连接，以便下次调用。
+
+#### 事件上报
+
+插件启动时会启动一个**保持连接**的客户端用于连接事件上报接口，即 `ws_reverse_event_url` 指定的接口，在后续接收到酷 Q 的事件时，会通过这个连接发送事件数据。发送事件数据格式和 HTTP POST 方式上报的完全一致，见 [上报数据格式](/Post#上报数据格式)，事件列表见 [事件列表](/Post#事件列表)。
+
+与 HTTP 上报不同的是，这里上报不会对数据进行签名（即 HTTP 上报中的 `X-Signature` 请求头在这里没有等价的东西），并且也不会处理响应数据。
+
+### 断线重连
+
+可通过配置项 `ws_reverse_reconnect_interval` 和 `ws_reverse_reconnect_on_code_1000` 来配置反向 WebSocket 的断线重连机制，分别设置尝试重连的时间间隔，和是否在关闭码 1000 的情况下进行重连。
+
+如果你的服务器重启时插件没有自动重连，建议尝试设置 `ws_reverse_reconnect_on_code_1000 = yes`。
+
+## WebSocket 的 API 调用响应顺序问题
+
+由于 WebSocket 的通信不像 HTTP 那样是固定的一来一回，而是一直保持连接，大多 WebSocket 框架都采用事件驱动的方式来提供接口。这就导致，在通过 WebSocket 进行**连续** API 调用时，很多情况下无法确切地知道插件返回的响应是对应哪次调用。因此插件现加入了 echo 机制，允许用户在调用 API 时在调用数据（JSON 对象）中加入一个 `echo` 字段（数据类型任意），以标记此次调用，插件会在该调用的响应数据中将其原样返回。
+
+### 调用示例
+
+```json
+{
+    "action": "send_private_msg",
+    "params": {
+        "user_id": 123456,
+        "message": "你好"
+    },
+    "echo": 1648451782
+}
+```
+
+### 响应示例
+
+```json
+{
+    "status": "ok",
+    "retcode": 0,
+    "data": null,
+    "echo": 1648451782
+}
+```
diff --git a/docs/4.7/Configuration.md b/docs/4.7/Configuration.md
@@ -0,0 +1,123 @@
+# 配置
+
+配置文件支持 INI 和 JSON 两种格式，并支持单个文件配置多个账号，或每个账号对应一个配置文件。
+
+插件启动时（或重启时）按如下顺序依次尝试加载配置文件，一旦有一条加载成功，就停止加载（所有路径均为相对于 `data\app\io.github.richardchien.coolqhttpapi` 的相对路径）：
+
+- `config.(cfg|ini)`（扩展名的括号和竖线表示优先加载 `.cfg`，若没有，则加载 `.ini`，下同），文件中通用配置需要放在 `[general]` 下，QQ 号特定配置放在 `[<user_id>]` 下
+- `config\general.(cfg|ini)` + `config\<user_id>.(cfg|ini)`，前者是通用配置，全部放在 `[general]` 下，后者是 QQ 号特定配置，全部放在 `[<user_id>]` 下，后者覆盖前者中已存在的内容
+- `config.json`，通用配置需放在根对象的 `general` 字段，QQ 号特定配置放在 QQ 号对应字段，例如 `{"general": {"host": "0.0.0.0"}, "123456": {"port": 6666}}`
+- `config\general.json` + `config\<user_id>.json`，配置项均直接放在根对象，后者覆盖前者中已存在的内容
+
+**重要：如果配置文件中需要使用中文或其它非 ASCII 字符，则必须使用 UTF-8 without BOM 编码保存文件！**
+
+## 几种典型的配置文件安排方式
+
+### 使用 INI 格式，在单个文件中存放多个账号的配置
+
+- `data\app\io.github.richardchien.coolqhttpapi\config.ini`
+
+```ini
+[general]
+host = 0.0.0.0
+post_url = http://192.168.0.11:8888
+
+[12345678]
+access_token = Mgep4rV49rM8Jf
+port = 5700
+
+[87654321]
+port = 5701
+```
+
+### 使用 JSON 格式，在单个文件中存放多个账号的配置
+
+- `data\app\io.github.richardchien.coolqhttpapi\config.json`
+
+```json
+{
+    "general": {
+        "host": "0.0.0.0",
+        "post_url": "http://127.0.0.1:8080"
+    },
+    "12345678": {
+        "access_token": "Mgep4rV49rM8Jf",
+        "port": 5700
+    },
+    "87654321": {
+        "port": 5701
+    }
+}
+```
+
+### 使用 JSON 格式，每个账号对应一个配置文件
+
+- `data\app\io.github.richardchien.coolqhttpapi\config\general.json`
+
+```json
+{
+    "host": "0.0.0.0",
+    "post_url": "http://127.0.0.1:8080"
+}
+```
+
+- `data\app\io.github.richardchien.coolqhttpapi\config\12345678.json`
+
+```json
+{
+    "access_token": "Mgep4rV49rM8Jf",
+    "port": 5700
+}
+```
+
+- `data\app\io.github.richardchien.coolqhttpapi\config\87654321.json`
+
+```json
+{
+    "port": 5701
+}
+```
+
+## 配置项
+
+| 配置项名称 | 默认值 | 说明 |
+| -------- | ------ | --- |
+| `host` | `[::]` | HTTP 服务器监听的 IP |
+| `port` | `5700` | HTTP 服务器监听的端口 |
+| `use_http` | `true` | 是否开启 HTTP 接口，即通过 HTTP 调用 API，见 [通信方式的第一种](/CommunicationMethods#插件作为-http-服务端) |
+| `ws_host` | `[::]` | WebSocket 服务器监听的 IP |
+| `ws_port` | `6700` | WebSocket 服务器监听的端口 |
+| `use_ws` | `false` | 是否开启 WebSocket 服务器，可用于调用 API 和推送事件，见 [通信方式的第二种](/CommunicationMethods#插件作为-websocket-服务端) |
+| `ws_reverse_url` | 空 | 反向 WebSocket Event 和事件上报的共用地址 |
+| `ws_reverse_api_url` | 空 | 反向 WebSocket API 地址，如果为空，则使用 `ws_reverse_url` 指定的值 |
+| `ws_reverse_event_url` | 空 | 反向 WebSocket 事件上报地址，如果为空，则使用 `ws_reverse_url` 指定的值 |
+| `ws_reverse_reconnect_interval` | `3000` | 反向 WebSocket 客户端断线重连间隔，单位毫秒 |
+| `ws_reverse_reconnect_on_code_1000` | `true` | 是否在关闭状态码为 1000 的时候重连 |
+| `ws_reverse_use_universal_client` | `false` | 是否使用 Universal 客户端 |
+| `use_ws_reverse` | `false` | 是否使用反向 WebSocket 服务，即插件作为 WebSocket 客户端主动连接指定的 API 和事件上报地址，见 [通信方式的第三种](/CommunicationMethods#插件作为-websocket-客户端（反向-websocket）) |
+| `post_url` | 空 | 消息和事件的上报地址，通过 POST 方式请求，数据以 JSON 格式发送 |
+| `post_timeout` | `0` | HTTP 上报（即访问 `post_url`）的超时时间，单位秒，0 表示不设置超时 |
+| `access_token` | 空 | API 访问 token，如果不为空，则会在接收到请求时验证 `Authorization` 请求头是否为 `Token xxxxxxxx`，`xxxxxxxx` 为 access token |
+| `secret` | 空 | 上报数据签名密钥，如果不为空，则会在 HTTP 上报时对 HTTP 正文进行 HMAC SHA1 哈希，使用 `secret` 的值作为密钥，计算出的哈希值放在上报的 `X-Signature` 请求头，例如 `X-Signature: sha1=f9ddd4863ace61e64f462d41ca311e3d2c1176e2` |
+| `post_message_format` | `string` | 上报消息格式，`string` 为字符串格式，`array` 为数组格式，具体见 [消息格式](/Message) |
+| `serve_data_files` | `false` | 是否提供请求 `data` 目录的文件的功能 |
+| `update_source` | `github` | 更新源，默认使用托管在 GitHub 的 [richardchien/coolq-http-api-release](https://github.com/richardchien/coolq-http-api-release) 仓库，对于酷 Q 运行在国内的情况，可以换成 `gitee` |
+| `update_channel` | `stable` | 更新通道，目前有 `stable`、`beta`、`alpha` 三个 |
+| `auto_check_update` | `false` | 是否自动检查更新（每次启用插件时检查），不启用的情况下，仍然可以在酷 Q 应用菜单中手动检查更新 |
+| `auto_perform_update` | `false` | 是否自动执行更新，仅在 `auto_check_update` 启用时有效，若启用，则插件将在自动检查到更新后，自动下载新版本并重启酷 Q 生效 |
+| `thread_pool_size` | `4` | 工作线程池大小，用于异步发送消息和一些其它小的异步任务，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |
+| `server_thread_pool_size` | `4` | API 服务器线程池大小，用于异步处理请求，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |
+| `convert_unicode_emoji` | `true` | 是否在 CQ:emoji 和实际的 Unicode 之间进行转换，转换可能耗更多时间，但日常情况下影响不大，如果你的机器人需要处理非常大段的消息（上千字），且对性能有要求，可以考虑关闭转换 |
+| `event_filter` | 空 | 指定事件过滤规则文件，见 [事件过滤器](/EventFilter)，留空将不开启事件过滤器 |
+| `enable_backward_compatibility` | `false` | 是否启用旧版兼容性，启用时**事件上报**的数据将和 3.x 版本保持兼容 |
+| `show_log_console` | `false` | 是否显示日志输出控制台 |
+| `max_log_file_size` | `6291456` | 最大单日志文件大小，单位字节，默认 6 MB |
+| `max_log_files` | `1` | 最大日志文件备份数量（采用日志轮替机制） |
+| `log_level` | `info` | 日志文件和日志控制台的日志等级，可选 `debug`、`info`、`warning`、`error`、`fatal` |
+| `use_extension` | `false` | 是否启用扩展机制，见 [扩展](/Extension) |
+| `disable_coolq_log` | `true` | 是否禁用酷 Q 原生日志，由于使用酷 Q 原生日志可能会导致快速重启时插件卡死，所以默认禁用，如果你不在乎重启时卡死，并且需要在酷 Q 原生日志窗口查看插件的日志，可以将此项设为 `false` |
+| `online_status_detection_method` | `log_db` | QQ 在线状态检测方式，默认（`log_db`）从酷 Q 的日志数据库判断，设为 `get_stranger_info` 可切换成通过查询陌生人接口判断（频繁请求可能导致结果不准） |
+| `enable_heartbeat` | `false` | 是否启用心跳机制，启用时会产生类型为 `heartbeat` 的元事件，见 [元事件](/Post#元事件) |
+| `heartbeat_interval` | `15000` | 产生心跳元事件的时间间隔，单位毫秒 |
+| `enable_rate_limited_actions` | `false` | 是否启用限速 API 调用的支持 |
+| `rate_limit_interval` | `500` | 限速 API 调用的排队间隔时间，单位毫秒 |