From f2bf1e4ca5219b8668989f4d6566b9c38178a38b Mon Sep 17 00:00:00 2001 From: K2cr2O1 <2221577113@qq.com> Date: Thu, 29 Jan 2026 21:35:20 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE=E7=BB=93?= =?UTF-8?q?=E6=9E=84=E5=92=8C=E9=83=A8=E7=BD=B2=E6=8C=87=E5=8D=97=EF=BC=8C?= =?UTF-8?q?=E4=BC=98=E5=8C=96=E5=BF=AB=E9=80=9F=E4=B8=8A=E6=89=8B=E9=83=A8?= =?UTF-8?q?=E5=88=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 52 ++++--- docs/core-concepts/architecture.md | 110 ++++++++------ docs/deployment.md | 229 +++++++++++++++++++++++------ docs/getting-started.md | 27 +--- docs/index.md | 57 ++++--- docs/project-structure.md | 148 +++++++++++++++---- 6 files changed, 437 insertions(+), 186 deletions(-) diff --git a/README.md b/README.md index 4b3c61f..3aacd20 100644 --- a/README.md +++ b/README.md @@ -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 # 启动入口 ``` diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 9d42c90..d1c1dc7 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -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. 技术栈全景 diff --git a/docs/deployment.md b/docs/deployment.md index 62e8d2f..cc829bf 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -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 +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 7f30bde..ca2910b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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 ``` diff --git a/docs/index.md b/docs/index.md index 4483aaf..7a27231 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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) - 代码风格、异步编程、错误处理规范 diff --git a/docs/project-structure.md b/docs/project-structure.md index 75362d3..51a6da9 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -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 连接 +- 启动插件加载器和文件监控（热重载） +- 处理程序生命周期