AstrBot 3.5.6__py3-none-any.whl → 4.7.0__py3-none-any.whl

astrbot/core/platform/astr_message_event.py

@@ -1,45 +1,33 @@
 import abc
 import asyncio
-import re
 import hashlib
+import re
 import uuid
-from dataclasses import dataclass
-from typing import List, Union, Optional, AsyncGenerator
+from collections.abc import AsyncGenerator
+from typing import Any
 
+from astrbot import logger
 from astrbot.core.db.po import Conversation
 from astrbot.core.message.components import (
-    Plain,
-    Image,
-    BaseMessageComponent,
-    Face,
     At,
     AtAll,
+    BaseMessageComponent,
+    Face,
     Forward,
+    Image,
+    Plain,
     Reply,
 )
-from astrbot.core.message.message_event_result import MessageEventResult, MessageChain
+from astrbot.core.message.message_event_result import MessageChain, MessageEventResult
 from astrbot.core.platform.message_type import MessageType
 from astrbot.core.provider.entities import ProviderRequest
 from astrbot.core.utils.metrics import Metric
+
 from .astrbot_message import AstrBotMessage, Group
+from .message_session import MessageSesion, MessageSession  # noqa
 from .platform_metadata import PlatformMetadata
 
 
-@dataclass
-class MessageSesion:
-    platform_name: str
-    message_type: MessageType
-    session_id: str
-
-    def __str__(self):
-        return f"{self.platform_name}:{self.message_type.value}:{self.session_id}"
-
-    @staticmethod
-    def from_str(session_str: str):
-        platform_name, message_type, session_id = session_str.split(":")
-        return MessageSesion(platform_name, MessageType(message_type), session_id)
-
-
 class AstrMessageEvent(abc.ABC):
     def __init__(
         self,
@@ -62,15 +50,15 @@ class AstrMessageEvent(abc.ABC):
         """是否唤醒(是否通过 WakingStage)"""
         self.is_at_or_wake_command = False
         """是否是 At 机器人或者带有唤醒词或者是私聊(插件注册的事件监听器会让 is_wake 设为 True, 但是不会让这个属性置为 True)"""
-        self._extras = {}
+        self._extras: dict[str, Any] = {}
         self.session = MessageSesion(
-            platform_name=platform_meta.name,
+            platform_name=platform_meta.id,
             message_type=message_obj.type,
             session_id=session_id,
         )
         self.unified_msg_origin = str(self.session)
         """统一的消息来源字符串。格式为 platform_name:message_type:session_id"""
-        self._result: MessageEventResult = None
+        self._result: MessageEventResult | None = None
         """消息事件的结果"""
 
         self._has_send_oper = False
@@ -78,140 +66,124 @@ class AstrMessageEvent(abc.ABC):
         self.call_llm = False
         """是否在此消息事件中禁止默认的 LLM 请求"""
 
+        self.plugins_name: list[str] | None = None
+        """该事件启用的插件名称列表。None 表示所有插件都启用。空列表表示没有启用任何插件。"""
+
         # back_compability
         self.platform = platform_meta
 
     def get_platform_name(self):
+        """获取这个事件所属的平台的类型（如 aiocqhttp, slack, discord 等）。
+
+        NOTE: 用户可能会同时运行多个相同类型的平台适配器。
+        """
         return self.platform_meta.name
 
     def get_platform_id(self):
+        """获取这个事件所属的平台的 ID。
+
+        NOTE: 用户可能会同时运行多个相同类型的平台适配器，但能确定的是 ID 是唯一的。
+        """
         return self.platform_meta.id
 
     def get_message_str(self) -> str:
-        """
-        获取消息字符串。
-        """
+        """获取消息字符串。"""
         return self.message_str
 
-    def _outline_chain(self, chain: List[BaseMessageComponent]) -> str:
-        outline = ""
+    def _outline_chain(self, chain: list[BaseMessageComponent] | None) -> str:
+        if not chain:
+            return ""
+
+        parts = []
         for i in chain:
             if isinstance(i, Plain):
-                outline += i.text
+                parts.append(i.text)
             elif isinstance(i, Image):
-                outline += "[图片]"
+                parts.append("[图片]")
             elif isinstance(i, Face):
-                outline += f"[表情:{i.id}]"
+                parts.append(f"[表情:{i.id}]")
             elif isinstance(i, At):
-                outline += f"[At:{i.qq}]"
+                parts.append(f"[At:{i.qq}]")
             elif isinstance(i, AtAll):
-                outline += "[At:全体成员]"
+                parts.append("[At:全体成员]")
             elif isinstance(i, Forward):
                 # 转发消息
-                outline += "[转发消息]"
+                parts.append("[转发消息]")
             elif isinstance(i, Reply):
                 # 引用回复
                 if i.message_str:
-                    outline += f"[引用消息({i.sender_nickname}: {i.message_str})]"
+                    parts.append(f"[引用消息({i.sender_nickname}: {i.message_str})]")
                 else:
-                    outline += "[引用消息]"
+                    parts.append("[引用消息]")
             else:
-                outline += f"[{i.type}]"
-            outline += " "
-        return outline
+                parts.append(f"[{i.type}]")
+            parts.append(" ")
+        return "".join(parts)
 
     def get_message_outline(self) -> str:
-        """
-        获取消息概要。
+        """获取消息概要。
 
         除了文本消息外，其他消息类型会被转换为对应的占位符。如图片消息会被转换为 [图片]。
         """
         return self._outline_chain(self.message_obj.message)
 
-    def get_messages(self) -> List[BaseMessageComponent]:
-        """
-        获取消息链。
-        """
+    def get_messages(self) -> list[BaseMessageComponent]:
+        """获取消息链。"""
         return self.message_obj.message
 
     def get_message_type(self) -> MessageType:
-        """
-        获取消息类型。
-        """
+        """获取消息类型。"""
         return self.message_obj.type
 
     def get_session_id(self) -> str:
-        """
-        获取会话id。
-        """
+        """获取会话id。"""
         return self.session_id
 
     def get_group_id(self) -> str:
-        """
-        获取群组id。如果不是群组消息，返回空字符串。
-        """
+        """获取群组id。如果不是群组消息，返回空字符串。"""
         return self.message_obj.group_id
 
     def get_self_id(self) -> str:
-        """
-        获取机器人自身的id。
-        """
+        """获取机器人自身的id。"""
         return self.message_obj.self_id
 
     def get_sender_id(self) -> str:
-        """
-        获取消息发送者的id。
-        """
+        """获取消息发送者的id。"""
         return self.message_obj.sender.user_id
 
     def get_sender_name(self) -> str:
-        """
-        获取消息发送者的名称。(可能会返回空字符串)
-        """
+        """获取消息发送者的名称。(可能会返回空字符串)"""
         return self.message_obj.sender.nickname
 
     def set_extra(self, key, value):
-        """
-        设置额外的信息。
-        """
+        """设置额外的信息。"""
         self._extras[key] = value
 
-    def get_extra(self, key=None):
-        """
-        获取额外的信息。
-        """
+    def get_extra(self, key: str | None = None, default=None) -> Any:
+        """获取额外的信息。"""
         if key is None:
             return self._extras
-        return self._extras.get(key, None)
+        return self._extras.get(key, default)
 
     def clear_extra(self):
-        """
-        清除额外的信息。
-        """
+        """清除额外的信息。"""
+        logger.info(f"清除 {self.get_platform_name()} 的额外信息: {self._extras}")
         self._extras.clear()
 
     def is_private_chat(self) -> bool:
-        """
-        是否是私聊。
-        """
+        """是否是私聊。"""
         return self.message_obj.type.value == (MessageType.FRIEND_MESSAGE).value
 
     def is_wake_up(self) -> bool:
-        """
-        是否是唤醒机器人的事件。
-        """
+        """是否是唤醒机器人的事件。"""
         return self.is_wake
 
     def is_admin(self) -> bool:
-        """
-        是否是管理员。
-        """
+        """是否是管理员。"""
         return self.role == "admin"
 
     async def process_buffer(self, buffer: str, pattern: re.Pattern) -> str:
-        """
-        将消息缓冲区中的文本按指定正则表达式分割后发送至消息平台，作为不支持流式输出平台的Fallback。
-        """
+        """将消息缓冲区中的文本按指定正则表达式分割后发送至消息平台，作为不支持流式输出平台的Fallback。"""
         while True:
             match = re.search(pattern, buffer)
             if not match:
@@ -223,24 +195,26 @@ class AstrMessageEvent(abc.ABC):
         return buffer
 
     async def send_streaming(
-        self, generator: AsyncGenerator[MessageChain, None], use_fallback: bool = False
+        self,
+        generator: AsyncGenerator[MessageChain, None],
+        use_fallback: bool = False,
     ):
         """发送流式消息到消息平台，使用异步生成器。
         目前仅支持: telegram，qq official 私聊。
-        Fallback仅支持 aiocqhttp, gewechat。
+        Fallback仅支持 aiocqhttp。
         """
         asyncio.create_task(
-            Metric.upload(msg_event_tick=1, adapter_name=self.platform_meta.name)
+            Metric.upload(msg_event_tick=1, adapter_name=self.platform_meta.name),
         )
         self._has_send_oper = True
 
     async def _pre_send(self):
-        """调度器会在执行 send() 前调用该方法"""
+        """调度器会在执行 send() 前调用该方法 deprecated in v3.5.18"""
 
     async def _post_send(self):
-        """调度器会在执行 send() 后调用该方法"""
+        """调度器会在执行 send() 后调用该方法 deprecated in v3.5.18"""
 
-    def set_result(self, result: Union[MessageEventResult, str]):
+    def set_result(self, result: MessageEventResult | str):
         """设置消息事件的结果。
 
         Note:
@@ -260,9 +234,13 @@ class AstrMessageEvent(abc.ABC):
             event.set_result(MessageEventResult().set_console_log("数量已增加", logging.DEBUG).set_result_type(EventResultType.CONTINUE))
             return
         ```
+
         """
         if isinstance(result, str):
             result = MessageEventResult().message(result)
+        # 兼容外部插件或调用方传入的 chain=None 的情况，确保为可迭代列表
+        if isinstance(result, MessageEventResult) and result.chain is None:
+            result.chain = []
         self._result = result
 
     def stop_event(self):
@@ -280,41 +258,32 @@ class AstrMessageEvent(abc.ABC):
             self._result.continue_event()
 
     def is_stopped(self) -> bool:
-        """
-        是否终止事件传播。
-        """
+        """是否终止事件传播。"""
         if self._result is None:
             return False  # 默认是继续传播
         return self._result.is_stopped()
 
     def should_call_llm(self, call_llm: bool):
-        """
-        是否在此消息事件中禁止默认的 LLM 请求。
+        """是否在此消息事件中禁止默认的 LLM 请求。
 
         只会阻止 AstrBot 默认的 LLM 请求链路，不会阻止插件中的 LLM 请求。
         """
         self.call_llm = call_llm
 
     def get_result(self) -> MessageEventResult:
-        """
-        获取消息事件的结果。
-        """
+        """获取消息事件的结果。"""
         return self._result
 
     def clear_result(self):
-        """
-        清除消息事件的结果。
-        """
+        """清除消息事件的结果。"""
         self._result = None
 
     """消息链相关"""
 
     def make_result(self) -> MessageEventResult:
-        """
-        创建一个空的消息事件结果。
+        """创建一个空的消息事件结果。
 
         Example:
-
         ```python
         # 纯文本回复
         yield event.make_result().message("Hi")
@@ -322,18 +291,16 @@ class AstrMessageEvent(abc.ABC):
         yield event.make_result().url_image("https://example.com/image.jpg")
         yield event.make_result().file_image("image.jpg")
         ```
+
         """
         return MessageEventResult()
 
     def plain_result(self, text: str) -> MessageEventResult:
-        """
-        创建一个空的消息事件结果，只包含一条文本消息。
-        """
+        """创建一个空的消息事件结果，只包含一条文本消息。"""
         return MessageEventResult().message(text)
 
     def image_result(self, url_or_path: str) -> MessageEventResult:
-        """
-        创建一个空的消息事件结果，只包含一条图片消息。
+        """创建一个空的消息事件结果，只包含一条图片消息。
 
         根据开头是否包含 http 来判断是网络图片还是本地图片。
         """
@@ -341,10 +308,8 @@ class AstrMessageEvent(abc.ABC):
             return MessageEventResult().url_image(url_or_path)
         return MessageEventResult().file_image(url_or_path)
 
-    def chain_result(self, chain: List[BaseMessageComponent]) -> MessageEventResult:
-        """
-        创建一个空的消息事件结果，包含指定的消息链。
-        """
+    def chain_result(self, chain: list[BaseMessageComponent]) -> MessageEventResult:
+        """创建一个空的消息事件结果，包含指定的消息链。"""
         mer = MessageEventResult()
         mer.chain = chain
         return mer
@@ -356,13 +321,12 @@ class AstrMessageEvent(abc.ABC):
         prompt: str,
         func_tool_manager=None,
         session_id: str = None,
-        image_urls: List[str] = [],
-        contexts: List = [],
+        image_urls: list[str] | None = None,
+        contexts: list | None = None,
         system_prompt: str = "",
-        conversation: Conversation = None,
+        conversation: Conversation | None = None,
     ) -> ProviderRequest:
-        """
-        创建一个 LLM 请求。
+        """创建一个 LLM 请求。
 
         Examples:
         ```py
@@ -381,8 +345,12 @@ class AstrMessageEvent(abc.ABC):
         func_tool_manager: 函数工具管理器，用于调用函数工具。用 self.context.get_llm_tool_manager() 获取。
 
         conversation: 可选。如果指定，将在指定的对话中进行 LLM 请求。对话的人格会被用于 LLM 请求，并且结果将会被记录到对话中。
-        """
 
+        """
+        if image_urls is None:
+            image_urls = []
+        if contexts is None:
+            contexts = []
         if len(contexts) > 0 and conversation:
             conversation = None
 
@@ -403,23 +371,33 @@ class AstrMessageEvent(abc.ABC):
 
         Args:
             message (MessageChain): 消息链，具体使用方式请参考文档。
+
         """
         # Leverage BLAKE2 hash function to generate a non-reversible hash of the sender ID for privacy.
         hash_obj = hashlib.blake2b(self.get_sender_id().encode("utf-8"), digest_size=16)
         sid = str(uuid.UUID(bytes=hash_obj.digest()))
         asyncio.create_task(
             Metric.upload(
-                msg_event_tick=1, adapter_name=self.platform_meta.name, sid=sid
-            )
+                msg_event_tick=1,
+                adapter_name=self.platform_meta.name,
+                sid=sid,
+            ),
         )
         self._has_send_oper = True
 
-    async def get_group(self, group_id: str = None, **kwargs) -> Optional[Group]:
+    async def react(self, emoji: str):
+        """对消息添加表情回应。
+
+        默认实现为发送一条包含该表情的消息。
+        注意：此实现并不一定符合所有平台的原生“表情回应”行为。
+        如需支持平台原生的消息反应功能，请在对应平台的子类中重写本方法。
+        """
+        await self.send(MessageChain([Plain(emoji)]))
+
+    async def get_group(self, group_id: str | None = None, **kwargs) -> Group | None:
         """获取一个群聊的数据, 如果不填写 group_id: 如果是私聊消息，返回 None。如果是群聊消息，返回当前群聊的数据。
 
         适配情况:
 
-        - gewechat
         - aiocqhttp(OneBotv11)
         """
-        ...

astrbot/core/platform/astrbot_message.py

@@ -1,14 +1,15 @@
 import time
-from typing import List
 from dataclasses import dataclass
+
 from astrbot.core.message.components import BaseMessageComponent
+
 from .message_type import MessageType
 
 
 @dataclass
 class MessageMember:
     user_id: str  # 发送者id
-    nickname: str = None
+    nickname: str | None = None
 
     def __str__(self):
         # 使用 f-string 来构建返回的字符串表示形式
@@ -22,15 +23,15 @@ class MessageMember:
 class Group:
     group_id: str
     """群号"""
-    group_name: str = None
+    group_name: str | None = None
     """群名称"""
-    group_avatar: str = None
+    group_avatar: str | None = None
     """群头像"""
-    group_owner: str = None
+    group_owner: str | None = None
     """群主 id"""
-    group_admins: List[str] = None
+    group_admins: list[str] | None = None
     """群管理员 id"""
-    members: List[MessageMember] = None
+    members: list[MessageMember] | None = None
     """所有群成员"""
 
     def __str__(self):
@@ -47,23 +48,42 @@ class Group:
 
 
 class AstrBotMessage:
-    """
-    AstrBot 的消息对象
-    """
+    """AstrBot 的消息对象"""
 
     type: MessageType  # 消息类型
     self_id: str  # 机器人的识别id
     session_id: str  # 会话id。取决于 unique_session 的设置。
     message_id: str  # 消息id
-    group_id: str = ""  # 群组id，如果为私聊，则为空
+    group: Group  # 群组
     sender: MessageMember  # 发送者
-    message: List[BaseMessageComponent]  # 消息链使用 Nakuru 的消息链格式
+    message: list[BaseMessageComponent]  # 消息链使用 Nakuru 的消息链格式
     message_str: str  # 最直观的纯文本消息字符串
     raw_message: object
     timestamp: int  # 消息时间戳
 
     def __init__(self) -> None:
         self.timestamp = int(time.time())
+        self.group = None
 
     def __str__(self) -> str:
         return str(self.__dict__)
+
+    @property
+    def group_id(self) -> str:
+        """向后兼容的 group_id 属性
+        群组id，如果为私聊，则为空
+        """
+        if self.group:
+            return self.group.group_id
+        return ""
+
+    @group_id.setter
+    def group_id(self, value: str):
+        """设置 group_id"""
+        if value:
+            if self.group:
+                self.group.group_id = value
+            else:
+                self.group = Group(group_id=value)
+        else:
+            self.group = None