文档 / 架构
东西都在哪
三层:core(内核)→ api(管理接口)→ webui(静态面板),依赖只能自上往下。 机器人链路和面板链路共用同一份运行时状态。
数据流
消息入站
QQ 开放平台
│ WebSocket 网关
▼
qq-botpy SDK ──► core/bot.py ──► core/events.py ──► core/handlers.py ──► plugins/*.py
▲ │
└────────── event.reply() ◄──────────┘
│
消息出站 └──► core/bot.py ──► SDK ──► QQ
状态与日志
core/bot.py / api/* ──► core/state.py(内存环形缓冲 + sink)
│
▼
core/logstore.py(SQLite)
面板
webui ──► /api/*(FastAPI)──► core/state.py / core/logstore.py
└──► api/bot_manager.py ──► core/bot.py(启停)
一句话:botpy 把 QQ 事件交给 core/bot.py,转成语义事件后由 core/handlers.py 分发给插件;所有日志经 core/state.py 的 sink 落到 SQLite,面板通过 FastAPI 读状态、读日志、启停机器人。
模块职责
| 模块 | 输入 | 输出 | 不做什么 |
|---|---|---|---|
core/bot.py | AppID / AppSecret、运行时状态 | 网关连接;把 SDK 回调转成事件;连接状态与入站日志 | 不处理 HTTP、不读写数据库、不做关键字匹配 |
core/events.py | SDK 入站消息、回复闭包 | GroupAtMessage 或 None | 不拼 msg_id / msg_seq,不直接发送 |
core/handlers.py | 装饰器注册、事件对象 | 按关键字分发;异常写 ERROR 日志 | 不解析消息、不认识插件文件 |
core/plugins.py | 插件目录、安装请求 | 插件记录;安装 / 重载 / 删除 | 不做消息分发、不碰 HTTP 路由 |
core/state.py | 各模块写入的状态与日志 | 连接状态、插件列表、日志环形缓冲、监听者快照 | 不持久化(交给 sink)、不做鉴权 |
core/logstore.py | 日志条目、SDK 日志队列 | SQLite 中的可查询日志(分页 / 筛选 / 保留策略) | 不产出 HTTP 响应、不格式化前端 |
core/config.py | .env、进程环境变量 | 校验过的 Settings、令牌生成 | 不发网络请求、不读运行时状态 |
core/cli.py | 命令行参数 | init / doctor / start / token | 不实现业务逻辑,只做编排 |
api/main.py | Settings、插件目录、BotManager、LogStore | FastAPI 实例;lifespan 接日志 sink、按需自动连机器人 | 不直接调用 botpy |
api/deps.py | 请求头 | 令牌 / Content-Type / Origin 校验 | 不读业务数据 |
api/routes/* | HTTP 请求 | JSON:状态、日志、插件、配置、启停 | 不含机器人连接逻辑 |
webui/ | 用户操作 | 静态资源;数据全部走 /api/* | 不内嵌业务规则,不直连 QQ |
分层规则
- core 不 import api,也不依赖 FastAPI。
- api 不直接操作 botpy:启停统一走
api/bot_manager.py→core/bot.py。 - webui 只通过
/api/*与后端通信,不假设本地文件结构。 - 事件模型(
core/events.py)不依赖 botpy;SDK 类型只出现在core/bot.py边界。
几个关键约定
处理器异常隔离
Router.dispatch() 逐个执行命中的处理器,单个处理器抛异常会被捕获并写一条 ERROR(来源 handler),后续处理器继续执行——插件写错不会拖垮机器人。
凭证运行时读取
BotManager 不缓存 AppID / AppSecret,每次 start() 都重新读 .env。所以面板里改完凭证,点「启动机器人」即生效,不需要重启进程。
日志单一入口
所有日志都走 RuntimeState.add_log():同时写内存环形缓冲(面板实时轮询)与 sink(LogStore.enqueue → SQLite)。落库失败只降级到内存模式,不影响机器人。
热重载只针对插件
面板的安装 / 重新加载 / 启用会按来源摘除旧处理器再重新导入;core/、api/ 的改动必须重启进程。
管理接口默认只绑本机
HOST 默认 127.0.0.1;写操作要求 X-Admin-Token、JSON Content-Type 与同源 Origin。
扩展点
| 想加什么 | 改哪里 |
|---|---|
| 新事件装饰器(私聊、频道) | core/events.py 加模型 → core/handlers.py 加装饰器与分发 → core/bot.py 接 SDK 回调 → 测试与本文档 |
| 新的管理接口 | api/routes/ 新建路由 → api/schema.py 加模型 → api/main.py 挂载 |
| 新的 CLI 命令 | core/cli.py 加 @app.command() → 测试 → 文档命令表 |
| 新的持久化数据 | core/logstore.py 同层新建 store,或在其中加表(保持异步、失败降级) |
改动前建议先看仓库里的 CONTRIBUTING.md,里面写了必须补的测试与手动验证要求。