ElainaQQ

面向多账号场景的异步 QQ 机器人框架，统一支持内置 QQ、QQ 注入、OneBot v11 和 Lagrange。

项目仅供学习交流，请遵守所在地法律、QQ 平台规则及相关服务条款。

特性

• 四种接入统一进入同一事件管线，插件不再感知渠道差异。
• 支持群聊、私聊、自身消息、通知、请求和元事件。
• 支持多账号路由、插件热重载、Web 管理和日志持久化。
• 对消息字段、消息段、动作响应、顺序和幂等进行统一规范化。

快速开始

环境要求：Python 3.11+、Git，以及当前系统可运行的 QQ 环境。

git clone https://github.com/ElainaCore/Elaina_QQBot.git ElainaQQ
cd ElainaQQ
python -m pip install -r requirements.txt
python main.py

启动后访问 http://localhost:5201/web/，首次管理密码会写入 config/settings.yaml。

配置文件由 config/*.example.yaml 自动生成，字段说明只保留在对应 YAML 中。

框架与扩展依赖

框架仅依赖 aiohttp、PyYAML 和 psutil。PIL 对应的 Pillow、绘图库及其他插件专用包不属于框架依赖。

start.bat、start.sh 默认只安装项目根目录的依赖清单，不再递归安装所有插件、模块的依赖。使用扩展时，用框架所在虚拟环境的 Python 安装对应扩展的 requirements.txt：

python -m pip install -r "plugins/插件目录/requirements.txt"

需要沿用批量安装全部扩展依赖的行为时，在启动前设置环境变量 ELAINAQQ_INSTALL_EXTENSION_DEPS=1。已有环境中的包不会自动卸载，以免影响已安装插件；要使用干净的最小环境，请创建新的虚拟环境并只安装根目录的 requirements.txt。

接入链路

内置 QQ ─┐
QQ 注入 ─┼─> 渠道适配 ─> EventPipeline ─> EventDispatcher ─> 插件
OneBot  ─┤
Lagrange─┘

所有入口先锁定 OneBot 固定字段，再执行短期幂等和会话有序分发；渠道差异只存在于入口转换与动作执行器。

目录

core/foundation   配置、日志和安全基础设施
core/protocols    OneBot 事件、消息、动作和连接契约
core/runtime      应用生命周期与 QQ 运行时
core/plugins      插件加载、分发和公开接口
core/services     文件、日志和监视服务
core/transport    HTTP 与 WebSocket 传输
web               Web 面板后端与构建产物
plugins           插件
modules           模块
tests             回归测试
docs              开发参考

最简插件

创建 plugins/hello/main.py：

from core.plugins import handler


@handler(r'^你好$', name='打招呼')
async def say_hello(event, match):
    await event.reply('你好！')

插件只应从 core.plugins 导入公开能力，保存 Python 文件后会自动热重载。

文档

• 开发文档索引
• 架构边界
• 插件开发
• OneBot API

Web 前端源码位于 Elaina_QQBot_web，插件市场索引位于 Elaina-plugins。

安全

• 公网部署必须配置强密码、OneBot Token/Secret、TLS 和访问控制。
• 不要提交账号目录、Token、Cookie、二维码、日志或插件私有数据。
• 插件和模块属于可执行代码，只安装可信来源。

反馈

请通过 Issues 提交问题，并附带系统、Python 版本、接入渠道、日志和复现步骤。

本项目采用 MIT License。