From 7e3d09d32b9e21ab53438e18c294b0c10846bd10 Mon Sep 17 00:00:00 2001 From: Richard Chien Date: Tue, 14 Aug 2018 23:52:52 +0800 Subject: [PATCH] Update docs --- README.md | 4 +- demo/__init__.py | 23 +++++++---- docs/.vuepress/config.js | 5 ++- docs/.vuepress/public/hero.png | Bin 0 -> 8596 bytes docs/README.md | 1 + docs/guide/README.md | 36 +++++++++++------- docs/guide/getting-started.md | 67 +++++++++++++++++++++++++++++++++ docs/guide/whats-happened.md | 3 ++ 8 files changed, 113 insertions(+), 26 deletions(-) create mode 100644 docs/.vuepress/public/hero.png create mode 100644 docs/guide/whats-happened.md diff --git a/README.md b/README.md index 72c8b73e..6fa485c5 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ [![License](https://img.shields.io/pypi/l/none-bot.svg)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/none-bot.svg)](https://pypi.python.org/pypi/none-bot) -NoneBot 是一个基于 [酷 Q](https://cqp.cc/) 的 Python 异步 QQ 机器人框架，框架与酷 Q 交互的部分使用 [aiocqhttp](https://github.com/richardchien/python-aiocqhttp)，后者是 [CoolQ HTTP API 插件](https://github.com/richardchien/coolq-http-api) 的一个 Python 异步 SDK。NoneBot 仅支持 Python 3.6+ 及 CoolQ HTTP API 插件 v4.2+。 +NoneBot 是一个基于 [酷 Q](https://cqp.cc/) 的 Python 异步 QQ 机器人框架，底层与酷 Q 交互的部分使用 [python-aiocqhttp](https://github.com/richardchien/python-aiocqhttp)，后者是 [CoolQ HTTP API 插件](https://github.com/richardchien/coolq-http-api) 的一个 Python 异步 SDK。NoneBot 仅支持 Python 3.6+ 及 CoolQ HTTP API 插件 v4.2+。 NoneBot 本身不包含任何实际功能，仅仅提供处理消息、解析命令等核心功能，框架的使用者需要使用框架提供的接口，以插件的形式来编写具体功能。 -文档暂时还没完成，请先参考 [none.plugins](none/plugins)、[demo](demo) 模块和 [richardchien/maruko](https://github.com/richardchien/maruko) 项目中的使用方式。 +文档暂时还没完成，可以在 [这里](https://none.rclab.tk/) 访问正在编写中的文档，对于文档中目前尚未写到的部分，请先参考 [none.plugins](none/plugins)、[demo](demo) 和 [richardchien/maruko](https://github.com/richardchien/maruko) 项目。 diff --git a/demo/__init__.py b/demo/__init__.py index 06e71871..3b5dd1bd 100644 --- a/demo/__init__.py +++ b/demo/__init__.py @@ -1,13 +1,20 @@ -from os import path +# from os import path +# +# import none +# from demo import config +# +# none.init(config) +# app = none.get_bot().asgi +# +# if __name__ == '__main__': +# none.load_builtin_plugins() +# none.load_plugins(path.join(path.dirname(__file__), 'plugins'), +# 'demo.plugins') +# none.run(host=config.HOST, port=config.PORT) import none -from demo import config - -none.init(config) -app = none.get_bot().asgi if __name__ == '__main__': + none.init() none.load_builtin_plugins() - none.load_plugins(path.join(path.dirname(__file__), 'plugins'), - 'demo.plugins') - none.run(host=config.HOST, port=config.PORT) + none.run(host='0.0.0.0', port=8080) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 89a334d3..74abeec4 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -13,8 +13,8 @@ module.exports = { lastUpdated: '上次更新', activeHeaderLinks: false, nav: [ - { text: '指南', link: '/guide/' }, - { text: '术语表', link: '/glossary' }, + { text: '入门指南', link: '/guide/' }, + { text: '术语表', link: '/glossary.md' }, ], sidebar: { '/guide/': [ @@ -25,6 +25,7 @@ module.exports = { '', 'installation', 'getting-started', + 'whats-happened', ] } ] diff --git a/docs/.vuepress/public/hero.png b/docs/.vuepress/public/hero.png new file mode 100644 index 0000000000000000000000000000000000000000..d9c5b33c55f84914b2b58d168711eca12a76b36e GIT binary patch literal 8596 zcmcI~gV&dqMmR68%n6!kVjF#^1mXc-|bcdvbbd4IF z@5A>O|G~TK+I2nmdCoa^p3mppXA5|xBu#pg?j`^Lq_Q$7RRDnOU45?;gOaY1nLq$| zs4I(lq3$|?n_{RYAGumhM%QN?tmM3I;7u^c#d}7_+nkEl<;MONDPnp1O z|93z3FZcxnN^u(-e`#(LR|hh&&a0iBz1W#o*qNW7YpdPUmP=int4I)Q4D8!JjH$Tn z+wOCv@V51Ic5%s_+k$&FFnD`=x;IXzrd$W2C}npoA9c(0w}jnlDV@2Os@&3ty(i8% zd{m)v_S}oZ%Twd*sPgD<5ShOpIkM2k&TfW-Vj9asz!fpmMe|VLfko;;h00lVBf`s5 z#nbfg;Naqkn779*z`WbMer9V%cIeM73%OIZonwcXYw;A`h;!{u4r9bK^tKsl1rCV*3o<)hH$JoY|8oe;S1DVbi?4i+) zo7UMG-r_l8=Q1Qd=xD3-)cZL=N$c1yMfVMs|Cn&d*n^j~VG)idtT4iX7=O zGuF|*W)(lXB_vGJAEI&;oiX4Y=WNF$^qH}(bWmu0GGjFE8k0Pee3^yv9-#Ax-!fa# zyp&v?c=b?oXs5V-=kji2E9+4Rn$k{U0ic7^?VzXKhRN2MRB#-Ne~YXR$9M zPIJeCsiikjq-jg4Q+U=@>%+V+qF#2IFCv}gs+Ot41mTAdV+{S;MpnkM!gg`LFLWWDZqFPUp%( z2?Z}7F}4^ig$c4UQjMEZqSNIRD%v9C>o{!}OzV!!8eRhP$_sZbEce>-oZ9(C98^{A ztYCW3Z+mr~H`8X5Ds^RUE`(03IQ)v2anM}NX=o`BKDRhFRnZXki41FJC4X|U%f-*5 zO}#9VWo-YHSqjJVvNCHJ(F`5r)GuVF8#E!3s9_s;tB~zG+8743F@-aY*waBB@>R2c z{CUa$Rw#DJS3CmT=c(k1-%3v{iR>=m@S6DE#7Rv}2%nur6R?

S79pp_MdEw86Y7HumN)plCC8k9~y3J7yRSCANvN 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 C!*{a) literal 0 HcmV?d00001 diff --git a/docs/README.md b/docs/README.md index 91a75c41..be2862af 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,6 @@ --- home: true +heroImage: /hero.png actionText: 即刻开始 actionLink: /guide/ features: diff --git a/docs/guide/README.md b/docs/guide/README.md index 792c8839..0059696b 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,29 +1,37 @@ # 介绍 -NoneBot 是一个基于 [酷 Q](https://cqp.cc/) 的 Python 异步 QQ 机器人框架，它会对 QQ 机器人收到的消息进行解析和处理，并以插件化的形式，分发给消息所对应的命令处理器和自然语言处理器，来完成具体的功能。 - -除了起到解析消息的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制，尤其对于命令处理器，它更是提供了完善且易用的用户会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。 - -NoneBot 在其底层与酷 Q 交互的部分使用 [python-aiocqhttp](https://github.com/richardchien/python-aiocqhttp) 库，后者是 [CoolQ HTTP API 插件](https://github.com/richardchien/coolq-http-api) 的一个 Python 异步 SDK，在 [Quart](https://pgjones.gitlab.io/quart/) 的基础上封装了与 CoolQ HTTP API 插件的网络交互。 - -得益于 Python 的 [asyncio](https://docs.python.org/3/library/asyncio.html) 机制，NoneBot 处理消息的吞吐量有了很大的保障，再配合 CoolQ HTTP API 插件可选的 WebSocket 通信方式（也是最建议的通信方式），NoneBot 的性能可以达到 HTTP 通信方式的两倍以上，相较于传统同步 I/O 的 HTTP 通信，性能更是有质的飞跃。 - -需要注意的是，NoneBot 仅支持 Python 3.6+ 及 CoolQ HTTP API 插件 v4.2+。 - ::: tip 提示 如果在阅读本文档时遇到难以理解的词汇，请随时查阅 [术语表](/glossary.md) 或使用 [Google 搜索](https://www.google.com/ncr)。 ::: ::: tip 提示 -如果初次使用时觉得这里的介绍过于枯燥，可简单略读之后直接前往 [安装](/guide/installation.md) 查看安装方法，并进行后续的基础使用教程。 +初次使用时可能会觉得这里的介绍过于枯燥，可以先简单略读之后直接前往 [安装](/guide/installation.md) 查看安装方法，并进行后续的基础使用教程。 ::: -## NoneBot 如何工作？ +NoneBot 是一个基于 [酷 Q](https://cqp.cc/) 的 Python 异步 QQ 机器人框架，它会对 QQ 机器人收到的消息进行解析和处理，并以插件化的形式，分发给消息所对应的命令处理器和自然语言处理器，来完成具体的功能。 + +除了起到解析消息的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制，尤其对于命令处理器，它更是提供了完善且易用的会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。 + +NoneBot 在其底层与酷 Q 交互的部分使用 [python-aiocqhttp](https://github.com/richardchien/python-aiocqhttp) 库，后者是 [CoolQ HTTP API 插件](https://github.com/richardchien/coolq-http-api) 的一个 Python 异步 SDK，在 [Quart](https://pgjones.gitlab.io/quart/) 的基础上封装了与 CoolQ HTTP API 插件的网络交互。 + +得益于 Python 的 [asyncio](https://docs.python.org/3/library/asyncio.html) 机制，NoneBot 处理消息的吞吐量有了很大的保障，再配合 CoolQ HTTP API 插件可选的 WebSocket 通信方式（也是最建议的通信方式），NoneBot 的性能可以达到 HTTP 通信方式的两倍以上，相较于传统同步 I/O 的 HTTP 通信，更是有质的飞跃。 + +需要注意的是，NoneBot 仅支持 Python 3.6+ 及 CoolQ HTTP API 插件 v4.2+。 + +## 它如何工作？ NoneBot 的运行离不开酷 Q 和 CoolQ HTTP API 插件。酷 Q 扮演着「无头 QQ 客户端」的角色，它进行实际的消息、通知、请求的接收和发送，当酷 Q 收到消息时，它将这个消息包装为一个事件（通知和请求同理），并通过它自己的插件机制将事件传送给 CoolQ HTTP API 插件，后者再根据其配置中的 `post_url` 或 `ws_reverse_event_url` 等项来将事件发送至 NoneBot。 在 NoneBot 收到事件前，它底层的 aiocqhttp 实际已经先看到了事件，aiocqhttp 根据事件的类型信息，通知到 NoneBot 的相应函数。特别地，对于消息类型的事件，还将消息内容转换成了 `aiocqhttp.message.Message` 类型，以便处理。 -NoneBot 的事件处理函数收到通知后，对于不同类型的事件，再做相应的预处理和解析，然后调用对应的插件，并向其提供适合此类事件的 `Session` 对象。NoneBot 插件的编写者要做的，就是利用 `Session` 对象所提供的数据，在插件的处理函数中实现所需的功能。 +NoneBot 的事件处理函数收到通知后，对于不同类型的事件，再做相应的预处理和解析，然后调用对应的插件，并向其提供适合此类事件的会话（Session）对象。NoneBot 插件的编写者要做的，就是利用 Session 对象中提供的数据，在插件的处理函数中实现所需的功能。 -## 特点 +## 特色 + +- 基于异步 I/O +- 同时支持 HTTP 和反向 WebSocket 通信方式 +- 支持命令、自然语言处理器等多种插件形式 +- 提供直观的交互式会话接口 +- 命令和自然语言处理器提供权限控制机制 +- 支持在命令会话运行过程中切换到其它命令或自然语言处理器 +- 多种方式渲染要发送的消息内容，使对话足够自然 diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 50d4688f..c81855ea 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,3 +1,70 @@ # 开始使用 一切都安装成功后，你就已经做好了进行简单配置以运行一个最小的 NoneBot 实例的准备。 + +## 最小实例 + +使用你最熟悉的编辑器或 IDE，创建一个名为 `bot.py` 的文件，内容如下： + +```python +# bot.py + +import none + +if __name__ == '__main__': + none.init() + none.load_builtin_plugins() + none.run(host='127.0.0.1', port=8080) +``` + +`if __name__ == '__main__'` 语句块的这几行代码将依次： + +1. 使用默认配置初始化 NoneBot 包 +2. 加载 NoneBot 内置的插件 +3. 在地址 `127.0.0.1:8080` 运行 NoneBot + +在命令行使用如下命令即可运行这个 NoneBot 实例： + +```bash +python bot.py +``` + +## 配置 CoolQ HTTP API 插件 + +单纯运行 NoneBot 实例并不会产生任何效果，因为此刻酷 Q 这边还不知道 NoneBot 的存在，也就无法把消息发送给它，因此现在需要对 CoolQ HTTP API 插件做一个简单的配置来让它把消息等事件上报给 NoneBot。 + +如果你在之前已经按照 [安装](/guide/installation.md) 的建议使用默认配置运行了一次 CoolQ HTTP API 插件，此时酷 Q 的 `app\io.github.richardchien.coolqhttpapi\config\` 目录中应该已经有了一个名为 `.json` 的文件（`` 为你登录的 QQ 账号）。修改这个文件，**添加**如下配置项： + +```json +{ + "ws_reverse_api_url": "ws://127.0.0.1:8080/ws/api/", + "ws_reverse_event_url": "ws://127.0.0.1:8080/ws/event/", + "ws_reverse_reconnect_on_code_1000": true, + "use_ws_reverse": true +} +``` + +注意，这里的 `127.0.0.1:8080` 即对应 `none.run()` 中传入的 `host` 和 `port`，如果在 `none.run()` 中传入的 `host` 是 `0.0.0.0`，则插件的配置中需使用任意一个能够访问到 NoneBot 所在环境的 IP。特别地，如果你的酷 Q 运行在 Docker 容器中，NoneBot 运行在宿主机中，则默认情况下这里需使用 `172.17.0.1`（不同机器有可能不同，需使用 `docker inspect bridge` 查看，具体见 Docker 文档的 [Configure networking](https://docs.docker.com/network/)）。 + +修改之后，在酷 Q 的应用菜单中重启 CoolQ HTTP API 插件，或直接重启酷 Q，以使新的配置文件生效。 + +## 历史性的第一次对话 + +一旦新的配置文件正确生效之后，NoneBot 所在的控制台（如果正在运行的话）应该会输出类似下面的内容： + +``` +[2018-08-14 23:35:35,532] 127.0.0.1:8080 GET /ws/api/ ws 101 - 2736 +[2018-08-14 23:35:35,534] 127.0.0.1:8080 GET /ws/event/ ws 101 - 4682 +``` + +这表示 CoolQ HTTP API 插件已经成功地连接上了 NoneBot，与此同时，插件的日志文件中也会输出反向 WebSocket 连接成功的日志。 + +如果到这一步你没有看到上面这样的日志，请注意排查配置中的 IP 和端口是否确实可以访问。 + +现在，尝试向你的 QQ 机器人账号发送如下内容： + +``` +/echo 你好，世界 +``` + +到这里如果一切都没有问题，你应该会收到机器人给你回复了 `你好，世界`。这一历史性的对话标志着你已经成功地运行了一个 NoneBot 的最小实例，开始了编写更强大的 QQ 机器人的创意之旅！ diff --git a/docs/guide/whats-happened.md b/docs/guide/whats-happened.md new file mode 100644 index 00000000..5bb62ad5 --- /dev/null +++ b/docs/guide/whats-happened.md @@ -0,0 +1,3 @@ +# 发生了什么？ + +本节将带你理解上一节中的 NoneBot 最小实例是如何对你发送的消息做出反应的。