mirror of
https://github.com/mamoe/mirai.git
synced 2024-12-26 08:30:11 +08:00
Rewrite docs for beginners
This commit is contained in:
Him188
parent
6cd45c7746
commit
fd5334946a
@ -121,6 +121,7 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效
|
||||
|
||||
## 开始
|
||||
|
||||
- **用户手册**: [UserManual](docs/UserManual.md)
|
||||
- 开发文档: [docs](docs/README.md)
|
||||
- 论坛: [Mirai Forum](https://mirai.mamoe.net/)
|
||||
> *Mirai 只有唯一一个官方论坛 Mirai Forum*
|
||||
|
||||
BIN
docs/.UserManual_images/MCLI-1.png
Normal file
BIN
docs/.UserManual_images/MCLI-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
BIN
docs/.UserManual_images/MCPS-1.png
Normal file
BIN
docs/.UserManual_images/MCPS-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
@ -4,7 +4,7 @@
|
||||
|
||||
### 选择版本
|
||||
|
||||
有关各类版本的区别，参考 [版本规范](Evolution.md#版本规范)
|
||||
有关各类版本的区别，参考 [版本规范](Evolution.md#版本规范)。通常建议选择最新稳定版本。
|
||||
|
||||
[Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-core/images/download.svg?
|
||||
[Bintray Download]: https://bintray.com/him188moe/mirai/mirai-core/
|
||||
|
||||
@ -1,19 +1,21 @@
|
||||
# Mirai
|
||||
|
||||
欢迎来到 mirai 文档。
|
||||
欢迎来到 mirai 开发文档。
|
||||
|
||||
## 生态
|
||||
本文面向要进行开发的用户。对于只使用现成插件的用户，请阅读 [用户手册](UserManual.md)。
|
||||
|
||||
请先阅读 **[Mirai 生态概览](mirai-ecology.md)**。
|
||||
[Mirai 生态概览](mirai-ecology.md)
|
||||
|
||||
## 社区 SDK
|
||||
|
||||
**mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果不熟悉这些语言，请使用以下社区 SDK：**
|
||||
**mirai 官方提供 [Kotlin/Java 等 JVM 平台语言开发支持](#jvm-平台-mirai-开发)。如果不熟悉这些语言，请使用以下社区 SDK：**
|
||||
|
||||
要使用这些插件需要先配置 Mirai Console，推荐阅读 [用户手册](UserManual.md)。
|
||||
|
||||
你可以使用一个或多个语言来开发插件，而且在自己开发的同时也可以[使用下载的插件](UserManual.md#下载和安装插件)。
|
||||
|
||||
[`mirai-console`]: https://github.com/mamoe/mirai-console
|
||||
|
||||
这些 SDK 基于 [`mirai-console`]。[`mirai-console`] 是 mirai 官方维护的一个*应用程序*。可以在 [这里](https://github.com/mamoe/mirai-console/blob/master/docs/Run.md) 了解如何启动 [`mirai-console`]（也可以稍后在各 SDK 的说明中了解）。
|
||||
|
||||
[mamoe/mirai-api-http]: https://github.com/mamoe/mirai-api-http
|
||||
[iTXTech/mirai-native]: https://github.com/iTXTech/mirai-native
|
||||
[iTXTech/mirai-js]: https://github.com/iTXTech/mirai-js
|
||||
@ -34,30 +36,51 @@
|
||||
[drinkal/Mirai-js]:https://github.com/drinkal/Mirai-js
|
||||
[Coloryr/ColorMirai]: https://github.com/Coloryr/ColorMirai
|
||||
|
||||
[Rhino]: https://github.com/mozilla/rhino
|
||||
[OneBot]: https://github.com/howmanybots/onebot
|
||||
[Mirai HTTP]: https://github.com/project-mirai/mirai-api-http
|
||||
|
||||
### 原生接口
|
||||
|
||||
这些接口直接在 JVM 上实现，不需要中间件，拥有更佳的性能。
|
||||
|
||||
| 技术 | 维护者及项目地址 |
|
||||
|:-------------------|:-----------------------|
|
||||
| `Kotlin Scripting` | [iTXTech/mirai-kts] |
|
||||
| `C++` | [Nambers/MiraiCP] |
|
||||
| `JavaScript` | [iTXTech/mirai-js] |
|
||||
| *酷 Q DLL 插件* | [iTXTech/mirai-native] |
|
||||
|
||||
### HTTP 接口
|
||||
|
||||
目前有两个 HTTP 协议插件。使用 HTTP 协议插件可以支持更多编程语言和技术。
|
||||
|
||||
- [***Mirai HTTP***][Mirai HTTP] 由 Mirai 开发团队提供第一级支持，目前多数 SDK 都基于它；
|
||||
- [OneBot] 标准则兼容原酷Q协议，可以让基于酷Q HTTP 插件的项目在 Mirai 平台运行。
|
||||
|
||||
| 名称 | 实现 | 维护者及项目地址 |
|
||||
|:-----------------|:-------------|:-------------------------------|
|
||||
| ***Mirai Http*** | Mirai 标准 | [mamoe/mirai-api-http] |
|
||||
| *OneBot Http* | [OneBot] 标准 | [yyuueexxiinngg/onebot-kotlin] |
|
||||
|
||||
下表列举基于 Mirai HTTP 插件实现对一些编程语言支持的项目列表。要使用它们，你需要[在 Mirai Console 安装 `mirai-api-http`](https://github.com/project-mirai/mirai-api-http#%E5%AE%89%E8%A3%85mirai-api-http)。
|
||||
|
||||
|
||||
| 语言和技术 | 维护者及项目地址 |
|
||||
|:--------------------------|:--------------------------------------------|
|
||||
| `Python` | [Graia Framework][GraiaProject/Application] |
|
||||
| `Python` | [NoneBot] |
|
||||
| `C++` | [cyanray/mirai-cpp] |
|
||||
| `C++` | [Chlorie/miraipp] |
|
||||
| `C#` | [Executor-Cheng/mirai-CSharp] |
|
||||
| `C#` | [Hyperai][theGravityLab/ProjHyperai] |
|
||||
| `C#` | [Coloryr/ColorMirai] |
|
||||
| `Rust` | [HoshinoTented/mirai-rs] |
|
||||
| `JavaScript` / Node.js | [RedBeanN/node-mirai] |
|
||||
| `JavaScript` / TypeScript | [YunYouJun/mirai-ts] |
|
||||
| `JavaScript` / Node.js | [drinkal/Mirai-js] |
|
||||
| `Go` | [Logiase/gomirai] |
|
||||
| `易语言` | [only52607/e-mirai] |
|
||||
|
||||
| 技术 | 实现 | 维护者及项目地址 |
|
||||
|:-------------------|:-----------------------------|:--------------------------------------------|
|
||||
| ***Mirai Http*** | Mirai 标准 | [mamoe/mirai-api-http] |
|
||||
| *OneBot Http* | [OneBot] 标准 | [yyuueexxiinngg/onebot-kotlin] |
|
||||
| `Kotlin Scripting` | JVM | [iTXTech/mirai-kts] |
|
||||
| `Python` | *Mirai Http* | [Graia Framework][GraiaProject/Application] |
|
||||
| `Python` | *Mirai Http* / *OneBot Http* | [NoneBot] |
|
||||
| `C++` | JNI | [Nambers/MiraiCP] |
|
||||
| `C++` | *Mirai Http* | [cyanray/mirai-cpp] |
|
||||
| `C++` | *Mirai Http* | [Chlorie/miraipp] |
|
||||
| `C#` | *Mirai Http* | [Executor-Cheng/mirai-CSharp] |
|
||||
| `C#` | *Mirai Http* | [Hyperai][theGravityLab/ProjHyperai] |
|
||||
| `C#` | *WebSocket* | [Coloryr/ColorMirai] |
|
||||
| `Rust` | *Mirai Http* | [HoshinoTented/mirai-rs] |
|
||||
| `JavaScript` | [Rhino] / JVM | [iTXTech/mirai-js] |
|
||||
| `JavaScript` | Node.js / *Mirai Http* | [RedBeanN/node-mirai] |
|
||||
| `JavaScript` | TypeScript / *Mirai Http* | [YunYouJun/mirai-ts] |
|
||||
| `JavaScript` | Node.js / *Mirai Http* | [drinkal/Mirai-js] |
|
||||
| `Go` | *Mirai Http* | [Logiase/gomirai] |
|
||||
| `易语言` | *Mirai Http* | [only52607/e-mirai] |
|
||||
| *酷 Q DLL 插件* | JNI | [iTXTech/mirai-native] |
|
||||
|
||||
> 排名不分先后
|
||||
> *想在这里添加你的项目？欢迎[提交 PR](https://github.com/mamoe/mirai/edit/dev/docs/README.md)。*
|
||||
@ -68,20 +91,22 @@
|
||||
|
||||
## JVM 平台 Mirai 开发
|
||||
|
||||
本节介绍使用 Java、Kotlin 等 JVM 平台编程语言开发 Mirai 或 Mirai Console 插件。
|
||||
|
||||
**为了避免遇到各种问题，请逐步仔细阅读。**
|
||||
|
||||
1. [JVM 环境和开发准备工作](Preparations.md#mirai---preparations)
|
||||
|
||||
2. 选择框架
|
||||
- 若要将 mirai 当做依赖库嵌入你的应用使用，则需要使用 mirai-core，请阅读 [配置项目依赖](ConfiguringProjects.md)。
|
||||
建议先阅读 [Mirai 生态概览](mirai-ecology.md)。
|
||||
|
||||
- 若要以插件模式开发，可以使用 mirai-console，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。
|
||||
- 若要将 mirai 当做依赖库嵌入你的应用使用（你调用 mirai），则需要使用 mirai-core，请阅读 [配置项目依赖](ConfiguringProjects.md)。
|
||||
|
||||
- 若要以插件模式开发（mirai 调用你），可以使用 mirai-console，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。
|
||||
|
||||
4. 阅读 API 文档（见下文）
|
||||
|
||||
|
||||
> 如果你不知道 `mirai-core` 或 [`mirai-console`] 是什么，请阅读 [Mirai 生态概览](mirai-ecology.md)。
|
||||
>
|
||||
> 如果你希望先确认 mirai 能够正常运行才能安心阅读文档，可克隆 [mirai-hello-world](https://github.com/project-mirai/mirai-hello-world) 并运行其中 Kotlin 或 Java 入口点 `main`。
|
||||
|
||||
|
||||
|
||||
95
docs/UserManual.md
Normal file
95
docs/UserManual.md
Normal file
@ -0,0 +1,95 @@
|
||||
# Mirai - UserManual
|
||||
|
||||
Mirai 用户手册。本文面向对开发不熟悉而希望使用 Mirai 的用户。
|
||||
|
||||
## 启动 Mirai
|
||||
|
||||
使用 Mirai，一般人要启动的是 Mirai 控制台（即 Mirai Console），它可以加载插件。
|
||||
|
||||
Mirai 控制台现在有两个版本，插件在这两个版本的 Mirai Console 上都可以运行:
|
||||
|
||||
[MCLI-1.png]: .UserManual_images/MCLI-1.png
|
||||
[MCPS-1.png]: .UserManual_images/MCPS-1.png
|
||||
|
||||
| 类型 | 长啥样? | 好用吗? | 怎么装? |
|
||||
|:-------|:-------------|:----------------|:-------------------------------|
|
||||
| 纯控制台 | [MCLI-1.png] | 稳定，也适合服务器 | [使用纯控制台版本](#使用纯控制台版本) |
|
||||
| 图形界面 | [MCPS-1.png] | 测试版，不稳定 | [使用图形界面版本](#使用图形界面版本) |
|
||||
|
||||
## 使用图形界面版本
|
||||
|
||||
前往 [sonder-joker/mirai-compose](https://github.com/sonder-joker/mirai-compose/releases) 下载适合你的系统的压缩包，解压到一个文件就可以使用。
|
||||
|
||||
## 使用纯控制台版本
|
||||
|
||||
### 安装
|
||||
|
||||
可以使用安装器来全自动安装：
|
||||
|
||||
1. 访问 [iTXTech/mcl-installer](https://github.com/iTXTech/mcl-installer/releases)；
|
||||
2. 下载适合你的系统的可执行文件；
|
||||
3. 在一个新文件夹存放这个文件，运行它；
|
||||
4. 通常可以一路回车使用默认设置完成安装，安装完成后程序自动退出；
|
||||
5. 运行 `mcl.cmd` 启动，成功后会看到绿色的 `mirai-console started successfully`。
|
||||
|
||||
### 了解运行环境
|
||||
|
||||
安装时自动下载了 Mirai Console 启动器（简称 [MCL](https://github.com/iTXTech/mirai-console-loader)）。
|
||||
|
||||
启动器会帮你准备运行环境，下载和更新 Mirai 核心。你也可以使用启动器下载一些插件（见下文）。
|
||||
|
||||
第一次运行 `mcl.cmd` 时会初始化运行环境。下表说明了各个文件夹的用途。
|
||||
|
||||
| 文件夹名称 | 用途 |
|
||||
|:---------:|:------------------------------|
|
||||
| `scripts` | 存放启动器的脚本，一般不需要在意他们 |
|
||||
| `plugins` | 存放插件 |
|
||||
| `data` | 存放插件的数据，一般不需要在意它们 |
|
||||
| `config` | 存放插件的配置，可以打开并修改配置 |
|
||||
| `logs` | 存放运行时的日志，日志默认保留 7 天 |
|
||||
|
||||
> 可以在[这里](https://github.com/iTXTech/mirai-console-loader)查看 MCL 详细用法
|
||||
|
||||
### 下载和安装插件
|
||||
|
||||
刚刚装好的 Mirai Console 是没有任何功能的。功能将由插件提供。
|
||||
|
||||
#### 如何安装官方插件
|
||||
|
||||
Mirai 官方提供两个插件：
|
||||
|
||||
- [chat-command](https://github.com/project-mirai/chat-command): 允许在聊天环境通过以 "/" 起始的消息执行指令
|
||||
- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供 HTTP 支持，允许使用其他编程语言的插件
|
||||
|
||||
打开命令行 (Windows 系统按住Shift+鼠标右键，点击"在此处打开 PowerShell"),
|
||||
可以使用 MCL 自动安装这些插件如：
|
||||
|
||||
```
|
||||
./mcl --update-package net.mamoe:mirai-api-http --type plugin --channel stable
|
||||
```
|
||||
|
||||
详细文档：[MCL/scripts](https://github.com/iTXTech/mirai-console-loader/blob/master/scripts/README.md)
|
||||
|
||||
#### 在哪找社区插件
|
||||
|
||||
- Mirai 官方论坛 [Mirai Forum](https://mirai.mamoe.net/category/11/%E6%8F%92%E4%BB%B6%E5%8F%91%E5%B8%83)
|
||||
|
||||
> *我们还正在建设插件中心，完成后将会简化寻找插件的工作*
|
||||
|
||||
#### 如何安装社区插件
|
||||
|
||||
如果是 JAR 文件的插件，放入 `plugins` 即可。其他插件一般都有特殊说明如何使用，请参考它们的说明。
|
||||
|
||||
|
||||
### 使用控制台指令
|
||||
|
||||
启动 `mcl.cmd` 就会看到控制台。在控制台可以输入指令，按回车执行这条指令。
|
||||
|
||||
Mirai Console 内置一些指令，输入 `?` 并回车可以查看指令列表。
|
||||
|
||||
一些常用指令介绍在[这里](https://github.com/mamoe/mirai-console/blob/master/docs/BuiltInCommands.md#mirai-console---builtin-commands)。
|
||||
|
||||
## 解决问题
|
||||
|
||||
如果遇到使用问题或想提建议，可以在 [issues](https://github.com/mamoe/mirai/issues) 发表。也可以在[论坛](https://mirai.mamoe.net/)交流想法。
|
||||
|
||||
@ -115,8 +115,6 @@ mirai-console-loader 应运而生，它的工作就是简化 console 启动流
|
||||
|
||||
即可快速启动 mirai-console 的 terminal 前端。同时 mirai-console-loader 还有一些拓展功能，可以自定义你的启动流程。
|
||||
|
||||
在 mirai-console-loader 诞生之前，还有一个非官方的 mirai-console-terminal 一键启动器 MiraiOK，但是我们已**不推荐**使用 MiraiOK。([为什么？](https://github.com/project-mirai/mirai-api-http/issues/212#issuecomment-743216244))
|
||||
|
||||
将 mirai-console-loader 放入上述关系图：
|
||||
|
||||
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgY2xhc3NEZWYgY29yZWhpZ2hsaWdodCBmaWxsOiNmOTYsc3Ryb2tlOiMzMzMsc3Ryb2tlLXdpZHRoOjNweDtcbiAgICBjbGFzc0RlZiBoaWdobGlnaHQgZmlsbDojZjg4LHN0cm9rZTojMzMzLHN0cm9rZS13aWR0aDozcHhcbiAgICBzdWJncmFwaCBtaXJhaSBbXCJNaXJhaSDmoYbmnrZcIl1cbiAgICAgICAgbWlyYWljb3JlYXBpKFwibWlyYWktY29yZS1hcGlcIik6Ojpjb3JlaGlnaGxpZ2h0XG4gICAgICAgIG1pcmFpY29yZXFxYW5kcm9pZChcIm1pcmFpLWNvcmU8YnIvPihRUUFuZHJvaWQg5Y2P6K6uKVwiKVxuICAgICAgICBtaXJhaWNvcmVxcWFuZHJvaWQgLS0-IHzmj5DkvpvljY_orq58bWlyYWljb3JlYXBpXG4gICAgZW5kXG4gICAgbWlyYWlpbnRlcmZhY2UoXCLkvaDnvJblhpnnmoQ8YnIvPuacuuWZqOS6uueoi-W6j1wiKVxuICAgIG1pcmFpY29yZWFwaSAtLT4gfOaPkOS-m-WfuuehgOWKn-iDvXxtaXJhaWludGVyZmFjZVxuICAgIG1pcmFpY29yZWFwaSAtLT4gfOWwgeijheWfuuehgOWKn-iDvXxtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgc3ViZ3JhcGggbWlyYWljb25zb2xlIFtcIk1pcmFpIENvbnNvbGVcIl1cbiAgICAgICAgbWlyYWljb25zb2xlYmFja2VuZChcIkJhY2tFbmRcIilcbiAgICAgICAgbWlyYWljb25zb2xlZnJvbnRlbmQtdGVybWluYWwoXCJGcm9udEVuZDogdGVybWluYWxcIilcbiAgICAgICAgbWlyYWljb25zb2xlZnJvbnRlbmQtYW5kcm9pZChcIkZyb250RW5kOiBBbmRyb2lkXCIpXG4gICAgICAgIG1pcmFpY29uc29sZWJhY2tlbmQgLS0-IG1pcmFpY29uc29sZWZyb250ZW5kLXRlcm1pbmFsXG4gICAgICAgIG1pcmFpY29uc29sZWJhY2tlbmQgLS0-IG1pcmFpY29uc29sZWZyb250ZW5kLWFuZHJvaWRcbiAgICBlbmRcbiAgICBzdWJncmFwaCBjb25zb2xlcGx1Z2lucyBbXCJNaXJhaSBDb25zb2xlIOaPkuS7tlwiXVxuICAgICAgICB5b3VybWlyYWljb25zb2xlcGx1Z2luKFwi5L2g57yW5YaZ55qEIENvbnNvbGUg5o-S5Lu2XCIpIC0tPiBtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgICAgIG1pcmFpYXBpaHR0cChcIm1pcmFpLWFwaS1odHRwIOaPkuS7tlwiKSAgLS0-IG1pcmFpY29uc29sZWJhY2tlbmRcbiAgICAgICAgb3RoZXJzbWlyYWlwbHVnaW4oXCLlhbbku5YgQ29uc29sZSDmj5Lku7ZcIikgLS0-IG1pcmFpY29uc29sZWJhY2tlbmRcbiAgICAgICAgbWlyYWluYXRpdmUoXCJtaXJhaS1uYXRpdmUg5o-S5Lu2XCIpIC0tPiBtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgZW5kXG4gICAgc3ViZ3JhcGggY29tbXVuaXR5c2RrIFtcIuekvuWMuiBTREtcIl1cbiAgICAgICAgY29tbXVuaXR5c2RrYmFzZWVkb25taXJhaWFwaWh0dHAoXCLln7rkuo4gbWlyYWktYXBpLWh0dHAg55qE56S-5Yy6IFNES1wiKSAtLT4gbWlyYWlhcGlodHRwXG4gICAgZW5kXG4gICAgY29vbHFwbHVnaW5zKFwi6YW3UeaPkuS7tlwiKSAtLT4gbWlyYWluYXRpdmVcbiAgICBtaXJhaWNvbnNvbGVsb2FkZXIoXCJtaXJhaS1jb25zb2xlLWxvYWRlclwiKTo6OmhpZ2hsaWdodCAtLS0-IHzlkK_liqh8bWlyYWljb25zb2xlZnJvbnRlbmQtdGVybWluYWxcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user