Skip to content

Commit 44e9bb1

Browse files
cssxshHim188
cssxsh
and
Him188
authored
[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 <[email protected]>
1 parent 9d1e783 commit 44e9bb1

7 files changed

+184
-57
lines changed

‎docs/.conf/nav.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2019-2022 Mamoe Technologies and contributors.
2+
* Copyright 2019-2023 Mamoe Technologies and contributors.
33
*
44
* 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
55
* 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 = {
1818
{text: '用户手册 - 控制台', link: '/ConsoleTerminal.html'},
1919
{text: 'JVM 环境和开发准备工作', link: '/Preparations.html'},
2020
{text: "配置项目", link: "/ConfiguringProjects.html"},
21+
{text: "常见问题", link: "/Questions.html"},
2122
{
2223
text: "CoreAPI", items: [
2324
{text: "CoreAPI", link: "/CoreAPI.html"},

‎docs/Bots.md

+27-11
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ interface BotFactory {
3333
fun newBot(qq: Long, password: String): Bot
3434
fun newBot(qq: Long, passwordMd5: ByteArray, configuration: BotConfiguration): Bot
3535
fun newBot(qq: Long, passwordMd5: ByteArray): Bot
36+
// 在 2.15.0 中加入
37+
fun newBot(qq: Long, authorization: BotAuthorization)
38+
fun newBot(qq: Long, authorization: BotAuthorization, configuration: BotConfiguration)
3639

3740
companion object : BotFactory by BotFactoryImpl
3841
}
@@ -55,16 +58,27 @@ Bot bot = BotFactory.INSTANCE.newBot( );
5558
仅能在构造 Bot 时修改其配置：
5659
```
5760
// Kotlin
61+
// 使用密码登录
5862
val bot = BotFactory.newBot(qq, password) {
5963
// 配置，例如：
6064
fileBasedDeviceInfo()
6165
}
66+
// 在 2.15.0 中加入, 使用二维码登录
67+
val bot = BotFactory.newBot(qq, BotAuthorization.byQRCode()) {
68+
protocol = BotConfiguration.MiraiProtocol.ANDROID_WATCH
69+
}
6270
6371
// Java
72+
// 使用密码登录
6473
Bot bot = BotFactory.INSTANCE.newBot(qq, password, new BotConfiguration() {{
6574
// 配置，例如：
6675
fileBasedDeviceInfo()
67-
}})
76+
}});
77+
Bot bot = BotFactory.INSTANCE.newBot(qq, password, configuration -> {})
78+
// 在 2.15.0 中加入, 使用二维码登录
79+
Bot bot = BotFactory.INSTANCE.newBot(qq, BotAuthorization.byQRCode(), configuration -> {
80+
configuration.setProtocol(BotConfiguration.MiraiProtocol.ANDROID_WATCH);
81+
});
6882
```
6983

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

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

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

256271
### 处理滑动验证码
257272

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

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

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

265-
**若遇到滑块验证问题无法解决，可以参考[论坛帮助页面](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)。**
280+
**若遇到滑块验证问题无法解决，可以参考[论坛帮助页面](https://mirai.mamoe.net/topic/223)。**
266281

267282
### 常见登录失败原因
268283

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

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

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

‎docs/ConsoleTerminal.md

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

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

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

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

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

5157
> 可以在[这里](https://github.com/iTXTech/mirai-console-loader)查看 MCL 详细用法
5258
@@ -57,7 +63,7 @@ MCL 只是启动器，没有机器人功能。MCL 支持从远程仓库下载插
5763
Mirai Console 原生支持 JAR 文件插件。一般插件的后缀为 `.mirai2.jar`（新版本）或 `.mirai.jar`
5864
（旧版本）。
5965

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

6268
Mirai Console
6369

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

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

8995
安装 chat-command：
9096

9197
```powershell
92-
./mcl --update-package net.mamoe:chat-command --type plugin --channel stable
98+
./mcl --update-package net.mamoe:chat-command --type plugin --channel maven-stable
9399
```
94100

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

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

100106
### 在哪找社区插件
101107

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

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

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

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

115121
- [chat-command](https://github.com/project-mirai/chat-command):
116-
不安装此环境不能在聊天环境中执行命令
117-
- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供
118-
HTTP 支持，允许使用其他编程语言的插件
122+
不安装此插件不能在聊天环境中执行命令
123+
124+
- [mirai-api-http](https://github.com/project-mirai/mirai-api-http):
125+
提供 HTTP 支持，允许使用其他编程语言的插件
126+
127+
- [mirai-silk-converter](https://github.com/project-mirai/mirai-silk-converter):
128+
可以自动将 `wav`, `mp3` 等格式转换为语音所需格式 `silk`
129+
130+
- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai):
131+
高级权限组插件，适合权限分配模型比较复杂的情况，并且可以提供网页UI的权限编辑器 (指令 `lp editor`)
119132

120-
- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai)
121-
：高级权限组插件，适合权限分配模型比较复杂的情况
133+
- [mirai-login-solver-sakura](https://github.com/KasukuSakura/mirai-login-solver-sakura):
134+
验证处理工具，主要是为了优化和方便处理各种验证码
122135

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

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

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

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

224237
### 管理日志
225238

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

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

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

232245
### 配置权限
233246

‎docs/EventList.md

+10-1
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,11 @@
3636
- 好友消息: FriendMessagePreSendEvent
3737
- 群临时会话消息: GroupTempMessagePreSendEvent
3838
- 陌生人消息：StrangerMessagePreSendEvent
39-
- 其他客户端消息：OtherClientMessagePreSendEvent
39+
- 从其他客户端同步消息 MessageSyncEvent
40+
- 群消息: GroupMessageSyncEvent
41+
- 好友消息: FriendMessageSyncEvent
42+
- 群临时会话消息: GroupTempMessageSyncEvent
43+
- 陌生人消息: StrangerMessageSyncEvent
4044
- 主动发送消息后: MessagePostSendEvent
4145
- 群消息: GroupMessagePostSendEvent
4246
- 好友消息: FriendMessagePostSendEvent
@@ -86,6 +90,7 @@
8690
##### 名片和头衔
8791
- 成员群名片改动: MemberCardChangeEvent
8892
- 成员群特殊头衔改动: MemberSpecialTitleChangeEvent
93+
- 成员群荣誉改变: MemberHonorChangeEvent
8994

9095
##### 成员权限
9196
- 成员权限改变: MemberPermissionChangeEvent
@@ -102,3 +107,7 @@
102107
- 好友头像改变: FriendAvatarChangedEvent
103108
- 好友昵称改变: FriendNickChangedEvent
104109
- 好友输入状态改变: FriendInputStatusChangedEvent
110+
111+
### 控制台
112+
- 自动登录执行后: StartupEvent [2.15.0, +∞)
113+
- 控制台启动完成: AutoLoginEvent [2.15.0, +∞)

‎docs/Preparations.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,13 @@
44

55
## JVM 环境要求
66

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

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

1615
**但注意不要使用 Oracle JDK**
1716
（[原因](https://github.com/mamoe/mirai/discussions/779)），可以使用其他任何 JDK。

‎docs/Questions.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Mirai - Questions
2+
3+
## 用户常见问题
4+
5+
> 'java' 不是内部或外部命令，也不是可运行的程序
6+
7+
没有安装 Java。
8+
9+
> `Failed to fetch announcement for ...`
10+
11+
[MCL](https://github.com/iTXTech/mirai-console-loader) 查询更新信息失败，可以尝试编辑 `config.json`，
12+
更换 [mirai repo](https://github.com/project-mirai/mirai-repo-mirror#%E4%BB%93%E5%BA%93%E9%95%9C%E5%83%8F)。
13+
14+
> Login failed: Error(bot=..., code=..., title=....
15+
16+
这些是服务器返回的信息，它表示你的账号被登录风控了。
17+
风控没有 100% 稳定的解决方法，你可以关注 [论坛公告帖 - 无法登录的临时处理方案](https://mirai.mamoe.net/topic/223)。
18+
密码登录中是否出现滑块验证或短信验证都是不可控的，这取决于腾讯的服务器要求你完成什么验证，没有办法自由选择。
19+
20+
> 登录协议如何修改
21+
22+
对于手动密码登录，第三个参数就是协议, 例如 `login 12345 114514 MACOS`
23+
24+
对于自动密码登录，可以使用指令修改，例如 `autoLogin setConfig 12345 protocol MACOS`，
25+
也可以在 Mirai Console 关闭的情况下, 编辑 `config/Console/AutoLogin.yml` 文件。
26+
27+
注意，文件中有一个账号为 `12345` 的示例，请注意确认修改的配置对应的账号，不要修改错了示例。
28+
29+
> 聊天框无法使用指令(使用指令后没效果)
30+
31+
1. 确认机器人收到消息
32+
日志里会有消息记录，没有就是没收到，如果是群聊消息，注意是否已 `收入群助手`，这可能会导致收不到消息
33+
34+
2. 确认是否已经安装 [chat-command](https://github.com/project-mirai/chat-command/releases/latest)
35+
如果插件的指令是对接的 `Mirai Console` 的指令接口，那它就需要 `chat-command`
36+
37+
3. 确认是否已经授权给目标用户
38+
默认情况下所有用户都是没有权限的，聊天框下无法使用指令
39+
备注：如果使用了 LuckPerms-Mirai，可通过在控制台执行 /lp verbose on 查看权限检测情况
40+
41+
4. 确认日志中没有相关报错
42+
如果插件指令执行出错，也有可能无法提供回复，请联系插件作者
43+
44+
> 如何确认 `Mirai 版本` 或 `插件版本` 等信息
45+
46+
可以启动 Mirai Console 的情况下:
47+
使用指令 `/status` 。
48+
49+
无法启动的情况下:
50+
Mirai Console 的组件在 `libs` 文件夹下, 文件名包含 `版本信息`。
51+
52+
> 找不到 `http api` 的相关配置文件
53+
54+
可能需要安装插件 <https://github.com/project-mirai/mirai-api-http>。
55+
56+
> 如何添加 jvm 参数，例如 `-Dmirai.no-desktop=true`
57+
58+
编辑启动脚本 `mcl.cmd`，在 `-jar` 前面加上 `-D...`，例如 `-Dmirai.no-desktop=true -jar mcl...`。
59+
60+
Linux 和 macOS 的启动脚本是 `mcl` (没有后缀的那个文件)。
61+
62+
## 开发者常见问题
63+
64+
> 如何自定义登录验证处理
65+
66+
[覆盖登录解决器](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)
67+
68+
> IDEA 下 `import` 爆红，mirai 相关依赖全部无法解析
69+
70+
IDEA 版本过于老旧，无法分析新版本的 Kotlin 依赖，请尝试升级 IDEA 后重试。
71+
72+
> 有些事件收到不到
73+
74+
`SignEvent` 或者 `NudgeEvent`：
75+
76+
总的来说 `MACOS` 和 `ANDROID_WATCH` 相对其他协议会缺少一些事件的接收。
77+
对于这些协议来说是不会收到的，因为这在他们对应官方客户端版本里本来就没有这些功能。
78+
79+
`GroupMessageEvent`：
80+
81+
群事件收不到可能是因为你将群设置为 `屏蔽群` 或者 `收入了群助手`。
82+
另外如果消息是 `转发消息` 或 `卡片消息` 等特殊消息, 也有可能因为风控无法接收和发出。
83+
84+
> 发送语音之后播放没有声音
85+
86+
你可能需要安装插件或引入依赖 <https://github.com/project-mirai/mirai-silk-converter>。

0 commit comments

Comments
 (0)