mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-07-27 16:21:28 +00:00
Replace "酷 Q" with "酷Q"
This commit is contained in:
Richard Chien
@ -8,19 +8,19 @@
|
||||
初次使用时可能会觉得这里的概览过于枯燥，可以先简单略读之后直接前往 [安装](/guide/installation.md) 查看安装方法，并进行后续的基础使用教程。
|
||||
:::
|
||||
|
||||
NoneBot 是一个基于 [酷 Q](https://cqp.cc/) 的 Python 异步 QQ 机器人框架，它会对 QQ 机器人收到的消息进行解析和处理，并以插件化的形式，分发给消息所对应的命令处理器和自然语言处理器，来完成具体的功能。
|
||||
NoneBot 是一个基于 [酷Q](https://cqp.cc/) 的 Python 异步 QQ 机器人框架，它会对 QQ 机器人收到的消息进行解析和处理，并以插件化的形式，分发给消息所对应的命令处理器和自然语言处理器，来完成具体的功能。
|
||||
|
||||
除了起到解析消息的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制，尤其对于命令处理器，它更是提供了完善且易用的会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。
|
||||
|
||||
NoneBot 在其底层与酷 Q 交互的部分使用 [python-aiocqhttp](https://github.com/richardchien/python-aiocqhttp) 库，后者是 [CoolQ HTTP API 插件](https://cqhttp.cc/) 的一个 Python 异步 SDK，在 [Quart](https://pgjones.gitlab.io/quart/) 的基础上封装了与 CoolQ HTTP API 插件的网络交互。
|
||||
NoneBot 在其底层与 酷Q 交互的部分使用 [python-aiocqhttp](https://github.com/richardchien/python-aiocqhttp) 库，后者是 [CoolQ HTTP API 插件](https://cqhttp.cc/) 的一个 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 仅支持 Python 3.6.1+ 及 CoolQ HTTP API 插件 v4.2+。
|
||||
|
||||
## 它如何工作？
|
||||
|
||||
NoneBot 的运行离不开酷 Q 和 CoolQ HTTP API 插件。酷 Q 扮演着「无头 QQ 客户端」的角色，它进行实际的消息、通知、请求的接收和发送，当酷 Q 收到消息时，它将这个消息包装为一个事件（通知和请求同理），并通过它自己的插件机制将事件传送给 CoolQ HTTP API 插件，后者再根据其配置中的 `post_url` 或 `ws_reverse_event_url` 等项来将事件发送至 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` 类型，以便处理。
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ async def tuling(session: CommandSession):
|
||||
reply = await call_tuling_api(session, message)
|
||||
if reply:
|
||||
# 如果调用图灵机器人成功，得到了回复，则转义之后发送给用户
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免酷 Q 将它们理解为 CQ 码
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免 酷Q 将它们理解为 CQ 码
|
||||
await session.send(escape(reply))
|
||||
else:
|
||||
# 如果调用失败，或者它返回的内容我们目前处理不了，发送无法获取图灵回复时的「表达」
|
||||
|
||||
@ -26,7 +26,7 @@ async def tuling(session: CommandSession):
|
||||
reply = await call_tuling_api(session, message)
|
||||
if reply:
|
||||
# 如果调用图灵机器人成功，得到了回复，则转义之后发送给用户
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免酷 Q 将它们理解为 CQ 码
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免 酷Q 将它们理解为 CQ 码
|
||||
await session.send(escape(reply))
|
||||
else:
|
||||
# 如果调用失败，或者它返回的内容我们目前处理不了，发送无法获取图灵回复时的「表达」
|
||||
|
||||
@ -26,7 +26,7 @@ async def tuling(session: CommandSession):
|
||||
reply = await call_tuling_api(session, message)
|
||||
if reply:
|
||||
# 如果调用图灵机器人成功，得到了回复，则转义之后发送给用户
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免酷 Q 将它们理解为 CQ 码
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免 酷Q 将它们理解为 CQ 码
|
||||
await session.send(escape(reply))
|
||||
else:
|
||||
# 如果调用失败，或者它返回的内容我们目前处理不了，发送无法获取图灵回复时的「表达」
|
||||
|
||||
@ -22,7 +22,7 @@ if __name__ == '__main__':
|
||||
3. 在地址 `127.0.0.1:8080` 运行 NoneBot
|
||||
|
||||
::: tip 提示
|
||||
这里 `nonebot.run()` 的参数 `host='127.0.0.1'` 表示让 NoneBot 监听本地环回地址，如果你的酷 Q 运行在非本机的其它位置，例如 Docker 容器内、局域网内的另一台机器上等，则这里需要修改 `host` 参数为希望让 CoolQ HTTP API 插件访问的 IP。如果不清楚该使用哪个 IP，或者希望本机的所有 IP 都被监听，可以使用 `0.0.0.0`。
|
||||
这里 `nonebot.run()` 的参数 `host='127.0.0.1'` 表示让 NoneBot 监听本地环回地址，如果你的 酷Q 运行在非本机的其它位置，例如 Docker 容器内、局域网内的另一台机器上等，则这里需要修改 `host` 参数为希望让 CoolQ HTTP API 插件访问的 IP。如果不清楚该使用哪个 IP，或者希望本机的所有 IP 都被监听，可以使用 `0.0.0.0`。
|
||||
:::
|
||||
|
||||
在命令行使用如下命令即可运行这个 NoneBot 实例：
|
||||
@ -33,9 +33,9 @@ python bot.py
|
||||
|
||||
## 配置 CoolQ HTTP API 插件
|
||||
|
||||
单纯运行 NoneBot 实例并不会产生任何效果，因为此刻酷 Q 这边还不知道 NoneBot 的存在，也就无法把消息发送给它，因此现在需要对 CoolQ HTTP API 插件做一个简单的配置来让它把消息等事件上报给 NoneBot。
|
||||
单纯运行 NoneBot 实例并不会产生任何效果，因为此刻 酷Q 这边还不知道 NoneBot 的存在，也就无法把消息发送给它，因此现在需要对 CoolQ HTTP API 插件做一个简单的配置来让它把消息等事件上报给 NoneBot。
|
||||
|
||||
如果你在之前已经按照 [安装](/guide/installation.md) 的建议使用默认配置运行了一次 CoolQ HTTP API 插件，此时酷 Q 的 `data\app\io.github.richardchien.coolqhttpapi\config\` 目录中应该已经有了一个名为 `<user-id>.json` 的文件（`<user-id>` 为你登录的 QQ 账号）。修改这个文件，**添加**如下配置项：
|
||||
如果你在之前已经按照 [安装](/guide/installation.md) 的建议使用默认配置运行了一次 CoolQ HTTP API 插件，此时 酷Q 的 `data\app\io.github.richardchien.coolqhttpapi\config\` 目录中应该已经有了一个名为 `<user-id>.json` 的文件（`<user-id>` 为你登录的 QQ 账号）。修改这个文件，**添加**如下配置项：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -47,10 +47,10 @@ python bot.py
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
这里的 `127.0.0.1:8080` 对应 `nonebot.run()` 中传入的 `host` 和 `port`，如果在 `nonebot.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/)）。
|
||||
这里的 `127.0.0.1:8080` 对应 `nonebot.run()` 中传入的 `host` 和 `port`，如果在 `nonebot.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，以使新的配置文件生效。
|
||||
修改之后，在 酷Q 的应用菜单中重启 CoolQ HTTP API 插件，或直接重启 酷Q，以使新的配置文件生效。
|
||||
|
||||
## 历史性的第一次对话
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
## NoneBot
|
||||
|
||||
::: warning 注意
|
||||
请确保你的 Python 版本 >= 3.6。
|
||||
请确保你的 Python 版本 >= 3.6.1。
|
||||
:::
|
||||
|
||||
可以使用 pip 安装已发布的最新版本：
|
||||
@ -22,19 +22,19 @@ python setup.py install
|
||||
|
||||
以上命令中的 `pip`、`python` 可能需要根据情况换成 `pip3`、`python3`。
|
||||
|
||||
## 酷 Q
|
||||
## 酷Q
|
||||
|
||||
前往酷 Q 官方论坛的 [版本发布](https://cqp.cc/b/news) 页面根据需要下载最新版本的酷 Q Air 或 Pro，解压后启动 `CQA.exe` 或 `CQP.exe` 并登录 QQ 机器人账号。
|
||||
前往 酷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 的运行机制有所了解。
|
||||
如果这是你第一次使用 酷Q，建议完成它自带的新手教程，从而对 酷Q 的运行机制有所了解。
|
||||
:::
|
||||
|
||||
## CoolQ HTTP API 插件
|
||||
|
||||
前往 [CoolQ HTTP API 插件官方文档](https://cqhttp.cc/docs/)，按照其教程安装插件。安装后，请先使用默认配置运行，并查看酷 Q 日志窗口的输出，以确定插件的加载、配置的生成和读取、插件版本等符合预期。
|
||||
前往 [CoolQ HTTP API 插件官方文档](https://cqhttp.cc/docs/)，按照其教程安装插件。安装后，请先使用默认配置运行，并查看 酷Q 日志窗口的输出，以确定插件的加载、配置的生成和读取、插件版本等符合预期。
|
||||
|
||||
::: warning 注意
|
||||
请确保你安装的插件版本 >= 4.2，通常建议插件在大版本内尽量及时升级至最新版本。
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 处理通知和请求
|
||||
|
||||
除了聊天消息，酷 Q 还提供了加群请求、加好友请求、出入群通知、管理员变动通知等很多其它事件，很多时候我们需要利用这些事件来实现群管功能，这也是 QQ 机器人除聊天之外的另一个很重要的应用之一。
|
||||
除了聊天消息，酷Q 还提供了加群请求、加好友请求、出入群通知、管理员变动通知等很多其它事件，很多时候我们需要利用这些事件来实现群管功能，这也是 QQ 机器人除聊天之外的另一个很重要的应用之一。
|
||||
|
||||
本章将介绍如何在插件中处理通知和请求。
|
||||
|
||||
|
||||
@ -49,7 +49,7 @@ async def tuling(session: CommandSession):
|
||||
reply = await call_tuling_api(session, message)
|
||||
if reply:
|
||||
# 如果调用图灵机器人成功，得到了回复，则转义之后发送给用户
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免酷 Q 将它们理解为 CQ 码
|
||||
# 转义会把消息中的某些特殊字符做转换，以避免 酷Q 将它们理解为 CQ 码
|
||||
await session.send(escape(reply))
|
||||
else:
|
||||
# 如果调用失败，或者它返回的内容我们目前处理不了，发送无法获取图灵回复时的「表达」
|
||||
@ -231,9 +231,9 @@ async def tuling(session: CommandSession):
|
||||
|
||||
### 消息转义
|
||||
|
||||
再看第 16 行，在调用 `session.send()` 之前先对 `reply` 调用了 `escape()`，这个 `escape()` 函数是 `aiocqhttp.message` 模块提供的，用于将字符串中的某些特殊字符进行转义。具体来说，这些特殊字符是酷 Q 看作是 CQ 码的一部分的那些字符，包括 `&`、`[`、`]`、`,`。
|
||||
再看第 16 行，在调用 `session.send()` 之前先对 `reply` 调用了 `escape()`，这个 `escape()` 函数是 `aiocqhttp.message` 模块提供的，用于将字符串中的某些特殊字符进行转义。具体来说，这些特殊字符是 酷Q 看作是 CQ 码的一部分的那些字符，包括 `&`、`[`、`]`、`,`。
|
||||
|
||||
CQ 码是酷 Q 用来表示非文本消息的一种表示方法，形如 `[CQ:image,file=ABC.jpg]`。具体的格式规则，请参考酷 Q 文档的 [CQ 码](https://d.cqp.me/Pro/CQ%E7%A0%81) 和 CoolQ HTTP API 插件文档的 [CQ 码](https://cqhttp.cc/docs/#/CQCode)。
|
||||
CQ 码是 酷Q 用来表示非文本消息的一种表示方法，形如 `[CQ:image,file=ABC.jpg]`。具体的格式规则，请参考 酷Q 文档的 [CQ 码](https://d.cqp.me/Pro/CQ%E7%A0%81) 和 CoolQ HTTP API 插件文档的 [CQ 码](https://cqhttp.cc/docs/#/CQCode)。
|
||||
|
||||
### 发送 Expression
|
||||
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
# 发生了什么？
|
||||
|
||||
上一章中我们已经运行了一个最小的 NoneBot 实例，在看着 QQ 机器人回复了自己的消息的同时，你可能想问，这是如何实现的？具体来说，NoneBot、CoolQ HTTP API 插件、酷 Q，这三者是如何协同工作的？本章将对这个问题做一个初步解答。
|
||||
上一章中我们已经运行了一个最小的 NoneBot 实例，在看着 QQ 机器人回复了自己的消息的同时，你可能想问，这是如何实现的？具体来说，NoneBot、CoolQ HTTP API 插件、酷Q，这三者是如何协同工作的？本章将对这个问题做一个初步解答。
|
||||
|
||||
::: tip 提示
|
||||
如果你已经有较丰富的 QQ 机器人开发经验，尤其是使用 CoolQ HTTP API 插件的经验，可以直接跳到 [NoneBot 出场](#nonebot-出场)。
|
||||
:::
|
||||
|
||||
## 一切从酷 Q 开始
|
||||
## 一切从 酷Q 开始
|
||||
|
||||
我们在 [概览](/guide/) 中提到过，酷 Q 扮演着「无头 QQ 客户端」的角色，一切的消息、通知、请求的发送和接收，最根本上都是由它来完成的，我们的最小 NoneBot 实例也不例外。
|
||||
我们在 [概览](/guide/) 中提到过，酷Q 扮演着「无头 QQ 客户端」的角色，一切的消息、通知、请求的发送和接收，最根本上都是由它来完成的，我们的最小 NoneBot 实例也不例外。
|
||||
|
||||
首先，我们向机器人发送的 `/echo 你好，世界` 进入腾讯的服务器，后者随后会把消息推送给酷 Q，就像推送给一个真正的 QQ 客户端一样。到这里，酷 Q 就已经收到了我们发送的消息了。
|
||||
首先，我们向机器人发送的 `/echo 你好，世界` 进入腾讯的服务器，后者随后会把消息推送给 酷Q，就像推送给一个真正的 QQ 客户端一样。到这里，酷Q 就已经收到了我们发送的消息了。
|
||||
|
||||
## 进入 CoolQ HTTP API 插件
|
||||
|
||||
酷 Q 在收到消息之后，按优先级依次将消息转交给已启用的各插件处理，在我们的例子中，只有一个插件，就是 CoolQ HTTP API 插件。
|
||||
酷Q 在收到消息之后，按优先级依次将消息转交给已启用的各插件处理，在我们的例子中，只有一个插件，就是 CoolQ HTTP API 插件。
|
||||
|
||||
CoolQ HTTP API 插件收到消息后，会将其包装为一个统一的事件格式，并对消息内容进行一个初步的处理，例如编码转换、数组化、CQ 码增强等，这里的细节目前为止不需要完全明白，在需要的时候，可以去参考 CoolQ HTTP API 插件的 [文档](https://cqhttp.cc/docs/)。
|
||||
|
||||
@ -79,10 +79,10 @@ async def echo(session: CommandSession):
|
||||
|
||||
## 再次进入 CoolQ HTTP API 插件
|
||||
|
||||
命令处理器在调用 `session.send()` 之后，NoneBot 把消息内容发送给了 CoolQ HTTP API 插件那边已连接的反向 WebSocket 客户端，同时告诉它要把消息发送到和收到消息相同的地方（即接收到消息所在的群组、讨论组或私聊）。CoolQ HTTP API 插件明白了 NoneBot 的要求之后，会对消息做一些必要的处理，然后按照指示调用酷 Q 提供的相应接口。
|
||||
命令处理器在调用 `session.send()` 之后，NoneBot 把消息内容发送给了 CoolQ HTTP API 插件那边已连接的反向 WebSocket 客户端，同时告诉它要把消息发送到和收到消息相同的地方（即接收到消息所在的群组、讨论组或私聊）。CoolQ HTTP API 插件明白了 NoneBot 的要求之后，会对消息做一些必要的处理，然后按照指示调用 酷Q 提供的相应接口。
|
||||
|
||||
## 一切又在酷 Q 结束
|
||||
## 一切又在 酷Q 结束
|
||||
|
||||
酷 Q 收到 CoolQ HTTP API 插件的接口调用之后，将消息内容发送给腾讯的服务器，就像一个真正的 QQ 客户端一样，于是你就收到了 QQ 机器人发来的消息了。
|
||||
酷Q 收到 CoolQ HTTP API 插件的接口调用之后，将消息内容发送给腾讯的服务器，就像一个真正的 QQ 客户端一样，于是你就收到了 QQ 机器人发来的消息了。
|
||||
|
||||
至此，我们已经理清楚了第一次对话中每一步到底都发生了些什么，以及 NoneBot 如何解析消息并调用到相应的命令处理器来进行回复。下面的几章中我们将一步一步地对最小 NoneBot 实例进行扩充，以实现一些非常棒的功能！
|
||||
|
||||
Reference in New Issue
Block a user