[core+console] Update docs (#2639)

* feat: Question.md * update: UserManual.md * update: ConsoleTerminal.md * update: ConsoleTerminal.md * update: Question.md * update: Bots.md * update: Question.md * update: EventList.md * update: Question.md * update: Preparations.md * update: ConsoleTerminal.md * update: Bots.md * update: nav.js * update: UserManual.md * update: Bots.md * update: Bots.md * update: Bots.md * update: ConsoleTerminal.md * update: Questions.md * update: Questions.md * update: ... * update: Bots.md * update: Questions.md --------- Co-authored-by: Him188 <Him188@mamoe.net>
2025-01-13 20:10:09 +08:00 · 2023-05-06 20:13:18 +08:00 · 2023-05-06 20:13:18 +08:00 · 44e9bb118c
commit 44e9bb118c
parent 9d1e78386e
7 changed files with 185 additions and 58 deletions
--- a/docs/.conf/nav.js
+++ b/docs/.conf/nav.js
@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 Mamoe Technologies and contributors.
+ * Copyright 2019-2023 Mamoe Technologies and contributors.
 *
 * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
 * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
@ -18,6 +18,7 @@ module.exports = {
        {text: '用户手册 - 控制台', link: '/ConsoleTerminal.html'},
        {text: 'JVM 环境和开发准备工作', link: '/Preparations.html'},
        {text: "配置项目", link: "/ConfiguringProjects.html"},
+        {text: "常见问题", link: "/Questions.html"},
        {
            text: "CoreAPI", items: [
                {text: "CoreAPI", link: "/CoreAPI.html"},
--- a/docs/Bots.md
+++ b/docs/Bots.md
@ -33,6 +33,9 @@ interface BotFactory {
    fun newBot(qq: Long, password: String): Bot
    fun newBot(qq: Long, passwordMd5: ByteArray, configuration: BotConfiguration): Bot
    fun newBot(qq: Long, passwordMd5: ByteArray): Bot
+    // 在 2.15.0 中加入
+    fun newBot(qq: Long, authorization: BotAuthorization)
+    fun newBot(qq: Long, authorization: BotAuthorization, configuration: BotConfiguration)
    
    companion object : BotFactory by BotFactoryImpl
 }
@ -55,16 +58,27 @@ Bot bot = BotFactory.INSTANCE.newBot(    );
 仅能在构造 Bot 时修改其配置：
 ```
 // Kotlin
+// 使用密码登录
 val bot = BotFactory.newBot(qq, password) {
    // 配置，例如：
    fileBasedDeviceInfo()
 }
+// 在 2.15.0 中加入, 使用二维码登录
+val bot = BotFactory.newBot(qq, BotAuthorization.byQRCode()) {
+    protocol = BotConfiguration.MiraiProtocol.ANDROID_WATCH
+}

 // Java
+// 使用密码登录
 Bot bot = BotFactory.INSTANCE.newBot(qq, password, new BotConfiguration() {{
    // 配置，例如：
    fileBasedDeviceInfo()
-}})
+}});
+Bot bot = BotFactory.INSTANCE.newBot(qq, password, configuration -> {})
+// 在 2.15.0 中加入, 使用二维码登录
+Bot bot = BotFactory.INSTANCE.newBot(qq, BotAuthorization.byQRCode(), configuration -> {
+    configuration.setProtocol(BotConfiguration.MiraiProtocol.ANDROID_WATCH);
+});
 ```

 下文示例代码都要放入 `// 配置` 中。
@ -176,7 +190,8 @@ deviceInfo = { bot ->  /* create device info */   }
 setDeviceInfo(bot -> /* create device info */)
 ```

-在线生成自定义设备信息的 `device.json`: https://ryoii.github.io/mirai-devicejs-generator/
+在线生成自定义设备信息的 `device.json`: https://ryoii.github.io/mirai-devicejs-generator/  
+更加仿真的设备信息的 `device.json`: https://github.com/cssxsh/mirai-device-generator

 #### 使用其他日志库接管 mirai 日志系统
 *mirai 2.7 起支持*
@ -255,25 +270,26 @@ contactListCache.setSaveIntervalMillis(60000) // 可选设置有更新时的保

 ### 处理滑动验证码

-[project-mirai/mirai-login-solver-selenium]: https://github.com/project-mirai/mirai-login-solver-selenium
+[mirai-login-solver-sakura]: https://github.com/KasukuSakura/mirai-login-solver-sakura

 服务器正在大力推广滑块验证码。

 部分账号可以跳过滑块验证码，Mirai 会自动尝试。  
-若你的账号无法跳过验证，可在 [project-mirai/mirai-login-solver-selenium] 查看处理方案。
+若你的账号无法跳过验证，可尝试使用 [mirai-login-solver-sakura] 处理。

-**若遇到滑块验证问题无法解决，可以参考[论坛帮助页面](https://mirai.mamoe.net/topic/223/%E6%97%A0%E6%B3%95%E7%99%BB%E5%BD%95%E7%9A%84%E4%B8%B4%E6%97%B6%E5%A4%84%E7%90%86%E6%96%B9%E6%A1%88)。**
+**若遇到滑块验证问题无法解决，可以参考[论坛帮助页面](https://mirai.mamoe.net/topic/223)。**

 ### 常见登录失败原因

 [#993]: https://github.com/mamoe/mirai/discussions/993

-| 错误信息       | 可能的原因        | 可能的解决方案                                               |
-|:--------------|:---------------|:-----------------------------------------------------------|
-| 当前版本过低    | 密码错误         | 检查密码或修改密码到 16 位以内                                  |
-| 当前上网环境异常 | 设备锁           | 开启或关闭设备锁 (登录保护)                                    |
-| 禁止登录       | 需要处理滑块验证码 | [project-mirai/mirai-login-solver-selenium]                |
-| 密码错误       | 密码错误或过长     | 手机协议最大支持 16 位密码 ([#993]). 在官方 PC 客户端登录后修改密码 |
+| 错误信息       | 可能的原因                | 可能的解决方案                                     |
+|:-----------|:---------------------|:--------------------------------------------|
+| 密码错误       | 密码错误或过长              | 手机协议最大支持 16 位密码 ([#993]). 在官方 PC 客户端登录后修改密码 |
+| `code=45`  | 协议版本过低或设备信息被拉黑       | 删除 device.json, 让其重新生成                      |
+| `code=235` | 协议版本过低或设备信息被拉黑       | 删除 device.json, 让其重新生成                      |
+| `code=237` | 滑块验证处理过慢或者提交ticket有误 | 尝试使用 [mirai-login-solver-sakura] 处理滑块验证     |
+| `code=238` | 当前协议已禁止密码登录          | 使用扫码登录                                      |

 若以上方案无法解决问题，请尝试 [切换登录协议](#切换登录协议) 和 **[处理滑动验证码](#处理滑动验证码)**。

--- a/docs/ConsoleTerminal.md
+++ b/docs/ConsoleTerminal.md
@ -9,10 +9,13 @@ Console，可参考 [Console 开发文档](../mirai-console/docs/README.md)。
 本文假设你使用 Windows 操作系统。但 Mirai Console 并不仅限于 Windows
 平台使用，在其他操作系统上的使用方法应当是类似的。

+**重要**：关闭 Mirai Console 需要通过 `stop` 命令关闭。  
+直接关闭窗口会导致数据损坏、数据丢失、系统崩溃等错误。
+
 安装
 ----

-可以使用[脚本](https://mirai.mamoe.net/assets/uploads/files/1618372079496-install-20210412.cmd)
+可以使用 [脚本](https://mirai.mamoe.net/assets/uploads/files/1618372079496-install-20210412.cmd)
 自动安装 32 位带 HTTP 插件的版本，也可以使用安装器个性化安装：

 [iTXTech/mcl-installer]: https://github.com/iTXTech/mcl-installer/releases
@ -40,13 +43,16 @@ MCL 只是启动器，没有机器人功能。MCL 支持从远程仓库下载插
 如果遇到启动器问题，请提交至 [iTXTech/mirai-console-loader](https://github.com/iTXTech/mirai-console-loader)
 。

-|   文件夹名称   | 用途                  |
-|:---------:|:--------------------|
-| `scripts` | 存放启动器的脚本，一般不需要在意他们  |
-| `plugins` | 存放插件                |
-|  `data`   | 存放插件的数据，一般不需要在意它们   |
-| `config`  | 存放插件的配置，可以打开并修改配置   |
-|  `logs`   | 存放运行时的日志，日志默认保留 7 天 |
+|           文件夹名称           | 用途                   |
+|:-------------------------:|:---------------------|
+|          `data`           | 存放插件的数据，一般不需要在意它们    |
+|         `config`          | 存放插件的配置，可以打开并修改配置    |
+|          `logs`           | 存放运行时的日志，日志默认保留 7 天  |
+|          `libs`           | 存放 mirai-core 等核心库文件 |
+|         `plugins`         | 存放插件                 |
+|    `plugin-libraries`     | 存放插件的库缓存             |
+| `plugin-shared-libraries` | 存放插件的公共库             |
+|         `modules`         | 存放启动器的拓展模块           |

 > 可以在[这里](https://github.com/iTXTech/mirai-console-loader)查看 MCL 详细用法

@ -57,7 +63,7 @@ MCL 只是启动器，没有机器人功能。MCL 支持从远程仓库下载插
 Mirai Console 原生支持 JAR 文件插件。一般插件的后缀为 `.mirai2.jar`（新版本）或 `.mirai.jar`
 （旧版本）。

-将插件 JAR 放在 `plugins` 目录中，重启 MCL 就会自动扫描并加载。
+将插件 JAR 放在 `plugins` 目录中，重启 Mirai Console 就会自动扫描并加载。

 Mirai Console

@ -83,19 +89,19 @@ Mirai 官方提供两个插件：
 安装 mirai-api-http 的 2.x 版本：

 ```powershell
-./mcl --update-package net.mamoe:mirai-api-http --type plugin --channel stable-v2
+./mcl --update-package net.mamoe:mirai-api-http --type plugin --channel maven-stable
 ```

 安装 chat-command：

 ```powershell
-./mcl --update-package net.mamoe:chat-command --type plugin --channel stable
+./mcl --update-package net.mamoe:chat-command --type plugin --channel maven-stable
 ```

-注意：插件有多个频道，`--channel stable` 表示使用名为 `stable`（稳定）的频道。不同的插件可能会设置不同的频道，
+注意：插件有多个频道，`--channel maven-stable` 表示使用从 `maven` 更新的 `stable`（稳定）的频道。不同的插件可能会设置不同的频道，
 具体需要使用哪个频道可参考特定插件的说明 (很多插件会单独说明要如何安装它们, 因此不必过多考虑)。

-详细文档：[MCL/scripts](https://github.com/iTXTech/mirai-console-loader/blob/master/cli.md)
+详细文档：[MCL 命令行参数](https://github.com/iTXTech/mirai-console-loader/blob/master/cli.md)

 ### 在哪找社区插件

@ -108,17 +114,24 @@ Mirai 官方提供两个插件：

 如果是 JAR 文件的插件，放入 `plugins` 即可。其他插件一般都有特殊说明如何使用，请参考它们的说明。

-注意，mirai 在 2.11 时修改了加载策略。在这之后如果要从 MCL 安装插件
+注意，mirai 在 2.11 时修改了加载策略。请尽量使用 `mirai2.jar` 后缀版本的插件

-### 推荐安装的插件
+### 常用的插件

 - [chat-command](https://github.com/project-mirai/chat-command):
-  不安装此环境不能在聊天环境中执行命令
- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供
-  HTTP 支持，允许使用其他编程语言的插件
+  不安装此插件不能在聊天环境中执行命令

- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai)
-  ：高级权限组插件，适合权限分配模型比较复杂的情况
+- [mirai-api-http](https://github.com/project-mirai/mirai-api-http): 
+  提供 HTTP 支持，允许使用其他编程语言的插件
+
+- [mirai-silk-converter](https://github.com/project-mirai/mirai-silk-converter):
+  可以自动将 `wav`, `mp3` 等格式转换为语音所需格式 `silk`
+
+- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai): 
+  高级权限组插件，适合权限分配模型比较复杂的情况，并且可以提供网页UI的权限编辑器 (指令 `lp editor`)
+
+- [mirai-login-solver-sakura](https://github.com/KasukuSakura/mirai-login-solver-sakura):
+  验证处理工具，主要是为了优化和方便处理各种验证码

 使用控制台指令
 -----
@ -130,7 +143,7 @@ Mirai Console 内置一些指令，输入 `?` 并回车可以查看指令列表
 一些常用指令介绍在[这里](/mirai-console/docs/BuiltInCommands.md#mirai-console---builtin-commands)
 。

-### 在群聊中使用命令 (权限授予)
+### 在聊天框中使用命令 (权限授予)

 要允许从 QQ 聊天环境中使用各种命令, 你 **必须** 完成以下的配置：

@ -223,11 +236,11 @@ Mirai Console 支持一些自定义配置。各项配置可以在 `config` 目

 ### 管理日志

-Mirai Console 会记录运行时的日志并保存到 `logs` 目录中，其中 `latest.log` 为最新日志。
+Mirai Console 会记录运行时的日志并保存到 `logs` 目录中。

 可以参考[日志文档](../mirai-console/docs/Logging.md)了解如何配置日志的详略程度。

-若要向插件开发者提交问题，建议将日志等级调整为 `ALL` 并复现问题后附加 `latest.log` 一并提交。
+若要向插件开发者提交问题，建议将日志等级调整为 `ALL` 并复现问题后将当天日志一并提交。

 ### 配置权限

--- a/docs/EventList.md
+++ b/docs/EventList.md
@ -36,7 +36,11 @@
  - 好友消息: FriendMessagePreSendEvent
  - 群临时会话消息: GroupTempMessagePreSendEvent
  - 陌生人消息：StrangerMessagePreSendEvent
-  - 其他客户端消息：OtherClientMessagePreSendEvent
+- 从其他客户端同步消息 MessageSyncEvent
+  - 群消息: GroupMessageSyncEvent
+  - 好友消息: FriendMessageSyncEvent
+  - 群临时会话消息: GroupTempMessageSyncEvent
+  - 陌生人消息: StrangerMessageSyncEvent
 - 主动发送消息后: MessagePostSendEvent
  - 群消息: GroupMessagePostSendEvent
  - 好友消息: FriendMessagePostSendEvent
@ -86,6 +90,7 @@
 ##### 名片和头衔
 - 成员群名片改动: MemberCardChangeEvent
 - 成员群特殊头衔改动: MemberSpecialTitleChangeEvent
+- 成员群荣誉改变: MemberHonorChangeEvent

 ##### 成员权限
 - 成员权限改变: MemberPermissionChangeEvent
@ -102,3 +107,7 @@
 - 好友头像改变: FriendAvatarChangedEvent
 - 好友昵称改变: FriendNickChangedEvent
 - 好友输入状态改变: FriendInputStatusChangedEvent
+
+### 控制台
+- 自动登录执行后: StartupEvent [2.15.0, +∞)
+- 控制台启动完成: AutoLoginEvent [2.15.0, +∞)
--- a/docs/Preparations.md
+++ b/docs/Preparations.md
@ -4,14 +4,13 @@

 ## JVM 环境要求

- 桌面 JVM：最低 Java 8，但推荐 Java 11（要使用一键启动器，需要 11）
+- 桌面 JVM：最低 Java 8，但推荐 Java 17（要使用一键启动器，需要 11 及以上）
 - Android：
    - mirai 2.15.0 起: API 等级 21 （Android 5.0，LOLLIPOP)
    - mirai 2.15.0 前: API 等级 26 （Android 8.0，O)

 目前主要使用的自动启动器，[Mirai Console Loader](https://github.com/iTXTech/mirai-console-loader)
-，（MCL） 默认安装 JRE 17。但旧版本 MCL 会默认安装 JRE 11。因此 Mirai Console 插件使用 JDK 11
-是较合适的。
+，（MCL） 默认安装 JRE 17。

 **但注意不要使用 Oracle JDK**
 （[原因](https://github.com/mamoe/mirai/discussions/779)），可以使用其他任何 JDK。
--- a/docs/Questions.md
+++ b/docs/Questions.md
@ -0,0 +1,86 @@
+# Mirai - Questions
+
+## 用户常见问题
+
+> 'java' 不是内部或外部命令，也不是可运行的程序
+
+没有安装 Java。
+
+> `Failed to fetch announcement for ...`
+
+[MCL](https://github.com/iTXTech/mirai-console-loader) 查询更新信息失败，可以尝试编辑 `config.json`，
+更换 [mirai repo](https://github.com/project-mirai/mirai-repo-mirror#%E4%BB%93%E5%BA%93%E9%95%9C%E5%83%8F)。
+
+> Login failed: Error(bot=..., code=..., title=....
+
+这些是服务器返回的信息，它表示你的账号被登录风控了。  
+风控没有 100% 稳定的解决方法，你可以关注 [论坛公告帖 - 无法登录的临时处理方案](https://mirai.mamoe.net/topic/223)。  
+密码登录中是否出现滑块验证或短信验证都是不可控的，这取决于腾讯的服务器要求你完成什么验证，没有办法自由选择。
+
+> 登录协议如何修改
+
+对于手动密码登录，第三个参数就是协议, 例如 `login 12345 114514 MACOS`  
+
+对于自动密码登录，可以使用指令修改，例如 `autoLogin setConfig 12345 protocol MACOS`，  
+也可以在 Mirai Console 关闭的情况下, 编辑 `config/Console/AutoLogin.yml` 文件。
+
+注意，文件中有一个账号为 `12345` 的示例，请注意确认修改的配置对应的账号，不要修改错了示例。
+
+> 聊天框无法使用指令(使用指令后没效果)
+
+1. 确认机器人收到消息  
+   日志里会有消息记录，没有就是没收到，如果是群聊消息，注意是否已 `收入群助手`，这可能会导致收不到消息
+
+2. 确认是否已经安装 [chat-command](https://github.com/project-mirai/chat-command/releases/latest)  
+   如果插件的指令是对接的 `Mirai Console` 的指令接口，那它就需要 `chat-command`
+
+3. 确认是否已经授权给目标用户  
+   默认情况下所有用户都是没有权限的，聊天框下无法使用指令  
+   备注：如果使用了 LuckPerms-Mirai，可通过在控制台执行 /lp verbose on 查看权限检测情况
+
+4. 确认日志中没有相关报错  
+   如果插件指令执行出错，也有可能无法提供回复，请联系插件作者
+
+> 如何确认 `Mirai 版本` 或 `插件版本` 等信息
+
+可以启动 Mirai Console 的情况下:  
+使用指令 `/status` 。
+
+无法启动的情况下:  
+Mirai Console 的组件在 `libs` 文件夹下, 文件名包含 `版本信息`。  
+
+> 找不到 `http api` 的相关配置文件
+
+可能需要安装插件 <https://github.com/project-mirai/mirai-api-http>。
+
+> 如何添加 jvm 参数，例如 `-Dmirai.no-desktop=true`
+
+编辑启动脚本 `mcl.cmd`，在 `-jar` 前面加上 `-D...`，例如 `-Dmirai.no-desktop=true -jar mcl...`。
+
+Linux 和 macOS 的启动脚本是 `mcl` (没有后缀的那个文件)。
+
+## 开发者常见问题
+
+> 如何自定义登录验证处理
+
+[覆盖登录解决器](https://github.com/mamoe/mirai/blob/dev/docs/Bots.md#%E8%A6%86%E7%9B%96%E7%99%BB%E5%BD%95%E8%A7%A3%E5%86%B3%E5%99%A8)
+
+> IDEA 下 `import` 爆红，mirai 相关依赖全部无法解析
+
+IDEA 版本过于老旧，无法分析新版本的 Kotlin 依赖，请尝试升级 IDEA 后重试。
+
+> 有些事件收到不到
+
+`SignEvent` 或者 `NudgeEvent`：
+
+总的来说 `MACOS` 和 `ANDROID_WATCH` 相对其他协议会缺少一些事件的接收。  
+对于这些协议来说是不会收到的，因为这在他们对应官方客户端版本里本来就没有这些功能。
+
+`GroupMessageEvent`：
+
+群事件收不到可能是因为你将群设置为 `屏蔽群` 或者 `收入了群助手`。  
+另外如果消息是 `转发消息` 或 `卡片消息` 等特殊消息, 也有可能因为风控无法接收和发出。
+
+> 发送语音之后播放没有声音
+
+你可能需要安装插件或引入依赖 <https://github.com/project-mirai/mirai-silk-converter>。
--- a/docs/UserManual.md
+++ b/docs/UserManual.md
@ -17,25 +17,7 @@ Mirai 控制台现在有两个版本，Mirai 插件在这两个版本的 Mirai C
 | 类型   | 长啥样?         | 好用吗?      | 怎么装?                  |
 |:-----|:-------------|:----------|:----------------------|
 | 纯控制台 | [MCLI-1.png] | 稳定，也适合服务器 | [使用纯控制台版本](#使用纯控制台版本) |
-| 图形界面 | [MCPS-1.png] | 测试版，不稳定   | [使用图形界面版本](#使用图形界面版本) |
-
-## 使用图形界面版本
-
-前往 [sonder-joker/mirai-compose](https://github.com/sonder-joker/mirai-compose/releases)
-下载适合你的系统的压缩包，  
->  MAC 系统下载 .dmg 后缀的文件  
->  Windows 系统下载 .msi 后缀的文件  
->  Linux 系统下载 .deb 后缀的文件  
-
-以 Windows 系统为例，以下为简要安装步骤：  
-
-1. 下载 `mirai-compose-<版本>.msi`
-2. 双击运行安装程序，选择一个合适的文件夹，然后点击安装
-3. 安装完毕后打开刚才指定的文件夹
-4. 双击启动其中的 `mirai-compose.exe` 即可开始运行
-5. 运行后点击左上角可以添加 QQ bot 账号
-
-安装插件只需要将下载好的插件置于 plugins 目录，安装完毕后重启 mirai-compose 以生效。
+| 图形界面 | [MCPS-1.png] | 测试版，不推荐使用 | [使用图形界面版本](#使用图形界面版本) |

 ## 使用纯控制台版本

@ -50,8 +32,29 @@ Mirai 控制台现在有两个版本，Mirai 插件在这两个版本的 Mirai C

 安装插件只需要将下载好的插件置于 plugins 目录，然后重启 MCL 控制台即可。  

+## ~~使用图形界面版本~~
+
+开发者已停止更新，且有许多历史问题，故不推荐使用  
+前往 [sonder-joker/mirai-compose](https://github.com/sonder-joker/mirai-compose/releases)
+下载适合你的系统的压缩包，
+>  MAC 系统下载 .dmg 后缀的文件  
+>  Windows 系统下载 .msi 后缀的文件  
+>  Linux 系统下载 .deb 后缀的文件
+
+以 Windows 系统为例，以下为简要安装步骤：
+
+1. 下载 `mirai-compose-<版本>.msi`
+2. 双击运行安装程序，选择一个合适的文件夹，然后点击安装
+3. 安装完毕后打开刚才指定的文件夹
+4. 双击启动其中的 `mirai-compose.exe` 即可开始运行
+5. 运行后点击左上角可以添加 QQ bot 账号
+
+安装插件只需要将下载好的插件置于 plugins 目录，安装完毕后重启 mirai-compose 以生效。
+
 ## 解决问题

+请先阅读 [常见问题](Questions.md)  。
+
 如果遇到使用问题或想提建议，可以在 [issues](https://github.com/mamoe/mirai/issues)
 发表。也可以在[论坛](https://mirai.mamoe.net/)交流想法。