From 5bb7e9a85ee8faa4d1aecc9f374962f46c55eb43 Mon Sep 17 00:00:00 2001 From: Him188 <Him188@mamoe.net> Date: Tue, 24 Dec 2019 01:51:14 +0800 Subject: [PATCH 1/2] Update README.md --- README.md | 158 +----------------------------------------------------- 1 file changed, 1 insertion(+), 157 deletions(-) diff --git a/README.md b/README.md index d5c66cd2c..bf993571f 100644 --- a/README.md +++ b/README.md @@ -101,161 +101,5 @@ Mirai 使用以下开源库: - [javafx](https://github.com/openjdk/jfx) - [kotlinx-serialization](https://github.com/Kotlin/kotlinx.serialization) -## Development Guide - Kotlin - -平台通用开发帮助(不含协议层). - -您需要有一定 Kotlin 基础才能读懂以下内容. -若您对本文档有建议, 请告诉我们 - -目录: -- [Introduction](#Introduction) Mirai 介绍 -- [Modules](#Modules) 模块介绍 - - [mirai-core](#mirai-core) 核心模块 - - [mirai-console](#mirai-console) JVM 控制台 - - [mirai-demo](#mirai-demo) 示例和演示程序 - - [mirai-debug](#mirai-debug) 抓包工具和分析工具 -- [Logger](#Logger) 日志系统 -- [Bot](#Bot) 机器人类 -- [Contact](#Contact) 联系人 -- [Message](#Message) 消息 - - [MessageChain](#MessageChain) `MessageChain` - - [Types](#Types-Of-Message) 消息类型 - - [Operators](#Operators) `Message` 一般用法 - - [Extensions](#Extensions) `Message` 的常用扩展方法 -- [Image](#Image) 图片 - - [Image JVM](#Image-JVM) JVM 平台扩展实现 -- [Event](#Event) 事件 - - [Subscription](#Subscription) 事件监听(订阅) - - [Message Event](#Message-Event) 针对消息事件的订阅实现 - -### Introduction - -Mirai 目前为快速流转（Moving fast）状态, 增量版本之间可能不具有兼容性，任何功能都可能在没有警告的情况下添加、删除或者更改。 -Mirai 源码完全开放, 您可以参考 Mirai 的协议实现来开发其他框架, 但需注明来源并遵守开源协议要求. - -### Modules -Mirai 的模块组成 - -#### mirai-core -Mirai 的核心部分. - -- 含全部协议和 `Bot`, `Message`, `Event` 等支持. -- 独立跨平台, 可以被以库的形式内置在任意项目内 -- 现有 JVM 与 AndroidLib 支持 -- 未来计划 Native 支持 - -#### mirai-http-api -Http API 调用支持. 这是一个单向依赖 `mirai-core` 的模块, 可作为一个附加功能使用. -您可以使用其他语言通过 Http API 调用 Mirai. - -开发尚未完成. - -#### mirai-console -- 仅 JVM 平台 -- 仅命令行 -- Jar 插件支持 - -#### mirai-demo -Samples and demos. -监听事件示例 [SubscribeSamples](mirai-demos/mirai-demo-1/src/main/java/demo/subscribe/SubscribeSamples.kt) -随机图片发送 [Gentleman](mirai-demos/mirai-demo-gentleman/src/main/kotlin/demo/gentleman/Main.kt) - -感谢 [@Freedom](https://github.com/Freedom0925) 的 [Android App Demo](https://github.com/mamoe/mirai/blob/master/mirai-demos/mirai-demo-android/src/main/kotlin/net/mamoe/mirai/demo/MainActivity.kt) -#### mirai-debug -抓包工具和分析工具. 不会进行稳定性维护. - -- 抓包自动解密和分析 -- Hex 着色比较器 -- GUI Hex 调试器(值转换) - -### Logger -[Logger](mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/MiraiLogger.kt) -Mirai 维护跨平台日志系统, 针对平台的实现为 `expect class PlatformLogger`, -一般推荐使用顶层的 `var DefaultLogger: (identity: String?) -> PlatformLogger` 通过 `DefaultLogger( ... )` 来创建日志记录器. -每个 `Bot` 都拥有一个日志记录器, 可通过 `Bot.logger` 获取 - -*日志记录尚不完善, 以后可能会修改* - -### Bot -[Bot](mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt) 为机器人 -一个机器人实例只有一个账号. - -Mirai 能同时维护多个机器人账号. - -[BotHelper](mirai-core/src/commonMain/kotlin/net.mamoe.mirai/BotHelper.kt) 中存在一些快捷方法, 您可以先继续阅读本文再查看捷径. - -### Contact -[Contact](mirai-core/src/commonMain/kotlin/net.mamoe.mirai/contact/Contact.kt) 为联系人. -虽是联系人, 但它包含 `QQ`, `Group`, 和 `Member`(群成员). -联系人并不是独立的, 它必须隶属于某个 `Bot`. - -**共有成员函数**: -- `suspend fun sendMessage`(`String`|`Message`|`MessageChain`) - -**共有属性**: -- `val id: UInt` (即 QQ 号和群号) - -注: 为减少出错概率, 联系人的 `id` 均使用无符号整型 `UInt`, 这是 Kotlin 1.3 的一个实验性类型 -我们建议您在开发中也使用 `UInt`, 以避免产生一些难以发现的问题 - -### Message -Mirai 中所有的消息均为对象化的 [Message](mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/Message.kt) -大多数 `Message` 都是 `inline class`, 因此这种模式不会带来性能损失. - -#### MessageChain - -一条发出去的消息或接收到的消息为一个 `MessageChain` 对象, 它实现 `Message` 接口: -`interface MessageChain : MutableList<Message>, Message` - -一个普通的 `Message` 不能发送, 只能组成 `MessageChain` 然后发送. - -它有多种实现: -- `internal inline class MessageChainImpl : MutableList<Message>, MessageChain`: 通常的实现. 非线程安全. -- `internal inline class SingleMessageChain : MessageChain`: 用于包装单个 `Message` 为 `MessageChain`. 实例化后不可修改 -- `object NullMessageChain : MessageChain`: 不可变的空集合. 只应改被用于替代 `null` 的情况 - -#### Types of Message -现支持的消息类型: -- `inline class PlainText : Message` 纯文本 -- `inline class Image : Message` 图片 (将会有独立章节来说明图片的上传等) -- `inline class Face : Message` 表情 (QQ 自带表情) -- `inline class At : Message` (仅限群, 将会被 QQ 显示为蓝色的连接) - -计划中: -- `XML` -- `File` (文件上传) - -#### Operators - -| 操作表示 | 说明 | -|---| ---| -| Message + Message | 连接 `Message`, 得到 `MessageChain` | -| Message + String | 连接 `Message` 与 `String`(`PlainText`) 为 `MessageChain` | -| Message eq String | 可读字符串如 "\[@10000\]" 判断 | -| String in Message | 内容包含判断 | - -#### Extensions - -| 扩展方法 | 说明 | -|---| ---| -|String.toChain():MessageChain| PlainText(this) | -|Message.toChain():MessageChain| 构造初始数量为一个的 MessageChain | -|suspend Message.sendTo(Contact)| 发送给联系人 | - -### Image -考虑到协议需求和内存消耗, Mirai 的所有 API 均使用 [ExternalImage](mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/ExternalImage.kt) -`ExternalImage` 包含图片长宽、大小、格式、文件数据 -您只需通过扩展函数处理图片. - -| 扩展函数 | 说明 | -|---| ---| -|suspend ExternalImage.sendTo(Contact)| 上传图片并以纯图片消息发送给联系人 | -|suspend ExternalImage.upload():Image | 上传图片并得到 [Image] 消息 | -|suspend Contact.sendImage(ExternalImage) | 上传图片并发送给指定联系人 | - -您无需记忆用法. -在监听事件后的事件处理过程中, 您可调用扩展 `image.send()` 来发送图片. 或是调用 `image.upload()` 来上传并得到一个类型为 `Image` 的 `Message` 以便于发送组合类型的消息 - ## Wiki -在 [WiKi](https://github.com/mamoe/mirai/wiki/Development-Guide---Kotlin) 中查看各类帮助 \ No newline at end of file +在 [WiKi](https://github.com/mamoe/mirai/wiki/Development-Guide---Kotlin) 中查看各类帮助 From e4253ac04c7a8385dd35e53b2706adca0dcd1668 Mon Sep 17 00:00:00 2001 From: Him188 <Him188@mamoe.net> Date: Tue, 24 Dec 2019 01:51:50 +0800 Subject: [PATCH 2/2] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bf993571f..8308db72e 100644 --- a/README.md +++ b/README.md @@ -102,4 +102,4 @@ Mirai 使用以下开源库: - [kotlinx-serialization](https://github.com/Kotlin/kotlinx.serialization) ## Wiki -在 [WiKi](https://github.com/mamoe/mirai/wiki/Development-Guide---Kotlin) 中查看各类帮助 +在 [Wiki](https://github.com/mamoe/mirai/wiki/Development-Guide---Kotlin) 中查看各类帮助