适配器指南

适配器指南

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

适配器选择的工作原理

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

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

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

QQ 平台 profile

QQ 平台是当前唯一实现的 profile。其已知适配器优先级为：

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

.env 配置：

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

停维适配器

停维适配器（Milky、QQ 官方、OneBot V12）已从项目中彻底移除，包括其源代码。不再提供按需加载工具。

停维适配器 ID 在 platforms/registry.py 的 _DEPRECATED_ADAPTER_IDS 中跟踪。在 LINGCHUAdapter 中配置其中任何一个都会以清晰的 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'})

错误处理

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

当 LINGCHUAdapter 配置了停维适配器时，机器人会以 PlatformAdapterDeprecatedError 退出，提供清晰的停维提示并建议使用 ~onebot.v11。停维适配器与未知适配器区分对待，以便运维人员判断所配置的 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）的支持：

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