K2CrO4/NeoBot
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

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

61
docs/core-concepts/architecture.md
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`，这玩意儿是基于 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 请求都用连接池

27
docs/core-concepts/event-flow.md
View File

@@ -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" 发到了群里。
* 完事。
* 恩。。。
至此，一个完整的事件流转闭环就完成了。理解这个流程后，您就能明白框架是如何将底层的网络通信与高层的插件逻辑解耦，并为开发者提供便捷接口的。
至此，一个完整的事件流转闭环就完成了。理解这个流程后，您就能明白框架是如何为开发者提供便捷接口的。

28
docs/core-concepts/performance.md
View File

@@ -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++。
这些高频调用的代码变成了机器码

48
docs/core-concepts/singleton-managers.md
View File

@@ -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

8
docs/deployment.md
View File

@@ -6,7 +6,7 @@
### a. 安装 Python 3.14
别用太旧的版本，也别用最新的，就用 3.14。怎么装我就不废话了，自己想办法。
用3.14。。。
### b. 安装依赖
@@ -24,7 +24,7 @@ pip install -r requirements.txt
### c. 编译核心模块 (可选，但强烈建议)
为了极致性能，把核心模块编译成 C 扩展。
为了性能，把核心模块编译成 C 扩展。
```bash
python setup_mypyc.py build_ext --inplace
@@ -95,4 +95,8 @@ pm2 delete neobot # 删除 neobot
* `url`: 改成你服务器的 IP 和 `main.py` 里配置的端口。
* `access_token`: 如果你在 `main.py` 里设置了 `ACCESS_TOKEN`，这里要保持一致。
或者你也可以用napcat的webui，不多赘述了。。。
改完后重启 NapCatQQ，Bot 应该就能收到消息了。

70
docs/getting-started.md
View File

@@ -1,74 +1,69 @@
# 快速上手
这篇文档教你怎么把 NEO Bot 跑起来。如果你连这都搞不定，建议先去补补 Python 基础。
runit
## 1. 环境准备
## 1. 你需要准备
别拿老古董环境来跑新代码，我们用的是最新的技术栈。
* **Python 3.14**: 必须是这个版本别问我为什么。。。
* **Git**: 拉取代码
* **Redis**: 装一个
* **脑子和手**: 这个最重要，或者你去问问镀铬酸钾，会给你一对一教学的。。。
* **OneBot v11 客户端**: 机器人本体，推荐用 [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
* **Python**: 必须 `3.14` 或更高。
* 推荐开启 JIT (`-X jit`)。
* 别问为什么不用 3.8，问就是慢。
## 2. 搭起来
* **Git**: 拉代码用的，这都要教？
### a. 克隆代码
* **Redis**: 必须装。
* Windows 用户自己想办法 (WSL2 或者 Memurai)。
* Linux/macOS 用户直接包管理器装。
* 没 Redis 跑不起来，别试了。
* **OneBot v11 客户端**: 机器人本体。
* **强烈推荐**: [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
* 别用那些几百年不更新的协议端，出了问题别找我。
## 2. 安装步骤
### 拉代码
找个你喜欢的地方，把代码从 GitHub 上clone下来
```bash
git clone [项目仓库地址]
cd [项目目录]
```
### 搞个虚拟环境
### b. 创建虚拟环境
别把系统环境搞脏了，这是基本礼貌。
别把你的系统环境搞得乱七八糟
```bash
# 创建
# Windows
python -m venv venv
# 激活 (Windows)
.\venv\Scripts\activate
# 激活 (Linux/macOS)
# Linux / macOS
python3.14 -m venv venv
source venv/bin/activate
```
### 装依赖
看到命令行前面多了个 `(venv)`，就说明你进来了。
### c. 安装依赖
```bash
pip install -r requirements.txt
```
### 装浏览器内核
### d. 安装 Playwright 依赖
我们用了 Playwright 做渲染，所以得装个 Chromium。
我们用 Playwright 来截图画画，它需要一个浏览器核心。
```bash
playwright install chromium
```
### 编译核心 (可选，但推荐)
### e. 编译核心 (可选，但强烈建议)
想体验极致速度？把核心模块编译成 C 扩展。
想让你的代码更快？把它的核心代码编译成 C。
```bash
python setup_mypyc.py build_ext --inplace
```
*注：Windows 上需要 Visual Studio Build Tools，Linux 上需要 GCC。编译失败就跳过，反正 JIT 也够快了。*
*注：Windows 上可能需要装个 Visual Studio Build Tools，Linux 上需要 GCC。编译失败也别慌，跳过就行，JIT 也能保证不错的速度*
## 3. 配置
## 3. 第一次
### a. 修改配置
去根目录找 `config.toml`。
@@ -84,14 +79,17 @@ host = "127.0.0.1"
port = 6379
db = 0
```
把 `uri` 改成你自己的 OneBot 地址。
## 4. 启动
### b. 启动！
一切就绪，起飞。
一切就绪
```bash
# 开启 JIT 模式启动
# 推荐开启 JIT 模式启动
python -X jit main.py
```
看到 `连接成功！` 就说明跑通了。如果报错，先看日志，别上来就问。
如果你看到日志刷出来，最后显示 “连接成功！”，恭喜，你成功了！
现在，试着给你的机器人发个 `/help`看看会返回什么东西

35
docs/index.md
View File

@@ -1,28 +1,29 @@
# NEO Bot Framework 开发文档
# NEO Bot 开发文档
欢迎来到 NEO Bot Framework 的官方开发文档。
嘿，朋友，欢迎来到 NEO Bot
这里没有废话，只有干货。这份文档会教你如何驾驭这个基于 Python 3.14 的高性能机器人框架。
这里没那么多规矩。这份文档是我写给你——未来的插件开发者、或者单纯好奇想拆开看看的家伙——的一份地图
## 📖 文档结构
### 1. 基础入门
* [快速上手](./getting-started.md): 环境配置、安装、启动。别跳过，除非你想报错。
* [项目结构](./project-structure.md): 了解各个目录是干嘛的。
* [部署指南](./deployment.md): 怎么在服务器上长期运行。
## 📖 地图导览
### 2. 核心概念 (必读)
* [核心架构](./core-concepts/architecture.md): 了解我们是如何把 Python 性能榨干的。
* [性能优化](./core-concepts/performance.md): 页面池、JIT、Mypyc...黑科技详解。
* [事件流转](./core-concepts/event-flow.md): 一条消息是如何在系统里流转的（含详细图解）。
* [单例管理器](./core-concepts/singleton-managers.md): 掌握 `matcher`, `browser_manager` 等核心组件。
### 1. 准备阶段
* [快速上手](./getting-started.md): 搭环境、装东西、启动。跟着走一遍，能省不少事。
* [项目怎么样](./project-structure.md): 看看各个文件夹都是干嘛的，免得迷路。
* [生产环境](./deployment.md): 怎么把你调教好的 Bot 扔服务器上，让它自己 7x24 小时跑。
### 2. 核心探秘
* [骨架](./core-concepts/architecture.md): 看看镀铬酸钾和python打架，嗯。。。
* [性能优化](./core-concepts/performance.md): 页面池、JIT、Mypyc...
* [消息流](./core-concepts/event-flow.md): 看看一条消息从被接收到被回复是如何运行的
* [核心](./core-concepts/singleton-managers.md): `matcher`, `browser_manager`... 认识这些核心模块。
### 3. 插件开发
* [基础指南](./plugin-development/index.md): 怎么写一个最简单的插件。
* [指令处理](./plugin-development/command-handling.md): 怎么注册命令、解析参数。
* [最佳实践](./plugin-development/best-practices.md): **重要！** 避免写出卡死机器人的垃圾代码。
* [插件开发第一步](./plugin-development/index.md): 带你写第一个插件
* [指南](./plugin-development/command-handling.md): 怎么教你的 Bot 听懂指令和参数。
* [绝对不要做的事情](./plugin-development/best-practices.md): **（必读！）**
## 🤝 贡献
## 贡献
发现 Bug 了？觉得文档写得烂？
直接提 Issue 或者 PR。代码质量是第一位的，Talk is cheap, show me the code.

14
docs/plugin-development/best-practices.md
View File

@@ -2,9 +2,9 @@
写插件很简单，但写出**高性能、不炸裂**的插件需要遵守规矩。
## 1. 绝对不要阻塞事件循环 (Don't Block the Loop!)
## 1. 绝对不要阻塞事件循环。。。
这是死罪。NEO Bot 是单线程异步架构，如果你在主线程里 `time.sleep(5)`，整个机器人就会卡死 5 秒，谁都别想说话。
这是底线。NEO Bot 是单线程异步架构，如果你在主线程里 `time.sleep(5)`，整个机器人就会卡死 5 秒
* **错误**: `time.sleep(1)`, `requests.get(...)`, 大量 CPU 计算。
* **正确**: `await asyncio.sleep(1)`, `await session.get(...)`。
@@ -40,23 +40,23 @@ weather = await redis_manager.get("weather:beijing")
## 4. 类型提示 (Type Hinting)
我们开启了 Mypyc 编译，这意味着你的代码最好有规范的类型提示。
这不仅是为了编译，也是为了让你自己少写 Bug。
我开启了 Mypyc 编译，这意味着你的代码最好有规范的类型提示。
这不仅是为了编译，也是为了让你自己少写 Bug
```python
# 好的写法
async def handle(event: MessageEvent, args: list[str]) -> None:
...
# 烂写法
# 不好写法
async def handle(event, args):
...
```
## 5. 异常处理
别让你的插件因为一个报错就搞崩整个机器人。
虽然框架层有捕获机制，但你自己处理好异常是基本素养。
别让你的插件因为一个报错就崩溃机器人
虽然框架层有捕获机制，但你自己处理好异常是最好的。。。
```python
try:

57
docs/plugin-development/command-handling.md
View File

@@ -1,6 +1,6 @@
# 指令处理与参数解析
光会 `event.reply()` 只能写玩具。正经的插件，都得和用户传进来的参数打交道。
光会 `event.reply()` 只能写小插件。。。认识一下其他的方法吧
## 1. 获取原始参数
@@ -15,7 +15,7 @@ async def handle_echo(event: MessageEvent, args: str):
# 如果用户发送 /echo hello world
# args 的值就是 "hello world"
if not args:
await event.reply("你啥也没说啊。")
await event.reply("你啥也没说啊")
else:
await event.reply(f"你说了：{args}")
```
@@ -26,7 +26,7 @@ async def handle_echo(event: MessageEvent, args: str):
一整坨字符串用起来太费劲了，还得自己 `split()`。框架提供了更高级的玩法：**参数自动解析**。
你只需要在函数签名里，用类型提示声明你想要的参数，框架会像 FastAPI 一样，自动帮你解析和注入。
你只需要在函数签名里，用类型提示声明你想要的参数，框架会动帮你解析和注入。
### a. 基础用法
@@ -85,6 +85,53 @@ async def handle_say(event: MessageEvent, target_user: str, content: str = ...):
await event.reply(f"正在对 {target_user} 说：{content}")
```
## 3. 更复杂的解析：依赖注入
## 3. 智能的参数注入
如果你的参数不是简单的 `int` 或 `str`，或者你需要更复杂的解析逻辑（比如 `@某人`），请参考 `FastAPI` 的依赖注入系统，我们用了同一套逻辑。
除了 `args` 列表，命令处理器还可以自动接收一些非常有用的上下文对象。框架底层使用了 Python 的 `inspect` 模块来分析你函数的参数签名，并自动“注入”你需要的对象。
这是一种轻量级的**依赖注入**，让你的代码更简洁、更易于测试。
### 可用的参数
你可以在命令处理函数的参数中声明以下任意名称，框架会自动为你传入：
| 参数名 | 类型 | 描述 |
| ------------------- | -------------------------------- | ---------------------------------------- |
| `bot` | `Bot` | 当前的 Bot 实例，用于调用 API 发送消息等。 |
| `event` | `MessageEvent` (或其子类) | 触发该命令的完整消息事件对象。 |
| `args` | `List[str]` | 和之前一样，包含命令参数的字符串列表。 |
| `permission_granted`| `bool` | 指示当前用户是否通过了权限检查。 |
### 示例
假设我们想写一个“回声”命令，但只在用户拥有管理员权限时才重复他们的消息。
```python
# plugins/echo_plus.py
from core.bot import Bot
from core.permission import ADMIN
from models.events.message import MessageEvent
from core.managers.command_manager import matcher
@matcher.command("echo_plus", permission=ADMIN)
async def echo_plus(bot: Bot, event: MessageEvent, args: list[str], permission_granted: bool):
"""
一个更强大的回声命令
"""
# 只有当 permission_granted 为 True 时，代码才会执行到这里
# 因为框架会自动处理权限拒绝的情况
if not args:
await bot.send(event, "你想要我复述什么呢？")
return
# 我们可以从 event 对象中获取更详细的信息
user_id = event.user_id
message_to_echo = " ".join(args)
response = f"管理员 {user_id} 说：{message_to_echo}"
await bot.send(event, response)
```
在这个例子中，我们没有手动检查权限。我们只是在 `@matcher.command` 中声明了 `permission=ADMIN`，然后在函数参数中请求了 `permission_granted: bool`。框架会自动完成权限检查，如果失败，甚至不会执行我们的函数，并会发送一条权限不足的消息。这就是依赖注入的强大之处。

4
docs/plugin-development/index.md
View File

@@ -1,6 +1,6 @@
# 插件开发入门
写插件是给 NEO Bot 添加功能的唯一方式。这玩意儿很简单，一个 Python 文件就是一个插件。
写插件是给 NEO Bot 添加功能的唯一方式，一个 Python 文件就是一个插件。（或者一个文件夹里边有__init__.py）
## 1. 创建你的第一个插件
@@ -35,8 +35,6 @@ async def handle_hello(event: MessageEvent):
不用你动手，NEO Bot 启动时会自动加载 `plugins/` 目录下的所有 `.py` 文件。
如果你是在 Bot 运行时新增或修改了插件，只需要在控制台输入 `reload` 命令，或者让管理员在群里发 `/reload`，就能热重载所有插件。
## 3. 测试插件
现在，去群里或者私聊给 Bot 发送：