架构概览
架构概览
Lingchu Bot 是一个以 NoneBot2 为基础的应用侧机器人项目。当前代码将核心插件、命令处理、配置、存储和数据库辅助能力拆分在 src/plugins/nonebot_plugin_lingchu_bot 下。
运行入口
pyproject.toml：声明插件目录、依赖、适配器和 NoneBot 插件配置，是当前本地插件加载配置的来源。Dockerfile/docker-compose.yml：容器运行入口，构建阶段通过nb-cli生成运行用/tmp/bot.py。nonebot_plugin_lingchu_bot：核心插件包，声明插件元数据并加载共享能力。
项目结构
核心模块
| 模块 | 职责 |
|---|---|
core/config.py | 核心配置、localstore 路径和平台信息 |
core/runtime_config.py | 运行时配置辅助 |
database/json5_store/ | JSON5 文件存储包 |
database/models/ | ORM 模型包（message、blocklist、registry、identity） |
database/orm_crud/ | 基于 nonebot-plugin-orm 的异步 CRUD 辅助 |
handle/menu.py | 菜单系统（页面、分区、功能、可用性） |
handle/qq/commands/ | 共享 QQ 命令定义（Alconna 匹配器、触发词） |
handle/qq/adapters/onebot11/ | OneBot V11 处理器（default、napcat） |
i18n/__init__.py | gettext/Babel 翻译辅助、locale 读取和异步 catalog 预热 |
platforms/registry.py | 平台能力与具体适配器的映射、优先级选择和同平台互斥校验 |
platforms/qq/permissions.py | QQ 默认身份组与运行时平台身份解析 |
permissions/ | UID 身份、平台账号、身份组成员、命令授权和 SUPERUSERS API |
repositories/blocklist.py | 黑名单数据访问 |
repositories/message_store.py | 消息存储仓库 |
repositories/permissions.py | 权限系统 ORM 仓库 |
services/message_store.py | 消息事件、处理结果、Bot 生命周期和平台 API 调用摘要记录 |
start/ | 启动钩子 |
适配器状态
插件按平台能力声明适配器，而不是把所有导入的具体适配器都视为可用。当前已实现 QQ 平台 profile，启动流程中仅 ~onebot.v11 可用。Milky（~milky）、QQ 官方（~qq）和 OneBot V12（~onebot.v12）已停维并从启动流程中移除，配置其中任何一个会以清晰的 PlatformAdapterDeprecatedError 退出。未配置时默认启用 OneBot V11。
同一平台显式配置多个已知适配器会抛出 PlatformAdapterConflictError。Lingchu Bot 不控制 NoneBot 实际导入或注册哪些适配器；它只校验被选中的适配器已经由 NoneBot 加载/注册。未配置时默认选择 ~onebot.v11，如果 OneBot V11 未加载会抛出 PlatformAdapterNotLoadedError。其他同平台适配器即使被导入或注册，也会被视为未启用，不参与平台识别、消息存储或 API 调用记录。LINGCHUAdapter 中显式声明 Lingchu 未实现或无法识别的适配器会启动失败；运行时额外出现的未知适配器不会被 is_adapter_enabled() 判定为已启用，消息存储会把它们归入统一的 unknown 平台。其他平台 profile 和非群管理能力以后续实现和测试为准。
平台权限模块现在通过适配器注册表中的 PlatformProfile.permission_module 字段动态发现，消除了硬编码的模块路径。这实现了平台标识的统一管理。
数据与配置边界
项目倾向使用 NoneBot 插件配置、localstore 和 ORM 插件提供的能力，而不是在业务代码中硬编码路径或数据库连接。
文件存储、JSON5 解析、deepcopy、命令解析和翻译 catalog 加载等潜在阻塞路径会放到 worker thread 执行，避免阻塞 NoneBot 事件循环。
最后更新于