diff --git a/docs/avilla/NAV.md b/docs/avilla/NAV.md index bf7cefe..4ea4bd3 100644 --- a/docs/avilla/NAV.md +++ b/docs/avilla/NAV.md @@ -1,10 +1,9 @@ - [概览](index.md) - [为什么是 Avilla ?](why-avilla.md) - 基础 - - [安装 Avilla](basic/installation/index.md) - - [拓展:包管理器的使用](basic/installation/package-manager.md) - - [使用 Console 部署最小实例](basic/installation/minimum.md) - - [配置其他平台](basic/installation/other-platform.md) + - 安装与部署 + - [组件安装](basic/installation/index.md) + - [部署最小实例](basic/installation/minimum.md) - Hello Avilla - [基本介绍](basic/hello-avilla/introduct.md) - [协议配置](basic/hello-avilla/protocol-config.md) @@ -70,7 +69,7 @@ - [使用 Luma 管理应用组件](best-practice/luma-manage.md) - [使用 Luma 发布功能](best-practice/luma-publish.md) - 社区 - - [概述](community/intro.md) + - [概述](community/index.md) - [生态系统](community/ecosystem.md) - [贡献指导](community/contribution.md) - [鸣谢](community/thanks.md) @@ -86,3 +85,4 @@ - [QQGuild (Official)](other/deploy-protocols/qqguild-official.md) - [Console](other/deploy-protocols/console.md) - [使用 outbound-onebot11](other/outbound-onebot11.md) + - [拓展:包管理器的使用](other/package-manager.md) diff --git a/docs/avilla/assets/img/console-hello.svg b/docs/avilla/assets/img/console-hello.svg new file mode 100644 index 0000000..5901995 --- /dev/null +++ b/docs/avilla/assets/img/console-hello.svg @@ -0,0 +1,168 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Console + + + + + + + + + + AvillaConsole — Welcome to Avilla23:28:21 +────────────────────────────────────────────────────────────────────────<function Avilla.__init__.<locals>.message_cacher at  +⛔  🗑️ Chat ⚙️ 📝 0x0000028B8EB8CC20> +────────────────────────────────────────────────────────────────────────<function on_message_received at 0x0000028B8EB8CB80> +23:282023-07-24 23:28:17.033 | INFO     |  +                                         User😃 avilla.console.perform.action.message:send_console_message:40 -  +───────console: [send][Console] <- 'Hello, Avilla!' +hello +─────── +🤖 Bot                                           +──────────────── +Hello, Avilla! +──────────────── + + + + + + + + +──────────────────────────────────────────────────────────────────────── +Send Message +──────────────────────────────────────────────────────────────────────── + CTRL+S  Save a screenshot  ctrl+/  Focus input  CTRL+L  Clear chat history  + + + diff --git a/docs/avilla/assets/img/minimum-terminal.svg b/docs/avilla/assets/img/minimum-terminal.svg new file mode 100644 index 0000000..017b993 --- /dev/null +++ b/docs/avilla/assets/img/minimum-terminal.svg @@ -0,0 +1,163 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Console + + + + + + + + + + AvillaConsole — Welcome to Avilla23:17:23 +──────────────────────────────────────────────────────────────────────── +⛔  🗑️ Chat ⚙️ 📝  +──────────────────────────────────────────────────────────────────────── + + + + + + + + + + + + + + + + + +──────────────────────────────────────────────────────────────────────── +Send Message +──────────────────────────────────────────────────────────────────────── + CTRL+D  Toggle dark mode  CTRL+S  Save a screenshot  ctrl+/  Focus input  + + + diff --git a/docs/avilla/basic/installation/index.md b/docs/avilla/basic/installation/index.md index 2fca8ae..eea84ba 100644 --- a/docs/avilla/basic/installation/index.md +++ b/docs/avilla/basic/installation/index.md @@ -19,9 +19,12 @@ poetry add avilla-core pip install avilla-core ``` -我们建议同时安装 [`avilla-console`](/avilla/other/deploy-protocols), +我们建议同时安装 [`avilla-console`](/avilla/other/deploy-protocols/console), 该包可用于在当前控制台页面展示用于调试的模拟聊天页面,是目前为止最容易配置的协议实现。 -但如果有其他的考虑(如已经具备预配置好的环境),也可以不选取。 + +但如果有其他的考虑(如已经具备预配置好的环境),也可以不选取,此时请参考 [相关文档](/avilla/other/deploy-protocols/) 的说明进行配置。 + +即使你是经由 Graia Ariadne,对我们已经有所认识与了解的话,你可以直接根据 [Elizabeth 部署指导](/avilla/other/deploy-protocols/mah) 复用你已有的 mirai-api-http 设置,并跳过安装与部署章节。当然,我们依旧建议你阅读完所有的文档,了解你可能会碰到的一些问题。 ``` # 使用 PDM (推荐) @@ -35,21 +38,28 @@ poetry add avilla-console pip install avilla-console ``` +关于包管理器,我们编写了一篇简略的指导,请查看: + +- [拓展:包管理器的使用](/avilla/other/package-manager) + !!! note - 协议实现是一种与 Avilla 协同的实现,可以能让 Avilla 具备某些能力,使其可以适配需要**直接**交互操作来操作的各种服务与协议。 + 协议实现是一种与 Avilla 协同的实现,可以能让 Avilla 具备某些能力,使其可以适配需要 **直接** 交互操作来操作的各种服务与协议。 如果谋求深入了解,你可以在阅读完基础章节后,在以下文档中找寻信息: - - [深入调查:协议](/avilla/advance/protocol-account.md) - - [平台信息 (Platform)](/avilla/advance/platform.md) - - [多平台特性:初识特性标准化 (Standards)](/avilla/advance/standards-intro.md) + - [深入调查:协议](/avilla/advance/protocol-account) + - [平台信息 (Platform)](/avilla/advance/platform) + - [多平台特性:初识特性标准化 (Standards)](/avilla/advance/standards-intro) 此外,作为官方,我们亦提供了为数众多的官方协议实现,以下为一部分的列举: -- [OneBot11 - miraigo/gocqhttp](/avilla/other/deploy-protocols/miraigo.md) -- [Elizabeth - mirai-api-http](/avilla/other/deploy-protocols/mah.md) -- [Red - BetterQQNT/RedProtocol](/avilla/other/deploy-protocols/red.md) -- [QQGuild (Official)](/avilla/other/deploy-protocols/qqguild-official.md) +- [OneBot11 - miraigo/gocqhttp](/avilla/other/deploy-protocols/miraigo) +- [Elizabeth - mirai-api-http](/avilla/other/deploy-protocols/mah) +- [Red - BetterQQNT/RedProtocol](/avilla/other/deploy-protocols/red) +- [QQGuild (Official)](/avilla/other/deploy-protocols/qqguild-official) 你可以在链接的文档处找寻更多详细信息。 在下一篇,我们将围绕 `avilla-core` 与 `avilla-console` 搭建起一个可交互的最小实例,并将在接下来的许多篇章中一步步解释,辅助你理解 Avilla 的使用方法。 + +!!! tip + 你可以直接点击右下角的大按钮跳转至下一篇章,该特性对本托管中的所有文档有效。 diff --git a/docs/avilla/basic/installation/minimum.md b/docs/avilla/basic/installation/minimum.md index e69de29..e6dbfa4 100644 --- a/docs/avilla/basic/installation/minimum.md +++ b/docs/avilla/basic/installation/minimum.md @@ -0,0 +1,51 @@ +在上一章中,我们安装了 `avilla-core` 与 `avilla-console`,在这一章中,我们将给出一段代码,并以总括的形式解释这段代码干了什么。 + +```python +import asyncio + +from launart import Launart +from graia.broadcast import Broadcast + +from avilla.core import Avilla, Context, MessageReceived +from avilla.console.protocol import ConsoleProtocol + +broadcast = Broadcast() +launart = Launart() +avilla = Avilla(broadcast, launart, [ConsoleProtocol()]) + +@broadcast.receiver(MessageReceived) +async def on_message_received(cx: Context, event: MessageReceived): + await cx.scene.send_message("Hello, Avilla!") + +launart.launch_blocking(loop=broadcast.loop) +``` + +当你启动应用,你理应会在控制台发现以下界面: + +![svg](/avilla/assets/img/minimum-terminal.svg) + +如果我们试着,在左侧下方的输入框内输入些什么,然后摁下回车……: + +![svg](/avilla/assets/img/console-hello.svg) + +太棒了!于昏暗 (?) 的世界中,Avilla 成功的发出了第一声啼鸣! + +可别小瞧了这段代码,基础章节,甚至进阶篇章中的大部分都以这段为基板进行不同程度的扩展,这也是你会碰到的最常见的用户界面。 + +接下来,你可以尝试 [配置其他协议端](/avilla/other/deploy-protocols/); +也可以先继续阅读文档的剩余部分,探索 Avilla 所具备的诸项特性与功能; +同时,你也可以探索 [生态系统](/avilla/community/ecosystem),找寻社区中有趣的千奇百怪,不过,记得要仔细阅读文档中的相关说明,遇到问题要善用搜索功能,或者你也可以 [抱持良好的态度](https://lug.ustc.edu.cn/wiki/doc/smart-questions/) 寻求 [社区](/avilla/community/intro) 的帮助。 + +我们并不面向毫无基础的读者,也为了节省篇幅,我们不会在这里过多的解释 *发生了什么* ,相对的,我们提供详尽的描述与必要的指示。 + +!!! tip + 这里是一些有用的链接,有助于你理解上面给出的代码片段。 + 此外,也欢迎使用本站的搜索功能。 + + - [引言:Broadcast Control](avilla/advance/intro-bcc) + - [事件监听器](basic/hello-avilla/listen) + - [上下文对象 Context](basic/hello-avilla/context-basic) + - [消息与消息事件](basic/hello-avilla/message-and-event) + - [发送消息](basic/hello-avilla/message-send) + - [启动应用](basic/hello-avilla/launch-app) + \ No newline at end of file diff --git a/docs/avilla/basic/installation/other-platform.md b/docs/avilla/community/index.md similarity index 100% rename from docs/avilla/basic/installation/other-platform.md rename to docs/avilla/community/index.md diff --git a/docs/avilla/community/intro.md b/docs/avilla/community/intro.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/avilla/basic/installation/package-manager.md b/docs/avilla/other/package-manager.md similarity index 100% rename from docs/avilla/basic/installation/package-manager.md rename to docs/avilla/other/package-manager.md