From 2c20f34346f92af9e335bcf473f046674f9f9502 Mon Sep 17 00:00:00 2001 From: Junyan Qin Date: Sun, 13 Apr 2025 17:28:15 +0800 Subject: [PATCH] doc: update low-level platform api access comment --- docs/.vitepress/config.mts | 2 +- docs/plugin/dev/messages.md | 33 ++++++++++++++++++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index afda65de9..a6b9d7608 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -162,7 +162,7 @@ export default defineConfig({ collapsed: true, items: [ { text: "基础教程", link: "/plugin/dev/tutor" }, - { text: "消息实体", link: "/plugin/dev/messages" }, + { text: "消息平台实体", link: "/plugin/dev/messages" }, { text: "API 参考", link: "/plugin/dev/api-ref" }, { text: "组件扩展", link: "/plugin/dev/extension" }, ], diff --git a/docs/plugin/dev/messages.md b/docs/plugin/dev/messages.md index 6b304d85a..b0c3b5eb8 100644 --- a/docs/plugin/dev/messages.md +++ b/docs/plugin/dev/messages.md @@ -1,4 +1,4 @@ -# 消息实体 +# 消息平台实体 :::info 目录 [[toc]] @@ -80,3 +80,34 @@ msg_chain = MessageChain([ - `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 个人号| aiocqhttp | adapter.bot | bot 对象对应 [aiocqhttp](https://github.com/nonebot/aiocqhttp) 的 CQHttp 对象，详细使用方式请参考 aiocqhttp 文档 | +| QQ 官方API | qqofficial | adapter.bot | bot 对象为 libs/qq_official_api 下的 SDK 对象，详细使用方式可以参考 libs/qq_official_api/api.py 中`QQOfficialClient`中的`send_group_text_msg`方法发起 HTTP 请求的方式，具体接口文档请查看 QQ 官方 API 文档| +| 个人微信 | gewechat | adapter.bot | bot 对象为 [hanfangyuan4396/gewechat-client](https://github.com/hanfangyuan4396/gewechat-python) 的 GewechatClient 对象，详细使用方式可以参考文档 | +| 企业微信 | wecom | adapter.bot | 参考 libs/wecom_api/api.py 中`WecomClient`中的`send_image`方法发起 HTTP 请求的方式，具体接口文档请查看企业微信 API 文档 | +| 微信公众号 | officialaccount | - | 请参考微信公众号的 API 文档中的接口文档信息，相关的凭据信息可以在 adapter.bot 中取得 | +| 飞书 | lark | adapter.api_client | 飞书 SDK 的 API Client 对象，具体请参考[oapi-sdk-python](https://github.com/larksuite/oapi-sdk-python) | +| 钉钉 | dingtalk | - | 请参考钉钉 API 文档，相关的凭据信息可以在 adapter.bot 中取得 | +| Discord | discord | adapter.bot | bot 对象为 [Rapptz/discord.py](https://github.com/Rapptz/discord.py) 的 Discord 对象，详细使用方式请参考文档 | +| Telegram | telegram | adapter.bot | bot 对象为 [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) 的 Telegram 对象，详细使用方式请参考文档 | +| Slack | slack | adapter.bot | bot 对象 libs/slack_api/api.py 中的对象，详细使用方式请参考其代码以及 Slack SDK | \ No newline at end of file