diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index d1c1dc7..27e905b 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -47,9 +47,12 @@ python setup_mypyc.py build_ext --inplace ## 2. 连接架构 -### 正向 WebSocket 连接 +### WebSocket 连接模式 -NEO Bot 采用**正向 WebSocket 连接**模式：Bot 主动连接 OneBot 实现（如 NapCatQQ）。 +NEO Bot 支持两种 WebSocket 连接模式，可根据需求在 `config.toml` 中配置： + +#### 1. 正向 WebSocket 连接 (默认) +Bot 主动连接 OneBot 实现（如 NapCatQQ）。 **流程**： @@ -63,6 +66,23 @@ Bot 启动 → 连接到 NapCatQQ (ws://127.0.0.1:3001) 调用 API 回复 ``` +#### 2. 反向 WebSocket 连接 +OneBot 客户端主动连接 Bot 提供的 WebSocket 服务。 + +**流程**： + +``` +Bot 启动反向 WS 服务 (监听 0.0.0.0:3002) + ↓ +NapCatQQ 主动连接到 Bot + ↓ + 监听消息事件 + ↓ + 分发到处理器 + ↓ + 调用 API 回复 +``` + ## 3. 资源管理架构 ### 单例管理器 diff --git a/docs/core-concepts/singleton-managers.md b/docs/core-concepts/singleton-managers.md index 9801c3b..ce98f82 100644 --- a/docs/core-concepts/singleton-managers.md +++ b/docs/core-concepts/singleton-managers.md @@ -65,6 +65,34 @@ * **记性好**: 模板用一次就记住，下次直接用缓存。 * **自动借还**: 它会自动找 `BrowserManager` 借页面，你只管 `render_template` 就行。 +### 8. `BotManager` (`bot_manager`) + +* **怎么找**: `from core.managers.bot_manager import bot_manager` +* **管啥**: + * **Bot 实例管理**: 统一管理 Bot 实例，方便在任何地方获取当前运行的 Bot。 + * **生命周期**: 协助管理 Bot 的启动和关闭流程。 + +### 9. `MysqlManager` (`mysql_manager`) + +* **怎么找**: `from core.managers.mysql_manager import mysql_manager` +* **管啥**: + * **数据库连接**: 管理与 MySQL 数据库的异步连接池。 + * **数据持久化**: 提供执行 SQL 语句的接口，用于需要长期保存的数据。 + +### 10. `ReverseWsManager` (`reverse_ws_manager`) + +* **怎么找**: `from core.managers.reverse_ws_manager import reverse_ws_manager` +* **管啥**: + * **反向 WS 服务**: 启动并管理反向 WebSocket 服务器，允许 OneBot 客户端主动连接 Bot。 + * **连接管理**: 处理客户端的连接、断开和消息接收。 + +### 11. `ThreadManager` (`thread_manager`) + +* **怎么找**: `from core.managers.thread_manager import thread_manager` +* **管啥**: + * **线程池管理**: 提供全局的线程池执行器，用于执行阻塞的同步任务。 + * **异步桥接**: 方便地将同步函数转换为异步调用，避免阻塞事件循环。 + ## 咋用？ `import` diff --git a/docs/index.md b/docs/index.md index c9c848b..2ef6b32 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ * [架构设计](./core-concepts/architecture.md) - 了解框架的设计理念 * [性能优化](./core-concepts/performance.md) - JIT、Mypyc、页面池等优化技术 * [事件流程](./core-concepts/event-flow.md) - 一条消息从接收到回复的完整流程 -* [核心管理器](./core-concepts/singleton-managers.md) - matcher、权限管理、浏览器池等 +* [核心管理器](./core-concepts/singleton-managers.md) - matcher、权限管理、浏览器池、数据库等 * [Redis原子操作](./core-concepts/redis-atomic-operations.md) - 权限管理的分布式实现 * [多线程架构](./core-concepts/multithreading.md) - 线程池和线程安全设计 * [错误处理](./core-concepts/error-handling.md) - 异常处理和错误码体系 @@ -29,6 +29,12 @@ * [账号 API](./api/account.md) - 机器人自身信息获取 * [媒体 API](./api/media.md) - 图片、语音、视频处理 +### 🌟 特色功能 +* **多平台互通** - 支持 Discord 与 QQ 频道的跨平台消息互通 +* **本地文件服务** - 内置轻量级 HTTP 文件服务器，方便传输大文件和媒体 +* **多数据库支持** - 同时支持 Redis 缓存和 MySQL 持久化存储 +* **反向 WebSocket** - 支持 OneBot 客户端主动连接 Bot + ### 📚 插件开发 * [插件入门](./plugin-development/index.md) - 写你的第一个插件 * [指令处理](./plugin-development/command-handling.md) - 参数解析、权限控制等 diff --git a/docs/project-structure.md b/docs/project-structure.md index 51a6da9..43bc987 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -4,41 +4,50 @@ ``` . +├── adapters/ # 适配器层（多平台支持） +│ ├── discord_adapter.py # Discord 适配器 +│ └── router.py # 消息路由 +│ ├── core/ # 核心代码，别乱动 │ ├── api/ # OneBot API 封装（消息、群组、好友、账号、媒体） │ ├── handlers/ # 底层事件处理器 │ ├── managers/ # 全局单例管理器 -│ │ ├── command_manager.py # 指令分发和事件处理 -│ │ ├── plugin_manager.py # 插件加载和热重载 -│ │ ├── permission_manager.py # 权限管理（Admin/User两级） +│ │ ├── bot_manager.py # Bot 实例管理 │ │ ├── browser_manager.py # Playwright页面池 +│ │ ├── command_manager.py # 指令分发和事件处理 │ │ ├── image_manager.py # 图片/HTML模板渲染 -│ │ └── redis_manager.py # Redis缓存管理 +│ │ ├── mysql_manager.py # MySQL 数据库管理 +│ │ ├── permission_manager.py # 权限管理（Admin/User两级） +│ │ ├── plugin_manager.py # 插件加载和热重载 +│ │ ├── redis_manager.py # Redis缓存管理 +│ │ ├── reverse_ws_manager.py # 反向 WebSocket 管理 +│ │ └── thread_manager.py # 线程池管理 +│ ├── services/ # 核心服务 +│ │ └── local_file_server.py # 本地文件服务 │ ├── utils/ # 工具函数和异常类 +│ │ ├── error_codes.py # 错误码定义 +│ │ ├── exceptions.py # 自定义异常类 +│ │ ├── executor.py # 代码沙箱执行引擎（Docker） │ │ ├── logger.py # 日志系统（Loguru） │ │ ├── performance.py # 性能分析工具 -│ │ ├── executor.py # 代码沙箱执行引擎（Docker） -│ │ ├── exceptions.py # 自定义异常类 │ │ └── singleton.py # 单例模式基类 -│ ├── ws.py # WebSocket 连接和消息处理（已Mypyc编译） +│ ├── ws.py # WebSocket 连接和消息处理 │ ├── bot.py # Bot 核心实例 │ ├── config_loader.py # 配置文件加载 │ ├── config_models.py # 配置数据模型 │ └── permission.py # 权限枚举类 │ -├── data/ # 持久化数据 -│ ├── admin.json # 管理员列表 -│ └── permissions.json # 用户权限配置 -│ ├── models/ # 数据模型 │ ├── events/ # OneBot 11 事件模型 +│ │ ├── base.py # 基础事件模型 +│ │ ├── factory.py # 事件工厂 │ │ ├── message.py # 消息事件 +│ │ ├── meta.py # 元事件 │ │ ├── notice.py # 通知事件 -│ │ ├── request.py # 请求事件 -│ │ └── factory.py # 事件工厂 +│ │ └── request.py # 请求事件 │ ├── message.py # 消息段（CQ码） -│ ├── sender.py # 发送者信息 -│ └── objects.py # API响应对象（群信息、用户信息等） +│ ├── objects.py # API响应对象（群信息、用户信息等） +│ └── sender.py # 发送者信息 │ ├── plugins/ # 你的插件都放这（最常修改的地方） │ ├── admin.py # 权限管理（Admin/User两级权限） @@ -46,66 +55,79 @@ │ ├── bot_status.py # Bot运行状态查询（图片形式） │ ├── broadcast.py # 管理员专用广播功能（隐藏插件） │ ├── code_py.py # Python代码沙箱执行（多行输入、图片输出） +│ ├── discord-cross/ # Discord 跨平台互通插件 │ ├── echo.py # Echo和点赞功能 │ ├── furry.py # Furry图片获取 │ ├── github_parser.py # GitHub仓库链接自动解析 +│ ├── group_welcome.py # 群欢迎插件 │ ├── jrcd.py # 今日人品/长度查询（随机生成） +│ ├── mirror_avatar.py # 镜像头像获取 +│ ├── osu!_plugin/ # osu! 相关功能插件 +│ ├── resource/ # 插件资源文件 │ ├── 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/ # 插件资源文件 +│ ├── weather.py # 天气查询插件 +│ └── web_parser/ # 综合Web链接解析系统 +│ ├── __init__.py # 主入口，自动检测链接 +│ ├── base.py # 解析器基类 +│ ├── parsers/ # 各平台解析器 +│ │ ├── bili.py # B站视频/直播解析 +│ │ ├── douyin.py # 抖音视频解析 +│ │ └── github.py # GitHub仓库解析 +│ └── utils.py # 解析工具函数 │ ├── templates/ # Jinja2 HTML模板 │ ├── code_execution.html # 代码执行结果展示 │ ├── github_repo.html # GitHub仓库信息展示 │ ├── help.html # 帮助页面 -│ └── status.html # Bot状态页面 +│ ├── status.html # Bot状态页面 +│ └── weather.html # 天气展示页面 │ ├── web_static/ # 静态资源 +│ ├── changelog.html # 更新日志页面 +│ ├── changelog_generator/# 更新日志生成器 │ └── html/ # HTML资源文件 │ -├── logs/ # 日志输出目录 -│ └── bot.log # 主日志文件 -│ ├── tests/ # 单元测试 │ ├── test_api.py # API功能测试 +│ ├── test_basic.py # 基础测试 │ ├── test_bot.py # Bot核心测试 │ ├── test_command_manager.py # 指令管理器测试 +│ ├── test_config_loader.py # 配置加载测试 +│ ├── test_core_managers.py # 核心管理器测试 +│ ├── test_event_factory.py # 事件工厂测试 +│ ├── test_event_handler.py # 事件处理器测试 +│ ├── test_executor.py # 执行器测试 +│ ├── test_models.py # 模型测试 │ ├── test_performance.py # 性能测试 -│ └── ... # 其他测试文件 +│ ├── test_plugin_manager_coverage.py # 插件管理器覆盖率测试 +│ ├── test_plugin_reload_meta.py # 插件重载测试 +│ ├── test_redis_manager.py # Redis管理器测试 +│ ├── test_thread_manager.py # 线程管理器测试 +│ ├── test_ws.py # WebSocket测试 +│ └── test_ws_pool.py # WebSocket池测试 │ ├── docs/ # 开发文档 -│ ├── index.md # 文档首页 -│ ├── getting-started.md # 快速上手 -│ ├── project-structure.md # 项目结构（本文件） -│ ├── deployment.md # 生产环境部署 -│ ├── core-concepts/ # 核心概念详解 │ ├── api/ # API参考文档 -│ └── plugin-development/ # 插件开发指南 +│ ├── core-concepts/ # 核心概念详解 +│ ├── plugin-development/ # 插件开发指南 +│ ├── deployment.md # 生产环境部署 +│ ├── development-standards.md # 开发规范 +│ ├── getting-started.md # 快速上手 +│ ├── index.md # 文档首页 +│ └── project-structure.md # 项目结构（本文件） │ ├── scripts/ # 工具脚本 +│ ├── add_plugins.py # 添加插件脚本 │ ├── check_python_env.py # Python环境检查 │ ├── compile_machine_code.py # 机器码编译 │ └── export_requirements.py # 依赖导出 │ -├── venv/ # Python 虚拟环境（git忽略） -├── __pycache__/ # Python缓存（git忽略） -├── .gitignore # Git忽略配置 +├── bili_login.py # B站登录脚本 +├── DEEPSEEK_API_SETUP.md # DeepSeek API 设置文档 ├── main.py # 启动入口 -├── config.toml # 配置文件（包含WS、Redis、Docker配置） -├── pytest.ini # 测试配置 +├── pyproject.toml # 项目配置 ├── requirements.txt # Python依赖列表 -├── requirements-dev.txt # 开发依赖（包括pytest、mypy等） -├── setup_mypyc.py # Mypyc编译脚本（可选性能优化） -├── check_syntax.py # 语法检查脚本 -├── profile_main.py # 性能分析脚本 -├── test_performance_simple.py # 简单性能测试 +├── requirements-dev.txt # 开发依赖 ├── sandbox.Dockerfile # 代码沙箱Docker镜像 ├── LICENSE # 许可证 └── README.md # 项目README