🔖 Release 2.1.0

nonebot · Sep 10, 2023 · 1e8c2cf · 1e8c2cf
1 parent 5ce0238
commit 1e8c2cf
Show file tree

Hide file tree

Showing 90 changed files with 16,829 additions and 2 deletions.
diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md
@@ -5,7 +5,7 @@ toc_max_heading_level: 2
 
 # 更新日志
 
-## 最近更新
+## v2.1.0
 
 ### 🚀 新功能
 

diff --git a/website/versioned_docs/version-2.1.0/README.md b/website/versioned_docs/version-2.1.0/README.md
@@ -0,0 +1,49 @@
+---
+sidebar_position: 0
+id: index
+slug: /
+---
+
+# 概览
+
+NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架（下称 NoneBot），它基于 Python 的类型注解和异步优先特性（兼容同步），能够为你的需求实现提供便捷灵活的支持。同时，NoneBot 拥有大量的开发者为其开发插件，用户无需编写任何代码，仅需完成环境配置及插件安装，就可以正常使用 NoneBot。
+
+需要注意的是，NoneBot 仅支持 **Python 3.8 以上版本**
+
+## 特色
+
+### 异步优先
+
+NoneBot 基于 Python [asyncio](https://docs.python.org/zh-cn/3/library/asyncio.html) 编写，并在异步机制的基础上进行了一定程度的同步函数兼容。
+
+### 完整的类型注解
+
+NoneBot 参考 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 等 PEP 完整实现了类型注解，通过 Pyright（Pylance） 检查。配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中（[编辑器支持](./editor-support)）。
+
+### 开箱即用
+
+NoneBot 提供了使用便捷、具有交互式功能的命令行工具--`nb-cli`，使得用户初次接触 NoneBot 时更容易上手。使用方法请阅读本文档[指南](./quick-start.mdx)以及 [CLI 文档](https://cli.nonebot.dev/)。
+
+### 插件系统
+
+插件系统是 NoneBot 的核心，通过它可以实现机器人的模块化以及功能扩展，便于维护和管理。
+
+### 依赖注入系统
+
+NoneBot 采用了一套自行定义的依赖注入系统，可以让事件的处理过程更加的简洁、清晰，增加代码的可读性，减少代码冗余。
+
+#### 什么是依赖注入
+
+[**『依赖注入』**](https://zh.m.wikipedia.org/wiki/%E6%8E%A7%E5%88%B6%E5%8F%8D%E8%BD%AC)意思是，在编程中，有一种方法可以让你的代码声明它工作和使用所需要的东西，即**『依赖』**。
+
+系统（在这里是指 NoneBot）将负责做任何需要的事情，为你的代码提供这些必要依赖（即**『注入』**依赖性）
+
+这在你有以下情形的需求时非常有用：
+
+- 这部分代码拥有共享的逻辑（同样的代码逻辑多次重复）
+- 共享数据库以及网络请求连接会话
+  - 比如 `httpx.AsyncClient`、`aiohttp.ClientSession` 和 `sqlalchemy.Session`
+- 机器人用户权限检查以及认证
+- 还有更多...
+
+它在完成上述工作的同时，还能尽量减少代码的耦合和重复
diff --git a/website/versioned_docs/version-2.1.0/advanced/adapter.md b/website/versioned_docs/version-2.1.0/advanced/adapter.md
@@ -0,0 +1,161 @@
+---
+sidebar_position: 1
+description: 注册适配器与指定平台交互
+
+options:
+  menu:
+    weight: 20
+    category: advanced
+---
+
+# 使用适配器
+
+适配器 (Adapter) 是机器人与平台交互的核心桥梁，它负责在驱动器和机器人插件之间转换与传递消息。
+
+## 适配器功能与组成
+
+适配器通常有两种功能，分别是**接收事件**和**调用平台接口**。其中，接收事件是指将驱动器收到的事件消息转换为 NoneBot 定义的事件模型，然后交由机器人插件处理；调用平台接口是指将机器人插件调用平台接口的数据转换为平台指定的格式，然后交由驱动器发送，并接收接口返回数据。
+
+为了实现这两种功能，适配器通常由四个部分组成：
+
+- **Adapter**：负责转换事件和调用接口，正确创建 Bot 对象并注册到 NoneBot 中。
+- **Bot**：负责存储平台机器人相关信息，并提供回复事件的方法。
+- **Event**：负责定义事件内容，以及事件主体对象。
+- **Message**：负责正确序列化消息，以便机器人插件处理。
+
+## 注册适配器
+
+在使用适配器之前，我们需要先将适配器注册到驱动器中，这样适配器就可以通过驱动器接收事件和调用接口了。我们以 Console 适配器为例，来看看如何注册适配器：
+
+```python {2,5} title=bot.py
+import nonebot
+from nonebot.adapters.console import Adapter
+
+driver = nonebot.get_driver()
+driver.register_adapter(Adapter)
+```
+
+我们首先需要从适配器模块中导入所需要的适配器类，然后通过驱动器的 `register_adapter` 方法将适配器注册到驱动器中即可。如果我们需要多平台支持，可以多次调用 `register_adapter` 方法来注册多个适配器。
+
+## 获取已注册的适配器
+
+NoneBot 提供了 `get_adapter` 方法来获取已注册的适配器，我们可以通过适配器的名称或类型来获取指定的适配器实例：
+
+```python
+import nonebot
+from nonebot.adapters.console import Adapter
+
+adapters = nonebot.get_adapters()
+console_adapter = nonebot.get_adapter(Adapter)
+console_adapter = nonebot.get_adapter(Adapter.get_name())
+```
+
+## 获取 Bot 对象
+
+当前所有适配器已连接的 Bot 对象可以通过 `get_bots` 方法获取，这是一个以机器人 ID 为键的字典：
+
+```python
+import nonebot
+
+bots = nonebot.get_bots()
+```
+
+我们也可以通过 `get_bot` 方法获取指定 ID 的 Bot 对象。如果省略 ID 参数，将会返回所有 Bot 中的第一个：
+
+```python
+import nonebot
+
+bot = nonebot.get_bot("bot_id")
+```
+
+如果需要获取指定适配器连接的 Bot 对象，我们可以通过适配器的 `bots` 属性获取，这也是一个以机器人 ID 为键的字典：
+
+```python
+import nonebot
+from nonebot.adapters.console import Adapter
+
+console_adapter = nonebot.get_adapter(Adapter)
+bots = console_adapter.bots
+```
+
+Bot 对象都具有一个 `self_id` 属性，它是机器人的唯一 ID，由适配器填写，通常为机器人的帐号 ID 或者 APP ID。
+
+## 获取事件通用信息
+
+适配器的所有事件模型均继承自 `Event` 基类，在[事件类型与重载](../appendices/overload.md)一节中，我们也提到了如何使用基类抽象方法来获取事件通用信息。基类能提供如下信息：
+
+### 事件类型
+
+事件类型通常为 `meta_event`、`message`、`notice`、`request`。
+
+```python
+type: str = event.get_type()
+```
+
+### 事件名称
+
+事件名称由适配器定义，通常用于日志记录。
+
+```python
+name: str = event.get_event_name()
+```
+
+### 事件描述
+
+事件描述由适配器定义，通常用于日志记录。
+
+```python
+description: str = event.get_event_description()
+```
+
+### 事件日志字符串
+
+事件日志字符串由事件名称和事件描述组成，用于日志记录。
+
+```python
+log: str = event.get_log_string()
+```
+
+### 事件主体 ID
+
+事件主体 ID 通常为机器人用户 ID。
+
+```python
+user_id: str = event.get_user_id()
+```
+
+### 事件会话 ID
+
+事件会话 ID 通常为机器人用户 ID 与群聊/频道 ID 组合而成。
+
+```python
+session_id: str = event.get_session_id()
+```
+
+### 事件消息
+
+如果事件包含消息，则可以通过该方法获取，否则会产生异常。
+
+```python
+message: Message = event.get_message()
+```
+
+### 事件纯文本消息
+
+通常为事件消息的纯文本内容，如果事件不包含消息，则会产生异常。
+
+```python
+text: str = event.get_plaintext()
+```
+
+### 事件是否与机器人有关
+
+由适配器实现的判断，通常将事件目标主体为机器人、消息中包含“@机器人”或以“机器人的昵称”开始视为与机器人有关。
+
+```python
+is_tome: bool = event.is_tome()
+```
+
+## 更多
+
+官方支持的适配器和社区贡献的适配器均可在[商店](/store)中查看。如果你想要开发自己的适配器，可以参考[开发文档](../developer/adapter-writing.md)。欢迎通过商店发布你的适配器。