feat(docs): 更新文档，添加项目结构和部署指南，优化快速上手部分
This commit is contained in:
@@ -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 连接
|
||||
- 启动插件加载器和文件监控（热重载）
|
||||
- 处理程序生命周期
|
||||
|
||||
Reference in New Issue
Block a user