feature: 添加插件工具类, 暂时这么多

2025-04-05 00:51:52 +08:00
parent 1c1a65b637
commit 3ebd2f746f
1 changed files with 135 additions and 0 deletions
@@ -0,0 +1,135 @@
+from typing import Union, Awaitable, List
+from asyncio import Queue
+from astrbot.core.message.components import BaseMessageComponent
+from astrbot.core.message.message_event_result import MessageChain
+from astrbot.api.platform import MessageType, MessageMember, AstrBotMessage
+from astrbot.core.platform.astr_message_event import MessageSesion
+from astrbot.core.star.context import Context
+from astrbot.core.star.filter.command import CommandFilter
+from astrbot.core.star.filter.regex import RegexFilter
+from astrbot.core.star import star_handlers_registry, StarHandlerMetadata, EventType
+from astrbot.core import sp
+
+
+class StarTools:
+    """
+    提供给插件使用的便捷工具函数集合
+    这些方法封装了一些常用操作，使插件开发更加简单便捷!
+    """
+
+    def __init__(self, context: Context):
+        """
+        初始化StarTools实例
+
+        Args:
+            context(Context): 暴露给插件的上下文
+        """
+        self._context = context
+
+    async def send_message(
+        self, session: Union[str, MessageSesion], message_chain: MessageChain
+    ) -> bool:
+        """
+        根据session(unified_msg_origin)主动发送消息
+
+        Args:
+            session: 消息会话。通过event.session或者event.unified_msg_origin获取
+            message_chain: 消息链
+
+        Returns:
+            bool: 是否找到匹配的平台
+
+        Raises:
+            ValueError: 当session为字符串且解析失败时抛出
+
+        Note:
+            qq_official(QQ官方API平台)不支持此方法
+        """
+        return await self._context.send_message(session, message_chain)
+
+    async def create_message(
+        self,
+        type: str,
+        self_id: str,
+        session_id: str,
+        message_id: str,
+        sender: MessageMember,
+        message: List[BaseMessageComponent],
+        message_str: str,
+        raw_message: object,
+        group_id: str = "",
+    ):
+        """
+        创建一个AstrBot消息对象
+
+        Args:
+            type (str): 消息类型
+            self_id (str): 机器人自身ID
+            session_id (str): 会话ID(通常为用户ID)(QQ号, 群号等)
+            message_id (str): 消息ID
+            sender (MessageMember): 发送者信息
+            message (List[BaseMessageComponent]): 消息组件列表
+            message_str (str): 消息字符串
+            raw_message (object): 原始消息对象
+            group_id (str, optional): 群组ID, 如果为私聊则为空. Defaults to "".
+
+        Returns:
+            AstrBotMessage: 创建的消息对象
+        """
+        abm = AstrBotMessage()
+        abm.type = type
+        abm.self_id = self_id
+        abm.session_id = session_id
+        abm.message_id = message_id
+        abm.sender = sender
+        abm.message = message
+        abm.message_str = message_str
+        abm.raw_message = raw_message
+        abm.group_id = group_id
+        return abm
+
+    # todo: 添加构造event的方法
+    # todo: 添加找到对应平台并提交对应事件的方法
+
+    def activate_llm_tool(self, name: str) -> bool:
+        """
+        激活一个已经注册的函数调用工具
+        注册的工具默认是激活状态
+
+        Args:
+            name (str): 工具名称
+        """
+        return self._context.activate_llm_tool(name)
+
+    def deactivate_llm_tool(self, name: str) -> bool:
+        """
+        停用一个已经注册的函数调用工具
+
+        Args:
+            name (str): 工具名称
+        """
+        return self._context.deactivate_llm_tool(name)
+
+    def register_llm_tool(
+        self, name: str, func_args: list, desc: str, func_obj: Awaitable
+    ) -> None:
+        """
+        为函数调用（function-calling/tools-use）添加工具
+
+        Args:
+            name (str): 工具名称
+            func_args (list): 函数参数列表
+            desc (str): 工具描述
+            func_obj (Awaitable): 函数对象，必须是异步函数
+        """
+        self._context.register_llm_tool(name, func_args, desc, func_obj)
+
+    def unregister_llm_tool(self, name: str) -> None:
+        """
+        删除一个函数调用工具
+        如果再要启用，需要重新注册
+
+        Args:
+            name (str): 工具名称
+        """
+        self._context.unregister_llm_tool(name)