Merge pull request #20 from anka-afk/v2

update: 补全部分文档

Author: anka-afk

.vitepress/config.mjs

@@ -196,9 +196,13 @@ export default defineConfig({
                 collapsed: true,
                 items: [
                   { text: "AstrMessageEvent", link: "/astr_message_event" },
+                  { text: "AstrBotMessage", link: "/astrbot_message" },
+                  { text: "MessageType", link: "/message_type" },
+                  { text: "MessageMember", link: "/message_member" },
                   { text: "Context", link: "/context" },
                   { text: "Star", link: "/star" },
                   { text: "StarMetadata", link: "/star_metadata" },
+                  { text: "PlatformMetadata", link: "/platform_metadata" },
                 ],
               },
             ],

dev/star/resources/astr_message_event.md

@@ -20,16 +20,16 @@ async def helloworld(self, event: AstrMessageEvent):
 #### 消息
 
 1. `message_str(str)`: 纯文本消息, 例如收到消息事件"你好", `event.message_str`将会是`"你好"`
-2. `message_obj(AstrBotMessage)`: 消息对象, 参考: [AstrBotMessage(施工中)]
+2. `message_obj(AstrBotMessage)`: 消息对象, 参考: [AstrBotMessage](./astrbot_message.md)
 3. `is_at_or_wake_command(bool)`: 是否@了机器人/消息带有唤醒词/为私聊(插件注册的事件监听器会让 is_wake 设为 True, 但是不会让这个属性置为 True)
 
 #### 消息来源
 
-4. `role(str)`: 用户是否为管理员, 两个可选选项:`"member" of "admin"`
-5. `platform_meta(PlatformMetadata)`: 消息平台的信息, 参考: [PlatformMetadata(施工中)]
-6. `session_id(str)`: 会话 id, 格式为 `platform_name:message_type:session_id`, 建议直接使用 9 中的`unified_msg_origin`作为代替
-7. `session(MessageSesion)`: 会话 id, 用于唯一识别一个会话, `session_id`与`unified_msg_origin`是它的字符串表示
-8. `unified_msg_origin(str)`: 会话 id, 等同于 6 中的`session_id`, 建议使用
+4. `role(str)`: 用户是否为管理员, 两个可选选项:`"member" or "admin"`
+5. `platform_meta(PlatformMetadata)`: 消息平台的信息, 参考: [PlatformMetadata](./platform_metadata.md)
+6. `session_id(str)`: 不包含平台的会话 id, 以 qq 平台为例, 在私聊中它是对方 qq 号, 在群聊中它是群号, 它无法标记具体平台, 建议直接使用 9 中的`unified_msg_origin`作为代替
+7. `session(MessageSession)`: 会话对象, 用于唯一识别一个会话, `unified_msg_origin`是它的字符串表示, `session_id`等价于`session.session_id`
+8. `unified_msg_origin(str)`: 会话 id, 格式为: `platform_name:message_type:session_id`, 建议使用
 
 #### 事件控制
 
@@ -71,7 +71,7 @@ get_messages() -> List[BaseMessageComponent]
 get_message_type() -> MessageType
 ```
 
-该方法用于获取消息类型, 消息类型参考: [MessageType(施工中)]
+该方法用于获取消息类型, 消息类型参考: [MessageType](./message_type.md)
 
 5. is_private_chat
 
@@ -142,7 +142,7 @@ get_group_id() -> str
 
 ```Python
 get_session_id() -> str
-# 等同于self.session_id或self.unified_msg_origin
+# 等同于self.session_id或self.session.session_id
 ```
 
 该方法用于获取当前会话 id, 格式为 `platform_name:message_type:session_id`

dev/star/resources/astrbot_message.md

@@ -0,0 +1,26 @@
+---
+outline: deep
+---
+
+# AstrBotMessage
+
+AstrBot 消息对象, 它是一个消息的容器, 所有平台的消息在接收时都被转换为该类型的对象, 以实现不同平台的统一处理。
+
+对于每个事件, 一定都有一个驱动该事件的 AstrBotMessage 对象。
+
+```mermaid
+平台发来的消息 --> AstrBotMessage --> AstrBot 事件
+```
+
+### 属性
+
+1. `type(MessageType)`: 消息类型, 参考: [MessageType](./message_type.md)
+2. `self_id(str)`: 机器人自身 id, 例如在 aiocqhttp 平台, 它是机器人自身的 qq 号
+3. `session_id(str)`: 不包含平台的会话 id, 以 qq 平台为例, 在私聊中它是对方 qq 号, 在群聊中它是群号
+4. `message_id(str)`: 消息 id, 消息的唯一标识符, 用于引用或获取某一条消息
+5. `group_id(str)`: 群组 id, 如果为私聊, 则为空字符串
+6. `sender(MessageMember)`: 消息发送者, 参考: [MessageMember](./message_member.md)
+7. `message(List[BaseMessageComponent])`: 消息链(Nakuru 格式), 包含该事件中的所有消息内容, 参考: [BaseMessageComponent(施工中)]
+8. `message_str(str)`: 纯文本消息字符串, 相当于把消息链转换为纯文本(会丢失信息!)
+9. `raw_message(object)`: 原始消息对象, 包含所有消息的原始数据(平台适配器发来的)
+10. `timestamp(int)`: 消息的时间戳(会自动初始化)

dev/star/resources/message_member.md

@@ -0,0 +1,12 @@
+---
+outline: deep
+---
+
+# MessageMember
+
+消息发送者对象, 用于标记一个消息发送者的最基本信息
+
+### 属性
+
+1. `user_id(str)`: 消息发送者 id, 唯一, 例如在 aiocqhttp 平台, 它是发送者的 qq 号
+2. `nickname(str)`: 昵称, 例如在 aiocqhttp 平台, 它是发送者的 qq 昵称, 它会被自动初始化

dev/star/resources/message_type.md

@@ -0,0 +1,20 @@
+---
+outline: deep
+---
+
+# MessageType
+
+消息类型, 用于区分消息是私聊还是群聊消息, 继承自`Enum`枚举类型
+
+使用方法如下:
+
+```Python
+from astrbot.api import MessageType
+print(MessageType.GROUP_MESSAGE)
+```
+
+### 内容
+
+1. `GROUP_MESSAGE`: 群聊消息
+2. `FRIEND_MESSAGE`: 私聊消息
+3. `OTHER_MESSAGE`: 其他消息, 例如系统消息等

dev/star/resources/platform_metadata.md

@@ -0,0 +1,15 @@
+---
+outline: deep
+---
+
+# PlatformMetadata
+
+平台元数据, 包含了平台的基本信息, 例如平台名称, 平台类型等.
+
+### 属性
+
+1. `name(str)`: 平台的名称
+2. `description(str)`: 平台的描述
+3. `id(str)`: 平台的唯一标识符, 用于区分不同的平台
+4. `default_config_tmpl(dict)`: 平台的默认配置模板, 用于生成平台的默认配置文件
+5. `adapter_display_name(str)`: 显示在 WebUI 中的平台名称, 默认为 `name`(可以更改)