mirror of
https://github.com/mamoe/mirai.git
synced 2024-12-27 09:00:15 +08:00
Update docs
This commit is contained in:
Him188
parent
393b3d52fb
commit
15f46985ec
@ -6,34 +6,31 @@ mirai 欢迎一切形式的代码贡献。你可以通过以下几种途径向 m
|
||||
|
||||
## 主仓库 `mirai-core`
|
||||
|
||||
**阅读文档**： [docs/mirai.md](docs/mirai.md)
|
||||
|
||||
### 构建
|
||||
- 要构建项目, 请运行 `gradlew assemble`
|
||||
- 要运行测试, 请运行 `gradlew test`
|
||||
- 要构建项目并运行测试, 请运行 `gradlew build`
|
||||
- 若要添加一个 suspend 函数, 请务必考虑 Java 兼容性, 使用 [kotlin-jvm-blocking-bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge/blob/master/README-chs.md)
|
||||
|
||||
### 能做什么?
|
||||
|
||||
#### 分支
|
||||
### 分支
|
||||
|
||||
- `master`: 最新稳定版
|
||||
- `1.x`: 1.x 现有版本的开发
|
||||
- `dev`: 2.0 重构版本的开发
|
||||
|
||||
**请基于 `master` 分支进行文档修改; 基于 `dev` 分支进行其他修改 (否则你的修改可能被关闭或不会立即合并)**
|
||||
**请基于 `dev` 分支进行修改**
|
||||
|
||||
### 能做什么?
|
||||
|
||||
- 代码优化: 优化任何功能设计或实现, 或是引入一个新的设计（请先通过 issue 与维护者达成共识）
|
||||
- 解决问题: 在 [issues](https://github.com/mamoe/mirai/issues) 查看 mirai 正遇到的所有问题, 或在 [里程碑](https://github.com/mamoe/mirai/milestones) 查看版本计划
|
||||
- 协议支持: 添加新协议支持, 但需要避免添加 [mirai.md#声明](docs/mirai.md#L9) 中的内容
|
||||
- 协议支持: 添加新协议支持
|
||||
|
||||
### 注意事项
|
||||
- 尽量不要引用新的库
|
||||
- 遵守 Kotlin 官方代码规范（提交前使用 IDE 格式化代码 (commit 时勾选 'Reformat code')）
|
||||
- 不要手动拆解数据包. 请一定使用 `kotlinx.serialization` 拆解 ProtoBuf, 使用 `net.mamoe.mirai.utils.serialization.Tars` 拆解 Tars 数据包, 使用 `kotlinx.serialization` 拆解 Json 数据.
|
||||
|
||||
## 社区
|
||||
|
||||
插件社区不要求太高的代码质量，任何人都可以帮助 mirai。
|
||||
可以为 [mirai-console](https://github.com/mamoe/mirai-console) 编写插件, 并发布到社区网站: (建设中)
|
||||
可以为 [mirai-console](https://github.com/mamoe/mirai-console) 编写插件, 并发布到 Discussions
|
||||
|
||||
@ -8,7 +8,7 @@ Mirai is designed to handle all sorts of messaging works that can be automatical
|
||||
> Tencent QQ: A modern messaging software used by all Chinese netizens.
|
||||
|
||||
## Start
|
||||
**Development document**： [docs/mirai.md](docs/mirai.md)
|
||||
**Development document**： [docs](docs)
|
||||
|
||||
### Use as a framework
|
||||
|
||||
|
||||
@ -109,15 +109,13 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效
|
||||
|
||||
## 开始
|
||||
|
||||
- 开发文档（新，编写中）：[docs](docs/README.md)
|
||||
- 开发文档（旧）：[docs/mirai.md](docs/mirai.md)
|
||||
- 开发文档：[docs](docs/README.md)
|
||||
- 更新日志: [release](https://github.com/mamoe/mirai/releases)
|
||||
- 开发计划: [milestones](https://github.com/mamoe/mirai/milestones)
|
||||
|
||||
- 贡献: [CONTRIBUTING](CONTRIBUTING.md)
|
||||
|
||||
- [awesome-mirai](https://github.com/project-mirai/awsome-mirai/blob/master/README.md) **mirai相关项目合集**
|
||||
- 常见问题: [docs/FAQ.md](docs/FAQ.md)
|
||||
|
||||
## [贡献](CONTRIBUTING.md)
|
||||
|
||||
|
||||
144
docs/mirai.md
144
docs/mirai.md
@ -1,144 +0,0 @@
|
||||
# mirai
|
||||
欢迎来到 mirai 文档.
|
||||
|
||||
本文档基于 mirai 1.0.0, 最后修改时间为 2020/5/22
|
||||
|
||||
## 声明
|
||||
1. mirai 为完全免费的开源项目，使用 AGPLv3 开源协议. mirai 项目维护者和贡献者 (下文简称 '我们') 不通过任何方式收取费用。所有人都可以免费获取并使用这个项目。
|
||||
2. mirai 不允许被用于任何违反相关法律法规的工作, 包括但不限于: 盗取账号密码, 盗窃用户资金, 群发违禁内容。 因此我们没有支持设备锁验证, 也没有支持免密登录 (在非常用地点登录会频繁要求输入验证码)。
|
||||
3. mirai 不提供任何可能促进上述违法行为的功能, 包括但不限于: 收发红包, 收发转账, 主动添加好友。
|
||||
4. mirai 不公开任何协议接口. 不支持任何协议扩展.
|
||||
5. mirai 开发者是友善的，建立在以下前提之上：
|
||||
- 我们只帮助**友善**的人
|
||||
- 我们只接受友善的**建议**，不接受任何**要求**
|
||||
- **我们没有任何义务解答你的问题**
|
||||
- 我们只接受友善的评价
|
||||
- 我们有权力拒绝你使用 mirai 相关服务
|
||||
|
||||
|
||||
## 项目整体架构
|
||||
mirai 项目整体由 核心 (`mirai-core`) 与 控制台(`mirai-console`) 组成.
|
||||
|
||||
|
||||
- [`mirai-core`](../mirai-core-api) 是机器人服务支持**库**. 提供所有机器人相关 API. **本身只包含抽象类和接口, 使用时还需要同时依赖协议模块**.
|
||||
可用的协议模块:
|
||||
- [`mirai-core-qqandroid`](../mirai-core): Android QQ 8.3.0 版本协议实现.
|
||||
|
||||
`mirai-core` 设计为一个 **`支持库`**, 意味着它可以被独立依赖, 在任意项目中使用. 详见下文.
|
||||
|
||||
- `mirai-serialization` 依赖 `mirai-core`, 是 mirai-core 的序列化支持模块. 提供 `Message` 类型的序列化支持与相关 [mirai 码](MiraiCodeSepecification.md) 支持.
|
||||
此模块自 mirai `1.1.0` 起可用, 引用方法同 `mirai-core`.
|
||||
|
||||
- [`mirai-login-solver-selenium`](https://github.com/project-mirai/mirai-login-solver-selenium).
|
||||
|
||||
`@see` [`mirai-login-solver-selenium/README.md`](https://github.com/project-mirai/mirai-login-solver-selenium#mirai-login-solver-selenium)
|
||||
|
||||
- [`mirai-console`](https://github.com/mamoe/mirai-console) 是基于 `mirai-core` 的, 支持插件加载, 指令系统, 和配置等的**控制台框架**.
|
||||
**注意: 此模块正在重写, 短时间内不可用**
|
||||
console 由 '后端' 和 '前端' 组成.
|
||||
[`backend/mirai-console`](https://github.com/mamoe/mirai-console/tree/reborn/backend/mirai-console) 为唯一的后端, 包含所有开发时需要用到的功能.
|
||||
可用的官方（由 mirai 所属 [mamoe](https://github.com/mamoe) 组成员维护）前端:
|
||||
- 纯命令行: [`frontend/mirai-console-pure`](https://github.com/mamoe/mirai-console/tree/reborn/frontend/mirai-console-pure)
|
||||
- 基于 JavaFX 的图形端: [`frontend/mirai-console-graphical`](https://github.com/mamoe/mirai-console/tree/reborn/frontend/mirai-console-graphical)
|
||||
- Unix 友好的终端: [`frontend/mirai-console-terminal`](https://github.com/mamoe/mirai-console/tree/reborn/frontend/mirai-console-terminal)
|
||||
- Android APP: [`MiraiAndroid`](https://github.com/mzdluo123/MiraiAndroid) 额外支持多种脚本 API
|
||||
|
||||
|
||||
**注意**: `mirai-core` 于 2020 年 5 月发布的 `1.0.0` 版本正式进入稳定更新阶段,
|
||||
**而 `mirai-console` 仍处于快速迭代阶段, 任何 API 都有可能在不经过警告的情况下改动, 任何 API 都不具有任何稳定性.**
|
||||
|
||||
## `mirai-core`
|
||||
|
||||
`mirai-core` 仅包含抽象类和接口和一些扩展方法, 且拥有非常完整的 KDoc (源码内文档). 此处没有必要过多赘述.
|
||||
|
||||
你可以在这里快速地大致了解 mirai 的全部 API.
|
||||
|
||||
### 准备
|
||||
|
||||
要能看懂下文, 建议至少学习 Java, Kotlin 或 C# 其中一门语言.
|
||||
|
||||
mirai 全部使用 Kotlin, 若你无法理解部分 API, 可先简略阅读 Kotlin 参考: [kotlincn.net](https://www.kotlincn.net/docs/reference/)
|
||||
|
||||
有关协程 (`suspend` 修饰符)部分, mirai 做了大量的兼容性转换以让 Java 使用相同的 API 阻塞地调用一个协程函数。
|
||||
对于 Kotlin 函数如 `suspend fun sendMessage(msg: Message)`,
|
||||
Kotlin 编译后生成 Java 方法 `public Object sendMessage(Message msg, Continuation<Unit> cont)`
|
||||
Mirai 通过某种方式同时生成了桥梁方法 `public void sendMessage(Message msg)` 使得 Java 使用者可无缝接入。
|
||||
|
||||
建议在 IDE 内打开本文件 (位置 /docs/mirai.md), 可以进行源码内跳转.
|
||||
|
||||
### 开始
|
||||
|
||||
1. [实验性 API 注解 MiraiExperimentalAPI](../mirai-core-api/src/commonMain/kotlin/utils/Annotations.kt#L41)
|
||||
|
||||
2. '机器人' 和 '联系人'
|
||||
1. [ContactOrBot](../mirai-core-api/src/commonMain/kotlin/contact/ContactOrBot.kt)
|
||||
2. [机器人对象 Bot](../mirai-core-api/src/commonMain/kotlin/Bot.kt)
|
||||
3. [Contact](../mirai-core-api/src/commonMain/kotlin/contact/Contact.kt)
|
||||
4. [用户对象 User](../mirai-core-api/src/commonMain/kotlin/contact/User.kt)
|
||||
5. [好友对象 Friend](../mirai-core-api/src/commonMain/kotlin/contact/Friend.kt)
|
||||
6. [群对象 Group](../mirai-core-api/src/commonMain/kotlin/contact/Group.kt)
|
||||
7. [群成员对象 Member](../mirai-core-api/src/commonMain/kotlin/contact/Member.kt)
|
||||
|
||||
总结: [机器人和联系人架构](../.github/机器人和联系人架构.png). 其中 `CoroutineScope` 为 Kotlin 协程作用域, Java 使用者可忽略.
|
||||
|
||||
|
||||
3. '消息'
|
||||
1. [消息对象 Message](../mirai-core-api/src/commonMain/kotlin/message/data/Message.kt)
|
||||
特别注意, `Message` 分为 单个消息(`SingleMessage`) 和 多个消息, 即消息链(`MessageChain` ).
|
||||
2. [消息链 MessageChain](../mirai-core-api/src/commonMain/kotlin/message/data/MessageChain.kt)
|
||||
// TODO 此处还有更详细的扩展 API 解释, 待更新
|
||||
3. 接下来可按需阅读各类型消息 [各类型消息](../mirai-core-api/src/commonMain/kotlin/message/data/). 一个文件包含一种消息.
|
||||
|
||||
|
||||
4. '事件'
|
||||
mirai 支持异步的事件系统.
|
||||
1. [事件接口 Event](../mirai-core-api/src/commonMain/kotlin/event/Event.kt)
|
||||
2. [广播事件 Event.broadcast](../mirai-core-api/src/commonMain/kotlin/event/Event.kt)
|
||||
3. - Kotlin: [函数式监听事件 subscribe](../mirai-core-api/src/commonMain/kotlin/event/subscriber.kt)
|
||||
- Kotlin & Java: [方法反射监听事件 JvmMethodListeners](../mirai-core-api/src/commonMain/kotlin/event/JvmMethodListeners.kt)
|
||||
4. 内建事件列表 [README](../mirai-core-api/src/commonMain/kotlin/event/events/README.md).
|
||||
**注意**: mirai 将接收到的消息事件独立放置在 `net.mamoe.mirai.message` 下, 并命名为 `MessageEvent`. 并为他们实现了一些扩展. 详见 [MessageEvent.kt](../mirai-core-api/src/commonMain/kotlin/message/MessageEvent.kt)
|
||||
5. 事件工具类和工具函数 (仅 Kotlin) (可以跳过本节):
|
||||
标注 (*) 代表需要比较好的 Kotlin 技能才能理解.
|
||||
- 挂起当前协程, 直到返回下一个事件实例: [nextEvent](../mirai-core-api/src/commonMain/kotlin/event/nextEvent.kt)
|
||||
- 挂起当前协程, 并从一个事件中同步一个值: [syncFromEvent](../mirai-core-api/src/commonMain/kotlin/event/linear.kt)
|
||||
- (*) 消息事件监听 DSL: [subscribeMessages](../mirai-core-api/src/commonMain/kotlin/event/subscribeMessages.kt)
|
||||
- (*) 协程 `select` 语法的监听方式: [selectMessages](../mirai-core-api/src/commonMain/kotlin/event/select.kt)
|
||||
- (*) 挂起协程并等待下一个与 `this` 语境相同的事件 [MessageEvent.nextMessage](../mirai-core-api/src/commonMain/kotlin/message/utils.kt#L50)
|
||||
|
||||
<br><br>
|
||||
<br><br>
|
||||
一切准备就绪. 现在开始构造 `Bot` 实例:
|
||||
|
||||
1. `Bot` 的配置: [BotConfiguration](../mirai-core-api/src/commonMain/kotlin/utils/BotConfiguration.kt)
|
||||
可大致了解或跳过. 一般使用默认属性即可.
|
||||
2. 构造 `Bot` 实例: [BotFactory](../mirai-core/src/jvmMain/kotlin/BotFactory.kt#L23), [newBot](../mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/BotFactory.kt#L53)
|
||||
|
||||
另外地, 你还可以了解 mirai 提供的多平台日志系统 (为了同时支持控制台和独立依赖): [MiraiLogger](../mirai-core-api/src/commonMain/kotlin/utils/MiraiLogger.kt), 也可以跳过这个内容
|
||||
|
||||
### 使用
|
||||
|
||||
使用 mirai 作为一个依赖库: 阅读 [Quick Start](../docs/guide_quick_start.md) 配置依赖.
|
||||
使用 mirai 作为控制台框架: 使用 [mirai-console](https://github.com/mamoe/mirai-console) 开发插件
|
||||
|
||||
#### 第三方依赖
|
||||
|
||||
在 `1.0.0` 及更新版本, mirai-core 通过 gradle 依赖的 `api` 方式暴露了如下依赖库:
|
||||
|
||||
- `kotlin-stdlib`: Kotlin 标准库, 版本 1.4.0
|
||||
- `kotlin-reflect`: Kotlin 反射, 版本 1.4.0
|
||||
- `kotlinx-coroutines-core`: Kotlin 协程, 版本 1.3.9
|
||||
- `kotlinx-serialization-core`: Kotlin 序列化运行时, 和 JSON 序列化, 版本 1.0.0-RC (此库不稳定, 请不要用新版本覆盖)
|
||||
- `kotlinx-serialization-protobuf`: Kotlin ProtocolBuffers 序列化, 版本 1.0.0-RC (此库不稳定, 请不要用新版本覆盖)
|
||||
- `kotlinx-io`: Kotlin IO, 版本至少为 0.1.16 (此库非常不稳定, 不建议使用它)
|
||||
- `kotlinx-coroutines-io`: Kotlin 异步 IO, 版本至少为 0.1.16 (此库非常不稳定, 不建议使用它)
|
||||
- `kotlinx-atomicfu`: Kotlin 原子操作, 版本至少为 0.14.4
|
||||
- `ktor-client-core`, `ktor-network`, `ktor-client-cio`: Ktor HTTP, 版本至少为 1.3.2-1.4.0-rc
|
||||
|
||||
在 JVM, mirai 使用 `"org.bouncycastle:bcprov-jdk15on:1.64"` 进行密匙计算.
|
||||
|
||||
## `mirai-core-qqandroid`
|
||||
`mirai-core` 的实现部分. 不提供任何说明. 使用者无需考虑任何协议实现过程.
|
||||
|
||||
## `mirai-console`
|
||||
控制台框架。此模块处于实验性阶段, 可能没有很好地文档支持, 详见 [mirai-console](https://github.com/mamoe/mirai-console)
|
||||
Loading…
Reference in New Issue
Block a user