Rewrite docs for beginners

README.md

@@ -121,6 +121,7 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效
 
 ## 开始
 
+- **用户手册**: [UserManual](docs/UserManual.md)
 - 开发文档: [docs](docs/README.md)
 - 论坛: [Mirai Forum](https://mirai.mamoe.net/)
   > *Mirai 只有唯一一个官方论坛 Mirai Forum*

docs/ConfiguringProjects.md

@@ -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/

docs/README.md

@@ -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] |
-| `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]                      |
+
+下表列举基于 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]                         |
+
 
 > 排名不分先后  
 > *想在这里添加你的项目？欢迎[提交 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`。
 
 

docs/UserManual.md

@@ -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/)交流想法。
+

docs/mirai-ecology.md

@@ -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.ink/img/eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgY2xhc3NEZWYgY29yZWhpZ2hsaWdodCBmaWxsOiNmOTYsc3Ryb2tlOiMzMzMsc3Ryb2tlLXdpZHRoOjNweDtcbiAgICBjbGFzc0RlZiBoaWdobGlnaHQgZmlsbDojZjg4LHN0cm9rZTojMzMzLHN0cm9rZS13aWR0aDozcHhcbiAgICBzdWJncmFwaCBtaXJhaSBbXCJNaXJhaSDmoYbmnrZcIl1cbiAgICAgICAgbWlyYWljb3JlYXBpKFwibWlyYWktY29yZS1hcGlcIik6Ojpjb3JlaGlnaGxpZ2h0XG4gICAgICAgIG1pcmFpY29yZXFxYW5kcm9pZChcIm1pcmFpLWNvcmU8YnIvPihRUUFuZHJvaWQg5Y2P6K6uKVwiKVxuICAgICAgICBtaXJhaWNvcmVxcWFuZHJvaWQgLS0-IHzmj5DkvpvljY_orq58bWlyYWljb3JlYXBpXG4gICAgZW5kXG4gICAgbWlyYWlpbnRlcmZhY2UoXCLkvaDnvJblhpnnmoQ8YnIvPuacuuWZqOS6uueoi-W6j1wiKVxuICAgIG1pcmFpY29yZWFwaSAtLT4gfOaPkOS-m-WfuuehgOWKn-iDvXxtaXJhaWludGVyZmFjZVxuICAgIG1pcmFpY29yZWFwaSAtLT4gfOWwgeijheWfuuehgOWKn-iDvXxtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgc3ViZ3JhcGggbWlyYWljb25zb2xlIFtcIk1pcmFpIENvbnNvbGVcIl1cbiAgICAgICAgbWlyYWljb25zb2xlYmFja2VuZChcIkJhY2tFbmRcIilcbiAgICAgICAgbWlyYWljb25zb2xlZnJvbnRlbmQtdGVybWluYWwoXCJGcm9udEVuZDogdGVybWluYWxcIilcbiAgICAgICAgbWlyYWljb25zb2xlZnJvbnRlbmQtYW5kcm9pZChcIkZyb250RW5kOiBBbmRyb2lkXCIpXG4gICAgICAgIG1pcmFpY29uc29sZWJhY2tlbmQgLS0-IG1pcmFpY29uc29sZWZyb250ZW5kLXRlcm1pbmFsXG4gICAgICAgIG1pcmFpY29uc29sZWJhY2tlbmQgLS0-IG1pcmFpY29uc29sZWZyb250ZW5kLWFuZHJvaWRcbiAgICBlbmRcbiAgICBzdWJncmFwaCBjb25zb2xlcGx1Z2lucyBbXCJNaXJhaSBDb25zb2xlIOaPkuS7tlwiXVxuICAgICAgICB5b3VybWlyYWljb25zb2xlcGx1Z2luKFwi5L2g57yW5YaZ55qEIENvbnNvbGUg5o-S5Lu2XCIpIC0tPiBtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgICAgIG1pcmFpYXBpaHR0cChcIm1pcmFpLWFwaS1odHRwIOaPkuS7tlwiKSAgLS0-IG1pcmFpY29uc29sZWJhY2tlbmRcbiAgICAgICAgb3RoZXJzbWlyYWlwbHVnaW4oXCLlhbbku5YgQ29uc29sZSDmj5Lku7ZcIikgLS0-IG1pcmFpY29uc29sZWJhY2tlbmRcbiAgICAgICAgbWlyYWluYXRpdmUoXCJtaXJhaS1uYXRpdmUg5o-S5Lu2XCIpIC0tPiBtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgZW5kXG4gICAgc3ViZ3JhcGggY29tbXVuaXR5c2RrIFtcIuekvuWMuiBTREtcIl1cbiAgICAgICAgY29tbXVuaXR5c2RrYmFzZWVkb25taXJhaWFwaWh0dHAoXCLln7rkuo4gbWlyYWktYXBpLWh0dHAg55qE56S-5Yy6IFNES1wiKSAtLT4gbWlyYWlhcGlodHRwXG4gICAgZW5kXG4gICAgY29vbHFwbHVnaW5zKFwi6YW3UeaPkuS7tlwiKSAtLT4gbWlyYWluYXRpdmVcbiAgICBtaXJhaWNvbnNvbGVsb2FkZXIoXCJtaXJhaS1jb25zb2xlLWxvYWRlclwiKTo6OmhpZ2hsaWdodCAtLS0-IHzlkK_liqh8bWlyYWljb25zb2xlZnJvbnRlbmQtdGVybWluYWxcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](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)