AstrBot 4.5.0__py3-none-any.whl → 4.5.2__py3-none-any.whl

astrbot/core/star/config.py

@@ -1,23 +1,20 @@
-"""
-此功能已过时，参考 https://astrbot.app/dev/plugin.html#%E6%B3%A8%E5%86%8C%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE-beta
-"""
+"""此功能已过时，参考 https://astrbot.app/dev/plugin.html#%E6%B3%A8%E5%86%8C%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE-beta"""
 
-from typing import Union
-import os
 import json
+import os
+
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
 
-def load_config(namespace: str) -> Union[dict, bool]:
-    """
-    从配置文件中加载配置。
+def load_config(namespace: str) -> dict | bool:
+    """从配置文件中加载配置。
     namespace: str, 配置的唯一识别符，也就是配置文件的名字。
     返回值: 当配置文件存在时，返回 namespace 对应配置文件的内容dict，否则返回 False。
     """
     path = os.path.join(get_astrbot_data_path(), "config", f"{namespace}.json")
     if not os.path.exists(path):
         return False
-    with open(path, "r", encoding="utf-8-sig") as f:
+    with open(path, encoding="utf-8-sig") as f:
         ret = {}
         data = json.load(f)
         for k in data:
@@ -26,8 +23,7 @@ def load_config(namespace: str) -> Union[dict, bool]:
 
 
 def put_config(namespace: str, name: str, key: str, value, description: str):
-    """
-    将配置项写入以namespace为名字的配置文件，如果key不存在于目标配置文件中。当前 value 仅支持 str, int, float, bool, list 类型（暂不支持 dict）。
+    """将配置项写入以namespace为名字的配置文件，如果key不存在于目标配置文件中。当前 value 仅支持 str, int, float, bool, list 类型（暂不支持 dict）。
     namespace: str, 配置的唯一识别符，也就是配置文件的名字。
     name: str, 配置项的显示名字。
     key: str, 配置项的键。
@@ -51,7 +47,7 @@ def put_config(namespace: str, name: str, key: str, value, description: str):
     if not os.path.exists(path):
         with open(path, "w", encoding="utf-8-sig") as f:
             f.write("{}")
-    with open(path, "r", encoding="utf-8-sig") as f:
+    with open(path, encoding="utf-8-sig") as f:
         d = json.load(f)
     assert isinstance(d, dict)
     if key not in d:
@@ -69,8 +65,7 @@ def put_config(namespace: str, name: str, key: str, value, description: str):
 
 
 def update_config(namespace: str, key: str, value):
-    """
-    更新配置文件中的配置项。
+    """更新配置文件中的配置项。
     namespace: str, 配置的唯一识别符，也就是配置文件的名字。
     key: str, 配置项的键。
     value: str, int, float, bool, list, 配置项的值。
@@ -78,7 +73,7 @@ def update_config(namespace: str, key: str, value):
     path = os.path.join(get_astrbot_data_path(), "config", f"{namespace}.json")
     if not os.path.exists(path):
         raise FileNotFoundError(f"配置文件 {namespace}.json 不存在。")
-    with open(path, "r", encoding="utf-8-sig") as f:
+    with open(path, encoding="utf-8-sig") as f:
         d = json.load(f)
     assert isinstance(d, dict)
     if key not in d:

astrbot/core/star/context.py

@@ -1,48 +1,51 @@
+import logging
 from asyncio import Queue
-from typing import List, Union
+from collections.abc import Awaitable, Callable
+from typing import Any
 
-from astrbot.core.provider.provider import (
-    Provider,
-    TTSProvider,
-    STTProvider,
-    EmbeddingProvider,
-    RerankProvider,
-)
-from astrbot.core.provider.entities import ProviderType
-from astrbot.core.db import BaseDatabase
+from deprecated import deprecated
+
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
 from astrbot.core.config.astrbot_config import AstrBotConfig
-from astrbot.core.provider.func_tool_manager import FunctionToolManager
-from astrbot.core.platform.astr_message_event import MessageSesion
+from astrbot.core.conversation_mgr import ConversationManager
+from astrbot.core.db import BaseDatabase
+from astrbot.core.knowledge_base.kb_mgr import KnowledgeBaseManager
 from astrbot.core.message.message_event_result import MessageChain
-from astrbot.core.provider.manager import ProviderManager
+from astrbot.core.persona_mgr import PersonaManager
 from astrbot.core.platform import Platform
+from astrbot.core.platform.astr_message_event import MessageSesion
 from astrbot.core.platform.manager import PlatformManager
 from astrbot.core.platform_message_history_mgr import PlatformMessageHistoryManager
-from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
-from astrbot.core.knowledge_base.kb_mgr import KnowledgeBaseManager
-from astrbot.core.persona_mgr import PersonaManager
-from .star import star_registry, StarMetadata, star_map
-from .star_handler import star_handlers_registry, StarHandlerMetadata, EventType
-from .filter.command import CommandFilter
-from .filter.regex import RegexFilter
-from typing import Awaitable, Any, Callable
-from astrbot.core.conversation_mgr import ConversationManager
+from astrbot.core.provider.entities import ProviderType
+from astrbot.core.provider.func_tool_manager import FunctionTool, FunctionToolManager
+from astrbot.core.provider.manager import ProviderManager
+from astrbot.core.provider.provider import (
+    EmbeddingProvider,
+    Provider,
+    RerankProvider,
+    STTProvider,
+    TTSProvider,
+)
 from astrbot.core.star.filter.platform_adapter_type import (
-    PlatformAdapterType,
     ADAPTER_NAME_2_TYPE,
+    PlatformAdapterType,
 )
-from deprecated import deprecated
+
+from .filter.command import CommandFilter
+from .filter.regex import RegexFilter
+from .star import StarMetadata, star_map, star_registry
+from .star_handler import EventType, StarHandlerMetadata, star_handlers_registry
+
+logger = logging.getLogger("astrbot")
 
 
 class Context:
-    """
-    暴露给插件的接口上下文。
-    """
+    """暴露给插件的接口上下文。"""
 
     registered_web_apis: list = []
 
     # back compatibility
-    _register_tasks: List[Awaitable] = []
+    _register_tasks: list[Awaitable] = []
     _star_manager = None
 
     def __init__(
@@ -78,7 +81,7 @@ class Context:
             if star.name == star_name:
                 return star
 
-    def get_all_stars(self) -> List[StarMetadata]:
+    def get_all_stars(self) -> list[StarMetadata]:
         """获取当前载入的所有插件 Metadata 的列表"""
         return star_registry
 
@@ -91,6 +94,7 @@ class Context:
 
         Returns:
             如果没找到，会返回 False
+
         """
         return self.provider_manager.llm_tools.activate_llm_tool(name, star_map)
 
@@ -98,17 +102,18 @@ class Context:
         """停用一个已经注册的函数调用工具。
 
         Returns:
-            如果没找到，会返回 False"""
+            如果没找到，会返回 False
+
+        """
         return self.provider_manager.llm_tools.deactivate_llm_tool(name)
 
     def register_provider(self, provider: Provider):
-        """
-        注册一个 LLM Provider(Chat_Completion 类型)。
-        """
+        """注册一个 LLM Provider(Chat_Completion 类型)。"""
         self.provider_manager.provider_insts.append(provider)
 
     def get_provider_by_id(
-        self, provider_id: str
+        self,
+        provider_id: str,
     ) -> (
         Provider | TTSProvider | STTProvider | EmbeddingProvider | RerankProvider | None
     ):
@@ -116,28 +121,28 @@ class Context:
         prov = self.provider_manager.inst_map.get(provider_id)
         return prov
 
-    def get_all_providers(self) -> List[Provider]:
+    def get_all_providers(self) -> list[Provider]:
         """获取所有用于文本生成任务的 LLM Provider(Chat_Completion 类型)。"""
         return self.provider_manager.provider_insts
 
-    def get_all_tts_providers(self) -> List[TTSProvider]:
+    def get_all_tts_providers(self) -> list[TTSProvider]:
         """获取所有用于 TTS 任务的 Provider。"""
         return self.provider_manager.tts_provider_insts
 
-    def get_all_stt_providers(self) -> List[STTProvider]:
+    def get_all_stt_providers(self) -> list[STTProvider]:
         """获取所有用于 STT 任务的 Provider。"""
         return self.provider_manager.stt_provider_insts
 
-    def get_all_embedding_providers(self) -> List[EmbeddingProvider]:
+    def get_all_embedding_providers(self) -> list[EmbeddingProvider]:
         """获取所有用于 Embedding 任务的 Provider。"""
         return self.provider_manager.embedding_provider_insts
 
     def get_using_provider(self, umo: str | None = None) -> Provider | None:
-        """
-        获取当前使用的用于文本生成任务的 LLM Provider(Chat_Completion 类型)。通过 /provider 指令切换。
+        """获取当前使用的用于文本生成任务的 LLM Provider(Chat_Completion 类型)。通过 /provider 指令切换。
 
         Args:
             umo(str): unified_message_origin 值，如果传入并且用户启用了提供商会话隔离，则使用该会话偏好的提供商。
+
         """
         prov = self.provider_manager.get_using_provider(
             provider_type=ProviderType.CHAT_COMPLETION,
@@ -148,11 +153,11 @@ class Context:
         return prov
 
     def get_using_tts_provider(self, umo: str | None = None) -> TTSProvider | None:
-        """
-        获取当前使用的用于 TTS 任务的 Provider。
+        """获取当前使用的用于 TTS 任务的 Provider。
 
         Args:
             umo(str): unified_message_origin 值，如果传入，则使用该会话偏好的提供商。
+
         """
         prov = self.provider_manager.get_using_provider(
             provider_type=ProviderType.TEXT_TO_SPEECH,
@@ -163,11 +168,11 @@ class Context:
         return prov
 
     def get_using_stt_provider(self, umo: str | None = None) -> STTProvider | None:
-        """
-        获取当前使用的用于 STT 任务的 Provider。
+        """获取当前使用的用于 STT 任务的 Provider。
 
         Args:
             umo(str): unified_message_origin 值，如果传入，则使用该会话偏好的提供商。
+
         """
         prov = self.provider_manager.get_using_provider(
             provider_type=ProviderType.SPEECH_TO_TEXT,
@@ -182,25 +187,19 @@ class Context:
         if not umo:
             # using default config
             return self._config
-        else:
-            return self.astrbot_config_mgr.get_conf(umo)
+        return self.astrbot_config_mgr.get_conf(umo)
 
     def get_db(self) -> BaseDatabase:
         """获取 AstrBot 数据库。"""
         return self._db
 
     def get_event_queue(self) -> Queue:
-        """
-        获取事件队列。
-        """
+        """获取事件队列。"""
         return self._event_queue
 
     @deprecated(version="4.0.0", reason="Use get_platform_inst instead")
-    def get_platform(
-        self, platform_type: Union[PlatformAdapterType, str]
-    ) -> Platform | None:
-        """
-        获取指定类型的平台适配器。
+    def get_platform(self, platform_type: PlatformAdapterType | str) -> Platform | None:
+        """获取指定类型的平台适配器。
 
         该方法已经过时，请使用 get_platform_inst 方法。(>= AstrBot v4.0.0)
         """
@@ -209,32 +208,32 @@ class Context:
             if isinstance(platform_type, str):
                 if name == platform_type:
                     return platform
-            else:
-                if (
-                    name in ADAPTER_NAME_2_TYPE
-                    and ADAPTER_NAME_2_TYPE[name] & platform_type
-                ):
-                    return platform
+            elif (
+                name in ADAPTER_NAME_2_TYPE
+                and ADAPTER_NAME_2_TYPE[name] & platform_type
+            ):
+                return platform
 
     def get_platform_inst(self, platform_id: str) -> Platform | None:
-        """
-        获取指定 ID 的平台适配器实例。
+        """获取指定 ID 的平台适配器实例。
 
         Args:
             platform_id (str): 平台适配器的唯一标识符。你可以通过 event.get_platform_id() 获取。
 
         Returns:
             Platform: 平台适配器实例，如果未找到则返回 None。
+
         """
         for platform in self.platform_manager.platform_insts:
             if platform.meta().id == platform_id:
                 return platform
 
     async def send_message(
-        self, session: Union[str, MessageSesion], message_chain: MessageChain
+        self,
+        session: str | MessageSesion,
+        message_chain: MessageChain,
     ) -> bool:
-        """
-        根据 session(unified_msg_origin) 主动发送消息。
+        """根据 session(unified_msg_origin) 主动发送消息。
 
         @param session: 消息会话。通过 event.session 或者 event.unified_msg_origin 获取。
         @param message_chain: 消息链。
@@ -245,7 +244,6 @@ class Context:
 
         NOTE: qq_official(QQ 官方 API 平台) 不支持此方法
         """
-
         if isinstance(session, str):
             try:
                 session = MessageSesion.from_str(session)
@@ -258,6 +256,46 @@ class Context:
                 return True
         return False
 
+    def add_llm_tools(self, *tools: FunctionTool) -> None:
+        """添加 LLM 工具。"""
+        tool_name = {tool.name for tool in self.provider_manager.llm_tools.func_list}
+        module_path = ""
+        for tool in tools:
+            if not module_path:
+                _parts = []
+                module_part = tool.__module__.split(".")
+                flags = ["packages", "plugins"]
+                for i, part in enumerate(module_part):
+                    _parts.append(part)
+                    if part in flags and i + 1 < len(module_part):
+                        _parts.append(module_part[i + 1])
+                        break
+                tool.handler_module_path = ".".join(_parts)
+                module_path = tool.handler_module_path
+            else:
+                tool.handler_module_path = module_path
+            logger.info(
+                f"plugin(module_path {module_path}) added LLM tool: {tool.name}"
+            )
+
+            if tool.name in tool_name:
+                logger.warning("替换已存在的 LLM 工具: " + tool.name)
+                self.provider_manager.llm_tools.remove_func(tool.name)
+            self.provider_manager.llm_tools.func_list.append(tool)
+
+    def register_web_api(
+        self,
+        route: str,
+        view_handler: Awaitable,
+        methods: list,
+        desc: str,
+    ):
+        for idx, api in enumerate(self.registered_web_apis):
+            if api[0] == route and methods == api[2]:
+                self.registered_web_apis[idx] = (route, view_handler, methods, desc)
+                return
+        self.registered_web_apis.append((route, view_handler, methods, desc))
+
     """
     以下的方法已经不推荐使用。请从 AstrBot 文档查看更好的注册方式。
     """
@@ -269,8 +307,7 @@ class Context:
         desc: str,
         func_obj: Callable[..., Awaitable[Any]],
     ) -> None:
-        """
-        为函数调用（function-calling / tools-use）添加工具。
+        """[DEPRECATED]为函数调用（function-calling / tools-use）添加工具。
 
         @param name: 函数名
         @param func_args: 函数参数列表，格式为 [{"type": "string", "name": "arg_name", "description": "arg_description"}, ...]
@@ -292,7 +329,7 @@ class Context:
         self.provider_manager.llm_tools.add_func(name, func_args, desc, func_obj)
 
     def unregister_llm_tool(self, name: str) -> None:
-        """删除一个函数调用工具。如果再要启用，需要重新注册。"""
+        """[DEPRECATED]删除一个函数调用工具。如果再要启用，需要重新注册。"""
         self.provider_manager.llm_tools.remove_func(name)
 
     def register_commands(
@@ -305,8 +342,7 @@ class Context:
         use_regex=False,
         ignore_prefix=False,
     ):
-        """
-        注册一个命令。
+        """注册一个命令。
 
         [Deprecated] 推荐使用装饰器注册指令。该方法将在未来的版本中被移除。
 
@@ -330,21 +366,10 @@ class Context:
             md.event_filters.append(RegexFilter(regex=command_name))
         else:
             md.event_filters.append(
-                CommandFilter(command_name=command_name, handler_md=md)
+                CommandFilter(command_name=command_name, handler_md=md),
             )
         star_handlers_registry.append(md)
 
     def register_task(self, task: Awaitable, desc: str):
-        """
-        注册一个异步任务。
-        """
+        """[DEPRECATED]注册一个异步任务。"""
         self._register_tasks.append(task)
-
-    def register_web_api(
-        self, route: str, view_handler: Awaitable, methods: list, desc: str
-    ):
-        for idx, api in enumerate(self.registered_web_apis):
-            if api[0] == route and methods == api[2]:
-                self.registered_web_apis[idx] = (route, view_handler, methods, desc)
-                return
-        self.registered_web_apis.append((route, view_handler, methods, desc))

astrbot/core/star/filter/__init__.py

@@ -1,7 +1,8 @@
 import abc
-from astrbot.core.platform.message_type import MessageType
-from astrbot.core.platform.astr_message_event import AstrMessageEvent
+
 from astrbot.core.config import AstrBotConfig
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.platform.message_type import MessageType
 
 
 class HandlerFilter(abc.ABC):
@@ -11,4 +12,4 @@ class HandlerFilter(abc.ABC):
         raise NotImplementedError
 
 
-__all__ = ["HandlerFilter", "MessageType", "AstrMessageEvent", "AstrBotConfig"]
+__all__ = ["AstrBotConfig", "AstrMessageEvent", "HandlerFilter", "MessageType"]

astrbot/core/star/filter/command.py

@@ -1,20 +1,20 @@
-import re
 import inspect
+import re
 import types
 import typing
-from typing import List, Any, Type, Dict
-from . import HandlerFilter
-from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from typing import Any
+
 from astrbot.core.config import AstrBotConfig
-from .custom_filter import CustomFilter
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+
 from ..star_handler import StarHandlerMetadata
+from . import HandlerFilter
+from .custom_filter import CustomFilter
 
 
 class GreedyStr(str):
     """标记指令完成其他参数接收后的所有剩余文本。"""
 
-    pass
-
 
 def unwrap_optional(annotation) -> tuple:
     """去掉 Optional[T] / Union[T, None] / T|None，返回 T"""
@@ -22,10 +22,9 @@ def unwrap_optional(annotation) -> tuple:
     non_none_args = [a for a in args if a is not type(None)]
     if len(non_none_args) == 1:
         return (non_none_args[0],)
-    elif len(non_none_args) > 1:
+    if len(non_none_args) > 1:
         return tuple(non_none_args)
-    else:
-        return ()
+    return ()
 
 
 # 标准指令受到 wake_prefix 的制约。
@@ -37,28 +36,30 @@ class CommandFilter(HandlerFilter):
         command_name: str,
         alias: set | None = None,
         handler_md: StarHandlerMetadata | None = None,
-        parent_command_names: List[str] = [""],
+        parent_command_names: list[str] | None = None,
     ):
         self.command_name = command_name
         self.alias = alias if alias else set()
-        self.parent_command_names = parent_command_names
+        self.parent_command_names = (
+            parent_command_names if parent_command_names is not None else [""]
+        )
         if handler_md:
             self.init_handler_md(handler_md)
-        self.custom_filter_list: List[CustomFilter] = []
+        self.custom_filter_list: list[CustomFilter] = []
 
         # Cache for complete command names list
         self._cmpl_cmd_names: list | None = None
 
     def print_types(self):
-        result = ""
+        parts = []
         for k, v in self.handler_params.items():
             if isinstance(v, type):
-                result += f"{k}({v.__name__}),"
+                parts.append(f"{k}({v.__name__}),")
             elif isinstance(v, types.UnionType) or typing.get_origin(v) is typing.Union:
-                result += f"{k}({v}),"
+                parts.append(f"{k}({v}),")
             else:
-                result += f"{k}({type(v).__name__})={v},"
-        result = result.rstrip(",")
+                parts.append(f"{k}({type(v).__name__})={v},")
+        result = "".join(parts).rstrip(",")
         return result
 
     def init_handler_md(self, handle_md: StarHandlerMetadata):
@@ -89,8 +90,10 @@ class CommandFilter(HandlerFilter):
         return True
 
     def validate_and_convert_params(
-        self, params: List[Any], param_type: Dict[str, Type]
-    ) -> Dict[str, Any]:
+        self,
+        params: list[Any],
+        param_type: dict[str, type],
+    ) -> dict[str, Any]:
         """将参数列表 params 根据 param_type 转换为参数字典。"""
         result = {}
         param_items = list(param_type.items())
@@ -101,7 +104,7 @@ class CommandFilter(HandlerFilter):
                 # GreedyStr 必须是最后一个参数
                 if i != len(param_items) - 1:
                     raise ValueError(
-                        f"参数 '{param_name}' (GreedyStr) 必须是最后一个参数。"
+                        f"参数 '{param_name}' (GreedyStr) 必须是最后一个参数。",
                     )
 
                 # 将剩余的所有部分合并成一个字符串
@@ -111,17 +114,16 @@ class CommandFilter(HandlerFilter):
             # 没有 GreedyStr 的情况
             if i >= len(params):
                 if (
-                    isinstance(param_type_or_default_val, (Type, types.UnionType))
+                    isinstance(param_type_or_default_val, (type, types.UnionType))
                     or typing.get_origin(param_type_or_default_val) is typing.Union
                     or param_type_or_default_val is inspect.Parameter.empty
                 ):
                     # 是类型
                     raise ValueError(
-                        f"必要参数缺失。该指令完整参数: {self.print_types()}"
+                        f"必要参数缺失。该指令完整参数: {self.print_types()}",
                     )
-                else:
-                    # 是默认值
-                    result[param_name] = param_type_or_default_val
+                # 是默认值
+                result[param_name] = param_type_or_default_val
             else:
                 # 尝试强制转换
                 try:
@@ -142,7 +144,7 @@ class CommandFilter(HandlerFilter):
                             result[param_name] = False
                         else:
                             raise ValueError(
-                                f"参数 {param_name} 必须是布尔值（true/false, yes/no, 1/0）。"
+                                f"参数 {param_name} 必须是布尔值（true/false, yes/no, 1/0）。",
                             )
                     elif isinstance(param_type_or_default_val, int):
                         result[param_name] = int(params[i])
@@ -165,7 +167,7 @@ class CommandFilter(HandlerFilter):
                             result[param_name] = param_type_or_default_val(params[i])
                 except ValueError:
                     raise ValueError(
-                        f"参数 {param_name} 类型错误。完整参数: {self.print_types()}"
+                        f"参数 {param_name} 类型错误。完整参数: {self.print_types()}",
                     )
         return result