mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-02-18 00:30:13 +08:00
📝 update guide docs
This commit is contained in:
yanyongyu
parent
ad994f04fc
commit
a085b47eac
@ -1,27 +1,30 @@
|
||||
# 概览
|
||||
|
||||
:::tip 提示
|
||||
<!-- :::tip 提示
|
||||
如果在阅读本文档时遇到难以理解的词汇，请随时查阅 [术语表](../glossary.md) 或使用 [Google 搜索](https://www.google.com/)。
|
||||
:::
|
||||
::: -->
|
||||
|
||||
:::tip 提示
|
||||
初次使用时可能会觉得这里的概览过于枯燥，可以先简单略读之后直接前往 [安装](./installation.md) 查看安装方法，并进行后续的基础使用教程。
|
||||
:::
|
||||
|
||||
NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的消息进行解析和处理，并以插件化的形式，分发给消息所对应的命令处理器和自然语言处理器，来完成具体的功能。
|
||||
## 简介
|
||||
|
||||
除了起到解析消息的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制，尤其对于命令处理器，它更是提供了完善且易用的会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。
|
||||
NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的事件进行解析和处理，并以插件化的形式，按优先级分发给事件所对应的事件响应器，来完成具体的功能。
|
||||
|
||||
目前 NoneBot2 在 [FastAPI](https://fastapi.tiangolo.com/) 的基础上封装了与 [CQHTTP(OneBot) 协议](http://cqhttp.cc/)插件的网络交互。
|
||||
除了起到解析事件的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制。对于命令处理，它更是提供了完善且易用的会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。
|
||||
|
||||
得益于 Python 的 [asyncio](https://docs.python.org/3/library/asyncio.html) 机制，NoneBot 处理消息的吞吐量有了很大的保障，再配合 WebSocket 通信方式（也是最建议的通信方式），NoneBot 的性能可以达到 HTTP 通信方式的两倍以上，相较于传统同步 I/O 的 HTTP 通信，更是有质的飞跃。
|
||||
得益于 Python 的 [asyncio](https://docs.python.org/3/library/asyncio.html) 机制，NoneBot 处理事件的吞吐量有了很大的保障，再配合 WebSocket 通信方式（也是最建议的通信方式），NoneBot 的性能可以达到 HTTP 通信方式的两倍以上，相较于传统同步 I/O 的 HTTP 通信，更是有质的飞跃。
|
||||
|
||||
需要注意的是，NoneBot 仅支持 Python 3.7+ 及 CQHTTP(OneBot) 插件 v11+。
|
||||
需要注意的是，NoneBot 仅支持 **Python 3.7+**
|
||||
|
||||
## 特色
|
||||
|
||||
- 提供直观的测试前端
|
||||
NoneBot2 的驱动框架 `Driver` 以及通信协议 `Adapter` 均可**自定义**，并且可以作为插件进行**替换/添加**！
|
||||
|
||||
- 提供使用简易的脚手架
|
||||
- 提供丰富的官方插件
|
||||
- 提供可添加/替换的驱动以及协议选项
|
||||
- 基于异步 I/O
|
||||
- 同时支持 HTTP 和反向 WebSocket 通信方式
|
||||
- 支持多个机器人账号负载均衡
|
||||
|
||||
@ -2,6 +2,12 @@
|
||||
|
||||
如果之前使用 `nb-cli` 生成了项目结构，那我们已经有了一个空的插件目录 `Awesome-Bot/awesome_bot/plugins`，并且它已在 `bot.py` 中被加载，我们现在可以开始创建插件了！
|
||||
|
||||
使用 `nb-cli` 创建包形式插件，或自行创建文件(夹)
|
||||
|
||||
```bash
|
||||
nb plugin new
|
||||
```
|
||||
|
||||
插件通常有两种形式，下面分别介绍
|
||||
|
||||
## 单文件形式
|
||||
|
||||
@ -4,16 +4,12 @@
|
||||
|
||||
## 目录结构
|
||||
|
||||
首先，我们可以使用 `nb-cli` 或者自行创建项目目录：
|
||||
首先，我们可以使用 `nb-cli` 或者自行创建完整的项目目录：
|
||||
|
||||
```bash
|
||||
pip install nonebot2[cli]
|
||||
# pip install nb-cli
|
||||
nb create
|
||||
```
|
||||
|
||||
这将创建默认的目录结构
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
:::vue
|
||||
AweSome-Bot
|
||||
|
||||
@ -4,7 +4,15 @@
|
||||
|
||||
## 最小实例
|
||||
|
||||
使用你最熟悉的编辑器或 IDE，创建一个名为 `bot.py` 的文件，内容如下：
|
||||
如果你已经按照推荐方式安装了 `nb-cli`，使用脚手架创建一个空项目：
|
||||
|
||||
```bash
|
||||
nb create
|
||||
```
|
||||
|
||||
根据脚手架引导，将在当前目录下创建一个项目目录，项目目录内包含 `bot.py`。
|
||||
|
||||
如果未安装 `nb-cli`，使用你最熟悉的编辑器或 IDE，创建一个名为 `bot.py` 的文件，内容如下：
|
||||
|
||||
```python{3,4,7}
|
||||
import nonebot
|
||||
@ -16,26 +24,30 @@ if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
这几行高亮代码将依次：
|
||||
## 解读
|
||||
|
||||
1. 使用默认配置初始化 NoneBot 包
|
||||
在上方 `bot.py` 中，这几行高亮代码将依次：
|
||||
|
||||
1. 使用默认配置初始化 NoneBot
|
||||
2. 加载 NoneBot 内置的插件
|
||||
3. 在地址 `127.0.0.1:8080` 运行 NoneBot
|
||||
|
||||
在命令行使用如下命令即可运行这个 NoneBot 实例：
|
||||
|
||||
```bash
|
||||
# nb-cli
|
||||
nb run
|
||||
# 其他
|
||||
python bot.py
|
||||
```
|
||||
|
||||
运行后会产生如下日志：
|
||||
|
||||
```default
|
||||
```plain
|
||||
09-14 21:02:00 [INFO] nonebot | Succeeded to import "nonebot.plugins.base"
|
||||
09-14 21:02:00 [INFO] nonebot | Running NoneBot...
|
||||
09-14 21:02:00 [INFO] uvicorn | Started server process [1234]
|
||||
09-14 21:02:00 [INFO] uvicorn | Waiting for application startup.
|
||||
09-14 21:02:00 [INFO] nonebot | Scheduler Started
|
||||
09-14 21:02:00 [INFO] uvicorn | Application startup complete.
|
||||
09-14 21:02:00 [INFO] uvicorn | Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
|
||||
```
|
||||
@ -50,19 +62,19 @@ python bot.py
|
||||
|
||||
QQ 协议端举例:
|
||||
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [cqhttp-mirai](https://github.com/yyuueexxiinngg/cqhttp-mirai)
|
||||
- [cqhttp-mirai-embedded](https://github.com/yyuueexxiinngg/cqhttp-mirai/tree/embedded)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [Mirai Native](https://github.com/iTXTech/mirai-native) + [CQHTTP](https://github.com/richardchien/coolq-http-api)
|
||||
- [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) (基于 [MiraiGo](https://github.com/Mrs4s/MiraiGo))
|
||||
- [cqhttp-mirai-embedded](https://github.com/yyuueexxiinngg/cqhttp-mirai/tree/embedded)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [cqhttp-mirai](https://github.com/yyuueexxiinngg/cqhttp-mirai)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [Mirai Native](https://github.com/iTXTech/mirai-native) + [CQHTTP](https://github.com/richardchien/coolq-http-api)
|
||||
- [OICQ-http-api](https://github.com/takayama-lily/onebot) (基于 [OICQ](https://github.com/takayama-lily/oicq))
|
||||
|
||||
这里以 [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) 为例
|
||||
|
||||
1. 下载 go-cqhttp 对应平台的 release 文件
|
||||
2. 双击 exe 文件或者使用 `./go-cqhttp` 启动
|
||||
1. 下载 go-cqhttp 对应平台的 release 文件，[点此前往](https://github.com/Mrs4s/go-cqhttp/releases)
|
||||
2. 运行 exe 文件或者使用 `./go-cqhttp` 启动
|
||||
3. 生成默认配置文件并修改默认配置
|
||||
|
||||
```json{2,3,30-31}
|
||||
```json{2,3,35-36,42}
|
||||
{
|
||||
"uin": 你的QQ号,
|
||||
"password": "你的密码",
|
||||
@ -75,6 +87,11 @@ QQ 协议端举例:
|
||||
"relogin_delay": 3,
|
||||
"max_relogin_times": 0
|
||||
},
|
||||
"_rate_limit": {
|
||||
"enabled": false,
|
||||
"frequency": 0,
|
||||
"bucket_size": 0
|
||||
},
|
||||
"ignore_invalid_cqcode": false,
|
||||
"force_fragmented": true,
|
||||
"heartbeat_interval": 0,
|
||||
@ -99,9 +116,16 @@ QQ 协议端举例:
|
||||
"reverse_reconnect_interval": 3000
|
||||
}
|
||||
],
|
||||
"post_message_format": "string",
|
||||
"post_message_format": "array",
|
||||
"use_sso_address": false,
|
||||
"debug": false,
|
||||
"log_level": ""
|
||||
"log_level": "",
|
||||
"web_ui": {
|
||||
"enabled": true,
|
||||
"host": "0.0.0.0",
|
||||
"web_ui_port": 9999,
|
||||
"web_input": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -6,14 +6,34 @@
|
||||
请确保你的 Python 版本 >= 3.7。
|
||||
:::
|
||||
|
||||
:::warning 注意
|
||||
请在安装 nonebot2 之前卸载 nonebot 1.x
|
||||
|
||||
```bash
|
||||
pip uninstall nonebot
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 通过脚手架安装(推荐安装方式)
|
||||
|
||||
1. (可选)使用你喜欢的 Python 环境管理工具创建新的虚拟环境。
|
||||
2. 使用 `pip` (或其他) 安装 NoneBot 脚手架。
|
||||
|
||||
```bash
|
||||
pip install nb-cli
|
||||
```
|
||||
|
||||
### 不使用脚手架(纯净安装)
|
||||
|
||||
```bash
|
||||
# poetry
|
||||
poetry add nonebot2
|
||||
# pip
|
||||
pip install nonebot2
|
||||
```
|
||||
|
||||
如果你需要使用最新的（可能尚未发布的）特性，可以直接从 GitHub 仓库安装：
|
||||
如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：
|
||||
|
||||
```bash
|
||||
# master
|
||||
@ -30,57 +50,3 @@ cd nonebot2
|
||||
poetry install --no-dev # 推荐
|
||||
pip install . # 不推荐
|
||||
```
|
||||
|
||||
## 额外依赖
|
||||
|
||||
### APScheduler
|
||||
|
||||
A task scheduling library for Python.
|
||||
|
||||
可用于计划任务，后台执行任务等
|
||||
|
||||
```bash
|
||||
pip install nonebot2[scheduler]
|
||||
poetry add nonebot2[scheduler]
|
||||
```
|
||||
|
||||
[](https://github.com/agronholm/apscheduler)
|
||||
|
||||
|
||||
### NoneBot-Test
|
||||
|
||||
A test frontend for nonebot2.
|
||||
|
||||
通过前端展示 nonebot 已加载的插件以及运行状态，同时可以用于模拟发送事件测试机器人
|
||||
|
||||
```bash
|
||||
pip install nonebot2[test]
|
||||
poetry add nonebot2[test]
|
||||
```
|
||||
|
||||
[](https://github.com/nonebot/nonebot-test)
|
||||
|
||||
### CLI
|
||||
|
||||
CLI for nonebot2.
|
||||
|
||||
一个多功能脚手架
|
||||
|
||||
```bash
|
||||
pip install nonebot2[cli]
|
||||
poetry add nonebot2[cli]
|
||||
```
|
||||
|
||||
[](https://github.com/yanyongyu/nb-cli)
|
||||
|
||||
### 我全都要
|
||||
|
||||
```bash
|
||||
pip install nonebot2[full]
|
||||
poetry add nonebot2[full]
|
||||
```
|
||||
|
||||
```bash
|
||||
pip install nonebot2[cli,scheduler]
|
||||
poetry add nonebot2[cli,scheduler]
|
||||
```
|
||||
|
||||
@ -76,8 +76,6 @@ if __name__ == "__main__":
|
||||
|
||||
## 子插件(嵌套插件)
|
||||
|
||||
<!-- TODO: 子插件 -->
|
||||
|
||||
在插件中同样可以加载子插件，例如如下插件目录结构：
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user