docs: 更新文档内容并优化语言风格

重构所有文档内容,使用更简洁直接的语言风格
更新架构、插件开发、部署等核心文档
优化代码示例和图表说明
统一术语和格式规范
This commit is contained in:
2026-01-13 04:09:13 +08:00
parent a6704a55ff
commit 7880f0f928
7 changed files with 361 additions and 421 deletions

View File

@@ -1,62 +1,62 @@
# 核心架构
NEO Bot Framework 不是那种随便写写的玩具。它的架构设计只有一个核心目标:**极致性能与稳定性的平衡**。
别把 NEO Bot 当成那些写着玩的玩具。这玩意的设计目标就一个:**又快又稳**。
我们不搞花里胡哨的抽象,只做最有效的工程实践
不搞虚头巴脑的,只上最实在的
## 1. 运行时架构
### Python 3.14 + JIT
我们激进地采用了 Python 3.14默认开 JIT (Just-In-Time) 编译
* **原理**: JIT 会在运行时分析热点代码,将其编译机器码,跳过字节码解释过程
* **收益**: CPU 密集型任务(如复杂的正则匹配、数据处理)性能提升显著
我们直接上了 Python 3.14,默认开 JIT (即时编译)
* **原理**: JIT 会在代码跑的时候,把那些一遍遍执行的热点代码直接编译机器码,下次再跑就不用解释器了,快得飞起
* **有啥用**: 正则匹配、数据处理这种吃 CPU 的活儿,效果特别明显
### Mypyc 编译 (AOT)
JIT 还不够。核心模块(`core/ws.py`, `core/managers/*.py`支持通过 Mypyc 编译 C 扩展。
* **原理**: Mypyc 利用 Python 的类型提示,将 Python 代码直接翻译成 C 代码,并编译二进制 `.pyd``.so` 文件。
* **收益**: 核心路径的执行速度接近 C 语言,完全摆脱 GIL 的部分束缚
光 JIT 还不够。核心模块(`core/ws.py`, `core/managers/*.py`我们都用 Mypyc 编译成了 C 扩展。
* **原理**: Mypyc 直接把带类型提示 Python 代码翻译成 C,再编译二进制文件。
* **有啥用**: 核心代码跑起来跟 C 差不多快,还能绕开 GIL
### 异步 IO 模型
* **Linux**: 强制使`uvloop`,这是目前最快的 Python 异步事件循环,基于 libuvNode.js 同款)。
* **Windows**: 使用原生 `ProactorEventLoop` (IOCP),虽然不如 uvloop但在 Windows 上是最优解
* **: 我们禁用了 `winloop`,因为它 Playwright 存在兼容性问题
* **Linux**: 必须`uvloop`,这玩意儿是基于 libuvNode.js 同款)的,公认最快
* **Windows**: 用的是系统自带的 IOCP虽然 uvloop,但在 Windows 上已经是最好的选择了
* **: 我们 `winloop` 禁了,因为它 Playwright 八字不合
## 2. 网络架构
### 正向 WebSocket + FastAPI 混合模式
是一个独特的混合架构,兼顾了部署便利性和功能扩展
套组合拳,既方便部署,又能随便扩展。
* **连接层 (Client)**: Bot 主动通过 WebSocket 连接到 OneBot (NapCat)。
* **优势**: 不需要公网 IP需要内网穿透,只要能上网就能跑
* **服务层 (Server)**: Bot 内部启动一个 FastAPI 服务。
* **优势**: 提供 HTTP API、Webhook 接收、静态资源托管(如帮助图片、Web 控制台
* **连接层 (Client)**: Bot 是个客户端,主动去连 OneBot (NapCat)。
* **好处**: 你电脑能上网就行,不用搞公网 IP内网穿透。
* **服务层 (Server)**: Bot 自己也带了个 FastAPI 服务。
* **好处**: 能对外提供 HTTP 接口,还能搞个 Web 控制台啥的
```mermaid
graph LR
subgraph Local [本地环境 / 服务器]
subgraph Local [你的电脑/服务器]
Bot[NEO Bot]
FastAPI[FastAPI Server]
Browser[Playwright Pool]
end
subgraph Remote [OneBot / 外部]
subgraph Remote [外部]
NapCat[NapCatQQ]
User[用户浏览器]
User["用户浏览器"]
end
Bot -- WebSocket (Client) --> NapCat
User -- HTTP --> FastAPI
Bot -- 控制 --> Browser
Bot -- "WebSocket (主动连接)" --> NapCat
User -- "HTTP (访问网页)" --> FastAPI
Bot -- "内部调用" --> Browser
```
## 3. 资源管理架构
### 单例管理器 (Singleton Managers)
所有的核心组件(指令、权限、浏览器、图片)都是全局单例
* **零开销访问**: 任何插件都可以直接 import 使用,无需传递上下文
* **状态一致性**: 全局共享状态,拒绝数据同步问题
所有管事的(指令、权限、浏览器、图片)都是全局独一份
* **随便用**: 在哪都能直接 `import`,不用传来传去
* **数据统一**: 全局就一份数据,不会乱
### 资源池化 (Pooling)
我们拒绝“用完即扔”的浪费行为
* **Browser Pool**: 浏览器页面预先创建,用完归还,拒绝反复启动进程
* **Connection Pool**: Redis 和 HTTP 请求共享连接池,拒绝反复握手
我们这没有“一次性”的说法,用完的东西都得回收
* **Browser Pool**: 浏览器页面提前开好,用完洗干净放回去,谁也别想每次都等浏览器启动
* **Connection Pool**: Redis 和 HTTP 请求都用连接池,省掉反复建连接的开销