diff --git a/README.md b/README.md index 7104d268f..b778801db 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,7 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效 ## 开始 +- **用户手册**: [UserManual](docs/UserManual.md) - 开发文档: [docs](docs/README.md) - 论坛: [Mirai Forum](https://mirai.mamoe.net/) > *Mirai 只有唯一一个官方论坛 Mirai Forum* diff --git a/docs/.UserManual_images/MCLI-1.png b/docs/.UserManual_images/MCLI-1.png new file mode 100644 index 000000000..b3bfba285 Binary files /dev/null and b/docs/.UserManual_images/MCLI-1.png differ diff --git a/docs/.UserManual_images/MCPS-1.png b/docs/.UserManual_images/MCPS-1.png new file mode 100644 index 000000000..15d2f921b Binary files /dev/null and b/docs/.UserManual_images/MCPS-1.png differ diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md index bf6f68928..3408d1522 100644 --- a/docs/ConfiguringProjects.md +++ b/docs/ConfiguringProjects.md @@ -4,7 +4,7 @@ ### 选择版本 -有关各类版本的区别，参考 [版本规范](Evolution.md#版本规范) +有关各类版本的区别，参考 [版本规范](Evolution.md#版本规范)。通常建议选择最新稳定版本。 [Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-core/images/download.svg? [Bintray Download]: https://bintray.com/him188moe/mirai/mirai-core/ diff --git a/docs/README.md b/docs/README.md index c2c489b46..de212b3aa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,19 +1,21 @@ # Mirai -欢迎来到 mirai 文档。 +欢迎来到 mirai 开发文档。 -## 生态 +本文面向要进行开发的用户。对于只使用现成插件的用户，请阅读 [用户手册](UserManual.md)。 -请先阅读 **[Mirai 生态概览](mirai-ecology.md)**。 +[Mirai 生态概览](mirai-ecology.md) ## 社区 SDK -**mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果不熟悉这些语言，请使用以下社区 SDK：** +**mirai 官方提供 [Kotlin/Java 等 JVM 平台语言开发支持](#jvm-平台-mirai-开发)。如果不熟悉这些语言，请使用以下社区 SDK：** + +要使用这些插件需要先配置 Mirai Console，推荐阅读 [用户手册](UserManual.md)。 + +你可以使用一个或多个语言来开发插件，而且在自己开发的同时也可以[使用下载的插件](UserManual.md#下载和安装插件)。 [`mirai-console`]: https://github.com/mamoe/mirai-console -这些 SDK 基于 [`mirai-console`]。[`mirai-console`] 是 mirai 官方维护的一个*应用程序*。可以在 [这里](https://github.com/mamoe/mirai-console/blob/master/docs/Run.md) 了解如何启动 [`mirai-console`]（也可以稍后在各 SDK 的说明中了解）。 - [mamoe/mirai-api-http]: https://github.com/mamoe/mirai-api-http [iTXTech/mirai-native]: https://github.com/iTXTech/mirai-native [iTXTech/mirai-js]: https://github.com/iTXTech/mirai-js @@ -34,30 +36,51 @@ [drinkal/Mirai-js]:https://github.com/drinkal/Mirai-js [Coloryr/ColorMirai]: https://github.com/Coloryr/ColorMirai -[Rhino]: https://github.com/mozilla/rhino [OneBot]: https://github.com/howmanybots/onebot +[Mirai HTTP]: https://github.com/project-mirai/mirai-api-http + +### 原生接口 + +这些接口直接在 JVM 上实现，不需要中间件，拥有更佳的性能。 + +| 技术 | 维护者及项目地址 | +|:-------------------|:-----------------------| +| `Kotlin Scripting` | [iTXTech/mirai-kts] | +| `C++` | [Nambers/MiraiCP] | +| `JavaScript` | [iTXTech/mirai-js] | +| *酷 Q DLL 插件* | [iTXTech/mirai-native] | + +### HTTP 接口 + +目前有两个 HTTP 协议插件。使用 HTTP 协议插件可以支持更多编程语言和技术。 + +- [***Mirai HTTP***][Mirai HTTP] 由 Mirai 开发团队提供第一级支持，目前多数 SDK 都基于它； +- [OneBot] 标准则兼容原酷Q协议，可以让基于酷Q HTTP 插件的项目在 Mirai 平台运行。 + +| 名称 | 实现 | 维护者及项目地址 | +|:-----------------|:-------------|:-------------------------------| +| ***Mirai Http*** | Mirai 标准 | [mamoe/mirai-api-http] | +| *OneBot Http* | [OneBot] 标准 | [yyuueexxiinngg/onebot-kotlin] | + +下表列举基于 Mirai HTTP 插件实现对一些编程语言支持的项目列表。要使用它们，你需要[在 Mirai Console 安装 `mirai-api-http`](https://github.com/project-mirai/mirai-api-http#%E5%AE%89%E8%A3%85mirai-api-http)。 + + +| 语言和技术 | 维护者及项目地址 | +|:--------------------------|:--------------------------------------------| +| `Python` | [Graia Framework][GraiaProject/Application] | +| `Python` | [NoneBot] | +| `C++` | [cyanray/mirai-cpp] | +| `C++` | [Chlorie/miraipp] | +| `C#` | [Executor-Cheng/mirai-CSharp] | +| `C#` | [Hyperai][theGravityLab/ProjHyperai] | +| `C#` | [Coloryr/ColorMirai] | +| `Rust` | [HoshinoTented/mirai-rs] | +| `JavaScript` / Node.js | [RedBeanN/node-mirai] | +| `JavaScript` / TypeScript | [YunYouJun/mirai-ts] | +| `JavaScript` / Node.js | [drinkal/Mirai-js] | +| `Go` | [Logiase/gomirai] | +| `易语言` | [only52607/e-mirai] | -| 技术 | 实现 | 维护者及项目地址 | -|:-------------------|:-----------------------------|:--------------------------------------------| -| ***Mirai Http*** | Mirai 标准 | [mamoe/mirai-api-http] | -| *OneBot Http* | [OneBot] 标准 | [yyuueexxiinngg/onebot-kotlin] | -| `Kotlin Scripting` | JVM | [iTXTech/mirai-kts] | -| `Python` | *Mirai Http* | [Graia Framework][GraiaProject/Application] | -| `Python` | *Mirai Http* / *OneBot Http* | [NoneBot] | -| `C++` | JNI | [Nambers/MiraiCP] | -| `C++` | *Mirai Http* | [cyanray/mirai-cpp] | -| `C++` | *Mirai Http* | [Chlorie/miraipp] | -| `C#` | *Mirai Http* | [Executor-Cheng/mirai-CSharp] | -| `C#` | *Mirai Http* | [Hyperai][theGravityLab/ProjHyperai] | -| `C#` | *WebSocket* | [Coloryr/ColorMirai] | -| `Rust` | *Mirai Http* | [HoshinoTented/mirai-rs] | -| `JavaScript` | [Rhino] / JVM | [iTXTech/mirai-js] | -| `JavaScript` | Node.js / *Mirai Http* | [RedBeanN/node-mirai] | -| `JavaScript` | TypeScript / *Mirai Http* | [YunYouJun/mirai-ts] | -| `JavaScript` | Node.js / *Mirai Http* | [drinkal/Mirai-js] | -| `Go` | *Mirai Http* | [Logiase/gomirai] | -| `易语言` | *Mirai Http* | [only52607/e-mirai] | -| *酷 Q DLL 插件* | JNI | [iTXTech/mirai-native] | > 排名不分先后 > *想在这里添加你的项目？欢迎[提交 PR](https://github.com/mamoe/mirai/edit/dev/docs/README.md)。* @@ -68,20 +91,22 @@ ## JVM 平台 Mirai 开发 +本节介绍使用 Java、Kotlin 等 JVM 平台编程语言开发 Mirai 或 Mirai Console 插件。 + **为了避免遇到各种问题，请逐步仔细阅读。** 1. [JVM 环境和开发准备工作](Preparations.md#mirai---preparations) 2. 选择框架 - - 若要将 mirai 当做依赖库嵌入你的应用使用，则需要使用 mirai-core，请阅读 [配置项目依赖](ConfiguringProjects.md)。 + 建议先阅读 [Mirai 生态概览](mirai-ecology.md)。 - - 若要以插件模式开发，可以使用 mirai-console，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。 + - 若要将 mirai 当做依赖库嵌入你的应用使用（你调用 mirai），则需要使用 mirai-core，请阅读 [配置项目依赖](ConfiguringProjects.md)。 + + - 若要以插件模式开发（mirai 调用你），可以使用 mirai-console，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。 4. 阅读 API 文档（见下文） -> 如果你不知道 `mirai-core` 或 [`mirai-console`] 是什么，请阅读 [Mirai 生态概览](mirai-ecology.md)。 -> > 如果你希望先确认 mirai 能够正常运行才能安心阅读文档，可克隆 [mirai-hello-world](https://github.com/project-mirai/mirai-hello-world) 并运行其中 Kotlin 或 Java 入口点 `main`。 diff --git a/docs/UserManual.md b/docs/UserManual.md new file mode 100644 index 000000000..76ae4a3d1 --- /dev/null +++ b/docs/UserManual.md @@ -0,0 +1,95 @@ +# Mirai - UserManual + +Mirai 用户手册。本文面向对开发不熟悉而希望使用 Mirai 的用户。 + +## 启动 Mirai + +使用 Mirai，一般人要启动的是 Mirai 控制台（即 Mirai Console），它可以加载插件。 + +Mirai 控制台现在有两个版本，插件在这两个版本的 Mirai Console 上都可以运行: + +[MCLI-1.png]: .UserManual_images/MCLI-1.png +[MCPS-1.png]: .UserManual_images/MCPS-1.png + +| 类型 | 长啥样? | 好用吗? | 怎么装? | +|:-------|:-------------|:----------------|:-------------------------------| +| 纯控制台 | [MCLI-1.png] | 稳定，也适合服务器 | [使用纯控制台版本](#使用纯控制台版本) | +| 图形界面 | [MCPS-1.png] | 测试版，不稳定 | [使用图形界面版本](#使用图形界面版本) | + +## 使用图形界面版本 + +前往 [sonder-joker/mirai-compose](https://github.com/sonder-joker/mirai-compose/releases) 下载适合你的系统的压缩包，解压到一个文件就可以使用。 + +## 使用纯控制台版本 + +### 安装 + +可以使用安装器来全自动安装： + +1. 访问 [iTXTech/mcl-installer](https://github.com/iTXTech/mcl-installer/releases)； +2. 下载适合你的系统的可执行文件； +3. 在一个新文件夹存放这个文件，运行它； +4. 通常可以一路回车使用默认设置完成安装，安装完成后程序自动退出； +5. 运行 `mcl.cmd` 启动，成功后会看到绿色的 `mirai-console started successfully`。 + +### 了解运行环境 + +安装时自动下载了 Mirai Console 启动器（简称 [MCL](https://github.com/iTXTech/mirai-console-loader)）。 + +启动器会帮你准备运行环境，下载和更新 Mirai 核心。你也可以使用启动器下载一些插件（见下文）。 + +第一次运行 `mcl.cmd` 时会初始化运行环境。下表说明了各个文件夹的用途。 + +| 文件夹名称 | 用途 | +|:---------:|:------------------------------| +| `scripts` | 存放启动器的脚本，一般不需要在意他们 | +| `plugins` | 存放插件 | +| `data` | 存放插件的数据，一般不需要在意它们 | +| `config` | 存放插件的配置，可以打开并修改配置 | +| `logs` | 存放运行时的日志，日志默认保留 7 天 | + +> 可以在[这里](https://github.com/iTXTech/mirai-console-loader)查看 MCL 详细用法 + +### 下载和安装插件 + +刚刚装好的 Mirai Console 是没有任何功能的。功能将由插件提供。 + +#### 如何安装官方插件 + +Mirai 官方提供两个插件： + +- [chat-command](https://github.com/project-mirai/chat-command): 允许在聊天环境通过以 "/" 起始的消息执行指令 +- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供 HTTP 支持，允许使用其他编程语言的插件 + +打开命令行 (Windows 系统按住Shift+鼠标右键，点击"在此处打开 PowerShell"), +可以使用 MCL 自动安装这些插件如： + +``` +./mcl --update-package net.mamoe:mirai-api-http --type plugin --channel stable +``` + +详细文档：[MCL/scripts](https://github.com/iTXTech/mirai-console-loader/blob/master/scripts/README.md) + +#### 在哪找社区插件 + +- Mirai 官方论坛 [Mirai Forum](https://mirai.mamoe.net/category/11/%E6%8F%92%E4%BB%B6%E5%8F%91%E5%B8%83) + +> *我们还正在建设插件中心，完成后将会简化寻找插件的工作* + +#### 如何安装社区插件 + +如果是 JAR 文件的插件，放入 `plugins` 即可。其他插件一般都有特殊说明如何使用，请参考它们的说明。 + + +### 使用控制台指令 + +启动 `mcl.cmd` 就会看到控制台。在控制台可以输入指令，按回车执行这条指令。 + +Mirai Console 内置一些指令，输入 `?` 并回车可以查看指令列表。 + +一些常用指令介绍在[这里](https://github.com/mamoe/mirai-console/blob/master/docs/BuiltInCommands.md#mirai-console---builtin-commands)。 + +## 解决问题 + +如果遇到使用问题或想提建议，可以在 [issues](https://github.com/mamoe/mirai/issues) 发表。也可以在[论坛](https://mirai.mamoe.net/)交流想法。 + diff --git a/docs/mirai-ecology.md b/docs/mirai-ecology.md index 4db2ed45e..eeec18b52 100644 --- a/docs/mirai-ecology.md +++ b/docs/mirai-ecology.md @@ -115,8 +115,6 @@ mirai-console-loader 应运而生，它的工作就是简化 console 启动流 即可快速启动 mirai-console 的 terminal 前端。同时 mirai-console-loader 还有一些拓展功能，可以自定义你的启动流程。 -在 mirai-console-loader 诞生之前，还有一个非官方的 mirai-console-terminal 一键启动器 MiraiOK，但是我们已**不推荐**使用 MiraiOK。([为什么？](https://github.com/project-mirai/mirai-api-http/issues/212#issuecomment-743216244)) - 将 mirai-console-loader 放入上述关系图： [](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgY2xhc3NEZWYgY29yZWhpZ2hsaWdodCBmaWxsOiNmOTYsc3Ryb2tlOiMzMzMsc3Ryb2tlLXdpZHRoOjNweDtcbiAgICBjbGFzc0RlZiBoaWdobGlnaHQgZmlsbDojZjg4LHN0cm9rZTojMzMzLHN0cm9rZS13aWR0aDozcHhcbiAgICBzdWJncmFwaCBtaXJhaSBbXCJNaXJhaSDmoYbmnrZcIl1cbiAgICAgICAgbWlyYWljb3JlYXBpKFwibWlyYWktY29yZS1hcGlcIik6Ojpjb3JlaGlnaGxpZ2h0XG4gICAgICAgIG1pcmFpY29yZXFxYW5kcm9pZChcIm1pcmFpLWNvcmU8YnIvPihRUUFuZHJvaWQg5Y2P6K6uKVwiKVxuICAgICAgICBtaXJhaWNvcmVxcWFuZHJvaWQgLS0-IHzmj5DkvpvljY_orq58bWlyYWljb3JlYXBpXG4gICAgZW5kXG4gICAgbWlyYWlpbnRlcmZhY2UoXCLkvaDnvJblhpnnmoQ8YnIvPuacuuWZqOS6uueoi-W6j1wiKVxuICAgIG1pcmFpY29yZWFwaSAtLT4gfOaPkOS-m-WfuuehgOWKn-iDvXxtaXJhaWludGVyZmFjZVxuICAgIG1pcmFpY29yZWFwaSAtLT4gfOWwgeijheWfuuehgOWKn-iDvXxtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgc3ViZ3JhcGggbWlyYWljb25zb2xlIFtcIk1pcmFpIENvbnNvbGVcIl1cbiAgICAgICAgbWlyYWljb25zb2xlYmFja2VuZChcIkJhY2tFbmRcIilcbiAgICAgICAgbWlyYWljb25zb2xlZnJvbnRlbmQtdGVybWluYWwoXCJGcm9udEVuZDogdGVybWluYWxcIilcbiAgICAgICAgbWlyYWljb25zb2xlZnJvbnRlbmQtYW5kcm9pZChcIkZyb250RW5kOiBBbmRyb2lkXCIpXG4gICAgICAgIG1pcmFpY29uc29sZWJhY2tlbmQgLS0-IG1pcmFpY29uc29sZWZyb250ZW5kLXRlcm1pbmFsXG4gICAgICAgIG1pcmFpY29uc29sZWJhY2tlbmQgLS0-IG1pcmFpY29uc29sZWZyb250ZW5kLWFuZHJvaWRcbiAgICBlbmRcbiAgICBzdWJncmFwaCBjb25zb2xlcGx1Z2lucyBbXCJNaXJhaSBDb25zb2xlIOaPkuS7tlwiXVxuICAgICAgICB5b3VybWlyYWljb25zb2xlcGx1Z2luKFwi5L2g57yW5YaZ55qEIENvbnNvbGUg5o-S5Lu2XCIpIC0tPiBtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgICAgIG1pcmFpYXBpaHR0cChcIm1pcmFpLWFwaS1odHRwIOaPkuS7tlwiKSAgLS0-IG1pcmFpY29uc29sZWJhY2tlbmRcbiAgICAgICAgb3RoZXJzbWlyYWlwbHVnaW4oXCLlhbbku5YgQ29uc29sZSDmj5Lku7ZcIikgLS0-IG1pcmFpY29uc29sZWJhY2tlbmRcbiAgICAgICAgbWlyYWluYXRpdmUoXCJtaXJhaS1uYXRpdmUg5o-S5Lu2XCIpIC0tPiBtaXJhaWNvbnNvbGViYWNrZW5kXG4gICAgZW5kXG4gICAgc3ViZ3JhcGggY29tbXVuaXR5c2RrIFtcIuekvuWMuiBTREtcIl1cbiAgICAgICAgY29tbXVuaXR5c2RrYmFzZWVkb25taXJhaWFwaWh0dHAoXCLln7rkuo4gbWlyYWktYXBpLWh0dHAg55qE56S-5Yy6IFNES1wiKSAtLT4gbWlyYWlhcGlodHRwXG4gICAgZW5kXG4gICAgY29vbHFwbHVnaW5zKFwi6YW3UeaPkuS7tlwiKSAtLT4gbWlyYWluYXRpdmVcbiAgICBtaXJhaWNvbnNvbGVsb2FkZXIoXCJtaXJhaS1jb25zb2xlLWxvYWRlclwiKTo6OmhpZ2hsaWdodCAtLS0-IHzlkK_liqh8bWlyYWljb25zb2xlZnJvbnRlbmQtdGVybWluYWxcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)