From d5ac3c8462b4321b397d37ded7e8069e4b50c90f Mon Sep 17 00:00:00 2001 From: Richard Chien Date: Tue, 14 Aug 2018 21:09:09 +0800 Subject: [PATCH] Update docs --- docs/.vuepress/config.js | 18 ++++++++-- docs/README.md | 8 ++--- docs/glossary.md | 69 ++++++++++++++++++++++++++++++++++++++ docs/guide/README.md | 26 ++++++++++++-- docs/guide/installation.md | 12 ++++--- 5 files changed, 120 insertions(+), 13 deletions(-) create mode 100644 docs/glossary.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 2afb0642..89a334d3 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -1,20 +1,32 @@ module.exports = { title: 'NoneBot', description: '基于酷 Q 的 Python 异步 QQ 机器人框架', + serviceWorker: true, + markdown: { + lineNumbers: true + }, themeConfig: { repo: 'richardchien/none-bot', docsDir: 'docs', editLinks: true, editLinkText: '在 GitHub 上编辑此页', lastUpdated: '上次更新', + activeHeaderLinks: false, nav: [ { text: '指南', link: '/guide/' }, + { text: '术语表', link: '/glossary' }, ], sidebar: { '/guide/': [ - '', - 'installation', - 'getting-started', + { + title: '指南', + collapsable: false, + children: [ + '', + 'installation', + 'getting-started', + ] + } ] }, } diff --git a/docs/README.md b/docs/README.md index 5ac3368e..91a75c41 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,11 +3,11 @@ home: true actionText: 即刻开始 actionLink: /guide/ features: -- title: 简洁的 API - details: 提供极其简洁易懂的 API，使你可以毫无压力地开始验证你的绝佳创意，只需编写最少量的代码。 +- title: 简洁 + details: 提供极其简洁易懂的 API，使你可以毫无压力地开始验证你的绝佳创意，只需编写最少量的代码，即可实现丰富的功能。 - title: 易于扩展 - details: 精心设计的消息和事件处理流程及强大的 API 使得你可以很方便地从原型扩展出具有丰富功能的聊天机器人。 + details: 精心设计的消息处理流程及强大的 API 使得你可以很方便地将最简单的原型变为具有大量实用功能的完整聊天机器人，并持续保证扩展性。 - title: 高性能 - details: 基于时下最流行的 asyncio 模块，使用 WebSocket 进行通信，以获得极高的性能；同时，支持使用多个机器人账号来负载均衡用户消息，减少业务宕机的可能。 + details: 基于时下流行的 asyncio 模块，利用 WebSocket 进行通信，以获得极高的性能；同时，支持使用多个机器人账号来负载均衡用户消息，减少业务宕机的可能。 footer: MIT Licensed | Copyright © 2018 Richard Chien --- diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..d2cd4357 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,69 @@ +--- +sidebar: auto +--- + +# 术语表 + +## 酷 Q + +[酷 Q](https://cqp.cc) 是一个易语言编写的 QQ 机器人平台，其本身没有任何具体的功能，只是负责实现 QQ 协议，并以 DLL 导出函数的形式向插件提供 API 和事件上报。 + +## CoolQ HTTP API 插件 + +[CoolQ HTTP API 插件](https://github.com/richardchien/coolq-http-api) 是酷 Q 的一个第三方插件，用于将酷 Q 所提供的所有 DLL 接口转换为 HTTP 或 WebSocket 的 web 形式，从而使利用任意语言编写酷 Q 插件成为可能。 + +有时被称为 cqhttp、CQHttp、酷 Q HTTP API 等。 + +## aiocqhttp + +[aiocqhttp](https://github.com/richardchien/python-aiocqhttp)（或称 python-aiocqhttp）是 CoolQ HTTP API 插件的一个 Python 异步 SDK，基于 asyncio，在 Quart 的基础上封装了与 CoolQ HTTP API 插件的网络交互。 + +## asyncio + +[asyncio](https://docs.python.org/3/library/asyncio.html) 是 Python 3.4 引入的一个模块，实际上它是 Python 中整个基于事件循环（Event Loop）的异步 I/O 编程机制。 + +## Quart + +[Quart](https://pgjones.gitlab.io/quart/) 是一个基于异步 I/O 的 web 框架，支持 HTTP 和 WebSocket，是 aiocqhttp 的基础。 + +## 异步 I/O + +有时直接称为「异步」，是一种对 I/O 操作的处理方式，它可以在单个线程内实现非阻塞 I/O，即在 I/O 操作进行时，仍可以调度程序的其它部分。在 Python 3.4+ 中，asyncio 模块提供的异步 I/O 调度的基本单位是「协程（Coroutine）」，通过 `await` 关键字即可在进行 I/O 操作时将程序的执行权转移给其它协程，直到 I/O 结束再次被唤起。 + +## 通信方式 + +CoolQ HTTP API 插件中的一个术语，表示其与通过 web 技术编写的酷 Q 插件之间通信的手段。 + +目前 CoolQ HTTP API 插件支持 HTTP、WebSocket、反向 WebSocket 三种通信方式，见 [通信方式](https://cqhttp.cc/docs/#/CommunicationMethods)，NoneBot 支持其中的 HTTP 和反向 WebSocket。 + +## 命令 + +NoneBot 主要支持的插件形式之一，主要用于处理符合特定格式的、意图明确的用户消息，例如： + +``` +天气 南京 明天 +/echo 喵喵喵 +note.add 这是一条笔记 +``` + +上面的每行都符合一种固定的格式，消息的第一个空格左边是命令的名字（可能包含命令的起始符和分隔符），右边是命令所需的参数，可能以空格分隔，或是完全作为单个参数。 + +你可以将命令理解为操作系统中的命令行程序，NoneBot 执行命令就像在 Shell 中运行程序一样： + +```bash +docker run hello-world +``` + +## 命令处理器 + +或称为「命令处理函数」，有时也简称为「命令」，是 NoneBot 插件中实际用于实现某个命令功能的函数。 + +通过 `none.on_command` 装饰器可以将一个函数注册为命令处理器，例如： + +```python +from none import on_command + +@on_command('echo') +async def echo(session): + pass +``` diff --git a/docs/guide/README.md b/docs/guide/README.md index b5be8648..792c8839 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,7 +1,29 @@ # 介绍 -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 机器人框架，它会对 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) 查看安装方法，并进行后续的基础使用教程。 +::: ## NoneBot 如何工作？ -## 特性 +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` 对象所提供的数据，在插件的处理函数中实现所需的功能。 + +## 特点 diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 31addbb0..9bccca53 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -12,7 +12,7 @@ pip install none-bot ``` -如果你需要使用最新的（可能还没发布的）特性，可以克隆 Git 仓库后手动安装： +如果你需要使用最新的（可能尚未发布的）特性，可以克隆 Git 仓库后手动安装： ```bash git clone https://github.com/richardchien/none-bot.git @@ -24,13 +24,17 @@ python setup.py install ## 酷 Q -前往酷 Q 官方论坛的 [版本发布](https://cqp.cc/b/news) 页面根据需要下载最新版本的酷 Q Air 或 Pro，解压后启动 `CQA.exe` 或 `CQP.exe` 完成新手教程。 +前往酷 Q 官方论坛的 [版本发布](https://cqp.cc/b/news) 页面根据需要下载最新版本的酷 Q Air 或 Pro，解压后启动 `CQA.exe` 或 `CQP.exe` 并登录 QQ 机器人账号。 -如果你使用 Linux 或 macOS，可以使用版本发布页中酷 Q 官方提供的 Docker 镜像，或直接跳至下一个标题，使用 CoolQ HTTP API 插件官方提供的 Docker 镜像。 +如果你的操作系统是 Linux 或 macOS，可以使用版本发布页中酷 Q 官方提供的 Docker 镜像，也可以直接跳至下一个标题，使用 CoolQ HTTP API 插件官方提供的 Docker 镜像。 + +::: tip 提示 +如果这是你第一次使用酷 Q，建议完成它自带的新手教程，从而对酷 Q 的运行机制有所了解。 +::: ## CoolQ HTTP API 插件 -前往 [CoolQ HTTP API 插件官方文档](https://cqhttp.cc/docs/)，按照其教程安装插件。安装后，请先使用默认配置运行，查看酷 Q 日至窗口的输出，以确定插件的加载、配置的生成和读取、插件版本符合预期。 +前往 [CoolQ HTTP API 插件官方文档](https://cqhttp.cc/docs/)，按照其教程安装插件。安装后，请先使用默认配置运行，并查看酷 Q 日志窗口的输出，以确定插件的加载、配置的生成和读取、插件版本等符合预期。 ::: warning 注意 请确保你安装的插件版本 >= 4.2，通常建议插件在大版本内尽量及时升级至最新版本。