NeoBot/docs/project-structure.md

项目结构

了解项目里每个文件夹是干嘛的，能让你更快找到代码。

.
├── core/                   # 核心代码，别乱动
│   ├── api/                # OneBot API 封装（消息、群组、好友、账号、媒体）
│   ├── handlers/           # 底层事件处理器
│   ├── managers/           # 全局单例管理器
│   │   ├── 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    # 用户权限配置
│
├── models/                 # 数据模型
│   ├── 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/ - 框架核心

不用修改这里，除非你想优化框架本身。所有功能都由这里的管理器提供：

• 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 连接
• 启动插件加载器和文件监控（热重载）
• 处理程序生命周期