diff --git a/docs/.conf/nav.js b/docs/.conf/nav.js index d914358bc1b..da21274830d 100644 --- 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"}, diff --git a/docs/Bots.md b/docs/Bots.md index 2feba3049f4..33291a7b18a 100644 --- 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` | 当前协议已禁止密码登录 | 使用扫码登录 | 若以上方案无法解决问题，请尝试 [切换登录协议](#切换登录协议) 和 **[处理滑动验证码](#处理滑动验证码)**。 diff --git a/docs/ConsoleTerminal.md b/docs/ConsoleTerminal.md index dbecdf3a166..eb571857a5d 100644 --- 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 支持，允许使用其他编程语言的插件 + 不安装此插件不能在聊天环境中执行命令 + +- [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`) -- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai) - ：高级权限组插件，适合权限分配模型比较复杂的情况 +- [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` 并复现问题后将当天日志一并提交。 ### 配置权限 diff --git a/docs/EventList.md b/docs/EventList.md index 1fd7f92749a..03bf72201f0 100644 --- 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, +∞) diff --git a/docs/Preparations.md b/docs/Preparations.md index cb038d5a40a..0bc9c39ae0d 100644 --- 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。 diff --git a/docs/Questions.md b/docs/Questions.md new file mode 100644 index 00000000000..72b49fb380e --- /dev/null +++ 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` 的相关配置文件 + +可能需要安装插件 。 + +> 如何添加 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`： + +群事件收不到可能是因为你将群设置为 `屏蔽群` 或者 `收入了群助手`。 +另外如果消息是 `转发消息` 或 `卡片消息` 等特殊消息, 也有可能因为风控无法接收和发出。 + +> 发送语音之后播放没有声音 + +你可能需要安装插件或引入依赖 。 diff --git a/docs/UserManual.md b/docs/UserManual.md index bbcbba2e3b4..a7180946fe4 100644 --- a/docs/UserManual.md +++ b/docs/UserManual.md @@ -17,17 +17,31 @@ Mirai 控制台现在有两个版本，Mirai 插件在这两个版本的 Mirai C | 类型 | 长啥样? | 好用吗? | 怎么装? | |:-----|:-------------|:----------|:----------------------| | 纯控制台 | [MCLI-1.png] | 稳定，也适合服务器 | [使用纯控制台版本](#使用纯控制台版本) | -| 图形界面 | [MCPS-1.png] | 测试版，不稳定 | [使用图形界面版本](#使用图形界面版本) | +| 图形界面 | [MCPS-1.png] | 测试版，不推荐使用 | [使用图形界面版本](#使用图形界面版本) | -## 使用图形界面版本 +## 使用纯控制台版本 + +详细教程请查看 [ConsoleTerminal.md](ConsoleTerminal.md)。 + +以 Windows 系统为例，以下为简要安装步骤： + +1. 前往 [iTXTech/mcl-installer](https://github.com/iTXTech/mcl-installer/releases) 下载适合您系统的最新版本的 MCL 安装器 +2. 创建好文件夹之后，将 MCL 安装器移动到其中 +3. 双击 `mcl-installer.exe` 过程中只需要按几次回车键，即可安装完毕 +4. 运行 `mcl.cmd` 即可启动 MCL 控制台 +安装插件只需要将下载好的插件置于 plugins 目录，然后重启 MCL 控制台即可。 + +## ~~使用图形界面版本~~ + +开发者已停止更新，且有许多历史问题，故不推荐使用 前往 [sonder-joker/mirai-compose](https://github.com/sonder-joker/mirai-compose/releases) -下载适合你的系统的压缩包， +下载适合你的系统的压缩包， > MAC 系统下载 .dmg 后缀的文件 > Windows 系统下载 .msi 后缀的文件 -> Linux 系统下载 .deb 后缀的文件 +> Linux 系统下载 .deb 后缀的文件 -以 Windows 系统为例，以下为简要安装步骤： +以 Windows 系统为例，以下为简要安装步骤： 1. 下载 `mirai-compose-<版本>.msi` 2. 双击运行安装程序，选择一个合适的文件夹，然后点击安装 @@ -37,21 +51,10 @@ Mirai 控制台现在有两个版本，Mirai 插件在这两个版本的 Mirai C 安装插件只需要将下载好的插件置于 plugins 目录，安装完毕后重启 mirai-compose 以生效。 -## 使用纯控制台版本 - -详细教程请查看 [ConsoleTerminal.md](ConsoleTerminal.md)。 - -以 Windows 系统为例，以下为简要安装步骤： - -1. 前往 [iTXTech/mcl-installer](https://github.com/iTXTech/mcl-installer/releases) 下载适合您系统的最新版本的 MCL 安装器 -2. 创建好文件夹之后，将 MCL 安装器移动到其中 -3. 双击 `mcl-installer.exe` 过程中只需要按几次回车键，即可安装完毕 -4. 运行 `mcl.cmd` 即可启动 MCL 控制台 - -安装插件只需要将下载好的插件置于 plugins 目录，然后重启 MCL 控制台即可。 - ## 解决问题 +请先阅读 [常见问题](Questions.md) 。 + 如果遇到使用问题或想提建议，可以在 [issues](https://github.com/mamoe/mirai/issues) 发表。也可以在[论坛](https://mirai.mamoe.net/)交流想法。