Adapter Guide

Adapter Guide

Lingchu Bot uses a platform profile system to map abstract platform capabilities to concrete NoneBot adapters. This page explains how the adapter registry works, how to select an adapter, and how to add support for a new platform.

How adapter selection works

The adapter registry lives in platforms/registry.py. Each platform profile declares:

• A list of known adapters in priority order.
• A default adapter used when LINGCHUAdapter is not set.
• Validation logic that prevents conflicting adapter selections.

When the plugin starts, it reads LINGCHUAdapter from NoneBot's global configuration and resolves it against the registered platform profiles. Only the selected adapter is considered "enabled"; all other adapters are treated as disabled, even if NoneBot has loaded them.

QQ platform profile

The QQ platform is the only currently implemented profile. Its known adapter priority is:

The default adapter. Requires a running OneBot V11 implementation (such as NapCat or Lagrange) connected to NoneBot via WebSocket or HTTP.

Configuration in .env:

DRIVER=~fastapi+~httpx+~websockets
ONEBOT_ACCESS_TOKEN=your-token

Deprecated adapters

Deprecated adapters (Milky, QQ Official, OneBot V12) have been fully removed from the project, including their source code. No on-demand loading utility is provided.

Deprecated adapter IDs are tracked in _DEPRECATED_ADAPTER_IDS in platforms/registry.py. Configuring any of them in LINGCHUAdapter exits with a clear PlatformAdapterDeprecatedError:

from nonebot import get_driver
from src.plugins.nonebot_plugin_lingchu_bot.platforms.registry import _DEPRECATED_ADAPTER_IDS

print(_DEPRECATED_ADAPTER_IDS)  # frozenset({'~milky', '~qq', '~onebot.v12'})

Error handling

The adapter registry raises specific exceptions when configuration is invalid:

When a deprecated adapter is specified in LINGCHUAdapter, the bot exits with PlatformAdapterDeprecatedError providing a clear deprecation message and suggesting ~onebot.v11. Deprecated adapters are distinguished from unknown adapters so that operators can tell whether the configured ID was once supported.

Permission API integration

The permission system now actively verifies user roles via the OneBot V11 get_group_member_info API when event data is incomplete, ensuring access control is enforced. When event.sender.role is missing, the system calls bot.call_api('get_group_member_info', group_id=..., user_id=...) to fetch the user's actual role; if the API call fails, the system falls back to the member role as a fail-safe measure.

Unknown adapters

An adapter that does not belong to any platform profile is not considered enabled. Message storage still accepts its events, but writes the platform field as unknown. This gives downstream displays a stable Unknown bucket instead of treating the raw adapter name as a platform ID.

Adding a new platform profile

To add support for a new platform (for example, Telegram or Discord):

1. Create a new platform profile class in platforms/ that declares the platform name, known adapters, and default adapter.
2. Register the profile in platforms/registry.py.
3. Add the corresponding adapter dependency to pyproject.toml.
4. Update the adapter selection documentation.