跳转到内容
Lingchu Bot

适配器指南

适配器指南

Section titled “适配器指南”

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

适配器选择的工作原理

Section titled “适配器选择的工作原理”

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

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

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

QQ 平台 profile

Section titled “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

错误处理

Section titled “错误处理”

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

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

权限 API 集成

Section titled “权限 API 集成”

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

未知适配器

Section titled “未知适配器”

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

添加新的平台 profile

Section titled “添加新的平台 profile”

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

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