diff --git a/docs/guide/README.md b/docs/guide/README.md index cacb58ac..4326ac1b 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,27 +1,30 @@ # 概览 -:::tip 提示 + :::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 通信方式 - 支持多个机器人账号负载均衡 diff --git a/docs/guide/creating-a-plugin.md b/docs/guide/creating-a-plugin.md index fe52a25d..0a6678db 100644 --- a/docs/guide/creating-a-plugin.md +++ b/docs/guide/creating-a-plugin.md @@ -2,6 +2,12 @@ 如果之前使用 `nb-cli` 生成了项目结构，那我们已经有了一个空的插件目录 `Awesome-Bot/awesome_bot/plugins`，并且它已在 `bot.py` 中被加载，我们现在可以开始创建插件了！ +使用 `nb-cli` 创建包形式插件，或自行创建文件(夹) + +```bash +nb plugin new +``` + 插件通常有两种形式，下面分别介绍 ## 单文件形式 diff --git a/docs/guide/creating-a-project.md b/docs/guide/creating-a-project.md index 74cdb24a..b8ac3b77 100644 --- a/docs/guide/creating-a-project.md +++ b/docs/guide/creating-a-project.md @@ -4,16 +4,12 @@ ## 目录结构 -首先，我们可以使用 `nb-cli` 或者自行创建项目目录： +首先，我们可以使用 `nb-cli` 或者自行创建完整的项目目录： ```bash -pip install nonebot2[cli] -# pip install nb-cli nb create ``` -这将创建默认的目录结构 - :::vue AweSome-Bot diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 5adf2f75..b1708b22 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -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 + } } ``` diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 2b54eae1..c1601dad 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -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] -``` - -[![apscheduler](https://img.shields.io/github/stars/agronholm/apscheduler?style=social)](https://github.com/agronholm/apscheduler) - - -### NoneBot-Test - -A test frontend for nonebot2. - -通过前端展示 nonebot 已加载的插件以及运行状态，同时可以用于模拟发送事件测试机器人 - -```bash -pip install nonebot2[test] -poetry add nonebot2[test] -``` - -[![nonebot-test](https://img.shields.io/github/stars/nonebot/nonebot-test?style=social)](https://github.com/nonebot/nonebot-test) - -### CLI - -CLI for nonebot2. - -一个多功能脚手架 - -```bash -pip install nonebot2[cli] -poetry add nonebot2[cli] -``` - -[![nb-cli](https://img.shields.io/github/stars/nonebot/nb-cli?style=social)](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] -``` diff --git a/docs/guide/loading-a-plugin.md b/docs/guide/loading-a-plugin.md index 2a3016d5..b0eaf7d7 100644 --- a/docs/guide/loading-a-plugin.md +++ b/docs/guide/loading-a-plugin.md @@ -76,8 +76,6 @@ if __name__ == "__main__": ## 子插件(嵌套插件) - - 在插件中同样可以加载子插件，例如如下插件目录结构：