34 KiB
A brief introduction of Mirai Ecosystem
Mirai是一个免费开源的QQ机器人框架，由于其开源和易拓展的优势，现在已经有很多基于Mirai的官方和非官方衍生框架和应用(下文统一称为项目)，其关系错综复杂。这里将简单为你介绍整个 Mirai 生态中各个框架和应用的关系。
强烈建议你从头并按照文章顺序和思路阅读，即使你对 Mirai 生态有一定的了解。
目录：
Mirai: 使用 Kotlin 编写的高效率 QQ 机器人框架
Mirai，正如你所见，这个名字不带任何的前缀或后缀，它是整个生态的中心，在这个生态中，所有的项目都直接或间接与 Mirai 有密不可分的关系，Mirai为用户提供了最基础且核心的功能：接收消息与发送消息。
你需要明确了解的是，Mirai 的定位是 QQ 机器人框架，或者说它是一个库(Library)。如果你觉得理解起来有点困难，你可以把它类比为建筑的骨架，一栋只有建筑骨架的建筑是不能住人的，你需要根据这个骨架来盖好这栋楼，它才能住人。同样地，Mirai 是不能直接启动的，需要使用这个框架并按照你的想法来编写QQ机器人程序。
通常来说，Mirai 就是一个 QQ 机器人框架，但是它的内部并不是一个单一的结构：
- mirai-core：是 Mirai 对 QQ 的具体协议实现，它承担具体且核心的工作。
- mirai-core-api：提供了使用 Mirai 的接口。它抽象了核心协议的接口，如收发消息，群操作等，但不承担具体工作。
它们的关系如下：
可以看到，协议内容只在 Mirai 内部使用，只有 mirai-core-api 对外提供了功能。
你需要使用 Kotlin 语言或 Java 语言来编写你的QQ机器人程序。在开发时需要依赖 mirai-core-api，而开发完成后要运行时需要有 mirai-core 来承担核心工作。
可以参考官方示例：project-mirai/mirai-demos。
mirai-console: Mirai 官方的可拓展式QQ机器人管理控制台
前面我们提到，你可以使用 Mirai 框架提供的对外开放接口来编写个性化QQ机器人程序，而 mirai-console 就是 Mirai 官方开发组编写的QQ机器人程序，它在 Mirai 框架提供的基础功能的基础上进行了封装并进一步提供了更方便的开放接口。
比如，console 提供了配置自动登录，自动配置/数据存储功能，这样你就不需要自己考虑写配置登录或者数据存储了，减少了代码工作量。承接上面的例子，mirai-console 就相当于为你在建筑骨架上砌好了墙，分好了房间，这样你就能更容易地盖好这栋楼了。
重要的是，mirai-console 有 CLI 即 command-line interface， 可以直接在终端运行它，并实时看到你的机器人状态、插件的运行情况，或者通过 console 提供的命令管理指令权限或者执行插件提供的指令等。
同样，你需要使用 Kotlin 语言或 Java 语言来编写基于 mirai-console 的 QQ机器人程序，在 mirai-console 中，你编写的程序被称作插件(Plugin)，它将被打包为 jar 文件，这样可以很方便发布你的机器人功能程序给其他人使用，把插件 mirai-console 指定的文件夹下，启动 mirai-console 就可以加载你的程序了。
你一定玩过 Minecraft， 这里的插件就像 Minecraft 的 mod 一样！
当然，在编写 console 插件时，你不仅能使用 console 提供的简便接口，你还可以同时使用 mirai-core-api 提供的基础接口。
mirai-console 的内部也不是单一的结构，它分为前端和后端具体如下：
- 后端(backEnd)：后端就是做了上述工作，即提供指令，权限，自动数据等开放接口。
- 前端(frontEnd)：前端就是启动 mirai-console 并监控后端运行状态的端口，上述 CLI 是前端的一种，即 mirai-console-terminal，在终端启动的前端。另外还有其他两个前端，分别是可以在 Android 启动的 MiraiAndroid 和正在开发的图形界面 mirai-console-graphical。
后端就像是“电脑主机”，执行着核心工作，前端就像是“显示器”、“鼠标”和“键盘”，可以控制后端。
注意这里的比喻并不是完全符合，因为 console 没有前端就无法运行后端，而电脑主机没了显示器等可以自行工作。
将 mirai-console 放入上述关系图：
你可以参考官方示例 Him188/mirai-console-example-plugin(Kotlin DSL) 和 Karlatemp/mirai-console-example-plugin(Groovy DSL) 来了解如何编写一个 console 插件。
如果你想自己编写一个 console 插件，你可以使用这个模板：project-mirai/mirai-console-plugin-template。
chat-command: Mirai Console 的官方的聊天命令插件
在 mirai-console 的前端中，我们提到可以在前端执行 console 内置和插件提供的命令，如果我们想在聊天环境(好友聊天/群聊天/临时会话)执行 console 命令，我们就需要官方提供的 chat-command，并且，console 中的权限管理正是管理聊天环境中用户执行权限的。
将 chat-command 放入上述关系图：
mirai-api-http: Mirai Console 的官方 HTTP API 插件
在 console 中提到，插件也可以使用 mirai-core-api 提供的基础接口， 而 mirai-api-http 插件就是一个将 mirai-core-api 的所有功能封装为 http 服务的插件，同时也提供了 WebSocket 服务。
这样即使你不懂 Java 或 Kotlin，使用 mirai-api-http 插件，你也可以与 Mirai 交互，极大地增加了语言拓展性，也因此衍生出了许多基于 mirai-api-http 的社区 SDK。
这些社区 SDK 封装了 mirai-api-http 提供的接口，且使用了其他语言的良好特性，使编写QQ机器人程序变得更加容易，高效。
将 mirai-api-http 和大部分官方列举的社区 SDK 放入上述关系图：
注：lua-mirai 使用了 luakt 库实现 Lua 语言和 Kotlin 的直接交互，它是基于 mirai-core-api 的，与 mirai-api-http 没有任何关系。
mirai-native: 与 CoolQ 对接的一个通道
如果你是 酷Q 用户，想在 Mirai 中使用 酷Q 插件，你可以使用 mirai-native 插件，它可以加载 CQP.dll 并兼容大部分酷Q插件，但不支持 CPK 和解包的 DLL。
不过 酷Q 已经停止提供服务，我们也不再建议使用 酷Q 的插件。
将 mirai-native 放入上述关系图：
mirai-console-loader: Mirai Console 的官方一键启动器
前面说道我们可以直接在终端运行 mirai-console 的前端 mirai-console-terminal，然而想运行起来 mirai-console-terminal 却不是很容易的事情：你需要下载好 Mirai 官方发布的 mirai-core，mirai-console 和 mirai-console-terminal 的 jar 文件，你还需要知道 terminal 前端的入口是 net.mamoe.mirai.console.terminal.MiraiConsoleTerminalLoader，然后你还需要通过一大串指令启动它。
java -cp "上述jar文件路径" net.mamoe.mirai.console.terminal.MiraiConsoleTerminalLoader
这种复杂的启动方式劝退了许多新手，尤其是未曾听说过 JVM 的新手。
mirai-console-loader 应运而生，它的工作就是简化 console 启动流程，一键帮你下载 jar 文件，自动更新，文件损坏检查...... 你能在手动启动时担心的问题 mirai-console-loader 都帮你想到了！你只需要：
./mcl
即可快速启动 mirai-console 的 terminal 前端。同时 mirai-console-loader 还有一些拓展功能，可以自定义你的启动流程。
在 mirai-console-loader 诞生之前，还有一个非官方的 mirai-console-terminal 一键启动器 MiraiOK，但是我们已不推荐使用 MiraiOK。(为什么？)
将 mirai-console-loader 放入上述关系图：
以上就是整个 Mirai 生态的概览，如有疏漏或错误，欢迎提出 Issue 修正。
实体关系图采用 Mermaid 绘制。