docs: 更新文档内容，简化语言并修正格式
- 简化插件开发指南中的描述，移除冗余内容 - 调整部署文档中的Python版本说明 - 优化最佳实践文档的措辞和格式 - 更新性能优化文档，删除不准确的数据 - 重构核心概念文档，使用更简洁的语言 - 修正README中的项目描述和技术栈说明 - 更新快速上手文档，简化安装步骤 - 调整事件流转文档的描述方式 - 简化架构文档内容 - 更新指令处理文档，添加参数注入示例 - 优化单例管理器文档的表述
This commit is contained in:
@@ -1,62 +1,55 @@
|
||||
# 核心架构
|
||||
# 骨架
|
||||
|
||||
别把 NEO Bot 当成那些写着玩的玩具。这玩意的设计目标就一个：**又快又稳**。
|
||||
Neobot是面向内部开发者的，我会开源，但是写的很烂。。。
|
||||
|
||||
不搞虚头巴脑的，只上最实在的。
|
||||
|
||||
## 1. 运行时架构
|
||||
## 1. 动力核心
|
||||
|
||||
### Python 3.14 + JIT
|
||||
我们直接上了 Python 3.14，默认就开 JIT (即时编译)。
|
||||
* **啥原理**: JIT 会在代码跑的时候，把那些一遍遍执行的热点代码直接编译成机器码，下次再跑就不用解释器了，快得飞起。
|
||||
* **有啥用**: 正则匹配、数据处理这种吃 CPU 的活儿，效果特别明显。
|
||||
镀铬酸钾创项目的时候用的 Python 3.14 3.14兼容JIT，那就这样吧
|
||||
* **何原理**: 提前编译了源代码，
|
||||
* **何用途**: 密集CPU运算能提升一些
|
||||
|
||||
### Mypyc 编译 (AOT)
|
||||
光 JIT 还不够爽。核心模块（`core/ws.py`, `core/managers/*.py`）我们都用 Mypyc 编译成了 C 扩展。
|
||||
* **啥原理**: Mypyc 直接把带类型提示的 Python 代码翻译成 C，再编译成二进制文件。
|
||||
* **有啥用**: 核心代码跑起来跟 C 差不多快，还能绕开 GIL。
|
||||
光 JIT 还不够。。核心模块（`core/ws.py`, `core/managers/*.py`）我编译成了C扩展
|
||||
* **何原理**: 因为这个项目有很多类型提示，然后我就编译成C库了。。。
|
||||
* **何用途**: WS和manager下边的模块都是机器码运行，或许会快一些。。。
|
||||
|
||||
### 异步 IO 模型
|
||||
* **Linux**: 必须用 `uvloop`，这玩意儿是基于 libuv（Node.js 同款）的，公认最快。
|
||||
* **Windows**: 用的是系统自带的 IOCP，虽然没 uvloop 猛，但在 Windows 上已经是最好的选择了。
|
||||
* *注*: 我们把 `winloop` 禁了，因为它跟 Playwright 八字不合。
|
||||
* **Linux**: uvloop
|
||||
* **Windows**:IOCP
|
||||
* *注*: `winloop` 死了，会和面具打架。。。
|
||||
|
||||
## 2. 网络架构
|
||||
## 2. 连接模式
|
||||
|
||||
### 正向 WebSocket + FastAPI 混合模式
|
||||
这套组合拳，既方便部署，又能随便扩展。
|
||||
### 正向 WebSocket 模式
|
||||
这是一种简单直接的模式
|
||||
|
||||
* **连接层 (Client)**: Bot 是个客户端，主动去连 OneBot (NapCat)。
|
||||
* **好处**: 你电脑能上网就行，不用搞公网 IP，不用内网穿透。
|
||||
* **服务层 (Server)**: Bot 自己也带了个 FastAPI 服务。
|
||||
* **好处**: 能对外提供 HTTP 接口，还能搞个 Web 控制台啥的。
|
||||
* **主动出击 (Client)**: Bot 是个客户端
|
||||
* **好处**: 你电脑能上网就行（实际上是因为没公网ip哈。。。）
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Local [你的电脑/服务器]
|
||||
Bot[NEO Bot]
|
||||
FastAPI[FastAPI Server]
|
||||
Browser[Playwright Pool]
|
||||
Browser[Playwright 页面池]
|
||||
end
|
||||
|
||||
subgraph Remote [外部]
|
||||
NapCat[NapCatQQ]
|
||||
User["用户浏览器"]
|
||||
end
|
||||
|
||||
Bot -- "WebSocket (主动连接)" --> NapCat
|
||||
User -- "HTTP (访问网页)" --> FastAPI
|
||||
Bot -- "内部调用" --> Browser
|
||||
```
|
||||
|
||||
## 3. 资源管理架构
|
||||
## 3. 资源管理
|
||||
|
||||
### 单例管理器 (Singleton Managers)
|
||||
所有管事的（指令、权限、浏览器、图片）都是全局独一份。
|
||||
* **随便用**: 在哪都能直接 `import`，不用传来传去。
|
||||
* **数据统一**: 全局就一份数据，不会乱。
|
||||
### 单例管理器
|
||||
所有东西（指令、权限、浏览器、图片）都是全局独一份的。
|
||||
* **随叫随到**: 在哪都能直接 `import`
|
||||
* **绝对权威**: 全局就一份数据
|
||||
|
||||
### 资源池化 (Pooling)
|
||||
我们这没有“一次性”的说法，用完的东西都得回收。
|
||||
* **Browser Pool**: 浏览器页面提前开好，用完洗干净放回去，谁也别想每次都等浏览器启动。
|
||||
* **Connection Pool**: Redis 和 HTTP 请求都用连接池，省掉反复建连接的开销。
|
||||
### 资源池化
|
||||
别几把开多个实例。。。
|
||||
* **Browser Pool**: 浏览器页面提前开好，用完洗干净放回去
|
||||
* **Connection Pool**: Redis 和 HTTP 请求都用连接池
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# 核心概念：事件流转
|
||||
|
||||
别管那些花里胡哨的，NEO Bot 的核心就是**事件驱动**。搞懂一个事件从哪来、到哪去，你就懂了一大半。
|
||||
NEO Bot 的核心就是**事件驱动**。搞懂一个事件从哪来、到哪去，你就懂了一大半。
|
||||
|
||||
下面就拿 `/echo hello` 这条傻瓜命令开刀，看看它在 Bot 内部是怎么裸奔的。
|
||||
下面就拿 `/echo hello` 举例
|
||||
|
||||
## 事件流转图
|
||||
|
||||
@@ -61,13 +61,12 @@ graph TD
|
||||
|
||||
* 你在群里发了条消息，OneBot (比如 NapCatQQ) 就会把它打包成一个 JSON，通过 WebSocket 扔给 Bot。
|
||||
* `core/ws.py` 里的 `_listen_loop` 一直在那蹲着，收到这个 JSON 字符串。
|
||||
* *注*: 这里用了 `orjson`，反序列化速度飞快。
|
||||
|
||||
### 2. 变成对象 (`models/events/factory.py`)
|
||||
|
||||
* `ws.py` 拿到 JSON 后，扔给 `EventFactory.create_event()`。
|
||||
* 工厂类眼疾手快，看一眼 `post_type` 是 `"message"`，`message_type` 是 `"group"`，直接把它变成一个 `GroupMessageEvent` 对象。
|
||||
* 这时候它就不是一堆冷冰冰的 JSON 了，而是个活生生的 Python 对象，有属性有方法，写代码的时候 IDE 还能给你补全。
|
||||
* 工厂类看一眼 `post_type` 是 `"message"`，`message_type` 是 `"group"`，会包装成 `GroupMessageEvent` 对象。
|
||||
* 这时候是python对象了，有属性有方法，感觉很方便。。。
|
||||
|
||||
### 3. 塞点东西，准备分发 (`core/ws.py`)
|
||||
|
||||
@@ -77,25 +76,25 @@ graph TD
|
||||
|
||||
### 4. 找找谁来处理 (`core/managers/command_manager.py`)
|
||||
|
||||
* `CommandManager` (就是代码里的 `matcher`) 是个大管家。
|
||||
* 它看了一眼：“哟，是条消息”，然后转手交给 `MessageHandler`。
|
||||
* `MessageHandler` 拿着放大镜看消息内容：“是以 `/` 开头的吗？”
|
||||
* 如果是 `/echo`，它就去翻小本本（注册的命令列表），找到了 `plugins/echo.py` 里那个被 `@matcher.command("echo")` 标记的函数。
|
||||
* `CommandManager` (就是代码里的 `matcher`)
|
||||
* 它看了一眼，然后转手交给 `MessageHandler`。
|
||||
* `MessageHandler` 看消息内容是以 `/` 开头的吗？”
|
||||
* 如果是 `/echo`，已经注册的指令列表，找到了 `plugins/echo.py` 里那个被 `@matcher.command("echo")` 标记的函数。
|
||||
|
||||
### 5. 干活 (`plugins/echo.py`)
|
||||
|
||||
* 找到了正主，直接调用它，把 `Event` 对象和参数 `args` 传进去。
|
||||
* 这时候就是你写的代码在跑了。你想干啥都行，查数据库、调 API、或者直接复读。
|
||||
* 直接调用它，把 `Event` 对象和参数 `args` 传进去。
|
||||
* 这时候就是你写的代码在跑了。你想干啥都行。。。
|
||||
|
||||
### 6. 回复消息 (`core/bot.py` -> `core/ws.py`)
|
||||
|
||||
* 你在插件里写了 `await event.reply("hello")`。
|
||||
* 这行代码背后，是 `core/bot.py` 把你的话封装成了一个标准的 OneBot API 请求（`send_group_msg`）。
|
||||
* 然后 `core/ws.py` 再次出场，把这个请求变成 JSON，通过 WebSocket 扔回给 OneBot。
|
||||
* 然后 `core/ws.py` 把这个请求变成 JSON，通过 WebSocket 扔回给 OneBot。
|
||||
|
||||
### 7. 发送成功
|
||||
|
||||
* OneBot 收到请求，把 "hello" 发到了群里。
|
||||
* 完事。
|
||||
* 恩。。。
|
||||
|
||||
至此，一个完整的事件流转闭环就完成了。理解这个流程后，您就能明白框架是如何将底层的网络通信与高层的插件逻辑解耦，并为开发者提供便捷接口的。
|
||||
至此，一个完整的事件流转闭环就完成了。理解这个流程后，您就能明白框架是如何为开发者提供便捷接口的。
|
||||
|
||||
@@ -1,27 +1,27 @@
|
||||
# 性能优化详解
|
||||
|
||||
NEO Bot 能跑这么快，不是因为运气好，是因为我们做了大量微小的优化工作。这里详细拆解每一个性能黑科技。
|
||||
NEO Bot 实际上是python，有人说用Java可能更好。。。嗯但是镀铬酸钾不会Java，镀铬酸钾只会python，所以只能用python了
|
||||
|
||||
## 1. Playwright 页面池 (Page Pool)
|
||||
|
||||
### 痛点
|
||||
传统的 Bot 发图流程：
|
||||
之前 Bot 发图流程：
|
||||
1. 用户发指令。
|
||||
2. Bot 启动浏览器 (耗时 500ms+)。
|
||||
3. 创建新页面 (耗时 100ms+)。
|
||||
2. Bot 启动浏览器。
|
||||
3. 创建新页面。。
|
||||
4. 渲染，截图。
|
||||
5. 关闭浏览器。
|
||||
|
||||
这种模式下，发一张图至少要等 1 秒以上，并发高了直接卡死。
|
||||
这种模式下，发一张图至少要等 1 秒以上。。。
|
||||
|
||||
### 解决方案
|
||||
`BrowserManager` 维护了一个**页面池**。
|
||||
* **启动时**: 自动预热 3 个页面（可配置），挂在后台待命。
|
||||
* **运行时**: 需要截图时，直接从池里 `get_page()`，耗时 **0ms**。
|
||||
* **运行时**: 需要截图时，直接从池里 `get_page()`
|
||||
* **结束后**: 截图完成，页面执行 `about:blank` 洗白，然后 `release_page()` 放回池里。
|
||||
|
||||
### 收益
|
||||
图片生成响应时间从 **1.5s** 降低到 **0.2s** (仅渲染耗时)。
|
||||
我不知道快了多少，也没人测试，嗯
|
||||
|
||||
## 2. Jinja2 模板缓存
|
||||
|
||||
@@ -34,7 +34,7 @@ NEO Bot 能跑这么快，不是因为运气好，是因为我们做了大量微
|
||||
* 后续请求直接从内存拿对象渲染。
|
||||
|
||||
### 收益
|
||||
模板加载时间归零。
|
||||
省了硬盘IO
|
||||
|
||||
## 3. 全局 HTTP 连接复用
|
||||
|
||||
@@ -48,26 +48,26 @@ NEO Bot 能跑这么快，不是因为运气好，是因为我们做了大量微
|
||||
* 复用底层的 TCP 连接 (Keep-Alive)。
|
||||
|
||||
### 收益
|
||||
API 请求延迟降低 50% 以上，大幅减少服务器 TCP 连接数。
|
||||
实际上我也不知道，bot没高并发的实验。。。
|
||||
|
||||
## 4. orjson 极速序列化
|
||||
|
||||
### 痛点
|
||||
Python 自带的 `json` 库性能平平，特别是在处理 OneBot 这种大量 JSON 通信的场景下。
|
||||
Python 自带的 `json` 库性能好像不太好，特别是在处理 OneBot 这种大量 JSON 通信的场景下。
|
||||
|
||||
### 解决方案
|
||||
我们全面替换为 `orjson`。
|
||||
* Rust 编写，速度是标准库的 10 倍以上。
|
||||
全面替换为 `orjson`。
|
||||
* Rust 编写
|
||||
* 支持直接返回 `bytes`，减少内存复制。
|
||||
|
||||
## 5. Mypyc 编译
|
||||
|
||||
### 痛点
|
||||
Python 是解释型语言，执行效率天生低。
|
||||
Python太慢了。。。
|
||||
|
||||
### 解决方案
|
||||
利用 `setup_mypyc.py` 将核心模块编译为 C 扩展。
|
||||
* `core/ws.py`: WebSocket 消息处理循环。
|
||||
* `core/managers/*.py`: 事件分发逻辑。
|
||||
|
||||
这些高频调用的代码变成了机器码，执行效率直逼 C++。
|
||||
这些高频调用的代码变成了机器码
|
||||
|
||||
@@ -1,43 +1,43 @@
|
||||
# 核心概念：单例管理器
|
||||
|
||||
`core/managers/` 这地方，放的都是些**管事的（Managers）**。它们是 NEO Bot 的权力核心。
|
||||
`core/managers/` 这地方，放的都是些**管事的**。它们是 NEO Bot 的核心。梨花飘落在你窗前。。。
|
||||
|
||||
## 为啥非得是单例 (Singleton)？
|
||||
## 为啥是单例？
|
||||
|
||||
说白了，就是**全局独一份，省事**。
|
||||
就是**全局独一份**。
|
||||
|
||||
* **到处都能用**: 在插件里 `import` 就行，不用传来传去。
|
||||
* **数据不打架**: 权限、命令这些东西，全局就一份，改了都认。
|
||||
* **省资源**: Redis 连接池、浏览器这种东西，开一个就够了，多了浪费。
|
||||
|
||||
我们专门在 `core/utils/singleton.py` 搞了个基类，继承一下就行。
|
||||
我专门在 `core/utils/singleton.py` 搞了个基类，继承一下就行，你会的，加油。。。
|
||||
|
||||
## 认识一下这帮“官”
|
||||
## 认识一下
|
||||
|
||||
### 1. `CommandManager` (外号 `matcher`)
|
||||
### 1. `CommandManager` (`matcher`)
|
||||
|
||||
* **怎么找**: `from core.managers.command_manager import matcher`
|
||||
* **管啥**:
|
||||
* **总调度**: 所有消息都得从它这过一遍，它说了算分给谁。
|
||||
* **总调度**: 所有消息都得从它这过一遍
|
||||
* **发牌的**: 你用的 `@matcher.command()` 这种装饰器，就是它发的。
|
||||
* **对号入座**: 消息来了，它负责对一下，看是哪个插件的活儿。
|
||||
* **对号入座**: 消息来了，它负责对一下，看是哪个插件的。
|
||||
|
||||
写插件天天都得跟它打交道。
|
||||
|
||||
### 2. `PermissionManager` (外号 `permission_manager`)
|
||||
### 2. `PermissionManager` (`permission_manager`)
|
||||
|
||||
* **怎么找**: `from core.managers.permission_manager import permission_manager`
|
||||
* **管啥**:
|
||||
* **划分三六九等**: `ADMIN`, `OP`, `USER` 这些等级都是它定的。
|
||||
* **记小本本**: 谁有啥权限，都记在 `core/data/permissions.json` 里。
|
||||
* **管理权限**: 谁有啥权限，都记在 `core/data/permissions.json` 里。
|
||||
* **会自动变通**: 查权限的时候，它会把 `AdminManager` 里的超管也当成 `ADMIN`。
|
||||
|
||||
### 3. `AdminManager` (外号 `admin_manager`)
|
||||
### 3. `AdminManager` (`admin_manager`)
|
||||
|
||||
* **怎么找**: `from core.managers.admin_manager import admin_manager`
|
||||
* **管啥**:
|
||||
* **钦差大臣**: 专门管机器人的超级管理员，增删改查都在这。
|
||||
* **三级缓存**: 内存 -> Redis -> 文件，又快又稳。
|
||||
* **三级缓存**: 内存 -> Redis -> 文件
|
||||
|
||||
### 4. `PluginManager`
|
||||
|
||||
@@ -45,36 +45,36 @@
|
||||
* **拉人头**: 启动时把 `plugins/` 目录下的插件都拉进来。
|
||||
* **热更新**: 你改了插件代码，它负责重载，不用重启机器人。
|
||||
|
||||
这家伙一般在幕后，你基本不用找它。
|
||||
这一般在幕后，你基本不用找它。
|
||||
|
||||
### 5. `RedisManager` (外号 `redis_manager`)
|
||||
### 5. `RedisManager` (`redis_manager`)
|
||||
|
||||
* **怎么找**: `from core.managers.redis_manager import redis_manager`
|
||||
* **管啥**:
|
||||
* **接线员**: 管着和 Redis 的连接。
|
||||
* **提供工具**: 你要用 Redis，就找它要 `redis_manager.redis`。
|
||||
* **提供工具**: 你要用 Redis，就找 `redis_manager.redis`。
|
||||
|
||||
### 6. `BrowserManager` (外号 `browser_manager`)
|
||||
### 6. `BrowserManager` (`browser_manager`)
|
||||
|
||||
* **怎么找**: `from core.managers.browser_manager import browser_manager`
|
||||
* **管啥**:
|
||||
* **浏览器司机**: 负责启动和关闭 Playwright。
|
||||
* **开个页面池**: 提前准备好几个空白页面（默认3个），你要用直接拿，省下几百毫秒的启动时间。
|
||||
* **循环利用**: 用完记得还回来 (`release_page`)，建设节约型社会。
|
||||
* **浏览器**: 负责启动和关闭 Playwright。
|
||||
* **页面池**: 提前准备好几个空白页面（默认3个），你要用直接拿
|
||||
* **循环利用**: 用完记得还回来 (`release_page`)
|
||||
|
||||
### 7. `ImageManager` (外号 `image_manager`)
|
||||
### 7. `ImageManager` (`image_manager`)
|
||||
|
||||
* **怎么找**: `from core.managers.image_manager import image_manager`
|
||||
* **管啥**:
|
||||
* **美工**: 把数据塞进网页模板，然后用浏览器咔嚓一下截图。
|
||||
* **美工**: 把数据塞进网页模板
|
||||
* **记性好**: 模板用一次就记住，下次直接用缓存。
|
||||
* **自动借还**: 它会自动找 `BrowserManager` 借页面，你只管喊一声 `render_template` 就行。
|
||||
* **自动借还**: 它会自动找 `BrowserManager` 借页面，你只管 `render_template` 就行。
|
||||
|
||||
## 咋用？
|
||||
|
||||
简单粗暴：`import` 就完事了。
|
||||
`import`
|
||||
|
||||
**举个栗子**: 查查这人是不是管理员。
|
||||
**例子**: 查查这人是不是op
|
||||
|
||||
```python
|
||||
# plugins/my_plugin.py
|
||||
|
||||
Reference in New Issue
Block a user