Update docs

docs/4.0/Configuration.md

@@ -84,27 +84,27 @@ port=5701
 | -------- | ------ | --- |
 | `host` | `0.0.0.0` | HTTP 服务器监听的 IP |
 | `port` | `5700` | HTTP 服务器监听的端口 |
-| `use_http` | `yes` | 是否开启 HTTP 接口，即通过 HTTP 调用 API，见 [通信方式的第一种](/CommunicationMethods#插件作为-http-服务端) |
+| `use_http` | `true` | 是否开启 HTTP 接口，即通过 HTTP 调用 API，见 [通信方式的第一种](/CommunicationMethods#插件作为-http-服务端) |
 | `ws_host` | `0.0.0.0` | WebSocket 服务器监听的 IP |
 | `ws_port` | `6700` | WebSocket 服务器监听的端口 |
-| `use_ws` | `no` | 是否开启 WebSocket 服务器，可用于调用 API 和推送事件，见 [通信方式的第二种](/CommunicationMethods#插件作为-websocket-服务端) |
+| `use_ws` | `false` | 是否开启 WebSocket 服务器，可用于调用 API 和推送事件，见 [通信方式的第二种](/CommunicationMethods#插件作为-websocket-服务端) |
 | `ws_reverse_api_url` | 空 | 反向 WebSocket API 地址 |
 | `ws_reverse_event_url` | 空 | 反向 WebSocket 事件上报地址 |
 | `ws_reverse_reconnect_interval` | `3000` | 反向 WebSocket 客户端断线重连间隔，单位毫秒 |
-| `ws_reverse_reconnect_on_code_1000` | `no` | 是否在关闭状态码为 1000 的时候重连 |
-| `use_ws_reverse` | `no` | 是否使用反向 WebSocket 服务，即插件作为 WebSocket 客户端主动连接指定的 API 和事件上报地址，见 [通信方式的第三种](/CommunicationMethods#插件作为-websocket-客户端（反向-websocket）) |
+| `ws_reverse_reconnect_on_code_1000` | `false` | 是否在关闭状态码为 1000 的时候重连 |
+| `use_ws_reverse` | `false` | 是否使用反向 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` 表示启用，否则不启用 |
+| `serve_data_files` | `false` | 是否提供请求 `data` 目录的文件的功能 |
 | `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 应用菜单中手动检查更新 |
-| `auto_perform_update` | `no` | 是否自动执行更新，仅在 `auto_check_update` 启用时有效，`yes` 或 `true` 表示启用，否则不启用，若启用，则插件将在自动检查更新后，自动下载新版本并重启酷 Q 生效 |
+| `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` | `1` | API 服务器线程池大小，用于异步处理请求，应根据计算机性能和实际需求适当调节，若设为 0，则使用 `CPU 核心数 * 2 + 1` |
-| `convert_unicode_emoji` | `yes` | 是否在 CQ:emoji 和实际的 Unicode 之间进行转换，转换可能耗更多时间，但日常情况下影响不大，如果你的机器人需要处理非常大段的消息（上千字），且对性能有要求，可以考虑关闭转换 |
+| `convert_unicode_emoji` | `true` | 是否在 CQ:emoji 和实际的 Unicode 之间进行转换，转换可能耗更多时间，但日常情况下影响不大，如果你的机器人需要处理非常大段的消息（上千字），且对性能有要求，可以考虑关闭转换 |
 | `event_filter` | 空 | 指定事件过滤规则文件，见 [事件过滤器](/EventFilter)，留空将不开启事件过滤器 |
-| `enable_backward_compatibility` | `yes` | 是否启用旧版兼容性，启用时事件上报的数据将和 3.x 版本保持兼容 |
-| `show_log_console` | `no` | 是否显示日志输出控制台 |
+| `enable_backward_compatibility` | `false` | 是否启用旧版兼容性，启用时**事件上报**的数据将和 3.x 版本保持兼容 |
+| `show_log_console` | `false` | 是否显示日志输出控制台 |

docs/4.0/UpgradeGuide.md

@@ -1,3 +1,38 @@
 # 升级指南
 
-待更新。
+由于 4.x 版本相比 3.x 引入了一些破坏性更改，因此这里给出一份升级指南，帮助用户从旧版升级到 4.x。
+
+## 事件上报的数据字段变更
+
+这个变化破坏性比较大，如果不更改配置或代码，可能使当前可用的程序变得不可用。首先列出变更如下：
+
+- 群组消息中匿名信息现在以对象形式表示，例如 `"anonymous": {"id": 1000019, "name": "邓八公", "flag": "AAAAAAAPQlMABrXLsMu5qwAokaXsWulfxg2hPMTHguk1acbiU1NyW2BfxEnEMR5SNYFSns6SKKVe5A=="}`，非匿名消息中此字段为 `null`
+- 通知类上报中（群成员增加、群管理员变更等），`post_type` 字段值从 `event` 变为 `notice`，原先的 `event` 字段变为 `notice_type` 字段
+- 请求类上报的 `message` 字段现变为 `comment` 字段
+
+如果你是应用作者，可将使用到的发生了变化的地方字段的键值直接做相应修改，如果现有代码过于复杂不易修改，可开启 `enable_backward_compatibility` 配置项来临时保持兼容；对于 SDK 作者，建议同时兼容 4.x 和 3.x 两种上报，且接口也分别和上报对应，例如同时提供 `event.NoticeType` 和 `event.Event` 来分别表示 4.x 的 `notice_type` 和 3.x 的 `event` 字段，并在文档或注释中做相应说明，如果无法同时兼容，建议将 SDK 的接口写为 4.x 版本的样式，然后再通过将 3.x 的上报转换为 4.x 的格式来兼容。
+
+## 事件过滤器的变更
+
+变更如下：
+
+- 事件过滤器不再使用 `use_filter` 配置项来开关，而是使用 `event_filter` 直接指定过滤器规则文件的相对路径（相对于 `app\io.github.richardchien.coolqhttpapi`），默认为空，即表示不启用事件过滤器
+- 事件过滤器规则中，旧版中对消息原始文本进行过滤的 `message` 字段现在改为处理过的数组格式的消息，未经处理的原始消息文本现在保存在 `raw_message` 字段
+
+如果在 3.x 版本时使用了过滤器，升级到 4.x 版本时，需要将配置文件中的 `use_filter=true` 改为 `event_filter=filter.json`，由于现在是直接指定过滤规则文件名，也意味着可以针对不同的 QQ 号应用不同的过滤规则。
+
+除了配置项需要修改之外，如果过滤规则中对原来的 `message` 字段写了规则，则需要改成 `raw_message`，然后将上一节中提到的上报数据中发生了变更的字段也做修改，比如 `{"post_type": "event"}` 改为 `{"post_type": "notice"}`，需要注意的是，`enable_backward_compatibility` 配置项**不会**影响事件过滤器看到的数据。
+
+## User-Agent 变更
+
+插件发送请求时的 User-Agent 由形如 `CoolQHttpApi/3.4.0` 改成了形如 `CQHttp/4.0.0`。
+
+## `/get_status` 接口返回数据的变更
+
+`/get_status` 接口的返回数据有所变化，但 `good`、`online`、`app_enabled` 字段仍然不变，具体请自行测试。如果你的应用需要检测酷 Q 和 HTTP API 插件的运行状态，建议只使用上述三个字段来判断。
+
+## Docker 镜像的变更
+
+版本锁的文件名由原来的 `app.lock` 改为 `version.lock`，如果你需要解除容器中插件版本的锁定（即每次启动容器时都使用镜像对应版本的插件 cpk 文件覆盖已有的 cpk），现在需要删除 `version.lock`。
+
+此外，这个文件不再影响配置文件，如果需要手动编辑配置文件，现在需要在容器启动的环境变量中加入 `CONFIG_MANUALLY=true`。