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 profile uses the following adapter:

Priority	Adapter	NoneBot package	Status
1 (default)	`~onebot.v11`	`nonebot-adapter-onebot`	Active

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

Telegram platform profile

Telegram is selected explicitly with LINGCHUAdapter=~telegram and uses the nonebot-adapter-telegram adapter. The adapter requires a ForwardDriver; HTTPX is the recommended choice:

DRIVER=~fastapi+~httpx
LINGCHUAdapter=~telegram
telegram_bots=[{"token":"1234567890:..."}]

Long polling is the default. Webhook mode requires an HTTPS endpoint and the adapter’s webhook configuration. Configure telegram_proxy when the host cannot reach Telegram directly. BotFather privacy mode must be disabled when the bot needs ordinary non-command group messages; chat_member updates also require administrator status and explicit update subscription.

Lingchu stores Telegram group messages under the Telegram chat.id, not the adapter session ID, because Telegram session IDs include the sender and forum topic. Telegram capabilities are exposed only when the selected adapter is ~telegram; unsupported QQ-only operations remain hidden.

Error handling

The adapter registry raises specific exceptions when configuration is invalid:

Exception	Cause
`PlatformAdapterConflictError`	Multiple known adapters explicitly configured for the same platform
`PlatformAdapterNotLoadedError`	The selected adapter was not loaded or registered by NoneBot
`PlatformAdapterUnknownError`	An adapter ID that Lingchu has not implemented or cannot recognize is specified in `LINGCHUAdapter`

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):

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