Coverage for merco/tools/base.py: 84%

1"""工具基类 — 所有工具继承此类，支持自注册、可用性检查、动态描述""" 

2 

3from abc import ABC, abstractmethod 

4from typing import Any 

5 

6 

7class BaseTool(ABC): 

8 """所有工具的基类 

9 

10 子类设置类属性即可完成注册： 

11 - name / description / parameters — 工具的基本定义 

12 - toolset — 工具所属分组（默认 "general"），用于配置驱动的启用/禁用 

13 - check() — 运行时可用性检查（默认 True），不可用时自动从 LLM 工具列表中隐藏 

14 - describe(context) — 动态描述扩展点，可在运行时根据上下文（如已加载的 skill 列表）增强工具描述 

15 """ 

16 

17 name: str = "" 

18 description: str = "" 

19 parameters: dict = {} 

20 toolset: str = "general" 

21 

22 def check(self) -> bool: 

23 """运行时可用性检查。返回 False 时工具从 LLM 工具列表中隐藏。 

24 

25 子类可重写以检查依赖条件（API key 已配置、依赖包已安装等）。 

26 """ 

27 return True 

28 

29 def describe(self, context: dict | None = None) -> str: 

30 """动态描述扩展点。返回工具的描述文本。 

31 

32 子类可重写以根据运行时上下文增强描述。 

33 例如：skill_view 工具可在描述中列出当前可用的 skill 列表。 

34 context 由注册中心传入，包含 {skills, config, ...} 等运行时信息。 

35 """ 

36 return self.description 

37 

38 def get_definition(self, context: dict | None = None) -> dict: 

39 """构建工具定义（用于 LLM function calling），使用动态描述""" 

40 return { 

41 "type": "function", 

42 "function": { 

43 "name": self.name, 

44 "description": self.describe(context), 

45 "parameters": self.parameters, 

46 }, 

47 } 

48 

49 @abstractmethod 

50 async def execute(self, **kwargs) -> Any: 

51 """执行工具""" 

52 pass 

53 

54 def validate(self, **kwargs) -> bool: 

55 """验证参数""" 

56 required = self.parameters.get("required", []) 

57 return all(key in kwargs for key in required)