Architecture
Architecture
Lingchu Bot is an application-side bot project based on NoneBot2. Current code splits the core plugin, command handling, configuration, storage, and database helpers under src/plugins/nonebot_plugin_lingchu_bot.
Runtime entrypoints
pyproject.toml: declares plugin directories, dependencies, adapters, and NoneBot plugin configuration, and is the current source for local plugin loading configuration.Dockerfile/docker-compose.yml: container runtime entrypoints; the build generates the runtime/tmp/bot.pywithnb-cli.nonebot_plugin_lingchu_bot: core plugin package. It declares plugin metadata and loads shared capabilities.
Project structure
Core modules
| Module | Responsibility |
|---|---|
core/config.py | Core configuration, localstore paths, and platform information |
core/runtime_config.py | Runtime configuration helpers |
database/json5_store/ | JSON5 file storage package |
database/models/ | ORM models package (message, blocklist, registry, identity) |
database/orm_crud/ | Async CRUD helpers based on nonebot-plugin-orm |
handle/menu.py | Menu system (pages, sections, features, availability) |
handle/qq/commands/ | Shared QQ command definitions (Alconna matchers, triggers) |
handle/qq/adapters/onebot11/ | OneBot V11 handlers (default, napcat) |
i18n/__init__.py | gettext/Babel translation helpers, locale reading, and async catalog warmup |
platforms/registry.py | Platform capabilities, adapter mapping, priority selection, and conflict validation |
platforms/qq/permissions.py | QQ default identity groups and runtime platform identity resolution |
permissions/ | UID identity, platform account, group membership, command grant, and SUPERUSERS APIs |
repositories/blocklist.py | Blocklist data access |
repositories/message_store.py | Message store repository |
repositories/permissions.py | Permission-system ORM repository |
services/message_store.py | Message event, processing result, bot lifecycle, and platform API call summary recording |
start/ | Startup hooks |
Adapter status
The plugin declares adapters by platform capability instead of treating every imported concrete adapter as enabled. The currently implemented profile is QQ, with only ~onebot.v11 active in the startup flow. Milky (~milky), QQ Official (~qq), and OneBot V12 (~onebot.v12) have been deprecated and removed from the startup flow; configuring any of them exits with a clear PlatformAdapterDeprecatedError. When unset, the default is OneBot V11.
Explicitly configuring multiple known adapters for the same platform raises PlatformAdapterConflictError. Lingchu Bot does not control which adapters NoneBot actually imports or registers; it only checks that the selected adapter has been loaded and registered by NoneBot. When unset, Lingchu selects ~onebot.v11 by default and raises PlatformAdapterNotLoadedError if OneBot V11 is not loaded. Other same-platform adapters may still be imported or registered, but Lingchu treats them as disabled and excludes them from platform resolution, message storage, and API call recording. Explicitly declaring an adapter that Lingchu has not implemented or cannot recognize in LINGCHUAdapter fails startup. Extra unknown adapters seen at runtime are not considered enabled by is_adapter_enabled(); message storage groups them under the stable unknown platform. Other platform profiles and non-group-management capabilities depend on later implementation and tests.
Platform permission modules are now discovered through the PlatformProfile.permission_module field in the adapter registry, eliminating hardcoded module paths. This unifies platform identifier management in a single location.
Learn more
For detailed adapter configuration and API differences, see Adapter Guide. For platform-, protocol-, and implementation-specific command references, see Platforms.
Data and configuration boundaries
The project prefers NoneBot plugin configuration, localstore, and ORM plugin capabilities instead of hard-coded paths or database connections in business code.
Potentially blocking paths such as file storage, JSON5 parsing, deepcopy, command parsing, and translation catalog loading are moved to worker threads to avoid blocking the NoneBot event loop.
Last updated on