From f4df1989deabc0682277d923e288776d7a00b2a4 Mon Sep 17 00:00:00 2001 From: K2Cr2O1 <2221577113@qq.com> Date: Tue, 24 Mar 2026 12:01:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=92=8C=E9=A1=B9=E7=9B=AE=E7=BB=93=E6=9E=84?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加反向WebSocket连接模式说明 补充核心管理器文档 更新项目结构文件 在文档首页添加特色功能说明 --- docs/project-structure.md | 162 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/project-structure.md diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 0000000..43bc987 --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,162 @@ +# 项目结构 + +了解项目里每个文件夹是干嘛的，能让你更快找到代码。 + +``` +. +├── adapters/ # 适配器层（多平台支持） +│ ├── discord_adapter.py # Discord 适配器 +│ └── router.py # 消息路由 +│ +├── core/ # 核心代码，别乱动 +│ ├── api/ # OneBot API 封装（消息、群组、好友、账号、媒体） +│ ├── handlers/ # 底层事件处理器 +│ ├── managers/ # 全局单例管理器 +│ │ ├── bot_manager.py # Bot 实例管理 +│ │ ├── browser_manager.py # Playwright页面池 +│ │ ├── command_manager.py # 指令分发和事件处理 +│ │ ├── image_manager.py # 图片/HTML模板渲染 +│ │ ├── 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 # 性能分析工具 +│ │ └── singleton.py # 单例模式基类 +│ ├── ws.py # WebSocket 连接和消息处理 +│ ├── bot.py # Bot 核心实例 +│ ├── config_loader.py # 配置文件加载 +│ ├── config_models.py # 配置数据模型 +│ └── permission.py # 权限枚举类 +│ +├── models/ # 数据模型 +│ ├── events/ # OneBot 11 事件模型 +│ │ ├── base.py # 基础事件模型 +│ │ ├── factory.py # 事件工厂 +│ │ ├── message.py # 消息事件 +│ │ ├── meta.py # 元事件 +│ │ ├── notice.py # 通知事件 +│ │ └── request.py # 请求事件 +│ ├── message.py # 消息段（CQ码） +│ ├── objects.py # API响应对象（群信息、用户信息等） +│ └── sender.py # 发送者信息 +│ +├── plugins/ # 你的插件都放这（最常修改的地方） +│ ├── admin.py # 权限管理（Admin/User两级权限） +│ ├── auto_approve.py # 自动同意好友请求和群邀请 +│ ├── 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随机图片 +│ ├── 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状态页面 +│ └── weather.html # 天气展示页面 +│ +├── web_static/ # 静态资源 +│ ├── changelog.html # 更新日志页面 +│ ├── changelog_generator/# 更新日志生成器 +│ └── html/ # HTML资源文件 +│ +├── 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/ # 开发文档 +│ ├── api/ # API参考文档 +│ ├── 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 # 依赖导出 +│ +├── bili_login.py # B站登录脚本 +├── DEEPSEEK_API_SETUP.md # DeepSeek API 设置文档 +├── main.py # 启动入口 +├── pyproject.toml # 项目配置 +├── requirements.txt # Python依赖列表 +├── requirements-dev.txt # 开发依赖 +├── sandbox.Dockerfile # 代码沙箱Docker镜像 +├── LICENSE # 许可证 +└── README.md # 项目README +``` + +## 核心目录说明 + +### `core/` - 框架核心 +不用修改这里，除非你想优化框架本身。所有功能都由这里的管理器提供： +- **managers/** - 全局单例（matcher、permission_manager、browser_manager等） +- **api/** - OneBot API 封装 +- **handlers/** - 事件处理逻辑 + +### `plugins/` - 插件目录 +**这是你最常待的地方**。所有业务功能都在这里，包括现有的15+个插件。 + +新建插件只需在这里添加 `.py` 文件，Bot 启动时会自动加载。支持热重载：修改后无需重启Bot。 + +### `data/` - 持久化数据 +- `admin.json` - 管理员QQ号列表 +- `permissions.json` - 用户权限配置 + +这些文件也会自动同步到 Redis 以加快访问速度。 + +### `templates/` - 图片模板 +使用 `ImageManager` 生成图片时，HTML模板放在这里。支持 Jinja2 模板语法。 + +### `main.py` - 程序入口 +- 加载配置文件 +- 初始化各管理器和 WebSocket 连接 +- 启动插件加载器和文件监控（热重载） +- 处理程序生命周期