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

Merge pull request #58 from Fairy-Oracle-Sanctuary/dev

Browse Source 
Dev
This commit is contained in:
镀铬酸钾
2026-02-01 23:56:25 +08:00
committed by GitHub
parent 08a7c1dc39 0efdd84bfc
commit aeb896e794
8 changed files with 799 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
README.md
View File

@@ -14,15 +14,15 @@
### 核心特性
* **模块化插件架构**：所有功能都在 `plugins/` 目录
* **模块化插件架构**：所有功能都在 `plugins/` 目录，开发者可轻松扩展
* **极致性能优化**：
* **Python 3.14 JIT**：pypy不支持那个浏览器扩展我只能用JIT了。。。
* **Mypyc 编译**：一些核心模块已经编译成机器码了
* **Playwright 页面池**：浏览器页面预热池
* **Python 3.14 JIT**：运行时热点代码编译成机器码
* **Mypyc AOT编译**：核心模块编译为C扩展
* **Playwright 页面池**：浏览器页面预热池，降低截图延迟
* **全局连接复用**：HTTP 和 Redis 连接池化管理
* **开发者友好**：完整的类型提示，清晰的 API 设计。
* **集成 Redis 缓存**：能缓存的都缓存了。群信息、用户信息、帮助图片
* **正向 WebSocket 连接**：我只会支持正向WS连接。。。不要提意见，我不会听的。。。
* **开发者友好**：完整的类型提示，清晰的 API 设计
* **集成 Redis 缓存**：缓存帮助图片、权限数据、会话状态等
* **正向 WebSocket 连接**：仅支持正向WS连接模式（Bot主动连接OneBot）
### 技术栈
@@ -42,24 +42,40 @@
```
.
├── plugins/ # 插件目录，业务逻辑都在这
│ ├── admin.py # 管理员指令
│ ├── bili_parser.py # B站解析 (高性能版)
│ ├── code_py.py # 代码沙箱
│ ├── echo.py # 复读机
│ ├── forward_test.py # 合并转发测试
│ ├── jrcd.py # 今日运势
│ └── thpic.py # 东方图片
│ ├── admin.py # 权限管理（Admin/User两级权限）
│ ├── auto_approve.py # 自动同意好友请求和群邀请
│ ├── bot_status.py # Bot运行状态查询（图片形式）
│ ├── broadcast.py # 管理员专用广播功能
│ ├── code_py.py # Python代码沙箱执行
│ ├── echo.py # Echo/点赞功能
│ ├── furry.py # Furry图片获取
│ ├── github_parser.py # GitHub仓库链接解析
│ ├── jrcd.py # 今日人品/长度查询
│ ├── thpic.py # 东方Project随机图片
│ ├── web_parser/ # Web链接解析系统（B站、抖音、GitHub等）
│ └── sync_async_test_plugin.py # 异步同步混用测试插件
├── core/ # 框架核心，非请勿动
│ ├── api/ # OneBot API 封装
│ ├── managers/ # 各种管理器 (指令, 浏览器, 图片, 插件)
│ ├── handlers/ # 事件处理器
│ ├── managers/ # 各种管理器 (指令, 浏览器, 图片, 插件, 权限)
│ ├── utils/ # 工具函数
│ ├── ws.py # WebSocket 通信层 (已编译)
│ └── bot.py # Bot 实例
│ ├── bot.py # Bot 实例
│ ├── config_loader.py # 配置加载
│ └── permission.py # 权限枚举
├── data/ # 数据存储
│ ├── admin.json # 管理员名单
│ └── permissions.json # 权限配置
├── templates/ # Jinja2 模板
├── setup_mypyc.py # 编译脚本
├── models/ # 数据模型
│ ├── events/ # OneBot事件模型
│ ├── message.py # 消息段模型
│ ├── sender.py # 发送者信息
│ └── objects.py # API响应对象
├── templates/ # Jinja2模板（用于图片生成）
├── docs/ # 开发文档
├── tests/ # 单元测试
├── setup_mypyc.py # Mypyc编译脚本
├── config.toml # 配置文件
└── main.py # 启动入口
```

110
docs/core-concepts/architecture.md
View File

@@ -1,59 +1,81 @@
# 骨架
# 架构设计
Neobot是面向内部开发者的，我会开源，但是写的很烂。。。
NEO Bot 是一个现代化的、高性能的异步 QQ 机器人框架。本文介绍其核心架构和设计理念。
## 1. 动力核心
## 1. 性能优化体系
### Python 3.14 + JIT
镀铬酸钾创项目的时候用的 Python 3.14 3.14兼容JIT，那就这样吧
* **何原理**: 运行时把热点代码编译成机器码（Just-In-Time）
* **何用途**: 密集CPU运算能提升一些，尤其是插件里的循环和函数调用
* **怎么开**: 启动时加 `-X jit` 参数
### Python 3.14 JIT（Just-In-Time 编译）
### Mypyc 编译 (AOT)
光 JIT 还不够。。核心模块（`core/ws.py`, `core/managers/*.py`）我编译成了C扩展
* **何原理**: 因为这个项目有很多类型提示，然后我就编译成C库了。。。
* **何用途**: WS和manager下边的模块都是机器码运行，或许会快一些。。。
**原理**：Python 3.14 内置 JIT 编译器，运行时将高频调用的代码编译成机器码。
### 异步 IO 模型
* **Linux**: uvloop
* **Windows**:IOCP
* *注*: `winloop` 死了，会和面具打架。。。
**适用场景**：
- 插件业务逻辑（循环、函数调用密集）
- 消息处理流程
## 2. 连接模式
**启用方法**：
### 正向 WebSocket 模式
这是一种简单直接的模式
* **主动出击 (Client)**: Bot 是个客户端
* **好处**: 你电脑能上网就行（实际上是因为没公网ip哈。。。）
```mermaid
graph LR
subgraph Local [你的电脑/服务器]
Bot[NEO Bot]
Browser[Playwright 页面池]
end
subgraph Remote [外部]
NapCat[NapCatQQ]
end
Bot -- "WebSocket (主动连接)" --> NapCat
Bot -- "内部调用" --> Browser
```bash
python -X jit main.py
```
## 3. 资源管理
预期性能提升：2-5 倍（取决于代码热点）。
### Mypyc 编译（AOT - Ahead-Of-Time）
**原理**：将类型注解的 Python 代码编译为 C 扩展，生成平台相关的二进制文件。
**编译范围**：
- `core/ws.py` - WebSocket 通信
- `core/managers/` - 各种管理器
- `core/api/` - API 封装
- `models/` - 数据模型
**启用方法**：
```bash
python setup_mypyc.py build_ext --inplace
```
预期性能提升：3-10 倍（核心模块）。
**注意**：编译产物平台相关，必须在目标环境编译。
### 异步 IO 模型
**Linux**：`uvloop`（libev 绑定，比 asyncio 快 2-4 倍）
**Windows**：IOCP（Windows 原生高性能 IO）
## 2. 连接架构
### 正向 WebSocket 连接
NEO Bot 采用**正向 WebSocket 连接**模式：Bot 主动连接 OneBot 实现（如 NapCatQQ）。
**流程**：
```
Bot 启动 → 连接到 NapCatQQ (ws://127.0.0.1:3001)
↓
监听消息事件
↓
分发到处理器
↓
调用 API 回复
```
## 3. 资源管理架构
### 单例管理器
所有东西（指令、权限、浏览器、图片）都是全局独一份的。
* **随叫随到**: 在哪都能直接 `import`
* **绝对权威**: 全局就一份数据
### 资源池化
别几把开多个实例。。。
* **Browser Pool**: 浏览器页面提前开好，用完洗干净放回去
* **Connection Pool**: Redis 和 HTTP 请求都用连接池
所有全局资源通过单例管理器统一管理，避免重复创建和资源泄漏。
### Playwright 页面池
预初始化页面，无需每次都启动浏览器，大幅降低延迟。
### HTTP 连接复用
全局 aiohttp.ClientSession 支持 Keep-Alive，减少连接建立开销。
## 4. 技术栈全景

229
docs/deployment.md
View File

@@ -1,107 +1,240 @@
# 部署指南
# 生产环境部署
把 Bot 扔到服务器上长期运行，比在自己电脑上跑要多几个步骤。
将 NEO Bot 部署到服务器长期运行，只需要几个额外的步骤。本指南以 Linux 服务器为例。
## 1. 环境准备
### a. 安装 Python 3.14
用3.14。。。
### b. 安装依赖
在 Linux 服务器上安装 Python 3.14 及开发工具：
```bash
# 切换到项目目录
cd /path/to/your/bot
# Ubuntu/Debian
sudo apt update
sudo apt install python3.14 python3.14-venv python3.14-dev gcc
# 创建虚拟环境 (强烈建议)
# CentOS/RHEL
sudo yum install python3.14 python3.14-devel gcc
```
### b. 克隆项目并创建虚拟环境
```bash
# 切换到项目目录（或新建）
cd /opt/neobot
git clone https://github.com/Fairy-Oracle-Sanctuary/NeoBot.git .
# 创建虚拟环境（强烈建议）
python3.14 -m venv venv
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
playwright install chromium
```
### c. 编译核心模块 (可选，但为获得最佳性能强烈建议)
### c. 编译核心模块（可选但强烈推荐）
为了最大化性能，你可以将项目中的核心 Python 模块编译成 C 语言扩展。这将大幅提升机器人的响应速度和处理效率。
为了最大化性能，建议在部署环境上编译 Mypyc 扩展：
```bash
# 确保你在虚拟环境中
python setup_mypyc.py
# 确保已激活虚拟环境
python setup_mypyc.py build_ext --inplace
```
该脚本会自动编译 `core` 和 `models` 目录下的指定模块。编译后的文件（`.pyd` 或 `.so`）会直接生成在源码旁边。
**注意**：编译产物是平台相关的，必须在目标服务器上执行。详见 [性能优化](../core-concepts/performance.md)。
> **注意**: 编译产物是平台相关的（例如，在 Windows 上编译的 `.pyd` 文件不能在 Linux 上使用）。因此，**请务必在你最终部署的服务器环境（例如 Linux）上执行此编译步骤**。更多关于 Mypyc 编译的细节，请参考 [性能优化详解](core-concepts/performance.md)。
## 2. 进程管理
## 2. 使用进程管理器
直接运行 `python main.py` 然后关闭 SSH 会导致 Bot 停止。需要用进程管理器来守护 Bot。
你想直接 `python main.py` 然后关掉 SSH？那机器人也跟着停了。必须用进程管理器来守护它。
推荐使用 `systemd`（Linux 原生方案）或 `pm2`。
这里推荐用 `pm2`，虽然是 Node.js 的工具，但管 Python 程序一样好用。
### 方案 A：systemd（推荐）
### a. 安装 pm2
创建 `/etc/systemd/system/neobot.service` 文件：
```ini
[Unit]
Description=NEO Bot Service
After=network.target redis.service
[Service]
Type=simple
User=bot
WorkingDirectory=/opt/neobot
ExecStart=/opt/neobot/venv/bin/python -X jit main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment="PYTHONUNBUFFERED=1"
[Install]
WantedBy=multi-user.target
```
然后启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable neobot
sudo systemctl start neobot
# 查看状态
sudo systemctl status neobot
# 查看日志
sudo journalctl -u neobot -f
```
### 方案 B：pm2
如果你习惯用 pm2（Node.js 工具），也可以：
```bash
# 你需要先装 Node.js 和 npm
npm install pm2 -g
```
### b. 启动 Bot
在项目根目录，创建一个 `ecosystem.config.js` 文件：
创建 `ecosystem.config.js`：
```javascript
module.exports = {
apps : [{
name : "neobot",
script : "main.py",
interpreter: "/path/to/your/bot/venv/bin/python", // 指定虚拟环境里的 python
max_memory_restart: "500M", // 内存超过 500M 自动重启
interpreter: "/opt/neobot/venv/bin/python",
args: "-X jit",
max_memory_restart: "512M",
env: {
"PYTHONUNBUFFERED": "1" // 禁用 python 输出缓冲，日志能实时看
}
"PYTHONUNBUFFERED": "1"
},
error_file: "./logs/pm2-error.log",
out_file: "./logs/pm2-out.log"
}]
}
```
然后启动：
启动：
```bash
pm2 start ecosystem.config.js
pm2 logs neobot
pm2 save
pm2 startup
```
### c. 常用 pm2 命令
## 3. 配置 OneBot 客户端
```bash
pm2 list # 查看所有进程状态
pm2 logs neobot # 查看 neobot 的实时日志
pm2 restart neobot# 重启 neobot
pm2 stop neobot # 停止 neobot
pm2 delete neobot # 删除 neobot
Bot 使用 **正向 WebSocket 连接**，即 Bot 主动连接 OneBot 实现（如 NapCatQQ）。
在 `config.toml` 中配置：
```toml
[napcat_ws]
# OneBot 客户端的 WebSocket 服务地址
uri = "ws://127.0.0.1:3001"
token = "your_token_here"
reconnect_interval = 5
```
## 3. 配置 NapCatQQ
### NapCatQQ 配置示例
最后一步，修改 NapCatQQ 的配置文件，让它把消息推送到你的服务器上。
找到 NapCatQQ 的 `config/onebot11.json` 文件，修改 `ws_reverse_servers` 部分：
在 NapCatQQ 的 `config/onebot11.json` 中，启用正向 WebSocket 服务器：
```json
"ws_reverse_servers": [
{
"url": "ws://你的服务器IP:8080/onebot/v11/ws",
"access_token": "你的访问令牌"
}
]
{
"ws": {
"enable": true,
"host": "127.0.0.1",
"port": 3001
},
"token": "your_token_here"
}
```
* `url`: 改成你服务器的 IP 和 `main.py` 里配置的端口。
* `access_token`: 如果你在 `main.py` 里设置了 `ACCESS_TOKEN`，这里要保持一致。
然后重启 NapCatQQ，Bot 启动后应该能正常连接。
## 4. 扩展配置
或者你也可以用napcat的webui，不多赘述了。。。
### Redis 连接
确保 Redis 服务运行在可访问的地址，在 `config.toml` 配置：
改完后重启 NapCatQQ，Bot 应该就能收到消息了。
```toml
[redis]
host = "127.0.0.1"
port = 6379
db = 0
password = "redis_password" # 如果有密码
```
### Docker 代码沙箱（可选）
若要使用 code_py 插件，需要配置 Docker：
```toml
[docker]
base_url = "unix:///var/run/docker.sock" # Linux socket
sandbox_image = "python-sandbox:latest"
timeout = 10
concurrency_limit = 5
```
## 5. 监控和日志
### 查看日志
日志文件位于 `logs/` 目录，使用 `tail` 实时查看：
```bash
tail -f logs/bot.log
```
### 监控系统资源
使用 systemd 时：
```bash
# 查看内存和 CPU 使用
systemctl status neobot
```
### 重启 Bot
```bash
# systemd
sudo systemctl restart neobot
# pm2
pm2 restart neobot
```
## 6. 常见问题
### Redis 连接失败
检查 Redis 是否运行：
```bash
redis-cli ping # 应返回 PONG
```
### Playwright 缓存问题
如果更新后图片渲染出现问题，清空 Playwright 缓存：
```bash
rm -rf ~/.cache/ms-playwright
playwright install chromium
```
### 内存持续增长
检查是否有内存泄漏。在 systemd 中添加内存限制：
```ini
[Service]
MemoryLimit=512M
MemoryAccounting=yes
```

27
docs/getting-started.md
View File

@@ -1,30 +1,24 @@
# 快速上手
runit
## 1. 你需要准备
* **Python 3.14**: 必须是这个版本别问我为什么。。。
* **Git**: 拉取代码
* **Redis**: 装一个
* **脑子和手**: 这个最重要，或者你去问问镀铬酸钾，会给你一对一教学的。。。
* **OneBot v11 客户端**: 机器人本体，推荐用 [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
* **Python 3.14**：必须是这个版本（JIT编译需要）
* **Git**：拉取代码
* **Redis**：缓存和权限管理，需要单独安装
* **Docker** (可选)：用于代码沙箱执行（code_py插件）
* **OneBot v11 客户端**：机器人本体，推荐用 [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
## 2. 搭起来
## 2. 搭环境
### a. 克隆代码
找个你喜欢的地方，把代码从 GitHub 上clone下来
```bash
git clone [项目仓库地址]
cd [项目目录]
git clone https://github.com/Fairy-Oracle-Sanctuary/NeoBot.git
cd NeoBot
```
### b. 创建虚拟环境
别把你的系统环境搞得乱七八糟
```bash
# Windows
python -m venv venv
@@ -39,17 +33,12 @@ source venv/bin/activate
### c. 安装依赖
```bash
pip install -r requirements.txt
```
这个文件里包含了所有需要的 Python 库，比如 `aiohttp` (HTTP 请求), `orjson` (JSON 解析), `jinja2` (模板渲染), `psutil` (系统监控) 等等。
### d. 安装 Playwright 依赖
我们用 Playwright 来截图画画，它需要一个浏览器核心。
```bash
playwright install chromium
```

57
docs/index.md
View File

@@ -1,39 +1,38 @@
# NEO Bot 开发文档
嘿，朋友，欢迎来到 NEO Bot
欢迎来到 NEO Bot Framework 开发文档！
这里没那么多规矩。这份文档是我写给你——未来的插件开发者、或者单纯好奇想拆开看看的家伙——的一份地图
这是一个现代化的 Python QQ 机器人框架，基于 OneBot v11 协议，采用异步架构和性能优化技术。无论你是想快速搭建机器人，还是深入了解框架设计，这份文档都能帮助你。
## 📖 地图导览
## 📖 文档导览
### 1. 准备阶段
* [快速上手](./getting-started.md): 搭环境、装东西、启动。跟着走一遍，能省不少事。
* [项目怎么样](./project-structure.md): 看看各个文件夹都是干嘛的，免得迷路。
* [生产环境](./deployment.md): 怎么把你调教好的 Bot 扔服务器上，让它自己 7x24 小时跑。
### 🚀 快速开始
* [快速上手](./getting-started.md) - 5分钟搭建开发环境
* [项目结构](./project-structure.md) - 了解代码组织方式
* [生产部署](./deployment.md) - 将Bot部署到服务器
### 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`... 认识这些核心模块。
* [Redis 原子操作与数据一致性](./core-concepts/redis-atomic-operations.md): 权限管理系统的原子操作实现，确保数据一致性
* [错误处理](./core-concepts/error-handling.md): 了解系统的错误处理机制和错误码定义。
### 💡 核心概念
* [架构设计](./core-concepts/architecture.md) - 了解框架的设计理念
* [性能优化](./core-concepts/performance.md) - JIT、Mypyc、页面池等优化技术
* [事件流程](./core-concepts/event-flow.md) - 一条消息从接收到回复的完整流程
* [核心管理器](./core-concepts/singleton-managers.md) - matcher、权限管理、浏览器池等
* [Redis原子操作](./core-concepts/redis-atomic-operations.md) - 权限管理的分布式实现
* [错误处理](./core-concepts/error-handling.md) - 异常处理和错误码体系
### 3. API 参考
* [API 总览](./api/index.md): 所有 API 的快速导航和调用方式
* [消息 API](./api/message.md): 发消息、撤回、转发、合并转发
* [群组 API](./api/group.md): 管群、禁言、踢人、改名片
* [好友 API](./api/friend.md): 好友列表、点赞、加好友请求
* [账号 API](./api/account.md): 机器人自己的信息、状态设置
* [媒体 API](./api/media.md): 图片、语音相关
### 🔌 API 参考
* [API 总览](./api/index.md) - API 调用方式和快速导航
* [消息 API](./api/message.md) - 发送、撤回、转发消息
* [群组 API](./api/group.md) - 群管理、禁言、踢人等
* [好友 API](./api/friend.md) - 好友列表、点赞等
* [账号 API](./api/account.md) - 机器人自身信息获取
* [媒体 API](./api/media.md) - 图片、语音、视频处理
### 4. 插件开发
* [插件开发第一步](./plugin-development/index.md): 带你写第一个插件
* [指南](./plugin-development/command-handling.md): 怎么教你的 Bot 听懂指令和参数。
* [绝对不要做的事情](./plugin-development/best-practices.md): **（必读！）**
### 📚 插件开发
* [插件入门](./plugin-development/index.md) - 写你的第一个插件
* [指令处理](./plugin-development/command-handling.md) - 参数解析、权限控制等
* [最佳实践](./plugin-development/best-practices.md) - 避免常见的坑
* [插件案例：状态监控](./plugin-development/status-plugin.md) - 深入学习复杂插件实现
## 贡献
发现 Bug 了？觉得文档写得烂？
直接提 Issue 或者 PR。代码质量是第一位的，Talk is cheap, show me the code.
### 📋 开发规范
* [开发规范](./development-standards.md) - 代码风格、异步编程、错误处理规范

148
docs/project-structure.md
View File

@@ -5,44 +5,136 @@
```
.
├── core/ # 核心代码，别乱动
│ ├── api/ # OneBot API 封装（消息、群组、好友、账号、媒体）
│ ├── handlers/ # 底层事件处理器
│ ├── managers/ # 全局单例管理器
│ ├── utils/ # 工具函数
│ └── ws.py # WebSocket 连接实现
├── data/ # 存放持久化数据
│ │ ├── command_manager.py # 指令分发和事件处理
│ │ ├── plugin_manager.py # 插件加载和热重载
│ │ ├── permission_manager.py # 权限管理（Admin/User两级）
│ │ ├── browser_manager.py # Playwright页面池
│ │ ├── image_manager.py # 图片/HTML模板渲染
│ │ └── redis_manager.py # Redis缓存管理
│ ├── utils/ # 工具函数和异常类
│ │ ├── logger.py # 日志系统（Loguru）
│ │ ├── performance.py # 性能分析工具
│ │ ├── executor.py # 代码沙箱执行引擎（Docker）
│ │ ├── exceptions.py # 自定义异常类
│ │ └── singleton.py # 单例模式基类
│ ├── ws.py # WebSocket 连接和消息处理（已Mypyc编译）
│ ├── bot.py # Bot 核心实例
│ ├── config_loader.py # 配置文件加载
│ ├── config_models.py # 配置数据模型
│ └── permission.py # 权限枚举类
│
├── data/ # 持久化数据
│ ├── admin.json # 管理员列表
│ └── permissions.json # 用户权限列表
├── docs/ # 开发文档
├── logs/ # 日志文件
│ └── permissions.json # 用户权限配置
│
├── models/ # 数据模型
│ └── events/ # OneBot 事件模型
├── plugins/ # 你的插件都放这
├── templates/ # 图片渲染用的网页模板
├── venv/ # Python 虚拟环境
├── .gitignore # Git 忽略配置
├── main.py # 主入口文件
├── requirements.txt # Python 依赖列表
└── setup_mypyc.py # [可选] Mypyc 编译脚本，用于将核心模块编译为 C 扩展以提升性能
│ ├── events/ # OneBot 11 事件模型
│ │ ├── message.py # 消息事件
│ │ ├── notice.py # 通知事件
│ │ ├── request.py # 请求事件
│ │ └── factory.py # 事件工厂
│ ├── message.py # 消息段（CQ码）
│ ├── sender.py # 发送者信息
│ └── objects.py # API响应对象（群信息、用户信息等）
│
├── plugins/ # 你的插件都放这（最常修改的地方）
│ ├── admin.py # 权限管理（Admin/User两级权限）
│ ├── auto_approve.py # 自动同意好友请求和群邀请
│ ├── bot_status.py # Bot运行状态查询（图片形式）
│ ├── broadcast.py # 管理员专用广播功能（隐藏插件）
│ ├── code_py.py # Python代码沙箱执行（多行输入、图片输出）
│ ├── echo.py # Echo和点赞功能
│ ├── furry.py # Furry图片获取
│ ├── github_parser.py # GitHub仓库链接自动解析
│ ├── jrcd.py # 今日人品/长度查询（随机生成）
│ ├── thpic.py # 东方Project随机图片
│ ├── web_parser/ # 综合Web链接解析系统
│ │ ├── __init__.py # 主入口，自动检测链接
│ │ ├── parsers/ # 各平台解析器
│ │ │ ├── bili.py # B站视频/直播解析
│ │ │ ├── douyin.py # 抖音视频解析
│ │ │ └── github.py # GitHub仓库解析
│ │ └── utils.py # 解析工具函数
│ ├── sync_async_test_plugin.py # 异步同步混用测试（开发用）
│ └── resource/ # 插件资源文件
│
├── templates/ # Jinja2 HTML模板
│ ├── code_execution.html # 代码执行结果展示
│ ├── github_repo.html # GitHub仓库信息展示
│ ├── help.html # 帮助页面
│ └── status.html # Bot状态页面
│
├── web_static/ # 静态资源
│ └── html/ # HTML资源文件
│
├── logs/ # 日志输出目录
│ └── bot.log # 主日志文件
│
├── tests/ # 单元测试
│ ├── test_api.py # API功能测试
│ ├── test_bot.py # Bot核心测试
│ ├── test_command_manager.py # 指令管理器测试
│ ├── test_performance.py # 性能测试
│ └── ... # 其他测试文件
│
├── docs/ # 开发文档
│ ├── index.md # 文档首页
│ ├── getting-started.md # 快速上手
│ ├── project-structure.md # 项目结构（本文件）
│ ├── deployment.md # 生产环境部署
│ ├── core-concepts/ # 核心概念详解
│ ├── api/ # API参考文档
│ └── plugin-development/ # 插件开发指南
│
├── scripts/ # 工具脚本
│ ├── check_python_env.py # Python环境检查
│ ├── compile_machine_code.py # 机器码编译
│ └── export_requirements.py # 依赖导出
│
├── venv/ # Python 虚拟环境（git忽略）
├── __pycache__/ # Python缓存（git忽略）
├── .gitignore # Git忽略配置
├── main.py # 启动入口
├── config.toml # 配置文件（包含WS、Redis、Docker配置）
├── pytest.ini # 测试配置
├── requirements.txt # Python依赖列表
├── requirements-dev.txt # 开发依赖（包括pytest、mypy等）
├── setup_mypyc.py # Mypyc编译脚本（可选性能优化）
├── check_syntax.py # 语法检查脚本
├── profile_main.py # 性能分析脚本
├── test_performance_simple.py # 简单性能测试
├── sandbox.Dockerfile # 代码沙箱Docker镜像
├── LICENSE # 许可证
└── README.md # 项目README
```
## 重点目录说明
## 核心目录说明
### `core/`
### `core/` - 框架核心
不用修改这里，除非你想优化框架本身。所有功能都由这里的管理器提供：
- **managers/** - 全局单例（matcher、permission_manager、browser_manager等）
- **api/** - OneBot API 封装
- **handlers/** - 事件处理逻辑
这是框架的心脏。除非你知道自己在干嘛，否则别碰这里面的东西。大部分功能都由 `managers` 里的管理器提供，你只需要 `import` 它们就行。
### `plugins/` - 插件目录
**这是你最常待的地方**。所有业务功能都在这里，包括现有的15+个插件。
### `data/`
新建插件只需在这里添加 `.py` 文件，Bot 启动时会自动加载。支持热重载：修改后无需重启Bot。
存放一些 JSON 格式的数据。管理员和用户权限默认存在这里。如果你用 Redis，这些文件会作为备份。
### `data/` - 持久化数据
- `admin.json` - 管理员QQ号列表
- `permissions.json` - 用户权限配置
### `plugins/`
这些文件也会自动同步到 Redis 以加快访问速度。
**这是你最常待的地方**。你写的所有插件（`.py` 文件）都扔在这个目录里。Bot 启动时会自动加载这里的所有插件。
### `templates/` - 图片模板
使用 `ImageManager` 生成图片时，HTML模板放在这里。支持 Jinja2 模板语法。
### `templates/`
如果你要用 `ImageManager` 画图，就需要把 HTML 模板文件放在这里。
### `main.py`
程序的入口。负责加载配置、初始化管理器、启动 WebSocket 连接和 FastAPI 服务。
### `main.py` - 程序入口
- 加载配置文件
- 初始化各管理器和 WebSocket 连接
- 启动插件加载器和文件监控（热重载）
- 处理程序生命周期

352
plugins/bot_status.py
View File

@@ -7,7 +7,11 @@ import os
import psutil
import time
import asyncio
import socket
import platform
from datetime import datetime, timedelta
from functools import lru_cache
from typing import Optional
from core.bot import Bot
from core.managers.command_manager import matcher
@@ -16,7 +20,7 @@ from core.managers.redis_manager import redis_manager
from core.utils.executor import run_in_thread_pool
from core.utils.logger import logger
from models.events.message import MessageEvent, MessageSegment
from models.objects import LoginInfo, Status, VersionInfo
from models.objects import Status, VersionInfo
__plugin_meta__ = {
"name": "bot_status",
@@ -28,14 +32,17 @@ __plugin_meta__ = {
START_TIME = time.time()
# 获取当前进程
PROCESS = psutil.Process(os.getpid())
# 缓存bot昵称（12小时过期）
_nickname_cache: dict[str, tuple[str, float]] = {}
def _get_system_info():
"""
同步函数：使用 psutil 获取系统信息，避免阻塞事件循环。
优化：使用 interval=None 获取自上次调用以来的平均 CPU 使用率
"""
try:
# interval=1 会阻塞1秒，必须在线程池中运行
cpu_percent = psutil.cpu_percent(interval=1)
# interval=None 会返回自上次调用以来的平均值，不会阻塞
cpu_percent = psutil.cpu_percent(interval=None)
mem_info = psutil.virtual_memory()
bot_mem_mb = PROCESS.memory_info().rss / (1024 * 1024)
@@ -45,94 +52,112 @@ def _get_system_info():
# 网络信息
net_io = psutil.net_io_counters()
# 进程数
process_count = len(psutil.pids())
# CPU核心数
cpu_count = psutil.cpu_count(logical=True)
cpu_count_physical = psutil.cpu_count(logical=False)
return {
"cpu_percent": f"{cpu_percent:.1f}",
"cpu_count": cpu_count,
"cpu_count_physical": cpu_count_physical,
"mem_percent": f"{mem_info.percent:.1f}",
"mem_total": f"{mem_info.total / (1024**3):.1f}",
"mem_used": f"{mem_info.used / (1024**3):.1f}",
"mem_available": f"{mem_info.available / (1024**3):.1f}",
"bot_mem_mb": f"{bot_mem_mb:.2f}",
"disk_percent": f"{disk_usage.percent:.1f}",
"disk_total": f"{disk_usage.total / (1024**3):.1f}",
"disk_used": f"{disk_usage.used / (1024**3):.1f}",
"disk_free": f"{disk_usage.free / (1024**3):.1f}",
"net_sent": f"{net_io.bytes_sent / (1024**2):.1f}",
"net_recv": f"{net_io.bytes_recv / (1024**2):.1f}",
"process_count": process_count,
}
except Exception as e:
logger.error(f"获取系统信息失败: {e}")
return {
"cpu_percent": "N/A",
"mem_percent": "N/A",
"mem_total": "N/A",
"mem_used": "N/A",
"bot_mem_mb": "N/A",
"disk_percent": "N/A",
"disk_total": "N/A",
"disk_used": "N/A",
"net_sent": "N/A",
"net_recv": "N/A",
}
return _create_error_system_info("N/A")
@matcher.command("status", "状态")
async def handle_status(bot: Bot, event: MessageEvent, args: list[str]):
async def _get_bot_nickname(bot: Bot) -> str:
"""
处理 status 指令，生成并回复机器人状态图片。
异步获取bot昵称，带缓存机制（12小时过期）
"""
logger.info(f"收到用户 {event.user_id} 的状态查询指令，开始生成状态图...")
cache_key = f"bot_{bot.self_id}"
now = time.time()
# 检查缓存是否有效
if cache_key in _nickname_cache:
nickname, timestamp = _nickname_cache[cache_key]
if now - timestamp < 43200: # 12小时
return nickname
# 优先使用 get_stranger_info，更轻量
try:
# 1. 获取API信息 (增加独立错误处理)
# 尝试获取或更新 bot.nickname
if not hasattr(bot, "nickname") or not bot.nickname:
try:
# 优先使用 get_stranger_info 获取自身信息，比 get_login_info 更轻量
stranger_info = await bot.get_stranger_info(user_id=bot.self_id)
bot.nickname = stranger_info.nickname
except Exception as e:
logger.warning(f"获取 stranger_info 失败: {e}, 将回退到 login_info")
nickname = stranger_info.nickname
except Exception:
try:
login_info = await bot.get_login_info()
bot.nickname = login_info.nickname
except Exception as e2:
logger.warning(f"获取 login_info 也失败了: {e2}")
bot.nickname = "获取失败"
nickname = bot.nickname
# 状态信息：如果能响应此命令，说明机器人必然在线且状态良好
# 这避免了依赖可能超时或未实现的 get_status API
logger.debug("正在推断机器人状态...")
status_info = Status(online=True, good=True)
logger.debug(f"推断状态成功: online={status_info.online}, good={status_info.good}")
try:
version_info = await bot.get_version_info()
nickname = login_info.nickname
except Exception as e:
logger.warning(f"获取 version_info 失败: {e}")
version_info = VersionInfo(app_name="获取失败", app_version="N/A", protocol_version="N/A")
logger.warning(f"获取bot昵称失败: {e}")
nickname = "获取失败"
# 2. 计算运行时长
uptime_seconds = int(time.time() - START_TIME)
_nickname_cache[cache_key] = (nickname, now)
return nickname
async def _get_bot_info(bot: Bot, start_time: float) -> dict:
"""
收集bot信息（id、昵称、头像、启动时间等）
"""
nickname = await _get_bot_nickname(bot)
uptime_seconds = int(time.time() - start_time)
uptime_delta = timedelta(seconds=uptime_seconds)
days = uptime_delta.days
hours, remainder = divmod(uptime_delta.seconds, 3600)
minutes, seconds = divmod(remainder, 60)
uptime_str = f"{days}天 {hours:02}:{minutes:02}:{seconds:02}"
bot_info_data = {
return {
"user_id": bot.self_id,
"nickname": nickname,
"avatar_url": f"https://q1.qlogo.cn/g?b=qq&nk={bot.self_id}&s=640",
"start_time": datetime.fromtimestamp(START_TIME).strftime("%Y-%m-%d %H:%M:%S"),
"start_time": datetime.fromtimestamp(start_time).strftime("%Y-%m-%d %H:%M:%S"),
"uptime": uptime_str,
}
# 3. 获取统计数据
async def _get_version_info(bot: Bot) -> dict:
"""
获取版本信息，失败时返回默认值
"""
try:
version_info = await bot.get_version_info()
return {
"app_name": version_info.app_name,
"app_version": version_info.app_version,
"protocol_version": version_info.protocol_version,
}
except Exception as e:
logger.warning(f"获取版本信息失败: {e}")
return {
"app_name": "获取失败",
"app_version": "N/A",
"protocol_version": "N/A",
}
async def _get_stats(redis_manager) -> tuple[dict, list]:
"""
获取统计数据和命令排行
"""
try:
msgs_recv = await redis_manager.get("neobot:stats:messages_received") or 0
msgs_sent = await redis_manager.get("neobot:stats:messages_sent") or 0
command_stats_raw = await redis_manager.redis.hgetall("neobot:command_stats")
total_commands = sum(int(v) for v in command_stats_raw.values())
total_commands = sum(int(v) for v in command_stats_raw.values()) if command_stats_raw else 0
stats_data = {
"messages_received": int(msgs_recv),
@@ -144,60 +169,216 @@ async def handle_status(bot: Bot, event: MessageEvent, args: list[str]):
[{"name": k, "count": int(v)} for k, v in command_stats_raw.items()],
key=lambda x: x["count"],
reverse=True
)
) if command_stats_raw else []
return stats_data, command_stats_data
except Exception as e:
logger.error(f"获取Redis统计数据失败: {e}")
stats_data = {
logger.error(f"获取统计数据失败: {e}")
return {
"messages_received": 0,
"messages_sent": 0,
"total_commands": 0,
}
command_stats_data = []
}, []
# 4. 异步获取系统信息
# 设置超时，防止 psutil 阻塞过久
async def _get_system_info_async(timeout: float = 3.0) -> dict:
"""
异步获取系统信息，带超时控制
"""
try:
system_data = await asyncio.wait_for(run_in_thread_pool(_get_system_info), timeout=5.0)
system_data = await asyncio.wait_for(
run_in_thread_pool(_get_system_info),
timeout=timeout
)
return system_data
except asyncio.TimeoutError:
logger.error("获取系统信息超时")
system_data = {
"cpu_percent": "Timeout",
"mem_percent": "Timeout",
"mem_total": "Timeout",
"mem_used": "Timeout",
"bot_mem_mb": "Timeout",
"disk_percent": "Timeout",
"disk_total": "Timeout",
"disk_used": "Timeout",
"net_sent": "Timeout",
"net_recv": "Timeout",
}
return _create_error_system_info("Timeout")
except Exception as e:
logger.error(f"获取系统信息异常: {e}")
system_data = {
"cpu_percent": "Error",
"mem_percent": "Error",
"mem_total": "Error",
"mem_used": "Error",
"bot_mem_mb": "Error",
"disk_percent": "Error",
"disk_total": "Error",
"disk_used": "Error",
"net_sent": "Error",
"net_recv": "Error",
return _create_error_system_info("Error")
async def _get_network_info_async() -> dict:
"""
异步获取网络信息
"""
try:
return await asyncio.wait_for(
run_in_thread_pool(_get_network_info),
timeout=2.0
)
except Exception as e:
logger.error(f"获取网络信息异常: {e}")
return {
"hostname": "获取失败",
"local_ip": "获取失败",
"public_ip": "获取失败",
}
# 5. 准备模板所需的所有数据
async def _get_os_info_async() -> dict:
"""
异步获取操作系统信息
"""
try:
return await asyncio.wait_for(
run_in_thread_pool(_get_os_info),
timeout=2.0
)
except Exception as e:
logger.error(f"获取操作系统信息异常: {e}")
return {
"os_name": "获取失败",
"os_version": "获取失败",
"os_arch": "获取失败",
"python_version": "获取失败",
}
def _create_error_system_info(error_msg: str = "N/A") -> dict:
"""
创建错误状态的系统信息字典
"""
return {
"cpu_percent": error_msg,
"cpu_count": error_msg,
"cpu_count_physical": error_msg,
"mem_percent": error_msg,
"mem_total": error_msg,
"mem_used": error_msg,
"mem_available": error_msg,
"bot_mem_mb": error_msg,
"disk_percent": error_msg,
"disk_total": error_msg,
"disk_used": error_msg,
"disk_free": error_msg,
"net_sent": error_msg,
"net_recv": error_msg,
"process_count": error_msg,
}
def _get_network_info():
"""
获取网络信息（IP地址、主机名等）
"""
try:
hostname = socket.gethostname()
# 获取本地IP
try:
local_ip = socket.gethostbyname(hostname)
except:
local_ip = "获取失败"
# 尝试获取公网IP（通过连接外部DNS）
try:
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.connect(("8.8.8.8", 80))
public_ip = s.getsockname()[0]
s.close()
except:
public_ip = "无法获取"
return {
"hostname": hostname,
"local_ip": local_ip,
"public_ip": public_ip,
}
except Exception as e:
logger.error(f"获取网络信息失败: {e}")
return {
"hostname": "获取失败",
"local_ip": "获取失败",
"public_ip": "获取失败",
}
def _get_os_info():
"""
获取操作系统信息
"""
try:
os_name = platform.system()
os_version = platform.release()
os_arch = platform.machine()
python_version = platform.python_version()
return {
"os_name": os_name,
"os_version": os_version,
"os_arch": os_arch,
"python_version": python_version,
}
except Exception as e:
logger.error(f"获取操作系统信息失败: {e}")
return {
"os_name": "获取失败",
"os_version": "获取失败",
"os_arch": "获取失败",
"python_version": "获取失败",
}
@matcher.command("status", "状态")
async def handle_status(bot: Bot, event: MessageEvent, args: list[str]):
"""
处理 status 指令，生成并回复机器人状态图片。
优化：并发获取各项数据，提升响应速度
"""
logger.info(f"收到用户 {event.user_id} 的状态查询指令，开始生成状态图...")
try:
# 并发获取所有数据，提升性能
bot_info, version_info, stats_result, system_data, network_info, os_info = await asyncio.gather(
_get_bot_info(bot, START_TIME),
_get_version_info(bot),
_get_stats(redis_manager),
_get_system_info_async(timeout=3.0),
_get_network_info_async(),
_get_os_info_async(),
return_exceptions=False
)
# 处理 _get_stats 返回的元组
if isinstance(stats_result, Exception):
logger.error(f"获取统计数据失败: {stats_result}")
stats_data, command_stats_data = {"messages_received": 0, "messages_sent": 0, "total_commands": 0}, []
else:
stats_data, command_stats_data = stats_result
# 处理异常返回值
if isinstance(system_data, Exception):
logger.error(f"获取系统信息失败: {system_data}")
system_data = _create_error_system_info("Error")
if isinstance(network_info, Exception):
logger.error(f"获取网络信息失败: {network_info}")
network_info = {
"hostname": "获取失败",
"local_ip": "获取失败",
"public_ip": "获取失败",
}
if isinstance(os_info, Exception):
logger.error(f"获取操作系统信息失败: {os_info}")
os_info = {
"os_name": "获取失败",
"os_version": "获取失败",
"os_arch": "获取失败",
"python_version": "获取失败",
}
# 推断机器人状态（能响应此命令说明在线且状态良好）
status_info = Status(online=True, good=True)
# 准备模板数据
template_data = {
"bot_info": bot_info_data,
"bot_info": bot_info,
"status_info": status_info,
"version_info": version_info,
"stats": stats_data,
"system": system_data,
"network": network_info,
"os": os_info,
"command_stats": command_stats_data,
}
# 6. 渲染图片
# 渲染图片
try:
base64_str = await image_manager.render_template_to_base64(
template_name="status.html",
@@ -209,8 +390,7 @@ async def handle_status(bot: Bot, event: MessageEvent, args: list[str]):
if base64_str:
await event.reply(MessageSegment.image(base64_str))
else:
# 如果渲染失败，image_manager 内部会记录错误，这里给用户一个通用提示
await event.reply("状态图片生成失败，可能是渲染服务出现问题，请联系管理员。")
await event.reply("状态图片生成失败，请稍后重试或联系管理员。")
except Exception as e:
logger.error(f"渲染图片失败: {e}")
await event.reply("状态图片渲染过程中发生错误。")

61
templates/status.html
View File

@@ -141,6 +141,11 @@
column-count: 2;
column-gap: 24px;
}
.multi-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 24px;
}
.footer {
margin-top: auto;
padding: 32px 40px;
@@ -221,10 +226,18 @@
<span class="info-label">CPU 占用</span>
<span class="info-value">{{ system.cpu_percent }}%</span>
</li>
<li class="info-item">
<span class="info-label">CPU 核心</span>
<span class="info-value">{{ system.cpu_count }} ({{ system.cpu_count_physical }} 物理)</span>
</li>
<li class="info-item">
<span class="info-label">内存占用</span>
<span class="info-value">{{ system.mem_percent }}% ({{ system.mem_used }}G / {{ system.mem_total }}G)</span>
</li>
<li class="info-item">
<span class="info-label">可用内存</span>
<span class="info-value">{{ system.mem_available }}G</span>
</li>
<li class="info-item">
<span class="info-label">Bot 进程内存</span>
<span class="info-value">{{ system.bot_mem_mb }} MB</span>
@@ -233,10 +246,18 @@
<span class="info-label">磁盘占用</span>
<span class="info-value">{{ system.disk_percent }}% ({{ system.disk_used }}G / {{ system.disk_total }}G)</span>
</li>
<li class="info-item">
<span class="info-label">磁盘可用</span>
<span class="info-value">{{ system.disk_free }}G</span>
</li>
<li class="info-item">
<span class="info-label">网络流量 (↑/↓)</span>
<span class="info-value">{{ system.net_sent }}MB / {{ system.net_recv }}MB</span>
</li>
<li class="info-item">
<span class="info-label">进程总数</span>
<span class="info-value">{{ system.process_count }}</span>
</li>
</ul>
</div>
@@ -257,6 +278,46 @@
</li>
</ul>
</div>
<div class="status-card">
<h2 class="card-title">网络信息 (Network)</h2>
<ul class="info-list">
<li class="info-item">
<span class="info-label">主机名</span>
<span class="info-value">{{ network.hostname }}</span>
</li>
<li class="info-item">
<span class="info-label">本地 IP</span>
<span class="info-value">{{ network.local_ip }}</span>
</li>
<li class="info-item">
<span class="info-label">公网 IP</span>
<span class="info-value">{{ network.public_ip }}</span>
</li>
</ul>
</div>
<div class="status-card">
<h2 class="card-title">操作系统 (OS)</h2>
<ul class="info-list">
<li class="info-item">
<span class="info-label">系统</span>
<span class="info-value">{{ os.os_name }}</span>
</li>
<li class="info-item">
<span class="info-label">版本</span>
<span class="info-value">{{ os.os_version }}</span>
</li>
<li class="info-item">
<span class="info-label">架构</span>
<span class="info-value">{{ os.os_arch }}</span>
</li>
<li class="info-item">
<span class="info-label">Python 版本</span>
<span class="info-value">{{ os.python_version }}</span>
</li>
</ul>
</div>
</div>
<div class="status-card">