适配器指南

Lingchu Bot 使用平台 profile 系统将抽象的平台能力映射到具体的 NoneBot 适配器。本页说明适配器注册表的工作原理、如何选择适配器，以及如何添加新平台支持。

适配器选择的工作原理

适配器注册表位于 platforms/registry.py。每个平台 profile 声明：

按优先级排列的已知适配器列表。
未设置 LINGCHUAdapter 时使用的默认适配器。
防止适配器选择冲突的校验逻辑。

插件启动时，从 NoneBot 全局配置读取 LINGCHUAdapter，并根据已注册的平台 profile 进行解析。只有选中的适配器被视为“已启用”；所有其他适配器被视为已禁用，即使 NoneBot 已加载它们。

QQ 平台 profile

QQ profile 使用以下适配器：

优先级	适配器	NoneBot 包	状态
1（默认）	`~onebot.v11`	`nonebot-adapter-onebot`	启用

默认适配器。需要运行中的 OneBot V11 实现（如 NapCat 或 Lagrange）通过 WebSocket 或 HTTP 连接到 NoneBot。

.env 配置：

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

Telegram 平台 profile

Telegram 使用 nonebot-adapter-telegram，通过 LINGCHUAdapter=~telegram 显式选择。该适配器需要 ForwardDriver，推荐 HTTPX：

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

默认使用 long polling；Webhook 需要 HTTPS 入口及适配器对应配置。受限网络请配置 telegram_proxy。如果需要接收群内普通非命令消息，必须在 BotFather 中关闭 privacy mode；chat_member 更新通常还要求机器人是管理员并显式订阅。

Telegram 群消息使用 Telegram 的 chat.id 作为持久化会话 ID，而不是适配器 session ID，因为后者包含发送者及论坛主题信息。仅在选择 ~telegram 时暴露 Telegram 能力，不支持的 QQ 专属操作保持隐藏。

错误处理

适配器注册表在配置无效时抛出特定异常：

异常	原因
`PlatformAdapterConflictError`	为同一平台显式配置了多个已知适配器
`PlatformAdapterNotLoadedError`	选中的适配器未被 NoneBot 加载或注册
`PlatformAdapterUnknownError`	在 `LINGCHUAdapter` 中指定了 Lingchu 未实现或无法识别的适配器 ID

权限 API 集成

权限系统现在通过 OneBot V11 get_group_member_info API 在事件数据不完整时主动验证用户角色，确保门禁实际生效。当 event.sender.role 缺失时，系统调用 bot.call_api('get_group_member_info', group_id=..., user_id=...) 获取用户实际角色；如果 API 调用失败，系统会降级为 member 角色作为安全措施。

未知适配器

不属于任何平台 profile 的适配器不被视为已启用。消息存储仍会接受其事件，但会将 platform 字段写入 unknown。这为下游展示提供了稳定的 Unknown 分桶，而非将原始适配器名称视为平台 ID。

添加新的平台 profile

要添加对新平台（如 Telegram 或 Discord）的支持：

在 platforms/ 中创建新的平台 profile 类，声明平台名称、已知适配器和默认适配器。
在 platforms/registry.py 中注册 profile。
将对应的适配器依赖添加到 pyproject.toml。
更新适配器选择文档。