From ec03f8322d408bcda8e45a5a74a01363c2dac7e8 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Sat, 19 Sep 2020 23:29:28 +0800
Subject: [PATCH] Update docs

---
 README.md                                     |  71 ++-----
 .../internal/MiraiConsoleBuildConstants.kt    |   4 +-
 buildSrc/src/main/kotlin/PublishingHelpers.kt |   2 +-
 docs/Appendix.md                              |  49 +++++
 docs/ConfiguringProjects.md                   |  80 ++++++++
 docs/Contributing.md                          |   2 +
 docs/Preparations.md                          | 103 ++++++++++
 docs/README.md                                | 180 ------------------
 docs/Run.md                                   |   4 +-
 tools/gradle-plugin/README.md                 |  47 ++++-
 10 files changed, 304 insertions(+), 238 deletions(-)
 create mode 100644 docs/Appendix.md
 create mode 100644 docs/ConfiguringProjects.md
 create mode 100644 docs/Contributing.md
 create mode 100644 docs/Preparations.md

diff --git a/README.md b/README.md
index fe7570100..9bc33196e 100644
--- a/README.md
+++ b/README.md
@@ -15,65 +15,32 @@ Mirai 是一个在全平台下运行，提供 QQ 协议支持的高效率机器
 
 # mirai-console
 
-高效率插件支持 QQ 机器人框架, 机器人核心来自 [mirai](https://github.com/mamoe/mirai)
+高效率 QQ 机器人框架，机器人核心来自 [mirai](https://github.com/mamoe/mirai)
 
-## 模块说明
+![Gradle CI](https://github.com/mamoe/mirai-console/workflows/Gradle%20CI/badge.svg?branch=master)
+[![Gitter](https://badges.gitter.im/mamoe/mirai.svg)](https://gitter.im/mamoe/mirai?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-console 由后端和前端一起工作. 使用时必须选择一个前端.
+## 开发
 
-- `mirai-console`: console 的后端, 包含插件管理, 指令系统, 配置系统.
+- **[准备工作 - 环境和前置知识](docs/Preparations.md)**
+- **[配置项目](docs/ConfiguringProjects.md)**
+- **[启动 Console](docs/Run.md)**
+
+### 后端插件开发基础
+
+- 插件 - [Plugin 模块](docs/Plugins.md)
+- 指令 - [Command 模块](docs/Commands.md)
+- 存储 - [PluginData 模块](docs/PluginData.md)
+- 权限 - [Permission 模块](docs/Permissions.md)
 
 
-
-前端:
-
-- `mirai-console-terminal`: console 的 Unix 终端界面前端.
-- `mirai-console-graphical`: console 的 JavaFX 图形化界面前端. (开发中)
-
-**注意：`mirai-console` 1.0-RC 发布之前, 前端请使用 `mirai-console-pure` 而不是 `mirai-console-terminal`**
-
-**注意：`mirai-console` 后端和 terminal 前端正在进行完全的重构, 所有 API 都不具有稳定性**
-
-### 版本
-
-[Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-console/images/download.svg?
-[Bintray Download]: https://bintray.com/him188moe/mirai/mirai-console/
-
-详见 [版本规范](docs/README.md#版本规范)
-
-| 版本类型 |    版本号     |
-|:------:|:------------:|
-|  稳定   |      -       |
-|  预览   |    1.0-M4    |
-|  开发   | [![Version]][Bintray Download] |
-
-### 使用
-
-**查看示例插件**
+**示例插件**：
 - [mirai-console-example-plugin (Kotlin DSL)](https://github.com/Him188/mirai-console-example-plugin)
 - [mirai-console-example-plugin (Groovy DSL)](https://github.com/Karlatemp/mirai-console-example-plugin)
 
-正在更新中的文档：[参考文档](docs/README.md)
+### 后端插件开发进阶
 
-#### Gradle
-`CORE_VERSION`: [ ![Download](https://api.bintray.com/packages/him188moe/mirai/mirai-core/images/download.svg?) ](https://bintray.com/him188moe/mirai/mirai-core/)
+- 扩展 - [Extension 模块和扩展点](docs/Extensions.md)
 
-
-build.gradle.kts
-```kotlin
-repositories {
-  jcenter()
-}
-
-dependencies {
-  implementation("net.mamoe:mirai-core:$CORE_VERSION") // mirai-core 的 API
-  implementation("net.mamoe:mirai-console:$CONSOLE_VERSION") // 后端
-  
-  testImplementation("net.mamoe:mirai-console-terminal:$CONSOLE_VERSION") // 前端, 用于启动测试
-}
-```
-
-**注意：`mirai-console` 1.0-RC 发布之前, 前端请使用 `mirai-console-pure` 而不是 `mirai-console-terminal`**
-
-#### Maven
-同理 Gradle
+### 实现前端
+- [FrontEnd](docs/FrontEnd.md)
\ No newline at end of file
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleBuildConstants.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleBuildConstants.kt
index 8ee34200d..19dd40076 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleBuildConstants.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleBuildConstants.kt
@@ -14,8 +14,8 @@ import java.time.Instant
 
 internal object MiraiConsoleBuildConstants { // auto-filled on build (task :mirai-console:fillBuildConstants)
     @JvmStatic
-    val buildDate: Instant = Instant.ofEpochSecond(1599934775)
+    val buildDate: Instant = Instant.ofEpochSecond(1600522812)
 
     @JvmStatic
-    val version: Semver = Semver("1.0-M4", Semver.SemverType.LOOSE)
+    val version: Semver = Semver("1.0-RC-dev-28", Semver.SemverType.LOOSE)
 }
diff --git a/buildSrc/src/main/kotlin/PublishingHelpers.kt b/buildSrc/src/main/kotlin/PublishingHelpers.kt
index a6af10e47..69b954dac 100644
--- a/buildSrc/src/main/kotlin/PublishingHelpers.kt
+++ b/buildSrc/src/main/kotlin/PublishingHelpers.kt
@@ -54,7 +54,7 @@ internal fun org.gradle.api.Project.`publishing`(configure: org.gradle.api.publi
 inline fun Project.setupPublishing(
     artifactId: String,
     bintrayRepo: String = "mirai",
-    bintrayPkgName: String = "mirai-console",
+    bintrayPkgName: String = artifactId,
     vcs: String = "https://github.com/mamoe/mirai-console"
 ) {
 
diff --git a/docs/Appendix.md b/docs/Appendix.md
new file mode 100644
index 000000000..b8fd0b047
--- /dev/null
+++ b/docs/Appendix.md
@@ -0,0 +1,49 @@
+# Mirai Console - Appendix
+
+### Mirai Console 演进
+
+Mirai Console 是不断前进的框架，将来必定会发生 API 弃用和重构。  
+维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。
+
+#### 版本规范
+
+Mirai Console 的版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/#spec-item-9) 规范。
+
+在日常开发中, Mirai Console 会以 `-dev-1`，`-dev-2` 等版本后缀发布开发预览版本。这些版本仅用于兼容性测试等目的，无稳定性保证。
+
+在大版本开发过程中，Mirai Console 会以 `-M1`, `-M2` 等版本后缀发布里程碑预览版本。代表一系列功能的完成，但还不稳定。  
+这些版本里新增的 API 仍可能还会在下一个 Milestone 版本变化，因此请按需使用。
+
+在大版本即将发布前，Mirai Console 会以 `-RC` 版本后缀发布最终的预览版本。  
+`RC` 表示新版本 API 已经确定，离稳定版发布只差最后的一些内部优化或 bug 修复。
+
+#### 版本选择
+
+**稳定性**：稳定 (`x.y.z`) > 发布预览 (`-RC`) > 里程碑预览 (`-M`) > 开发 (`-dev`)。
+
+|            目的            | 推荐至少更新到版本 |
+|:--------------------------:|:--------------:|
+|          生产环境           |     `x.y.z`     |
+| 希望尽早体验稳定新特性的插件作者 |     `-RC`      |
+| 无论如何都想体验新特性的插件作者 |      `-M`      |
+|    前端实现者, 底层插件作者    |      `-M`      |
+|  为 Mirai Console 提交 PR   |     `-dev`     |
+
+其中，‘底层插件’ 表示提供扩展等的插件。如权限系统，其他语言插件加载器等。
+
+#### 更新兼容性
+
+对于 `x.y.z` 版本号:
+- 当 `z` 增加时，只会有 bug 修复，和必要的新函数添加（为了解决某一个问题），不会有破坏性变化。
+- 当 `y` 增加时，可能有新 API 的引入，和旧 API 的弃用。但这些弃用会经过一个弃用周期后才被删除（隐藏）。向下兼容得到保证。
+- 当 `x` 增加时，任何 API 都可能会有变化。无兼容性保证。
+
+#### 弃用周期
+
+一个计划被删除的 API，将会在下一个次版本开始经历弃用周期。
+
+如一个 API 在 `1.1.0` 起被弃用，它首先会是 `WARNING` (使用时会得到一个编译警告）弃用级别。  
+在 `1.2.0` 上升为 `ERROR`（使用时会得到一个编译错误）；  
+在 `1.3.0` 上升为 `HIDDEN`（使用者无法看到这些 API)。
+
+`HIDDEN` 的 API 仍然会保留在代码中并正常编译，以提供二进制兼容性，直到下一个主版本更新。
diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md
new file mode 100644
index 000000000..6cd90981c
--- /dev/null
+++ b/docs/ConfiguringProjects.md
@@ -0,0 +1,80 @@
+# Mirai Console - Configuring Projects
+
+配置 Mirai Console 项目。
+
+## 模块说明
+
+console 由后端和前端一起工作. 使用时必须选择一个前端.
+
+- `mirai-console`: Mirai Console 后端。
+
+- `mirai-console-terminal`: 终端前端，适用于 JVM。
+- [`MiraiAndroid`](https://github.com/mzdluo123/MiraiAndroid): Android 应用前端。
+
+**注意：`mirai-console` 1.0-RC 发布之前, 前端请使用 `mirai-console-pure` 而不是 `mirai-console-terminal`**
+
+## 选择版本
+
+有关各类版本的区别，参考 [版本规范](Appendix.md#版本规范)
+
+[Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-console/images/download.svg?
+[Bintray Download]: https://bintray.com/him188moe/mirai/mirai-console/
+
+| 版本类型 |    版本号     |
+|:------:|:------------:|
+|  稳定   |      -       |
+|  预览   |    1.0-M4    |
+|  开发   | [![Version]][Bintray Download] |
+
+## 配置项目
+
+### 使用模板项目
+
+Mirai 鼓励插件开发者将自己的作品开源，并为此提供了模板项目。
+
+注意，模板项目依赖的 Mirai Console 不一定是最新的。请检查
+
+1. 访问 [mirai-console-plugin-template](https://github.com/project-mirai/mirai-console-plugin-template)
+2. 点击绿色按钮 "Use this template"，创建项目
+3. 克隆项目，检查并修改生成的属性
+
+### 使用 Gradle 插件配置项目
+
+`VERSION` 可在
+
+若使用 `build.gradle.kts`:
+```kotlin
+plugins {
+    id("net.mamoe.mirai-console") version "VERSION"
+}
+```
+
+若使用 `build.gradle`:
+```groovy
+plugins {
+    id 'net.mamoe.mirai-console' version 'VERSION'
+}
+```
+
+完成。Mirai Console Gradle 插件会为你配置依赖等所有编译环境。
+
+### 手动配置项目
+
+添加依赖：
+`build.gradle.kts`：
+```kotlin
+repositories {
+  jcenter()
+}
+
+dependencies {
+  compileOnly("net.mamoe:mirai-core:$CORE_VERSION") // mirai-core 的 API
+  compileOnly("net.mamoe:mirai-console:$CONSOLE_VERSION") // 后端
+  
+  testImplementation("net.mamoe:mirai-console-terminal:$CONSOLE_VERSION") // 前端, 用于启动测试
+  testImplementation("net.mamoe:mirai-console-terminal:$CONSOLE_VERSION") // 前端, 用于启动测试
+}
+```
+
+之后还需要配置 Kotlin `jvm-default` 编译参数，Kotlin 和 Java 的编译目标等。  
+在打包插件时必须将依赖一并打包进插件 JAR，且排除 `mirai-core`，`mirai-console` 和它们的间接依赖，否则插件不会被加载。
\ No newline at end of file
diff --git a/docs/Contributing.md b/docs/Contributing.md
new file mode 100644
index 000000000..d90a8dd4c
--- /dev/null
+++ b/docs/Contributing.md
@@ -0,0 +1,2 @@
+# Mirai Console - Contributing
+
diff --git a/docs/Preparations.md b/docs/Preparations.md
new file mode 100644
index 000000000..3b3597637
--- /dev/null
+++ b/docs/Preparations.md
@@ -0,0 +1,103 @@
+# Mirai Console - Preparations
+
+***如果跳过本节内容，你很可能遇到无法解决的问题。***
+
+### 环境要求
+
+*不接受降低最低版本要求的建议*
+
+- JDK 11
+- Android：Android SDK 26+ （Android 8.0)
+- Kotlin: 1.4
+
+*Mirai Console 需要的 Kotlin 版本会与 Kotlin 最新稳定版本同步。*
+
+### 开发插件的准备工作
+
+- 安装并配置 JDK 11
+
+若使用 Java，或要修改 Mirai Console：
+
+- 使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) （或 `Android Studio`）。
+- IDE 需装有 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) 插件 (先启动你的 IDE，再点击 [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))
+
+若使用 Kotlin，无特别要求。
+
+## 前置知识
+
+要学习为 mirai-console 开发原生支持的插件, 需要:
+
+- 掌握 Java 基础
+- 至少粗略了解 Kotlin 基础语法（30 分钟）:
+  - [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html)
+  - [类与继承](https://www.kotlincn.net/docs/reference/classes.html)
+  - [属性与字段](https://www.kotlincn.net/docs/reference/properties.html)
+  - [接口](https://www.kotlincn.net/docs/reference/interfaces.html)
+  - [扩展](https://www.kotlincn.net/docs/reference/extensions.html)
+  - [数据类](https://www.kotlincn.net/docs/reference/data-classes.html)
+  - [对象](https://www.kotlincn.net/docs/reference/object-declarations.html)
+  - [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html)
+  - **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)**
+- 对于 Java 使用者，请阅读：
+  - [Java 用户的使用指南](#kotlin-源码阅读帮助)
+  - [在 Java 使用 Mirai Console 中的 Kotlin `suspend` 函数](#在-java-使用-mirai-console-中的-kotlin-suspend-函数)
+- 对于 Kotlin 使用者，请熟知 [Kotlin `1.4` 版本带来的新特性](#mirai-console-使用的-kotlin-14-版本的新特性)
+
+
+### Kotlin 源码阅读帮助
+
+- Java 中的「方法」在 Kotlin 中均被称为「函数」。
+- Kotlin 默认的访问权限是 `public`。如 Kotlin `class Test` 相当于 Java 的 `public class Test {}`
+- Kotlin 的函数定义 `fun test(int: Int): String` 相当于 Java 的方法定义 `public String test(int int)`
+
+### 在 Java 使用 Mirai Console 中的 Kotlin `suspend` 函数
+
+#### 什么是 `suspend` 函数
+
+`suspend` 函数中文是「挂起函数」，是 Kotlin 「[协程](https://www.kotlincn.net/docs/reference/coroutines/coroutines-guide.html)」的一部分。
+
+Kotlin 协程是语言级特性，函数的修饰符 `suspend` 会在编译阶段被处理。
+
+对于一个挂起函数:
+```kotlin
+suspend fun test(): String
+```
+
+它会被编译为 `public Object test(Continuation<String> $completion)`。
+
+这是因为 Kotlin 对所有挂起函数都有这样的内部变化，并在编译时实现了协程的一些特性。
+
+Java 用户无法调用这样的方法，因为 `Continuation` 的实现很复杂。
+
+Mamoe 为此开发了 Kotlin 编译器插件 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge)，通过 `@JvmBlockingBridge` 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。
+
+要获取详细信息，参考 [Kotlin Jvm Blocking Bridge 编译器插件](https://github.com/mamoe/kotlin-jvm-blocking-bridge/blob/master/README-chs.md#%E7%BC%96%E8%AF%91%E5%99%A8%E6%8F%92%E4%BB%B6)
+
+### Mirai Console 使用的 Kotlin `1.4` 版本的新特性
+
+在官方文档的 [语言特性与改进](https://www.kotlincn.net/docs/reference/whatsnew14.html#%E8%AF%AD%E8%A8%80%E7%89%B9%E6%80%A7%E4%B8%8E%E6%94%B9%E8%BF%9B) 基础上，Mirai Console 的一些设计基于 Kotlin 1.4 的更多新特性。
+
+#### `object` 内的扩展函数的自动引用
+对于如下定义：
+```kotlin
+package org.example
+object Obj {
+  fun String.foo()
+}
+```
+在 Kotlin `1.3`，要调用 `foo`，必须使用：
+```kotlin
+Obj.run {
+  "str".foo()
+}
+```
+因为 IDE 不会自动为 `String.foo` 添加 `import`。
+
+Kotlin `1.4` 解决了这个问题。在使用 `"str".foo` 时 Kotlin 会自动添加 `org.example.Obj.foo` 的引用。
+
+Mirai Console 很多单例对象都设计为 `interface + companion object INSTANCE` 的接口与实现模式，需要这样的新特性。例如：
+```kotlin
+interface MiraiConsole {
+    companion object INSTANCE : MiraiConsole by MiraiConsoleImpl // MiraiConsoleImpl 是内部实现，不公开
+}
+```
diff --git a/docs/README.md b/docs/README.md
index 6db0f09d9..95de05428 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,183 +1,3 @@
 # Mirai Console
 
 欢迎来到 mirai-console 开发文档!
-
-## 目录
-
-- **[准备工作](#准备工作)**
-- **[启动 Console](Run.md)**
-
-### 后端插件开发基础
-
-- 插件 - [Plugin 模块](Plugins.md)
-- 指令 - [Command 模块](Commands.md)
-- 存储 - [PluginData 模块](PluginData.md)
-- 权限 - [Permission 模块](Permissions.md)
-
-### 后端插件开发进阶
-
-- 扩展 - [Extension 模块和扩展点](Extensions.md)
-
-### 实现前端
-- [FrontEnd](FrontEnd.md)
-
-[`Plugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/Plugin.kt
-[`Annotations`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/Annotations.kt
-[`PluginData`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
-[`JavaPluginScheduler`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPluginScheduler.kt
-[`JvmPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JvmPlugin.kt
-[`PluginConfig`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginConfig.kt
-[`PluginLoader`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/loader/PluginLoader.kt
-[`ConsoleInput`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/ConsoleInput.kt
-[`PluginDataStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
-[`Command`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/Command.kt
-
-## 准备工作
-***如果跳过本节内容，你很可能遇到无法解决的问题。***
-
-### 环境要求
-
-*不接受降低最低版本要求的建议*
-
-- JDK 11
-- Android：Android SDK 26+ （Android 8.0)
-- Kotlin: 1.4
-
-*Mirai Console 需要的 Kotlin 版本会与 Kotlin 最新稳定版本同步。*
-
-### 开发插件的准备工作
-
-- 安装并配置 JDK 11
-
-若使用 Java，或要修改 Mirai Console：
-
-- 使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) （或 `Android Studio`）。
-- IDE 需装有 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) 插件 (先启动你的 IDE，再点击 [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))
-
-若使用 Kotlin，无特别要求。
-
-### 前置知识
-要学习为 mirai-console 开发原生支持的插件, 需要:
-
-- 掌握 Java 基础
-- 至少粗略了解 Kotlin 基础语法（30 分钟）:
-  - [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html)
-  - [类与继承](https://www.kotlincn.net/docs/reference/classes.html)
-  - [属性与字段](https://www.kotlincn.net/docs/reference/properties.html)
-  - [接口](https://www.kotlincn.net/docs/reference/interfaces.html)
-  - [扩展](https://www.kotlincn.net/docs/reference/extensions.html)
-  - [数据类](https://www.kotlincn.net/docs/reference/data-classes.html)
-  - [对象](https://www.kotlincn.net/docs/reference/object-declarations.html)
-  - [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html)
-  - **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)**
-- 对于 Java 使用者，请阅读 [Java 用户的使用指南](#java-用户的使用指南)，[在 Java 使用 Mirai Console 中的 Kotlin `suspend` 函数](#在-java-使用-mirai-console-中的-kotlin-suspend-函数)
-- 对于 Kotlin 使用者，请熟知 [Kotlin `1.4` 版本带来的新特性](#mirai-console-使用的-kotlin-14-版本的新特性)
-
-
-## 附录
-
-### Java 用户的使用指南
-
-- Java 中的「方法」在 Kotlin 中均被称为「函数」。
-- Kotlin 默认的访问权限是 `public`。如 Kotlin `class Test` 相当于 Java 的 `public class Test {}`
-- Kotlin 的函数定义 `fun test(int: Int): String` 相当于 Java 的方法定义 `public String test(int int)`
-
-### 在 Java 使用 Mirai Console 中的 Kotlin `suspend` 函数
-
-#### 什么是 `suspend` 函数
-
-`suspend` 函数中文是「挂起函数」，是 Kotlin 「[协程](https://www.kotlincn.net/docs/reference/coroutines/coroutines-guide.html)」的一部分。
-
-Kotlin 协程是语言级特性，函数的修饰符 `suspend` 会在编译阶段被处理。
-
-对于一个挂起函数:
-```kotlin
-suspend fun test(): String
-```
-
-它会被编译为 `public Object test(Continuation<String> $completion)`。
-
-这是因为 Kotlin 对所有挂起函数都有这样的内部变化，并在编译时实现了协程的一些特性。
-
-Java 用户无法调用这样的方法，因为 `Continuation` 的实现很复杂。
-
-Mamoe 为此开发了 Kotlin 编译器插件 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge)，通过 `@JvmBlockingBridge` 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。
-
-要获取详细信息，参考 [Kotlin Jvm Blocking Bridge 编译器插件](https://github.com/mamoe/kotlin-jvm-blocking-bridge/blob/master/README-chs.md#%E7%BC%96%E8%AF%91%E5%99%A8%E6%8F%92%E4%BB%B6)
-
-### Mirai Console 使用的 Kotlin `1.4` 版本的新特性
-
-在官方文档的 [语言特性与改进](https://www.kotlincn.net/docs/reference/whatsnew14.html#%E8%AF%AD%E8%A8%80%E7%89%B9%E6%80%A7%E4%B8%8E%E6%94%B9%E8%BF%9B) 基础上，Mirai Console 的一些设计基于 Kotlin 1.4 的更多新特性。
-
-#### `object` 内的扩展函数的自动引用
-对于如下定义：
-```kotlin
-package org.example
-object Obj {
-  fun String.foo()
-}
-```
-在 Kotlin `1.3`，要调用 `foo`，必须使用：
-```kotlin
-Obj.run {
-  "str".foo()
-}
-```
-因为 IDE 不会自动为 `String.foo` 添加 `import`。
-
-Kotlin `1.4` 解决了这个问题。在使用 `"str".foo` 时 Kotlin 会自动添加 `org.example.Obj.foo` 的引用。
-
-Mirai Console 很多单例对象都设计为 `interface + companion object INSTANCE` 的接口与实现模式，需要这样的新特性。例如：
-```kotlin
-interface MiraiConsole {
-    companion object INSTANCE : MiraiConsole by MiraiConsoleImpl // MiraiConsoleImpl 是内部实现，不公开
-}
-```
-
-#### Mirai Console 演进
-
-Mirai Console 是不断前进的框架，将来必定会发生 API 弃用和重构。  
-维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。
-
-##### 版本规范
-
-Mirai Console 的版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/#spec-item-9) 规范。
-
-在日常开发中, Mirai Console 会以 `-dev-1`，`-dev-2` 等版本后缀发布开发预览版本。这些版本仅用于兼容性测试等目的，无稳定性保证。
-
-在大版本开发过程中，Mirai Console 会以 `-M1`, `-M2` 等版本后缀发布里程碑预览版本。代表一系列功能的完成，但还不稳定。  
-这些版本里新增的 API 仍可能还会在下一个 Milestone 版本变化，因此请按需使用。
-
-在大版本即将发布前，Mirai Console 会以 `-RC` 版本后缀发布最终的预览版本。  
-`RC` 表示新版本 API 已经确定，离稳定版发布只差最后的一些内部优化或 bug 修复。
-
-##### 版本选择
-
-**稳定性**：稳定 (`x.y.z`) > 发布预览 (`-RC`) > 里程碑预览 (`-M`) > 开发 (`-dev`)。
-
-|            目的            | 推荐至少更新到版本 |
-|:--------------------------:|:--------------:|
-|          生产环境           |     `x.y.z`     |
-| 希望尽早体验稳定新特性的插件作者 |     `-RC`      |
-| 无论如何都想体验新特性的插件作者 |      `-M`      |
-|    前端实现者, 底层插件作者    |      `-M`      |
-|  为 Mirai Console 提交 PR   |     `-dev`     |
-
-其中，‘底层插件’ 表示提供扩展等的插件。如权限系统，其他语言插件加载器等。
-
-##### 更新兼容性
-
-对于 `x.y.z` 版本号:
-- 当 `z` 增加时，只会有 bug 修复，和必要的新函数添加（为了解决某一个问题），不会有破坏性变化。
-- 当 `y` 增加时，可能有新 API 的引入，和旧 API 的弃用。但这些弃用会经过一个弃用周期后才被删除（隐藏）。向下兼容得到保证。
-- 当 `x` 增加时，任何 API 都可能会有变化。无兼容性保证。
-
-##### 弃用周期
-
-一个计划被删除的 API，将会在下一个次版本开始经历弃用周期。
-
-如一个 API 在 `1.1.0` 起被弃用，它首先会是 `WARNING` (使用时会得到一个编译警告）弃用级别。  
-在 `1.2.0` 上升为 `ERROR`（使用时会得到一个编译错误）；  
-在 `1.3.0` 上升为 `HIDDEN`（使用者无法看到这些 API)。
-
-`HIDDEN` 的 API 仍然会保留在代码中并正常编译，以提供二进制兼容性，直到下一个主版本更新。
diff --git a/docs/Run.md b/docs/Run.md
index 2cf39c5de..c4651e4bf 100644
--- a/docs/Run.md
+++ b/docs/Run.md
@@ -2,11 +2,11 @@
 
 Mirai Console 可以独立启动，也可以被嵌入到某个应用中。
 
-## 使用第三方工具自动启动
+## 使用第三方工具自动独立启动
 
 https://github.com/LXY1226/MiraiOK
 
-## 独立启动
+## 手动配置独立启动
 
 ### 环境
 - JRE 11+ / JDK 11+
diff --git a/tools/gradle-plugin/README.md b/tools/gradle-plugin/README.md
index 78e0e7f29..dbe0dd749 100644
--- a/tools/gradle-plugin/README.md
+++ b/tools/gradle-plugin/README.md
@@ -1,2 +1,47 @@
-# mirai-console-gradle
+# Mirai Console Gradle Plugin
 
+Mirai Console Gradle 插件。
+
+## 使用
+
+参考 [ConfiguringProjects](../../docs/ConfiguringProjects.md#gradle)[
+
+## 功能
+
+- 为 `main` 源集配置 `mirai-core`，`mirai-console` 依赖
+- 为 `test` 源集配置 `mirai-core-qqandroied`, `mirai-console-terminal` 的依赖 (用于启动测试)
+- 添加 mirai 依赖仓库链接
+- 配置插件 JAR 打包构建任务 `buildPlugin` (带依赖)
+
+
+### `buildPlugin`
+
+用于打包插件和依赖为可以放入 Mirai Console `plugins` 目录加载的插件 JAR。
+
+#### 执行 `buildPlugin`
+```shell script
+$ gradlew buildPlugin
+```
+
+打包结果存放在 `build/mirai/` 目录下。
+
+## 配置
+
+若要修改 Mirai Console Gradle 插件的默认配置，在 `build.gradle.kts` 或 `build.gradle` 内，使用 `mirai`：
+```kotlin
+mirai { // this: MiraiConsoleExtension
+    // 配置
+}
+```
+
+DSL 详见 [MiraiConsoleExtension](src/main/kotlin/net/mamoe/mirai/console/gradle/MiraiConsoleExtension.kt)。
+
+#### 排除依赖
+
+如果要在打包 JAR（`buildPlugin`）时排除一些依赖，请使用如下配置：
+
+```kotlin
+mirai {
+    excludeDependency("com.google.code.gson", "gson")
+}
+```
\ No newline at end of file