docs: 更新文档内容,简化语言并修正格式

- 简化插件开发指南中的描述,移除冗余内容
- 调整部署文档中的Python版本说明
- 优化最佳实践文档的措辞和格式
- 更新性能优化文档,删除不准确的数据
- 重构核心概念文档,使用更简洁的语言
- 修正README中的项目描述和技术栈说明
- 更新快速上手文档,简化安装步骤
- 调整事件流转文档的描述方式
- 简化架构文档内容
- 更新指令处理文档,添加参数注入示例
- 优化单例管理器文档的表述
This commit is contained in:
2026-01-13 04:49:03 +08:00
parent 7880f0f928
commit 7f331970dd
11 changed files with 213 additions and 172 deletions

View File

@@ -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`,这玩意儿是基于 libuvNode.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 请求都用连接池