Qmin简Q

文档 / 架构

东西都在哪

三层: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.pyAppID / AppSecret、运行时状态网关连接;把 SDK 回调转成事件;连接状态与入站日志不处理 HTTP、不读写数据库、不做关键字匹配
core/events.pySDK 入站消息、回复闭包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.pySettings、插件目录、BotManager、LogStoreFastAPI 实例;lifespan 接日志 sink、按需自动连机器人不直接调用 botpy
api/deps.py请求头令牌 / Content-Type / Origin 校验不读业务数据
api/routes/*HTTP 请求JSON:状态、日志、插件、配置、启停不含机器人连接逻辑
webui/用户操作静态资源;数据全部走 /api/*不内嵌业务规则,不直连 QQ

分层规则

  1. core 不 import api,也不依赖 FastAPI。
  2. api 不直接操作 botpy:启停统一走 api/bot_manager.py → core/bot.py。
  3. webui 只通过 /api/* 与后端通信,不假设本地文件结构。
  4. 事件模型(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,里面写了必须补的测试与手动验证要求。