📝 update guide docs

2025-10-31 06:56:39 +00:00 · 2020-12-01 12:24:14 +08:00
parent ad994f04fc
commit a085b47eac
6 changed files with 76 additions and 83 deletions
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -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 通信方式
 - 支持多个机器人账号负载均衡
--- 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
+```
+
 插件通常有两种形式，下面分别介绍

 ## 单文件形式
--- 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
 ```

-这将创建默认的目录结构
-
 <!-- prettier-ignore-start -->
 :::vue
 AweSome-Bot
--- 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
+  }
 }
 ```

--- 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]
-```
--- a/docs/guide/loading-a-plugin.md
+++ b/docs/guide/loading-a-plugin.md
@@ -76,8 +76,6 @@ if __name__ == "__main__":

 ## 子插件(嵌套插件)

-<!-- TODO: 子插件 -->
-
 在插件中同样可以加载子插件，例如如下插件目录结构：

 <!-- prettier-ignore-start -->