LangBot 文档

Appearance

消息平台实体 ​

目录

LangBot 支持多种消息平台，但每个消息平台的消息实体格式均不相同，为了屏蔽这些差异，LangBot 具有一套统一的标准。插件开发者只需要掌握并在插件中使用此页所述的消息实体，LangBot 内部的消息处理逻辑能够自动完成消息的解析和转换。

INFO

LangBot 的消息平台实体是基于 YiriMirai 的实现改造的。

消息链 ​

消息平台的消息不同于用于 AI 交互的消息，消息平台的消息以消息链的形式描述，QQ 上展示的每一个独立的消息就是一条消息链，消息链中可以包含文字、图片、@组件等多种消息链组件，例如：

这就是一个消息链，包含 一个 Plain 组件（Hello World）和 一个 Image 组件（乌萨奇）

消息链和消息链组件的定义位于pkg/platform/types/messages.py中。

构造消息链 ​

请先引入pkg.platform.types包，才能使用其中的消息组件。

python
from pkg.platform.types import *

# 构建一个包含文字 Hello LangBot 和图片（从URL获取）的消息
msg_chain = MessageChain([
    Plain("Hello LangBot"),
    Image(url='https://qchatgpt.rockchin.top/langbot-logo.png')
])

# 构建一个包含 @全体成员 和文字 Hello LangBot 的消息
msg_chain = MessageChain([
    AtAll(),
    Plain("Hello LangBot")
])

# 构建一个包含 @指定成员 和文字 Hello LangBot 的消息
msg_chain = MessageChain([
    At(123456),
    Plain("Hello LangBot")
])

目前支持的消息链组件：

  • Source 源消息链信息，如果是从消息平台收到的消息，都会在消息链最前端包含此组件，记录消息信息
  • Plain 纯文本消息
  • Quote 引用消息
  • Image 图片消息
  • AtAll @全体成员消息
  • At @指定成员消息
  • Voice 语音消息
    • 需要检查消息平台支持性
  • Forward 转发消息
    • 在很多平台不受支持，不建议使用
  • File 文件消息

具体使用方式可以查看源码pkg/platform/types/messages.py中的定义。

消息平台事件 ​

这些事件不同于 LangBot 插件事件，是消息平台系统独立的一套事件系统。这些事件是 LangBot 消息的源事件，可以从每个 Query.message_event 取得。

python
    # 例如在插件中
    @handler(GroupMessageReceived)
    async def _(self, ctx: EventContext):
        # 取得消息平台事件
        message_event = ctx.query.message_event

消息平台事件定义位于pkg/platform/types/events.py中。

其他实体 ​

除了上述实体之外，还有好友 Friend和群 Group等实体，这些实体的定义位于pkg/platform/types/entities.py中。 他们一般被包含于上述事件对象中，可以从中取得一些未被包含在插件事件中的信息。

向后兼容性 ​

以 3.x 版本为基础开发的插件，均可以无缝适配 3.4 版本。但 import mirai 在新版本已经不受支持，开发插件时编辑器会报错。请做如下修改：

  • import mirai 改为 import pkg.platform.types as mirai
    • 不建议直接改成 as mirai，建议使用 import pkg.platform.types as platform_types 并将插件代码中对应的 mirai.xxx 替换为 platform_types.xxx
  • from mirai import * 改为 from pkg.platform.types import *

访问消息平台底层 API ​

为了抹平各个平台的差异，LangBot 在消息平台API之上，提供了一个抽象层，即上方所述的内容，以及pkg/platform/sources目录下的各个平台适配器。
但由于各个平台的差异较大，抽象层内的实体和 API 封装并不完整，如果您的插件需要访问特定平台的功能，可以按照以下说明访问底层 API。

INFO

其中的adapter为每个适配器的实例化对象，对应 pkg/platform/sources/ 下各个文件中的 xxxAdapter(adapter.MessagePlatformAdapter) 类。可以在插件事件的query.adapter中取得，例如：

python
    # 例如在插件中
    @handler(GroupMessageReceived)
    async def _(self, ctx: EventContext):
        # 取得适配器对象
        adapter = ctx.query.adapter
平台适配器访问方式说明
QQ 个人号aiocqhttpadapter.botbot 对象对应 aiocqhttp 的 CQHttp 对象，详细使用方式请参考 aiocqhttp 文档
QQ 官方APIqqofficialadapter.botbot 对象为 libs/qq_official_api 下的 SDK 对象，详细使用方式可以参考 libs/qq_official_api/api.py 中QQOfficialClient中的send_group_text_msg方法发起 HTTP 请求的方式，具体接口文档请查看 QQ 官方 API 文档
个人微信gewechatadapter.botbot 对象为 hanfangyuan4396/gewechat-client 的 GewechatClient 对象，详细使用方式可以参考文档
企业微信wecomadapter.bot参考 libs/wecom_api/api.py 中WecomClient中的send_image方法发起 HTTP 请求的方式，具体接口文档请查看企业微信 API 文档
微信公众号officialaccount-请参考微信公众号的 API 文档中的接口文档信息，相关的凭据信息可以在 adapter.bot 中取得
飞书larkadapter.api_client飞书 SDK 的 API Client 对象，具体请参考oapi-sdk-python
钉钉dingtalk-请参考钉钉 API 文档，相关的凭据信息可以在 adapter.bot 中取得
Discorddiscordadapter.botbot 对象为 Rapptz/discord.py 的 Discord 对象，详细使用方式请参考文档
Telegramtelegramadapter.botbot 对象为 python-telegram-bot 的 Telegram 对象，详细使用方式请参考文档
Slackslackadapter.botbot 对象 libs/slack_api/api.py 中的对象，详细使用方式请参考其代码以及 Slack SDK