doc: 添加消息平台实体文档

docs/.vitepress/config.mts

@@ -134,8 +134,8 @@ export default defineConfig({
             items: [
               { text: "基础教程", link: "/plugin/dev/tutor" },
               { text: "消息平台实体", link: "/plugin/dev/messages" },
-              { text: "组件扩展", link: "/plugin/dev/extension" },
               { text: "API 参考", link: "/plugin/dev/api-ref" },
+              { text: "组件扩展", link: "/plugin/dev/extension" },
             ]
           },
           // { text: "技术信息", link: "/plugin/tech-info" },

docs/plugin/dev/api-ref.md

@@ -11,26 +11,26 @@
 ### 回复消息
 
 ```python
-ctx.reply(message_chain: mirai.MessageChain)
+ctx.reply(message_chain: MessageChain)
 ```
 
 回复此次事件的发起会话。
 
-- `message_chain`：[YiriMirai 的 MessageChain 对象](https://yiri-mirai.wybxc.cc/docs/basic/message-chain)，若用户使用的不是 YiriMirai 适配器，程序也能自动转换为目标消息链
+- `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
 
 ### 发送主动消息
 
 > 由于 QQ 官方 API 对主动消息的支持性很差，故若用户使用的是 QQ 官方 API，发送主动消息可能会失败
 
 ```python
-ctx.send_message(target_type: str, target_id: str, message_chain: mirai.MessageChain)
+ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
 ```
 
 发送主动消息给目标。
 
 - `target_type`：目标类型，可选值：`"person"`、`"group"`
 - `target_id`：目标 ID（QQ 号或群号）
-- `message_chain`：[YiriMirai 的 MessageChain 对象](https://yiri-mirai.wybxc.cc/docs/basic/message-chain)，若用户使用的不是 YiriMirai 适配器，程序也能自动转换为目标消息链
+- `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
 
 ## 事件处理
 

docs/plugin/dev/messages.md

@@ -0,0 +1,74 @@
+# 消息平台实体
+
+:::info 目录
+[[toc]]
+:::
+
+LangBot 支持多种消息平台，但每个消息平台的`消息实体`格式均不相同，为了屏蔽这些差异，LangBot 具有一套统一的标准。插件开发者只需要掌握并在插件中使用此页所述的消息实体，LangBot 内部的消息处理逻辑能够自动完成消息的解析和转换。
+
+:::info
+LangBot 的消息平台实体是基于 [YiriMirai](https://github.com/YiriMiraiProject/YiriMirai) 的实现改造的
+:::
+
+## 消息链
+
+消息平台的`消息`不同于用于 AI 交互的消息，消息平台的消息以`消息链`的形式描述，QQ 上展示的每一个独立的消息就是一条消息链，消息链中可以包含`文字`、`图片`、`@组件`等多种`消息链组件`，例如：
+
+![](/assets/image/plugin_dev_messages_01.png)
+
+这就是一个消息链，包含 一个 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 取得。
+
+消息平台事件定义位于`pkg/platform/types/events.py`中。
+
+## 其他实体
+
+除了上述实体之外，还有`好友 Friend`和`群 Group`等实体，这些实体的定义位于`pkg/platform/types/entities.py`中。
+他们一般被包含于上述事件对象中，可以从中取得一些未被包含在插件事件中的信息。

docs/plugin/dev/tutor.md

@@ -208,7 +208,7 @@ async def access_web(self, query, url: str):
 
 若一个事件是一次请求（用户发送消息）中的事件，其事件对象中会含有`query`对象，这个对象中包含了此次请求（即用户发送一条消息的处理过程，一个请求过程可能会触发多个事件）处理过程中的上下文数据。  
 所有支持的事件，请查看`pkg.plugin.events`文件中的每个事件类的注释。  
-关于`YiriMirai`支持的消息链组件，请查看 [YiriMirai的文档](https://yiri-mirai.wybxc.cc/docs/basic/message-chain)
+关于`消息链组件`，请查看 [消息平台实体](./messages)
 
 ### BasePlugin 结构
 
@@ -218,4 +218,8 @@ async def access_web(self, query, url: str):
 
 #### self.host
 
-在插件的方法中访问`self.host`即为`pkg.plugin.context.APIHost`类的对象，提供了主程序的一些API，详细请查看其源码。
+在插件的方法中访问`self.host`即为`pkg.plugin.context.APIHost`类的对象，提供了主程序的一些API，详细请查看其源码。
+
+### API 参考
+
+关于插件可以调用的 API，请查看 [API 参考](./api-ref)