mirror of
https://github.com/mamoe/mirai.git
synced 2025-01-10 02:20:14 +08:00
Add docs
This commit is contained in:
Him188
parent
6a34c0a673
commit
3ded2cc87b
@ -94,7 +94,7 @@ import kotlin.reflect.full.findAnnotation
|
||||
* newList.add(1) // 不会添加到 MyPluginData.nestedMap 中, 因为 `mutableListOf` 创建的 MutableList 被非引用地添加进了 MyPluginData.nestedMap
|
||||
* ```
|
||||
*
|
||||
* 一个解决方案是对 [SerializerAwareValue] 做映射或相关修改. 如 [PluginDataExtensions]。
|
||||
* 一个解决方案是对 [SerializerAwareValue] 做映射或相关修改. 如 [PluginDataExtensions].
|
||||
*
|
||||
* 要查看详细的解释，请查看 [docs/PluginData.md](https://github.com/mamoe/mirai-console/blob/master/docs/PluginData.md)
|
||||
*
|
||||
@ -176,7 +176,7 @@ public interface PluginData {
|
||||
): T
|
||||
|
||||
/**
|
||||
* 所有 [valueNodes] 更新和保存序列化器. 仅供内部使用。
|
||||
* 所有 [valueNodes] 更新和保存序列化器. 仅供内部使用
|
||||
*/
|
||||
public val updaterSerializer: KSerializer<Unit>
|
||||
|
||||
|
||||
@ -31,7 +31,7 @@ import java.nio.file.Path
|
||||
* [JvmPluginLoader] 实现一个 [PluginDataStorage], 用于管理所有 [JvmPlugin] 的 [PluginData] 实例.
|
||||
*
|
||||
* ### 实现 [PluginDataStorage]
|
||||
* 无特殊需求。实现两个成员函数即可。可参考内建 [MultiFilePluginDataStorageImpl]
|
||||
* 无特殊需求. 实现两个成员函数即可. 可参考内建 [MultiFilePluginDataStorageImpl]
|
||||
*
|
||||
* @see PluginDataHolder
|
||||
* @see JvmPluginLoader.dataStorage
|
||||
|
||||
@ -20,10 +20,10 @@ import net.mamoe.mirai.console.plugin.jvm.JvmPlugin.Companion.onLoad
|
||||
* 表示一个扩展.
|
||||
*
|
||||
* ### 获取扩展
|
||||
* Console 不允许插件获取自己或其他插件注册的扩展。
|
||||
* Console 不允许插件获取自己或其他插件注册的扩展
|
||||
*
|
||||
* ### 注册扩展
|
||||
* 插件仅能在 [JvmPlugin.onLoad] 阶段注册扩展。
|
||||
* 插件仅能在 [JvmPlugin.onLoad] 阶段注册扩展
|
||||
*
|
||||
* ```kotlin
|
||||
* object MyPlugin : KotlinPlugin( /* ... */ ) {
|
||||
|
||||
@ -76,7 +76,7 @@ public interface Permission {
|
||||
}
|
||||
|
||||
/**
|
||||
* 根权限. 是所有权限的父权限.
|
||||
* 根权限. 是所有权限的父权限. 权限 ID 为 "*:*"
|
||||
*/
|
||||
@get:JvmSynthetic
|
||||
public val RootPermission: Permission
|
||||
|
||||
@ -19,6 +19,9 @@ import net.mamoe.mirai.console.internal.data.map
|
||||
* 表示一个 [权限][Permission] 的唯一 ID.
|
||||
*
|
||||
* [PermissionId] 与 [Permission] 唯一对应.
|
||||
*
|
||||
* ### 字符串表示
|
||||
* `"$namespace:$name"`. 如 "console:command.stop", "*:*"
|
||||
*/
|
||||
@Serializable(with = PermissionId.PermissionIdAsStringSerializer::class)
|
||||
public data class PermissionId(
|
||||
|
||||
@ -49,7 +49,7 @@ public interface PluginDescription {
|
||||
public val id: String
|
||||
|
||||
/**
|
||||
* 插件名称用于展示给用户，仅取决于 `PluginDescription` 提供的 `name`，与主类类名等其他信息无关。
|
||||
* 插件名称用于展示给用户，仅取决于 `PluginDescription` 提供的 `name`，与主类类名等其他信息无关.
|
||||
*
|
||||
* 名称允许中文, 允许各类符号，但不能完全是以下其中一种（忽略大小写）([FORBIDDEN_ID_NAMES]):
|
||||
* - console
|
||||
|
||||
@ -22,9 +22,9 @@ import net.mamoe.mirai.console.plugin.jvm.JvmPluginLoader
|
||||
/**
|
||||
* 插件加载器.
|
||||
*
|
||||
* 插件加载器只实现寻找插件列表, 加载插件, 启用插件, 关闭插件这四个功能。
|
||||
* 插件加载器只实现寻找插件列表, 加载插件, 启用插件, 关闭插件这四个功能.
|
||||
*
|
||||
* 一个插件要在何时被加载，依赖如何处理，[PluginLoader] 都无需关心。
|
||||
* 一个插件要在何时被加载，依赖如何处理，[PluginLoader] 都无需关心.
|
||||
*
|
||||
* 有关插件的依赖和已加载的插件列表由 [PluginManager] 维护.
|
||||
*
|
||||
|
||||
@ -2,8 +2,36 @@
|
||||
|
||||
Mirai Console 拥有灵活的 Extensions API，支持扩展 Console 的一些服务。
|
||||
|
||||
## 扩展
|
||||
Extensions 属于插件开发的进阶内容。
|
||||
|
||||
[`Extension`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/Extension.kt
|
||||
[`ExtensionPoint`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/ExtensionPoint.kt
|
||||
[`PluginComponentStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/PluginComponentStorage.kt
|
||||
[`ComponentStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/ComponentStorage.kt
|
||||
|
||||
## [扩展][`Extension`]
|
||||
|
||||
## 注册扩展
|
||||
### [组件容器][`ComponentStorage`]
|
||||
|
||||
容纳插件注册的 [扩展][`Extension`]。
|
||||
|
||||
### 注册扩展
|
||||
|
||||
插件仅能在 [`onLoad`](Plugins.md#加载) 阶段注册扩展。
|
||||
|
||||
示例：
|
||||
|
||||
```kotlin
|
||||
object MyPlugin : KotlinPlugin( /* ... */ ) {
|
||||
fun PluginComponentStorage.onLoad() {
|
||||
contributePermissionService { /* ... */ }
|
||||
contributePluginLoader { /* ... */ }
|
||||
contribute(ExtensionPoint) { /* ... */ }
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### 可用扩展
|
||||
|
||||
查看 [extensions](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/)。每个文件对应一个扩展。
|
||||
@ -1 +1,35 @@
|
||||
#
|
||||
# Mirai Console Frontend
|
||||
|
||||
Mirai Console 前端开发文档。
|
||||
|
||||
[`MiraiConsole`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsole.kt
|
||||
|
||||
## 实现前端
|
||||
|
||||
### 添加编译器设置
|
||||
|
||||
在 `build.gradle` 或 `build.gradle.kts` 添加：
|
||||
```kotlin
|
||||
kotlin {
|
||||
sourceSets.all {
|
||||
languageSettings.useExperimentalAnnotation("net.mamoe.mirai.console.ConsoleFrontEndImplementation")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
此后就可以使用 `net.mamoe.mirai.console.ConsoleFrontEndImplementation` 标记的所有 API。
|
||||
|
||||
|
||||
### 实现 Mirai Console
|
||||
|
||||
[`MiraiConsole`] 是后端的公开对象，由 [MiraiConsoleImplementationBridge](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleImplementationBridge.kt) 代理，与前端链接。
|
||||
|
||||
前端需要实现 [MiraiConsoleImplementation.kt](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt)。
|
||||
|
||||
由于实现前端需要一定的技术能力，相信实现者都能理解源码内注释。
|
||||
|
||||
### 启动 Mirai Console
|
||||
|
||||
通过 `public fun MiraiConsoleImplementation.start()`。
|
||||
|
||||
[MiraiConsoleImplementation.kt: Line 161](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt#L161)
|
||||
@ -0,0 +1,141 @@
|
||||
# Mirai Console Backend - Permissions
|
||||
|
||||
权限系统。
|
||||
|
||||
[`PermissionService`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionService.kt
|
||||
[`Permission`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt
|
||||
[`RootPermission`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt#L82
|
||||
[`PermissionId`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionId.kt
|
||||
[`PermissionIdNamespace`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionIdNamespace.kt
|
||||
[`Permittee`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permittee.kt
|
||||
[`PermitteeId`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermitteeId.kt
|
||||
[`AbstractPermitteeId`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermitteeId.kt#L77
|
||||
[`CommandSender`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandSender.kt
|
||||
|
||||
## 权限
|
||||
|
||||
每个权限都由 [`Permission`] 对象表示。
|
||||
|
||||
一个 [`Permission`] 拥有这些信息：
|
||||
```kotlin
|
||||
interface Permission {
|
||||
val id: PermissionId // 唯一识别 ID
|
||||
val description: String // 描述信息
|
||||
val parent: Permission // 父权限
|
||||
}
|
||||
```
|
||||
|
||||
「权限」表示的意义是 “做一项工作的能力”。如 “执行指令 /stop”，“操作数据库” 都叫作权限。
|
||||
|
||||
[`Permission`] 对象由 Console 内置或者由特定权限插件实现。其他插件不能实现 [`Permission`] 接口。
|
||||
|
||||
### 权限 ID
|
||||
|
||||
```kotlin
|
||||
data class PermissionId(
|
||||
val namespace: String, // 命名空间
|
||||
val name: String, // 名称
|
||||
)
|
||||
```
|
||||
|
||||
[`PermissionId`] 是 [`Permission`] 的唯一标识符。知道 [`PermissionId`] 就可以获取到对应的 [`Permission`]。
|
||||
|
||||
字符串表示为 "$namespace:$name"，如 "console:command.stop", "*:*"
|
||||
|
||||
#### 命名空间
|
||||
|
||||
命名空间（“namespace”）用于限定权限的创建者，避免冲突。
|
||||
|
||||
一些常见命名空间：
|
||||
|
||||
| 用途 | 命名空间 |
|
||||
|:-------------|:------------|
|
||||
| 根权限 | `"*"` |
|
||||
| Console 内置 | `"console"` |
|
||||
| ID 为 A 的插件 | `"A"` |
|
||||
|
||||
#### 名称
|
||||
|
||||
名称则表示特定的含义。如一个指令，某一项操作等。
|
||||
|
||||
一些常见名称：
|
||||
|
||||
| 用途 | 名称 |
|
||||
|:--------------------------|:--------------|
|
||||
| 根权限 | `"*"` |
|
||||
| Console 内置的名为 A 的指令 | `"command.A"` |
|
||||
| ID 为 A 的插件的名为 B 的指令 | `"command.B"` |
|
||||
|
||||
#### 根权限
|
||||
|
||||
[`RootPermission`] 是所有权限的父权限。其 ID 为 "*:*"
|
||||
|
||||
## 被许可人
|
||||
|
||||
```kotlin
|
||||
interface Permittee {
|
||||
val permitteeId: PermitteeId
|
||||
}
|
||||
```
|
||||
|
||||
[`Permittee`] 表示一个可被赋予权限的对象，即 '被许可人'。
|
||||
|
||||
[`CommandSender`] 实现 [`Permittee`]。
|
||||
|
||||
被许可人自身不持有拥有的权限列表，而是拥有 [`PermitteeId`]，标识自己的身份，供 [权限服务][`PermissionService`] 处理。
|
||||
|
||||
**注意**：请不要自主实现 [`Permittee`]。
|
||||
|
||||
### 被许可人 ID
|
||||
|
||||
```kotlin
|
||||
interface PermitteeId {
|
||||
val directParents: Array<out PermitteeId> // 直接父对象
|
||||
fun asString(): String // 转换为字符串表示
|
||||
}
|
||||
````
|
||||
|
||||
[`PermitteeId`] 是被许可人的标识符。
|
||||
|
||||
一个这样的标识符即可代表特定的单个 [`Permittee`], 也可以表示多个同类 [`Permittee`].
|
||||
|
||||
#### `directParents`
|
||||
[`PermitteeId`] 允许拥有多个父对象。在检查权限时会首先检查自己, 再递归检查父类。
|
||||
|
||||
#### 衍生类型
|
||||
|
||||
[`PermitteeId`] 的实现通常是 [`AbstractPermitteeId`]
|
||||
|
||||
在 [`AbstractPermitteeId`] 查看其子类。
|
||||
|
||||
### 获取被许可人
|
||||
|
||||
通常使用 `CommandSender.permitteeId`。
|
||||
也可以直接构造 [`AbstractPermitteeId`] 的子类。或者在 Kotlin 使用扩展 `User.permitteeId`
|
||||
|
||||
## 权限服务
|
||||
|
||||
[`PermissionService`] 承载权限的授权和管理。Console 内置一个实现，而权限服务可以由插件提供（见 [扩展](Extensions.md)）。
|
||||
|
||||
### 判断权限
|
||||
|
||||
在 Kotlin，在该有扩展的对象上 Console 都为它们实现了扩展。可以使用：
|
||||
```kotlin
|
||||
fun Permittee.hasPermission(Permission): Boolean
|
||||
fun Permission.testPermission(Permittee): Boolean
|
||||
fun PermitteeId.hasPermission(Permission): Boolean
|
||||
fun PermissionId.testPermission(Permittee): Boolean
|
||||
fun Permittee.hasPermission(PermissionId): Boolean
|
||||
fun Permission.testPermission(PermitteeId): Boolean
|
||||
// ...
|
||||
```
|
||||
|
||||
请查看 [`PermissionService`] 中的伴生对象。
|
||||
|
||||
### 注册权限
|
||||
|
||||
每一条指令都会默认自动创建一个权限。
|
||||
|
||||
如果希望手动注册一个其他用途的权限，使用 `PermissionService.register`。
|
||||
|
||||
**注意**：权限只能在插件 [启用](Plugins.md#启用) 之后才能注册。否则会得到一个异常。
|
||||
@ -59,7 +59,7 @@ interface Plugin : CommandOwner { // CommandOwner 是空的 interface
|
||||
}
|
||||
```
|
||||
|
||||
[`Plugin`] 接口拥有强扩展性，以支持 Mirai Console 统一管理使用其他编程语言编写的插件 （详见进阶章节 [实现 PluginLoader](PluginLoader.md)）。
|
||||
[`Plugin`] 接口拥有强扩展性，以支持 Mirai Console 统一管理使用其他编程语言编写的插件 （详见进阶章节 [扩展 - PluginLoader](Extensions.md)）。
|
||||
|
||||
## JVM 平台插件接口 - [`JvmPlugin`]
|
||||
|
||||
|
||||
@ -17,8 +17,6 @@
|
||||
### 后端插件开发进阶
|
||||
|
||||
- 扩展 - [Extension 模块和扩展点](Extensions.md)
|
||||
- 扩展 - [实现 PluginLoader](PluginLoader.md)
|
||||
- 扩展 - [实现 PermissionService](PermissionService.md)
|
||||
|
||||
### 实现前端
|
||||
- [FrontEnd](FrontEnd.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user