doc：完善doc

2025-06-19 23:21:31 +08:00
parent 98735b067c
commit 43425b3c1f
16 changed files with 2824 additions and 521 deletions
--- a/src/plugin_system/apis/send_api.py
+++ b/src/plugin_system/apis/send_api.py
@@ -2,10 +2,20 @@
 发送API模块

 专门负责发送各种类型的消息，采用标准Python包设计模式
+
 使用方式：
    from src.plugin_system.apis import send_api
+    
+    # 方式1：直接使用stream_id（推荐）
+    await send_api.text_to_stream("hello", stream_id)
+    await send_api.emoji_to_stream(emoji_base64, stream_id)
+    await send_api.custom_to_stream("video", video_data, stream_id)
+    
+    # 方式2：使用群聊/私聊指定函数
    await send_api.text_to_group("hello", "123456")
-    await send_api.emoji_to_group(emoji_base64, "123456")
+    await send_api.text_to_user("hello", "987654")
+    
+    # 方式3：使用通用custom_message函数
    await send_api.custom_message("video", video_data, "123456", True)
 """

@@ -224,6 +234,96 @@ async def _find_reply_message(target_stream, reply_to: str) -> Optional[MessageR
 # =============================================================================


+async def text_to_stream(
+    text: str,
+    stream_id: str,
+    typing: bool = False,
+    reply_to: str = "",
+    storage_message: bool = True,
+) -> bool:
+    """向指定流发送文本消息
+
+    Args:
+        text: 要发送的文本内容
+        stream_id: 聊天流ID
+        typing: 是否显示正在输入
+        reply_to: 回复消息，格式为"发送者:消息内容"
+        storage_message: 是否存储消息到数据库
+
+    Returns:
+        bool: 是否发送成功
+    """
+    return await _send_to_target("text", text, stream_id, "", typing, reply_to, storage_message)
+
+
+async def emoji_to_stream(emoji_base64: str, stream_id: str, storage_message: bool = True) -> bool:
+    """向指定流发送表情包
+
+    Args:
+        emoji_base64: 表情包的base64编码
+        stream_id: 聊天流ID
+        storage_message: 是否存储消息到数据库
+
+    Returns:
+        bool: 是否发送成功
+    """
+    return await _send_to_target("emoji", emoji_base64, stream_id, "", typing=False, storage_message=storage_message)
+
+
+async def image_to_stream(image_base64: str, stream_id: str, storage_message: bool = True) -> bool:
+    """向指定流发送图片
+
+    Args:
+        image_base64: 图片的base64编码
+        stream_id: 聊天流ID
+        storage_message: 是否存储消息到数据库
+
+    Returns:
+        bool: 是否发送成功
+    """
+    return await _send_to_target("image", image_base64, stream_id, "", typing=False, storage_message=storage_message)
+
+
+async def command_to_stream(command: str, stream_id: str, storage_message: bool = True) -> bool:
+    """向指定流发送命令
+
+    Args:
+        command: 命令
+        stream_id: 聊天流ID
+        storage_message: 是否存储消息到数据库
+
+    Returns:
+        bool: 是否发送成功
+    """
+    return await _send_to_target("command", command, stream_id, "", typing=False, storage_message=storage_message)
+
+
+async def custom_to_stream(
+    message_type: str,
+    content: str,
+    stream_id: str,
+    display_message: str = "",
+    typing: bool = False,
+    reply_to: str = "",
+    storage_message: bool = True,
+) -> bool:
+    """向指定流发送自定义类型消息
+
+    Args:
+        message_type: 消息类型，如"text"、"image"、"emoji"、"video"、"file"等
+        content: 消息内容（通常是base64编码或文本）
+        stream_id: 聊天流ID
+        display_message: 显示消息
+        typing: 是否显示正在输入
+        reply_to: 回复消息，格式为"发送者:消息内容"
+        storage_message: 是否存储消息到数据库
+
+    Returns:
+        bool: 是否发送成功
+    """
+    return await _send_to_target(message_type, content, stream_id, display_message, typing, reply_to, storage_message)
+
+
 async def text_to_group(
    text: str,
    group_id: str,
--- a/src/plugin_system/base/base_action.py
+++ b/src/plugin_system/base/base_action.py
@@ -204,22 +204,20 @@ class BaseAction(ABC):

        Args:
            content: 文本内容
+            reply_to: 回复消息，格式为"发送者:消息内容"

        Returns:
            bool: 是否发送成功
        """
-        if not self.target_id or not self.platform:
-            logger.error(f"{self.log_prefix} 缺少发送消息所需的信息")
+        if not self.chat_id:
+            logger.error(f"{self.log_prefix} 缺少聊天ID")
            return False

-        if self.is_group:
-            return await send_api.text_to_group(
-                text=content, group_id=self.target_id, platform=self.platform, reply_to=reply_to
-            )
-        else:
-            return await send_api.text_to_user(
-                text=content, user_id=self.target_id, platform=self.platform, reply_to=reply_to
-            )
+        return await send_api.text_to_stream(
+            text=content, 
+            stream_id=self.chat_id, 
+            reply_to=reply_to
+        )

    async def send_emoji(self, emoji_base64: str) -> bool:
        """发送表情包
@@ -230,17 +228,11 @@ class BaseAction(ABC):
        Returns:
            bool: 是否发送成功
        """
-        # 导入send_api
-        from src.plugin_system.apis import send_api
-
-        if not self.target_id or not self.platform:
-            logger.error(f"{self.log_prefix} 缺少发送消息所需的信息")
+        if not self.chat_id:
+            logger.error(f"{self.log_prefix} 缺少聊天ID")
            return False

-        if self.is_group:
-            return await send_api.emoji_to_group(emoji_base64, self.target_id, self.platform)
-        else:
-            return await send_api.emoji_to_user(emoji_base64, self.target_id, self.platform)
+        return await send_api.emoji_to_stream(emoji_base64, self.chat_id)

    async def send_image(self, image_base64: str) -> bool:
        """发送图片
@@ -251,43 +243,34 @@ class BaseAction(ABC):
        Returns:
            bool: 是否发送成功
        """
-        # 导入send_api
-        from src.plugin_system.apis import send_api
-
-        if not self.target_id or not self.platform:
-            logger.error(f"{self.log_prefix} 缺少发送消息所需的信息")
+        if not self.chat_id:
+            logger.error(f"{self.log_prefix} 缺少聊天ID")
            return False

-        if self.is_group:
-            return await send_api.image_to_group(image_base64, self.target_id, self.platform)
-        else:
-            return await send_api.image_to_user(image_base64, self.target_id, self.platform)
+        return await send_api.image_to_stream(image_base64, self.chat_id)

-    async def send_custom(self, message_type: str, content: str, typing: bool = False) -> bool:
+    async def send_custom(self, message_type: str, content: str, typing: bool = False, reply_to: str = "") -> bool:
        """发送自定义类型消息

        Args:
            message_type: 消息类型，如"video"、"file"、"audio"等
            content: 消息内容
            typing: 是否显示正在输入
+            reply_to: 回复消息，格式为"发送者:消息内容"

        Returns:
            bool: 是否发送成功
        """
-        # 导入send_api
-        from src.plugin_system.apis import send_api
-
-        if not self.target_id or not self.platform:
-            logger.error(f"{self.log_prefix} 缺少发送消息所需的信息")
+        if not self.chat_id:
+            logger.error(f"{self.log_prefix} 缺少聊天ID")
            return False

-        return await send_api.custom_message(
+        return await send_api.custom_to_stream(
            message_type=message_type,
            content=content,
-            target_id=self.target_id,
-            is_group=self.is_group,
-            platform=self.platform,
+            stream_id=self.chat_id,
            typing=typing,
+            reply_to=reply_to,
        )

    async def store_action_info(
@@ -318,36 +301,30 @@ class BaseAction(ABC):
    ) -> bool:
        """发送命令消息

-        使用和send_text相同的方式通过MessageAPI发送命令
+        使用stream API发送命令

        Args:
            command_name: 命令名称
            args: 命令参数
            display_message: 显示消息
+            storage_message: 是否存储消息到数据库

        Returns:
            bool: 是否发送成功
        """
        try:
+            if not self.chat_id:
+                logger.error(f"{self.log_prefix} 缺少聊天ID")
+                return False
+
            # 构造命令数据
            command_data = {"name": command_name, "args": args or {}}

-            if self.is_group:
-                # 群聊
-                success = await send_api.command_to_group(
-                    command=command_data,
-                    group_id=str(self.group_id),
-                    platform=self.platform,
-                    storage_message=storage_message,
-                )
-            else:
-                # 私聊
-                success = await send_api.command_to_user(
-                    command=command_data,
-                    user_id=str(self.user_id),
-                    platform=self.platform,
-                    storage_message=storage_message,
-                )
+            success = await send_api.command_to_stream(
+                command=command_data,
+                stream_id=self.chat_id,
+                storage_message=storage_message,
+            )

            if success:
                logger.info(f"{self.log_prefix} 成功发送命令: {command_name}")
--- a/src/plugin_system/base/base_command.py
+++ b/src/plugin_system/base/base_command.py
@@ -86,30 +86,30 @@ class BaseCommand(ABC):

        return current

-    async def send_text(self, content: str) -> None:
+    async def send_text(self, content: str, reply_to: str = "") -> bool:
        """发送回复消息

        Args:
            content: 回复内容
+            reply_to: 回复消息，格式为"发送者:消息内容"
+
+        Returns:
+            bool: 是否发送成功
        """
        # 获取聊天流信息
        chat_stream = self.message.chat_stream
+        if not chat_stream or not hasattr(chat_stream, 'stream_id'):
+            logger.error(f"{self.log_prefix} 缺少聊天流或stream_id")
+            return False

-        if chat_stream.group_info:
-            # 群聊
-
-            await send_api.text_to_group(
-                text=content, group_id=str(chat_stream.group_info.group_id), platform=chat_stream.platform
-            )
-        else:
-            # 私聊
-
-            await send_api.text_to_user(
-                text=content, user_id=str(chat_stream.user_info.user_id), platform=chat_stream.platform
-            )
+        return await send_api.text_to_stream(
+            text=content, 
+            stream_id=chat_stream.stream_id, 
+            reply_to=reply_to
+        )

    async def send_type(
-        self, message_type: str, content: str, display_message: str = None, typing: bool = False
+        self, message_type: str, content: str, display_message: str = "", typing: bool = False, reply_to: str = ""
    ) -> bool:
        """发送指定类型的回复消息到当前聊天环境

@@ -117,78 +117,54 @@ class BaseCommand(ABC):
            message_type: 消息类型，如"text"、"image"、"emoji"等
            content: 消息内容
            display_message: 显示消息（可选）
+            typing: 是否显示正在输入
+            reply_to: 回复消息，格式为"发送者:消息内容"

        Returns:
            bool: 是否发送成功
        """
        # 获取聊天流信息
        chat_stream = self.message.chat_stream
+        if not chat_stream or not hasattr(chat_stream, 'stream_id'):
+            logger.error(f"{self.log_prefix} 缺少聊天流或stream_id")
+            return False

-        if chat_stream.group_info:
-            # 群聊
-            from src.plugin_system.apis import send_api
+        return await send_api.custom_to_stream(
+            message_type=message_type,
+            content=content,
+            stream_id=chat_stream.stream_id,
+            display_message=display_message,
+            typing=typing,
+            reply_to=reply_to,
+        )

-            return await send_api.custom_message(
-                message_type=message_type,
-                content=content,
-                target_id=str(chat_stream.group_info.group_id),
-                is_group=True,
-                platform=chat_stream.platform,
-                typing=typing,
-            )
-        else:
-            # 私聊
-            from src.plugin_system.apis import send_api
-
-            return await send_api.custom_message(
-                message_type=message_type,
-                content=content,
-                target_id=str(chat_stream.user_info.user_id),
-                is_group=False,
-                platform=chat_stream.platform,
-                typing=typing,
-            )
-
-    async def send_command(self, command_name: str, args: dict = None, display_message: str = None) -> bool:
+    async def send_command(self, command_name: str, args: dict = None, display_message: str = "", storage_message: bool = True) -> bool:
        """发送命令消息

        Args:
            command_name: 命令名称
            args: 命令参数
            display_message: 显示消息
+            storage_message: 是否存储消息到数据库

        Returns:
            bool: 是否发送成功
        """
        try:
+            # 获取聊天流信息
+            chat_stream = self.message.chat_stream
+            if not chat_stream or not hasattr(chat_stream, 'stream_id'):
+                logger.error(f"{self.log_prefix} 缺少聊天流或stream_id")
+                return False
+
            # 构造命令数据
            command_data = {"name": command_name, "args": args or {}}

-            # 获取聊天流信息
-            chat_stream = self.message.chat_stream
-
-            if chat_stream.group_info:
-                # 群聊
-                from src.plugin_system.apis import send_api
-
-                success = await send_api.custom_message(
-                    message_type="command",
-                    content=command_data,
-                    target_id=str(chat_stream.group_info.group_id),
-                    is_group=True,
-                    platform=chat_stream.platform,
-                )
-            else:
-                # 私聊
-                from src.plugin_system.apis import send_api
-
-                success = await send_api.custom_message(
-                    message_type="command",
-                    content=command_data,
-                    target_id=str(chat_stream.user_info.user_id),
-                    is_group=False,
-                    platform=chat_stream.platform,
-                )
+            success = await send_api.command_to_stream(
+                command=command_data,
+                stream_id=chat_stream.stream_id,
+                storage_message=storage_message,
+            )

            if success:
                logger.info(f"{self.log_prefix} 成功发送命令: {command_name}")
@@ -201,6 +177,38 @@ class BaseCommand(ABC):
            logger.error(f"{self.log_prefix} 发送命令时出错: {e}")
            return False

+    async def send_emoji(self, emoji_base64: str) -> bool:
+        """发送表情包
+
+        Args:
+            emoji_base64: 表情包的base64编码
+
+        Returns:
+            bool: 是否发送成功
+        """
+        chat_stream = self.message.chat_stream
+        if not chat_stream or not hasattr(chat_stream, 'stream_id'):
+            logger.error(f"{self.log_prefix} 缺少聊天流或stream_id")
+            return False
+
+        return await send_api.emoji_to_stream(emoji_base64, chat_stream.stream_id)
+
+    async def send_image(self, image_base64: str) -> bool:
+        """发送图片
+
+        Args:
+            image_base64: 图片的base64编码
+
+        Returns:
+            bool: 是否发送成功
+        """
+        chat_stream = self.message.chat_stream
+        if not chat_stream or not hasattr(chat_stream, 'stream_id'):
+            logger.error(f"{self.log_prefix} 缺少聊天流或stream_id")
+            return False
+
+        return await send_api.image_to_stream(image_base64, chat_stream.stream_id)
+
    @classmethod
    def get_command_info(cls) -> "CommandInfo":
        """从类属性生成CommandInfo