Update docs

Author: stdrc

docs/3.2/API.md

@@ -0,0 +1,71 @@
+# 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]
+```
+
+### 发送文件系统中另一个地方的图片或语音
+
+除了发送网络上的图片、语音，还可以发送本地文件系统中其它地方的图片、语音，使用 `file://` 加文件的绝对路径，例如：
+
+```
+[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)。

docs/3.2/CQCode.md

@@ -0,0 +1,87 @@
+# 通信方式
+
+目前支持三种通信方式：
+
+- 插件作为 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` 配置为 `yes`（默认即 `yes`），然后通过 `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` 配置为 `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/` 来接收事件推送。
+
+这两个接口的具体用法见 [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` 配置为 `yes`（默认为 `no`），重启插件即可开启反向 WebSocket 服务。
+
+插件会在特定的时候向指定的 URL 建立连接，如果配置了 `access_token`，则在建立连接时，会加入 `Authorization` 请求头，例如：
+
+```http
+Authorization: Token kSLuTF2GC2Q4q4ugm3
+```
+
+#### API 调用
+
+首先插件启用时会启动一个**保持连接**的客户端用于连接 API 调用接口，即 `ws_reverse_api_url` 指定的接口，一旦收到服务端发来的消息就会调用相应的 API 并返回调用结果。
+
+API 的调用方式和插件作为 WebSocket 服务端的 `/api/` 接口使用方式相同，见 [WebSocket API 描述的 `/api/`](/WebSocketAPI#api)，不同在于你的服务端必须在调用 API 后保持连接，以便下次调用。
+
+#### 事件上报
+
+从 3.1.1 版本开始行为和 3.1.0 不太一致，下面区别对待：
+
+##### v3.1.1
+
+插件启动时会启动一个**保持连接**的客户端用于连接事件上报接口，即 `ws_reverse_event_url` 指定的接口，在后续接收到酷 Q 的事件时，会通过这个连接发送事件数据。发送事件数据格式和 HTTP POST 方式上报的完全一致，见 [上报数据格式](/Post#上报数据格式)，事件列表见 [事件列表](/Post#事件列表)。
+
+与 HTTP 上报不同的是，这里上报不会对数据进行签名（即 HTTP 上报中的 `X-Signature` 请求头在这里没有等价的东西），并且也不会处理响应数据。
+
+**注：3.1.1 之后的版本这里是保持连接的，启动时建立连接，每次发送之后连接都不会变动。**
+
+##### v3.1.0
+
+插件在收到酷 Q 事件时，会向 `ws_reverse_event_url` 指定的接口建立连接，并发送事件数据，**然后关闭连接**。发送事件数据格式和 HTTP POST 方式上报的完全一致，见 [上报数据格式](/Post#上报数据格式)，事件列表见 [事件列表](/Post#事件列表)。
+
+与 HTTP 上报不同的是，这里上报不会对数据进行签名（即 HTTP 上报中的 `X-Signature` 请求头在这里没有等价的东西），并且也不会处理响应数据。
+
+**注：3.1.0 版本这里是不保持连接的，每次事件上报会重新建立连接，上报之后关闭。**

docs/3.2/CommunicationMethods.md

@@ -0,0 +1,56 @@
+# 配置文件说明
+
+配置文件使用 ini 格式编写，如下：
+
+```ini
+[general]
+host=0.0.0.0
+port=5700
+post_url=http://192.168.0.11:8888
+access_token=Mgep4rV49rM8Jf
+```
+
+注意上面的 `[general]` 不能少，它下方的配置是各账号的共用配置项。
+
+如果需要对多个账号进行不同的配置，例如对不同的账号指定不同的上报地址和监听地址，则填写在 QQ 号对应的 section 下，如：
+
+```ini
+[general]
+host=0.0.0.0
+
+[12345678]
+port=5700
+post_url=http://192.168.0.11:8888
+access_token=Mgep4rV49rM8Jf
+
+[23456789]
+host=127.0.0.1
+port=5701
+secret=kP9yK2lrGxoymmpo
+```
+
+**重要：如果配置文件中需要使用中文或其它非 ASCII 字符，则必须使用 UTF-8 without BOM 编码保存文件！**
+
+支持的配置项如下：
+
+| 配置项名称 | 默认值 | 说明 |
+| -------- | ------ | --- |
+| `host` | `0.0.0.0` | HTTP 服务器监听的 IP |
+| `port` | `5700` | HTTP 服务器监听的端口 |
+| `use_http` | `yes` | 是否开启 HTTP 接口，即通过 HTTP 调用 API，见 [通信方式的第一种](/CommunicationMethods#插件作为-http-服务端) |
+| `ws_host` | `0.0.0.0` | WebSocket 服务器监听的 IP |
+| `ws_port` | `6700` | WebSocket 服务器监听的端口 |
+| `use_ws` | `no` | 是否开启 WebSocket 服务器，可用于调用 API 和推送事件，见 [通信方式的第二种](/CommunicationMethods#插件作为-websocket-服务端) |
+| `ws_reverse_api_url` | 空 | 反向 WebSocket API 地址 |
+| `ws_reverse_event_url` | 空 | 反向 WebSocket 事件上报地址 |
+| `use_ws_reverse` | `no` | 是否使用反向 WebSocket 服务，即插件作为 WebSocket 客户端主动连接指定的 API 和事件上报地址，见 [通信方式的第三种](/CommunicationMethods#插件作为-websocket-客户端（反向-websocket）) |
+| `post_url` | 空 | 消息和事件的上报地址，通过 POST 方式请求，数据以 JSON 格式发送 |
+| `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` | `no` | 是否提供请求 `data` 目录的文件的功能，`yes` 或 `true` 表示启用，否则不启用 |
+| `update_source` | `https://raw.githubusercontent.com/richardchien/coolq-http-api-release/master/` | 更新源，默认使用 GitHub 的 [richardchien/coolq-http-api-release](https://github.com/richardchien/coolq-http-api-release) 仓库，对于酷 Q 运行在国内的情况，可以换成 `https://gitee.com/richardchien/coolq-http-api-release/raw/master/` |
+| `update_channel` | `stable` | 更新通道，目前有 `stable` 和 `beta` 两个 |
+| `auto_check_update` | `no` | 是否自动检查更新（每次启用插件时检查），`yes` 或 `true` 表示启用，否则不启用，不启用的情况下，仍然可以在酷 Q 应用菜单中手动检查更新 |
+| `thread_pool_size` | `4` | 工作线程池大小，用于异步发送消息和一些其它小的异步任务，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |
+| `server_thread_pool_size` | `1` | API 服务器线程池大小，用于异步处理请求，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |

docs/3.2/Configuration.md

@@ -0,0 +1,49 @@
+# Docker
+
+酷 Q 目前可以在 Wine 中运行，见 [酷Q Air / Pro on Wine](https://cqp.cc/t/30966)，因此也就自然而然有了相应的 docker 镜像 [coolq/wine-coolq](https://hub.docker.com/r/coolq/wine-coolq/)。
+
+要在 docker 中使用本插件，你可以使用酷 Q 官方的 docker 镜像，然后在其中安装本插件（下载 cpk、编辑配置文件、启用插件），也可以使用我维护的已安装并启用了插件的镜像 [richardchien/cqhttp](https://hub.docker.com/r/richardchien/cqhttp/)（基于酷 Q 官方的镜像修改）。下面介绍这个镜像的用法。
+
+## 基本用法
+
+```bash
+$ docker pull richardchien/cqhttp:latest
+$ mkdir coolq  # 用于存储酷 Q 的程序文件
+$ docker run -ti --rm --name cqhttp-test \
+             -v $(pwd)/coolq:/home/user/coolq \  # 将宿主目录挂载到容器内用于持久化酷 Q 的程序文件
+             -p 9000:9000 \  # noVNC 端口，用于从浏览器控制酷 Q
+             -p 5700:5700 \  # HTTP API 插件开放的端口
+             -e CQHTTP_POST_URL=http://example.com:8080 \  # 事件上报地址
+             -e CQHTTP_SERVE_DATA_FILES=yes \  # 允许通过 HTTP 接口访问酷 Q 数据文件
+             richardchien/cqhttp:latest
+```
+
+其中，`CQHTTP_POST_URL`、`CQHTTP_SERVE_DATA_FILES` 是用于配置插件运行的，格式为「`CQHTTP_` + 插件配置项的大写」，具体的配置项，见 [配置文件说明](/Configuration)。
+
+然后访问 `http://<你的IP>:9000/` 进入 noVNC（默认密码 `MAX8char`），登录酷 Q，即可开始使用（插件已自动启用，配置文件也根据启动命令的环境变量自动生成了）。一般情况下，你不太需要关注插件是如何存在于容器中的。
+
+注意，默认情况下，容器启动时会将 `CQHTTP_` 开头的环境变量写入到配置文件中（整个覆盖已有的配置文件），**因此，尽管你可以在酷 Q 运行时修改配置文件并重启插件以使用修改后的配置，但容器重启后配置文件将再次被覆盖**，如果你不要使用环境变量来配置，请看下面的 [强制手动模式](#强制手动模式)。
+
+## 由官方镜像继承来的配置
+
+除了 `CQHTTP_` 开头的环境变量用来配置插件，还有若干环境变量可以用来调整容器的运行，它们都继承自 coolq/wine-coolq 镜像：
+
+| 环境变量名 | 说明 |
+| -------- | ---- |
+| `VNC_PASSWD` | noVNC 的密码（官方说不能超过 8 个字符，但实测可以超过） |
+| `COOLQ_ACCOUNT` | 设置要登录酷 Q 的 QQ 号。在第一次手动登录后，你可以勾选「快速登录」功能以启用自动登录，此后，容器启动或酷 Q 异常退出时，会自动登录该帐号。 |
+| `COOLQ_URL` | 设置下载酷 Q 的地址，默认为 `http://dlsec.cqp.me/cqa-tuling`，即酷 Q Air 图灵版。请确保下载后的文件能解压出 `酷Q Air/CQA.exe` 或 `酷Q Pro/CQP.exe` |
+
+## 更换／升级插件版本
+
+Docker 镜像使用 tag 来标记版本，插件版本 3.0.0 之后的 richardchien/cqhttp 镜像遵循了这一点（旧版本没有，已移至镜像的 `legacy` 标签）。
+
+上一节的示例给出的命令拉取了 `richardchien/cqhttp:latest`，即当前最新版本，如果你需要更新插件到最新版本，重新拉取一次 `latest` 标签即可，如果你需要使用指定版本的插件，如 `3.0.0` 版本，则使用镜像 `richardchien/cqhttp:3.0.0`。插件的 GitHub 仓库中的每个 release 对应 docker 镜像的一个 tag，注意，release 的标题中的版本号有 `v` 开头，docker 镜像的 tag 没有。
+
+此外，docker 容器在每次运行时，会将相应版本的 cpk 文件复制到酷 Q 的 app 目录，并覆盖已有的文件（假设有的话）。这意味着，**当使用某个版本的 docker 镜像时，如果你自行更换了 cpk 文件，那么下次容器重启时将会重新覆盖它**。如果你不要这个行为，请看下面的 [强制手动模式](#强制手动模式)。
+
+## 强制手动模式
+
+Docker 容器在第一次启动时在酷 Q 的 `app\io.github.richardchien.coolqhttpapi` 目录中创建了一个 `app.lock` 文件，只要该文件存在，就会覆盖 cpk 文件，并使用环境变量覆盖配置文件。
+
+如果你需要手动更换 cpk（或使用插件的检查更新功能），或者手动编辑配置文件，只需要删掉 `app.lock` 文件即可。