From a81cd2239c703dc7524a50301e236a75b12b6d7c Mon Sep 17 00:00:00 2001 From: Him188 Date: Thu, 14 Jan 2021 17:21:50 +0800 Subject: [PATCH] Update docs --- README.md | 4 +-- .../src/MiraiConsoleImplementation.kt | 4 +-- docs/BuiltInCommands.md | 14 ++++++++++ docs/Commands.md | 10 ++++++- docs/ConfiguringProjects.md | 7 +++++ docs/FrontEnd.md | 2 +- docs/Permissions.md | 11 ++++++-- docs/PluginData.md | 9 ++++++- docs/Plugins.md | 7 ++++- tools/gradle-plugin/README.md | 27 +++++++++++++++---- 10 files changed, 80 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index a9a5d1c03..ce637bef5 100644 --- a/README.md +++ b/README.md @@ -27,11 +27,11 @@ Mirai 是一个在全平台下运行，提供 QQ 协议支持的高效率机器 ### 安装 JAR 插件 -将 `jar` 文件放入 `plugins` 并重启 Mirai Console 即可。 +将 `jar` 文件放入 `plugins` 并重启 Mirai Console。 ### 执行指令 -在控制台输入 `?` 查看可用指令列表。 +在控制台输入 `?` 查看可用指令列表。**注意，请先为用户授予执行某些指令的权限，详见 [示例](docs/BuiltInCommands.md#授予一个用户执行所有指令的权限)**。 ### 内置指令 diff --git a/backend/mirai-console/src/MiraiConsoleImplementation.kt b/backend/mirai-console/src/MiraiConsoleImplementation.kt index bd7791c05..bf3af09cd 100644 --- a/backend/mirai-console/src/MiraiConsoleImplementation.kt +++ b/backend/mirai-console/src/MiraiConsoleImplementation.kt @@ -167,8 +167,8 @@ public interface MiraiConsoleImplementation : CoroutineScope { /** * 创建一个 [MiraiLogger]. * - * **注意**: [MiraiConsole] 会将 [net.mamoe.mirai.utils.DefaultLogger] 设置为 `MiraiConsole::createLogger`. - * 因此不要在 [createLogger] 中调用 [net.mamoe.mirai.utils.DefaultLogger] + * **注意**: [MiraiConsole] 会将 [net.mamoe.mirai.utils.MiraiLogger.setDefaultLoggerCreator] 设置为 `MiraiConsole::createLogger`. + * 因此不要在 [createLogger] 中调用 [net.mamoe.mirai.utils.MiraiLogger.create] */ public fun createLogger(identity: String?): MiraiLogger diff --git a/docs/BuiltInCommands.md b/docs/BuiltInCommands.md index cb342ff10..13f27508f 100644 --- a/docs/BuiltInCommands.md +++ b/docs/BuiltInCommands.md @@ -44,6 +44,20 @@ Mirai Console 内置一些指令。 示例：`/perm permit u123456 console:command.stop` +### 授予一个用户执行所有指令的权限 + +示例： +- `/perm permit u123456 *:*` 允许用户 123456 执行任意指令 +- `/perm permit u123456 console:*` 允许用户 123456 执行任意 Console 内置指令 +- `/perm permit u123456 org.example.my-plugin:*` 允许用户 123456 执行插件 `org.example.my-plugin` 的任意指令 + +### 授予所有用户执行某个指令的权限 + +示例： +- `/perm permit u* console:command.help` 允许所有用户执行 `console:command.help`（即 `/help`） +- `/perm permit u* console:*` 允许所有用户执行任意 Console 内置指令 +- `/perm permit u* org.example.my-plugin:*` 允许所有用户执行插件 `org.example.my-plugin` 的任意指令 + ## AutoLoginCommand 主指令: `/autoLogin` diff --git a/docs/Commands.md b/docs/Commands.md index 621d994e9..33a77c260 100644 --- a/docs/Commands.md +++ b/docs/Commands.md @@ -263,4 +263,12 @@ ConsoleCommandSender AbstractUserCommandSender | 表示几个消息对象的’域‘，即消息对象的集合。用于最小化将同一条消息发送给多个类型不同的目标的付出。 -参考 [MessageScope](../backend/mirai-console/src/util/MessageScope.kt#L28-L99) \ No newline at end of file +参考 [MessageScope](../backend/mirai-console/src/util/MessageScope.kt#L28-L99) + + +---- + +> 下一步，[PluginData](PluginData.md#mirai-console-backend---plugindata) +> +> 返回 [开发文档索引](README.md#mirai-console) + diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md index 5cc9debce..4160e65b7 100644 --- a/docs/ConfiguringProjects.md +++ b/docs/ConfiguringProjects.md @@ -58,6 +58,10 @@ plugins { 完成。Mirai Console Gradle 插件会为你配置依赖等所有编译环境。 +可以在 [README](../tools/gradle-plugin/README.md#mirai-console-gradle-plugin) 获取详细的 Gradle 插件使用方法，**如配置 mirai-core 版本**。 + +> 现在你已经配置好了项目，返回 [开发文档索引](README.md#mirai-console) + ### 手动配置项目 添加依赖： @@ -77,3 +81,6 @@ dependencies { 之后还需要配置 Kotlin `jvm-default` 编译参数，Kotlin 和 Java 的编译目标等。 在打包插件时必须将依赖一并打包进插件 JAR，且排除 `mirai-core`，`mirai-console` 和它们的间接依赖，否则插件不会被加载。 + +> 现在你已经配置好了项目，返回 [开发文档索引](README.md#mirai-console) + diff --git a/docs/FrontEnd.md b/docs/FrontEnd.md index 03a764a49..e665a39f8 100644 --- a/docs/FrontEnd.md +++ b/docs/FrontEnd.md @@ -22,7 +22,7 @@ kotlin.sourceSets.all { [`MiraiConsole`] 是后端的公开对象，由 [MiraiConsoleImplementationBridge](../backend/mirai-console/src/internal/MiraiConsoleImplementationBridge.kt) 代理，与前端链接。 -前端需要实现 [MiraiConsoleImplementation.kt](../backend/mirai-console/src/MiraiConsoleImplementation)。 +前端需要实现 [MiraiConsoleImplementation.kt](../backend/mirai-console/src/MiraiConsoleImplementation.kt)。 由于实现前端需要一定的技术能力，相信实现者都能理解源码内注释。 diff --git a/docs/Permissions.md b/docs/Permissions.md index 3b4e375e3..c17800b50 100644 --- a/docs/Permissions.md +++ b/docs/Permissions.md @@ -27,7 +27,7 @@ interface Permission { 「权限」表示的意义是 “做一项工作的能力”。如 “执行指令 /stop”，“操作数据库” 都叫作权限。 -[`Permission`] 对象由 Console 内置或者由特定权限插件实现。其他插件不能实现 [`Permission`] 接口。 +[`Permission`] 对象由 Console 内置或者由特定权限插件实现。其他插件不能实现 [`Permission`] 接口，只能从 `PermissionService` 注册并获取。 ### 权限 ID @@ -154,7 +154,7 @@ fun Permission.testPermission(PermitteeId): Boolean // ... ``` -请查看 [`PermissionService`] 中的伴生对象。 +在 Java，请查看 [`PermissionService`] 中的伴生对象。 ### 注册权限 @@ -178,3 +178,10 @@ fun Permission.testPermission(PermitteeId): Boolean ``` 其中, 被许可人 ID 使用 [字符串表示](#字符串表示), 权限 ID 参见 [权限 ID](#权限-id) + +---- + +> 这是文档的最后一个章节。 +> +> 返回 [开发文档索引](README.md#mirai-console) + diff --git a/docs/PluginData.md b/docs/PluginData.md index c1731f9c3..063099475 100644 --- a/docs/PluginData.md +++ b/docs/PluginData.md @@ -243,4 +243,11 @@ value[bot] = listOf() [`PluginData`] 的存储仓库，将 [`PluginData`] 从内存序列化到文件或到数据库，或反之。 -内置的实现包含：[`MultiFilePluginDataStorage`], [`MemoryPluginDataStorage`] \ No newline at end of file +内置的实现包含：[`MultiFilePluginDataStorage`], [`MemoryPluginDataStorage`] + +---- + +> 下一步，[Permissions](Permissions.md#mirai-console-backend---permissions) +> +> 返回 [开发文档索引](README.md#mirai-console) + diff --git a/docs/Plugins.md b/docs/Plugins.md index cb722ceb4..e99ed01bf 100644 --- a/docs/Plugins.md +++ b/docs/Plugins.md @@ -415,4 +415,9 @@ object MyData : AutoSavePluginData() { *TODO* ### 附录：Java 插件的多线程调度器 - [`JavaPluginScheduler`] -拥有生命周期管理的简单 Java 线程池。其中所有的任务都会在插件被关闭时自动停止。 \ No newline at end of file +拥有生命周期管理的简单 Java 线程池。其中所有的任务都会在插件被关闭时自动停止。 + +> 下一步，[Commands](Commands.md#mirai-console-backend---commands) +> +> 返回 [开发文档索引](README.md#mirai-console) + diff --git a/tools/gradle-plugin/README.md b/tools/gradle-plugin/README.md index d1d1c79d0..0a326622e 100644 --- a/tools/gradle-plugin/README.md +++ b/tools/gradle-plugin/README.md @@ -8,13 +8,14 @@ Mirai Console Gradle 插件。 ## 功能 -- 为 `main` 源集配置 `mirai-core`，`mirai-console` 依赖 -- 为 `test` 源集配置 `mirai-core-qqandroid`, `mirai-console-terminal` 的依赖 （用于启动测试） -- 配置 Kotlin 编译目标为 Java 1.8 +- 为 `main` 源集配置 `mirai-core-api`，`mirai-console` 依赖 +- 为 `test` 源集配置 `mirai-core`, `mirai-console-terminal` 的依赖 （用于启动测试） +- 配置 Kotlin 编译目标为 1.8 - 配置 Kotlin 编译器 jvm-default 设置为 `all`, 即为所有接口中的默认实现生成 Java 1.8 起支持的 `default` 方法 -- 配置 Java 编译目标为 Java 1.8 +- 配置 Java 编译目标为 1.8 - 配置 Java 编译编码为 UTF-8 - 配置插件 JAR 打包构建任务 `buildPlugin`（带依赖, 成品 JAR 可以被 Mirai Console 加载） +- 配置插件 JAR 发布任务 `publishPlugin`（到 Bintray） 支持 Kotlin 多平台项目（Multiplatform Projects）。每个 JVM 或 Android 目标平台都会被如上配置，对应打包任务带有编译目标的名称，如 `buildPluginJvm` @@ -34,12 +35,28 @@ Mirai Console Gradle 插件。 若要修改 Mirai Console Gradle 插件的默认配置，在 `build.gradle.kts` 或 `build.gradle` 内，使用 `mirai`： ```kotlin mirai { // this: MiraiConsoleExtension - // 配置 + // 配置，例如 + coreVersion = "2.0-RC" // 修改 mirai-core 版本 } ``` DSL 详见 [MiraiConsoleExtension](src/MiraiConsoleExtension.kt)。 +### `publishPlugin` + +配置好 Bintray 参数，使用 `./gradlew publishPlugin` 可自动发布并上传插件到 Bintray。 + +如果仓库是公开的，上传的插件在未来可以被 [mirai-console-loader](https://github.com/iTXTech/mirai-console-loader) 自动识别并展示在社区插件列表中。 + +```kotlin +mirai { + publishing { + repo = "mirai" + packageName = "chat-command" + } +} +``` + #### 排除依赖 如果要在打包 JAR（`buildPlugin`）时排除一些依赖，请使用如下配置：