perf: 平台适配器注释

Author: Soulter

dev/plugin-platform-adapter.md

@@ -50,14 +50,14 @@ import asyncio
 
 from astrbot.api.platform import Platform, AstrBotMessage, MessageMember, PlatformMetadata, MessageType
 from astrbot.api.event import MessageChain
-from astrbot.api.message_components import Plain, Image, Record
+from astrbot.api.message_components import Plain, Image, Record # 消息链中的组件，可以根据需要导入
 from astrbot.core.platform.astr_message_event import MessageSesion
 from astrbot.api.platform import register_platform_adapter
 from astrbot import logger
 from .client import FakeClient
 from .fake_platform_event import FakePlatformEvent
 
-
+# 注册平台适配器。第一个参数为平台名，第二个为描述。第三个为默认配置。
 @register_platform_adapter("fake", "fake 适配器", default_config_tmpl={
     "token": "your_token",
     "username": "bot_username"
@@ -66,52 +66,60 @@ class FakePlatformAdapter(Platform):
 
     def __init__(self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue) -> None:
         super().__init__(event_queue)
-        self.config = platform_config
-        self.settingss = platform_settings
+        self.config = platform_config # 上面的默认配置，用户填写后会传到这里
+        self.settings = platform_settings # platform_settings 平台设置。
 
     async def send_by_session(self, session: MessageSesion, message_chain: MessageChain):
+        # 必须实现
         await super().send_by_session(session, message_chain)
 
     def meta(self) -> PlatformMetadata:
+        # 必须实现，直接像下面一样返回即可。
         return PlatformMetadata(
             "fake",
             "fake 适配器",
         )
 
     async def run(self):
-        
+        # 必须实现，这里是主要逻辑。
+
+        # FakeClient 是我们自己定义的，这里只是示例。这个是其回调函数
         async def on_received(data):
             logger.info(data)
             abm = await self.convert_message(data=data) # 转换成 AstrBotMessage
-            await self.handle_msg(abm)
-            
+            await self.handle_msg(abm) 
+        
+        # 初始化 FakeClient
         self.client = FakeClient(self.config['token'], self.config['username'])
         self.client.on_message_received = on_received
         await self.client.start_polling() # 持续监听消息，这是个堵塞方法。
 
     async def convert_message(self, data: dict) -> AstrBotMessage:
+        # 将平台消息转换成 AstrBotMessage
+        # 这里就体现了适配程度，不同平台的消息结构不一样，这里需要根据实际情况进行转换。
         abm = AstrBotMessage()
-        abm.type = MessageType.GROUP_MESSAGE # 还有 friend_message，对应私聊。具体平台具体分析
-        abm.group_id = data['group_id']
-        abm.message_str = data['content']
-        abm.sender = MessageMember(user_id=data['userid'], nickname=data['username'])
-        abm.message = [Plain(text=data['content'])] # 消息链
-        abm.raw_message = data
-        abm.self_id = data['bot_id'],
-        abm.session_id = data['userid']
-        abm.message_id = data['message_id']
+        abm.type = MessageType.GROUP_MESSAGE # 还有 friend_message，对应私聊。具体平台具体分析。重要！
+        abm.group_id = data['group_id'] # 如果是私聊，这里可以不填
+        abm.message_str = data['content'] # 纯文本消息。重要！
+        abm.sender = MessageMember(user_id=data['userid'], nickname=data['username']) # 发送者。重要！
+        abm.message = [Plain(text=data['content'])] # 消息链。如果有其他类型的消息，直接 append 即可。重要！
+        abm.raw_message = data # 原始消息。
+        abm.self_id = data['bot_id']
+        abm.session_id = data['userid'] # 会话 ID。重要！
+        abm.message_id = data['message_id'] # 消息 ID。
 
         return abm
 
     async def handle_msg(self, message: AstrBotMessage):
+        # 处理消息
         message_event = FakePlatformEvent(
             message_str=message.message_str,
             message_obj=message,
             platform_meta=self.meta(),
             session_id=message.session_id,
             client=self.client
         )
-        self.commit_event(message_event) # 提交事件到事件队列
+        self.commit_event(message_event) # 提交事件到事件队列。不要忘记！
 ```