mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-13 16:10:05 +08:00
✨ feat!(llm): 重构并升级大语言模型服务为全新 AI 智能体框架 (#2146)
* ✨ feat!(llm): 重构并升级大语言模型服务为全新 AI 智能体框架 - 【重构】将原 services/llm 重构并迁移至全新的 services/ai 架构，提供向下兼容垫片 - 【新增】引入 Agent、Team、Workflow 三大智能体与工作流编排范式 - 【新增】引入基于 RAG 的长期向量记忆与中期槽位记忆系统 - 【新增】引入基于 Docker 的安全代码执行沙箱环境 - 【新增】支持 MCP 协议，允许动态管理和调用 MCP 服务 - 【新增】引入输入输出安全合规护栏与自愈反思机制 - 【优化】重构并优化多厂商 API 适配器 (Gemini, OpenAI, DeepSeek, GLM 等) - 【优化】优化日志脱敏与 Token 预估机制 - 【移除】移除旧版 llm default 和 llm reset-key 命令，新增 llm mcp 管理命令 * 🔧 chore(deps): 更新项目依赖与配置 - 添加 mcp、jieba 和 aiodocker 依赖到配置文件及 requirements.txt - 在 pyright 配置中设置 reportMissingImports 为 none - 调整 .gitignore 中 resources 目录的忽略规则 * ♻️ refactor(tools): 重构工具终止机制并清理知识库日志输出 - 统一使用 `context.state["__end_run__"]` 替代 `EndRunResult` 控制任务结束 - 移除文件系统和向量知识库检索工具中 `ToolResult` 的 `.with_log` 调用 - 调整指令处理器（Directive）的返回值为 `tool_res.output` - 修复部分类型检查警告并优化联合类型判断语法 * ♻️ refactor(tools): 重构工具副作用指令与控制流熔断机制 - 引入 `DirectivePayload` 及 `ToolResult` 的子类以结构化表达工具副作用 - 移除通过 `context.state` 传递魔术变量的隐式控制流设计 - 重构 `DirectiveManager` 处理器接口，直接在处理器中修改 `AgentState` 并构建 `AgentRunResult` - 在 `StandardAgentExecutor` 中统一通过 `directive_manager` 调度工具返回的副作用指令 - 补全 `MessageBuilder` 中部分核心方法的文档注释 * 🐛 fix(sandbox): 修复 Docker 沙箱容器状态检测与会话清理逻辑 -【修复】修正 `is_alive` 中直接读取私有属性的问题，改用 `show()` 返回值 -【修复】解决 `execute_code` 中缓存的执行器与当前会话不一致的问题 -【优化】在清理工作区前增加容器存活检测，避免向已死容器发送请求 -【优化】创建容器时增加运行状态校验，若已停止则自动从缓存中移除并重建 -【优化】优化容器销毁和清理逻辑，静默处理容器不存在 (404) 的异常 * 📝 docs(core): 补充核心模块初始化方法的文档注释 * 🚨 auto fix by pre-commit hooks --------- Co-authored-by: webjoin111 <455457521@qq.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Rumio
co-authored by
webjoin111
pre-commit-ci[bot]
webjoin111
pre-commit-ci[bot]
parent
bdc1374848
commit
80fc5b86a7
@@ -0,0 +1,23 @@
|
||||
from .decorators import Rules, tool
|
||||
from .schema import (
|
||||
FieldPermission,
|
||||
RequireAdminLevel,
|
||||
RequireSuperUser,
|
||||
)
|
||||
from .tool import BaseTool, FunctionTool
|
||||
from .toolkit import (
|
||||
BaseToolkit,
|
||||
CompositeToolkit,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"BaseTool",
|
||||
"BaseToolkit",
|
||||
"CompositeToolkit",
|
||||
"FieldPermission",
|
||||
"FunctionTool",
|
||||
"RequireAdminLevel",
|
||||
"RequireSuperUser",
|
||||
"Rules",
|
||||
"tool",
|
||||
]
|
||||
@@ -0,0 +1,398 @@
|
||||
import asyncio
|
||||
from collections.abc import Callable
|
||||
from typing import Any
|
||||
|
||||
from aiocache import SimpleMemoryCache
|
||||
|
||||
from zhenxun.services.ai.capabilities import (
|
||||
AbstractCapability,
|
||||
WrapToolExecuteHandler,
|
||||
WrapToolValidateHandler,
|
||||
)
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.tools.models import ToolResult
|
||||
from zhenxun.services.ai.utils import PermissionUtils
|
||||
from zhenxun.services.log import logger
|
||||
from zhenxun.utils.pydantic_compat import model_dump, parse_as
|
||||
|
||||
_TOOL_RESULT_CACHE = SimpleMemoryCache(namespace="zhenxun_tool_cache")
|
||||
|
||||
|
||||
class CacheCapability(AbstractCapability):
|
||||
"""
|
||||
极速缓存能力中间件 (Tool-Level)
|
||||
拦截相同的参数调用，直接返回缓存结果，无需请求底层。
|
||||
"""
|
||||
|
||||
def __init__(self, ttl: int = 3600, cache_function: Callable | None = None):
|
||||
"""
|
||||
初始化极速缓存能力中间件。
|
||||
|
||||
参数:
|
||||
ttl: 缓存结果的有效存活时长（秒），默认 3600。
|
||||
cache_function: 自定义判定函数，接收 arguments 与 result，
|
||||
返回布尔值决定该次结果是否允许缓存，默认 None。
|
||||
"""
|
||||
self.ttl = ttl
|
||||
self.cache_function = cache_function
|
||||
|
||||
async def wrap_tool_execute(
|
||||
self,
|
||||
context: RunContext,
|
||||
tool_name: str,
|
||||
arguments: dict[str, Any],
|
||||
handler: WrapToolExecuteHandler,
|
||||
) -> Any:
|
||||
tool = context.call.current_tool
|
||||
if tool is None:
|
||||
return await handler(arguments)
|
||||
if not hasattr(tool, "_generate_cache_key"):
|
||||
return await handler(arguments)
|
||||
|
||||
cache_key = tool._generate_cache_key(arguments)
|
||||
cached_data = await _TOOL_RESULT_CACHE.get(cache_key)
|
||||
if cached_data is not None:
|
||||
cached_result = (
|
||||
parse_as(ToolResult, cached_data)
|
||||
if isinstance(cached_data, dict)
|
||||
else cached_data
|
||||
)
|
||||
logger.info(
|
||||
f"⚡ [Cache Hit] 工具 {tool_name} 命中极速缓存, "
|
||||
f"熔断执行! Key: {cache_key}"
|
||||
)
|
||||
return cached_result
|
||||
|
||||
result = await handler(arguments)
|
||||
|
||||
if result and not getattr(result, "is_error", False):
|
||||
should_cache = True
|
||||
if self.cache_function:
|
||||
try:
|
||||
should_cache = self.cache_function(arguments, result)
|
||||
except Exception as ce:
|
||||
logger.warning(f"Cache function 执行失败: {ce}")
|
||||
should_cache = False
|
||||
if should_cache:
|
||||
await _TOOL_RESULT_CACHE.set(
|
||||
cache_key, model_dump(result), ttl=self.ttl
|
||||
)
|
||||
|
||||
return result
|
||||
|
||||
|
||||
class ApprovalCapability(AbstractCapability):
|
||||
"""
|
||||
人工审批能力中间件 (Tool-Level / HITL)
|
||||
执行高危操作前在群聊中发起授权确认，拒绝则抛出取消异常。
|
||||
"""
|
||||
|
||||
async def wrap_tool_execute(
|
||||
self,
|
||||
context: RunContext,
|
||||
tool_name: str,
|
||||
arguments: dict[str, Any],
|
||||
handler: WrapToolExecuteHandler,
|
||||
) -> Any:
|
||||
tool = context.call.current_tool
|
||||
if tool is None:
|
||||
return await handler(arguments)
|
||||
|
||||
import json
|
||||
|
||||
args_str = json.dumps(arguments, ensure_ascii=False, indent=2)
|
||||
confirm_msg = f"即将在本地执行高危工具 [{tool_name}]\n参数：\n{args_str}"
|
||||
|
||||
if "global" not in context.run.hitl_locks:
|
||||
context.run.hitl_locks["global"] = asyncio.Lock()
|
||||
hitl_lock = context.run.hitl_locks["global"]
|
||||
|
||||
await hitl_lock.acquire()
|
||||
try:
|
||||
from zhenxun.services.ai.run.hitl import HITLController
|
||||
|
||||
hitl = HITLController(context)
|
||||
await hitl.ask_confirm(f"⚠️ **安全交互审批**\n\n{confirm_msg}", timeout=60.0)
|
||||
logger.info(f"🛡️ [HITL] 工具 {tool_name} 审批通过。")
|
||||
finally:
|
||||
hitl_lock.release()
|
||||
|
||||
return await handler(arguments)
|
||||
|
||||
|
||||
class LifecycleCapability(AbstractCapability):
|
||||
"""
|
||||
通用生命周期能力中间件 (Generic Lifecycle Capability)
|
||||
接收开发者传入的简单函数，自动为其提供依赖注入 (DI) 和洋葱模型拦截。
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
before_execute: Callable | None = None,
|
||||
after_execute: Callable | None = None,
|
||||
validate_args: Callable | None = None,
|
||||
prepare_tool: Callable | None = None,
|
||||
):
|
||||
"""
|
||||
初始化通用生命周期能力中间件。
|
||||
|
||||
参数:
|
||||
before_execute: 在工具开始执行前触发的钩子函数，默认 None。
|
||||
after_execute: 在工具执行完毕后触发的钩子/拦截函数，默认 None。
|
||||
validate_args: 在工具参数验证阶段拦截的自定义校验函数，默认 None。
|
||||
prepare_tool: 在加载并提供大模型 Schema 定义前进行拦截加工的准备函数，
|
||||
默认 None。
|
||||
"""
|
||||
self.before_execute_hook = before_execute
|
||||
self.after_execute_hook = after_execute
|
||||
self.validate_args_hook = validate_args
|
||||
self.prepare_tool_hook = prepare_tool
|
||||
|
||||
async def prepare_tools(
|
||||
self, context: RunContext, tool_defs: list[Any]
|
||||
) -> list[Any]:
|
||||
if not self.prepare_tool_hook:
|
||||
return tool_defs
|
||||
new_defs = []
|
||||
for tdef in tool_defs:
|
||||
res = await DependencyInjector.invoke(
|
||||
self.prepare_tool_hook, {"tool_def": tdef}, context
|
||||
)
|
||||
if res is not None:
|
||||
new_defs.append(res)
|
||||
return new_defs
|
||||
|
||||
async def wrap_tool_validate(
|
||||
self,
|
||||
context: RunContext,
|
||||
tool_name: str,
|
||||
args: str | dict[str, Any],
|
||||
handler: WrapToolValidateHandler,
|
||||
) -> dict[str, Any]:
|
||||
if not self.validate_args_hook or not isinstance(args, dict):
|
||||
return await handler(args)
|
||||
call_kwargs = dict(args)
|
||||
call_kwargs["args"] = args
|
||||
call_kwargs["tool_args"] = args
|
||||
call_kwargs["tool_name"] = tool_name
|
||||
await DependencyInjector.invoke(self.validate_args_hook, call_kwargs, context)
|
||||
return await handler(args)
|
||||
|
||||
async def wrap_tool_execute(
|
||||
self,
|
||||
context: RunContext,
|
||||
tool_name: str,
|
||||
arguments: dict[str, Any],
|
||||
handler: WrapToolExecuteHandler,
|
||||
) -> Any:
|
||||
if not self.before_execute_hook:
|
||||
pass
|
||||
else:
|
||||
call_kwargs = dict(arguments)
|
||||
call_kwargs["args"] = arguments
|
||||
call_kwargs["tool_args"] = arguments
|
||||
call_kwargs["tool_name"] = tool_name
|
||||
await DependencyInjector.invoke(
|
||||
self.before_execute_hook, call_kwargs, context
|
||||
)
|
||||
|
||||
result = await handler(arguments)
|
||||
|
||||
if not self.after_execute_hook:
|
||||
return result
|
||||
call_kwargs = dict(arguments)
|
||||
call_kwargs["args"] = arguments
|
||||
call_kwargs["tool_args"] = arguments
|
||||
call_kwargs["tool_name"] = tool_name
|
||||
call_kwargs["result"] = result
|
||||
call_kwargs["tool_result"] = result
|
||||
|
||||
res = await DependencyInjector.invoke(
|
||||
self.after_execute_hook, call_kwargs, context
|
||||
)
|
||||
return res if res is not None else result
|
||||
|
||||
|
||||
class SuperuserCapability(AbstractCapability):
|
||||
"""仅超级管理员可见"""
|
||||
|
||||
async def prepare_tools(
|
||||
self, context: RunContext, tool_defs: list[Any]
|
||||
) -> list[Any]:
|
||||
if await PermissionUtils.check_superuser(context):
|
||||
return tool_defs
|
||||
return []
|
||||
|
||||
|
||||
class AdminLevelCapability(AbstractCapability):
|
||||
"""需要指定群聊权限等级"""
|
||||
|
||||
def __init__(self, min_level: int):
|
||||
"""
|
||||
初始化群聊权限等级限制能力。
|
||||
|
||||
参数:
|
||||
min_level: 允许执行该工具的最小群聊管理权限等级。
|
||||
"""
|
||||
self.min_level = min_level
|
||||
|
||||
async def prepare_tools(
|
||||
self, context: RunContext, tool_defs: list[Any]
|
||||
) -> list[Any]:
|
||||
if await PermissionUtils.check_admin_level(context, self.min_level):
|
||||
return tool_defs
|
||||
return []
|
||||
|
||||
|
||||
class GroupOnlyCapability(AbstractCapability):
|
||||
"""仅群聊可用"""
|
||||
|
||||
async def prepare_tools(
|
||||
self, context: RunContext, tool_defs: list[Any]
|
||||
) -> list[Any]:
|
||||
if context.get_group_id():
|
||||
return tool_defs
|
||||
return []
|
||||
|
||||
|
||||
class ConfigDependencyCapability(AbstractCapability):
|
||||
"""依赖特定配置开关"""
|
||||
|
||||
def __init__(self, module: str, key: str, expected_value: Any = True):
|
||||
"""
|
||||
初始化配置依赖开关能力。
|
||||
|
||||
参数:
|
||||
module: 目标配置所属的模块名。
|
||||
key: 目标配置项的键名。
|
||||
expected_value: 期望该配置项所匹配的值，如果匹配通过才可见/可用该工具，默认 True。
|
||||
""" # noqa: E501
|
||||
self.module = module
|
||||
self.key = key
|
||||
self.expected_value = expected_value
|
||||
|
||||
async def prepare_tools(
|
||||
self, context: RunContext, tool_defs: list[Any]
|
||||
) -> list[Any]:
|
||||
from zhenxun.configs.config import Config
|
||||
|
||||
if Config.get_config(self.module, self.key) == self.expected_value:
|
||||
return tool_defs
|
||||
return []
|
||||
|
||||
|
||||
class InteractiveCapability(AbstractCapability):
|
||||
"""交互式补全局部中间件：在验证阶段拦截参数缺失异常并向用户提问"""
|
||||
|
||||
async def wrap_tool_validate(
|
||||
self,
|
||||
context: RunContext,
|
||||
tool_name: str,
|
||||
args: str | dict[str, Any],
|
||||
handler: WrapToolValidateHandler,
|
||||
) -> dict[str, Any]:
|
||||
from zhenxun.services.ai.core.exceptions import (
|
||||
NeedsInputException,
|
||||
ToolFatalError,
|
||||
ToolRetryError,
|
||||
)
|
||||
|
||||
tool = context.call.current_tool
|
||||
current_kwargs = dict(args) if isinstance(args, dict) else args
|
||||
|
||||
while True:
|
||||
try:
|
||||
return await handler(current_kwargs)
|
||||
except NeedsInputException as e:
|
||||
bot = context.get_bot()
|
||||
event = context.get_event()
|
||||
|
||||
if not bot or not event:
|
||||
logger.warning(
|
||||
"交互式工具 "
|
||||
f"{getattr(tool, 'name', 'unknown')} "
|
||||
"缺少参数，但处于非交互环境。"
|
||||
)
|
||||
raise ToolRetryError(f"缺少必填参数: {e.missing_description}。")
|
||||
|
||||
prompt_msg = (
|
||||
f"执行 {getattr(tool, 'name', '该操作')} "
|
||||
f"需要补充参数：\n[{e.missing_description}]\n"
|
||||
"请发送文本补充，或回复“取消”中止。"
|
||||
)
|
||||
try:
|
||||
from zhenxun.services.ai.run.hitl import HITLController
|
||||
|
||||
hitl = HITLController(context)
|
||||
user_input = await hitl.ask_text(prompt_msg, timeout=60.0)
|
||||
except ToolFatalError:
|
||||
raise ToolFatalError(
|
||||
"参数收集超时，用户已离开，任务已中止。",
|
||||
display_content=(
|
||||
"❌ 工具 "
|
||||
f"'{getattr(tool, 'name', '')}' "
|
||||
"等待参数输入超时被取消。"
|
||||
),
|
||||
)
|
||||
if not isinstance(current_kwargs, dict):
|
||||
current_kwargs = {}
|
||||
current_kwargs[e.missing_field] = user_input
|
||||
|
||||
|
||||
class FallbackCapability(AbstractCapability):
|
||||
"""
|
||||
降级路由器局部中间件。
|
||||
拦截执行结果，若发现报错且配置了备用工具，则透明重定向执行流。
|
||||
"""
|
||||
|
||||
def __init__(self, fallback_tool_name: str):
|
||||
"""
|
||||
初始化降级路由器局部中间件。
|
||||
|
||||
参数:
|
||||
fallback_tool_name: 当主工具执行遇到错误时，自动透明重定向到的备用工具名称。
|
||||
"""
|
||||
self.fallback_tool_name = fallback_tool_name
|
||||
|
||||
async def wrap_tool_execute(
|
||||
self,
|
||||
context: RunContext,
|
||||
tool_name: str,
|
||||
arguments: dict[str, Any],
|
||||
handler: WrapToolExecuteHandler,
|
||||
) -> Any:
|
||||
result = await handler(arguments)
|
||||
if result and getattr(result, "is_error", False):
|
||||
available_tools = context.state.get("__available_tools", {})
|
||||
fallback_executable = available_tools.get(self.fallback_tool_name)
|
||||
if fallback_executable:
|
||||
logger.info(
|
||||
f"🔄 [语义容错路由] 主工具 '{tool_name}' 故障，"
|
||||
"正在透明重定向至备用工具 "
|
||||
f"'{self.fallback_tool_name}'..."
|
||||
)
|
||||
try:
|
||||
fallback_result = await fallback_executable.execute(
|
||||
context=context, **arguments
|
||||
)
|
||||
notice = (
|
||||
f"[系统底座：由于主工具 '{tool_name}' 发生故障，"
|
||||
"系统已自动路由至备用工具 "
|
||||
f"'{self.fallback_tool_name}' 并执行成功]\n"
|
||||
)
|
||||
if isinstance(fallback_result.output, str):
|
||||
fallback_result.output = notice + fallback_result.output
|
||||
return fallback_result
|
||||
except Exception as fallback_e:
|
||||
logger.error(
|
||||
"容错路由工具 "
|
||||
f"'{self.fallback_tool_name}' "
|
||||
f"也执行失败: {fallback_e}"
|
||||
)
|
||||
context.run.add_system_prompt(
|
||||
"🚨 [系统警告] 原工具和备用工具"
|
||||
f"({self.fallback_tool_name})均执行失败，"
|
||||
"请停止尝试并告知用户。"
|
||||
)
|
||||
return result
|
||||
@@ -0,0 +1,423 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from typing import Any
|
||||
|
||||
from zhenxun.services.ai.capabilities import AbstractCapability
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
from zhenxun.services.ai.tools.models import ToolOptions
|
||||
|
||||
|
||||
def _update_settings(func: Callable, **kwargs) -> Callable:
|
||||
"""叠加协议底层：创建或更新函数的 __tool_settings__"""
|
||||
if not hasattr(func, "__tool_settings__"):
|
||||
setattr(func, "__tool_settings__", ToolOptions())
|
||||
settings: ToolOptions = getattr(func, "__tool_settings__")
|
||||
for k, v in kwargs.items():
|
||||
if k == "capabilities":
|
||||
settings.capabilities.extend(v)
|
||||
elif k == "metadata":
|
||||
settings.metadata.update(v)
|
||||
else:
|
||||
setattr(settings, k, v)
|
||||
return func
|
||||
|
||||
|
||||
def require_sandbox(
|
||||
python_packages: list[str] | None = None,
|
||||
node_packages: list[str] | None = None,
|
||||
system_packages: list[str] | None = None,
|
||||
):
|
||||
"""显式声明该工具所需安装的沙箱环境依赖"""
|
||||
|
||||
def decorator(func):
|
||||
setattr(
|
||||
func,
|
||||
"__sandbox_requirements__",
|
||||
{
|
||||
"python": python_packages or [],
|
||||
"node": node_packages or [],
|
||||
"system": system_packages or [],
|
||||
},
|
||||
)
|
||||
return func
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
class ToolkitMethodDescriptor:
|
||||
"""用于 Toolkit 类方法的描述符，确保在实例化时绑定正确的 self 并生成 FunctionTool"""
|
||||
|
||||
def __init__(
|
||||
self, func: Callable, name: str, description: str, settings: ToolOptions
|
||||
):
|
||||
self.func = func
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.settings = settings
|
||||
self.__toolkit_tool__ = True
|
||||
self.__tool_original_name__ = name
|
||||
|
||||
def __get__(self, instance, owner):
|
||||
if instance is None:
|
||||
return self
|
||||
import types
|
||||
|
||||
from zhenxun.services.ai.tools.core.tool import FunctionTool
|
||||
from zhenxun.utils.pydantic_compat import model_copy
|
||||
|
||||
bound_func = types.MethodType(self.func, instance)
|
||||
return FunctionTool(
|
||||
func=bound_func,
|
||||
name=self.name,
|
||||
description=self.description,
|
||||
settings=model_copy(self.settings, deep=True),
|
||||
)
|
||||
|
||||
def __call__(self, *args, **kwargs):
|
||||
"""使其兼容 Callable 协议，避免静态类型检查器报错"""
|
||||
return self.func(*args, **kwargs)
|
||||
|
||||
|
||||
def tool(
|
||||
name: str | None = None,
|
||||
description: str | None = None,
|
||||
settings: ToolOptions | None = None,
|
||||
tags: list[str] | None = None,
|
||||
auto_register: bool = False,
|
||||
require_prefix: bool = False,
|
||||
):
|
||||
"""
|
||||
将普通函数或类方法注册为 LLM 工具的统一装饰器大一统。
|
||||
|
||||
参数:
|
||||
name: 工具的名称(英文字母及下划线)。
|
||||
大模型将看到此名称。如果为空则默认使用函数名。
|
||||
description: 工具描述。
|
||||
大模型将基于此决定何时、如何使用该工具。如果为空，将读取函数 docstring。
|
||||
settings: 工具的高阶配置对象 (ToolOptions)。
|
||||
用于控制极速缓存、人工审批拦截、静默执行等扩展能力。
|
||||
tags: 工具的标签列表。
|
||||
用于被 Agent 的智能字符串路由识别并进行能力注入。
|
||||
auto_register: 是否自动注册到当前命名空间的工具注册表。
|
||||
默认为 False，开发者需要显式传递实例。若为 True 方可通过字符串调用。
|
||||
require_prefix: 是否自动添加插件命名空间前缀（仅对游离函数生效）。默认为 False。
|
||||
返回:
|
||||
Callable | FunctionTool: 包装后的函数或方法。
|
||||
"""
|
||||
|
||||
def decorator(func: Callable):
|
||||
base_settings = settings or ToolOptions()
|
||||
if tags:
|
||||
base_settings.tags = list(set(base_settings.tags + tags))
|
||||
existing_settings = getattr(func, "__tool_settings__", None)
|
||||
if existing_settings and isinstance(existing_settings, ToolOptions):
|
||||
base_settings = existing_settings.merge(base_settings)
|
||||
|
||||
reqs = getattr(func, "__sandbox_requirements__", None)
|
||||
if reqs:
|
||||
base_settings.sandbox_requirements = reqs
|
||||
|
||||
tool_name = name or func.__name__
|
||||
tool_desc = description or func.__doc__ or "未提供描述"
|
||||
|
||||
import inspect
|
||||
|
||||
is_method = False
|
||||
if (
|
||||
hasattr(func, "__qualname__")
|
||||
and "." in func.__qualname__
|
||||
and "<locals>" not in func.__qualname__
|
||||
):
|
||||
is_method = True
|
||||
else:
|
||||
try:
|
||||
sig = inspect.signature(func)
|
||||
params = list(sig.parameters.keys())
|
||||
if params and params[0] in ("self", "cls"):
|
||||
is_method = True
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
if is_method:
|
||||
return ToolkitMethodDescriptor(
|
||||
func=func, name=tool_name, description=tool_desc, settings=base_settings
|
||||
)
|
||||
else:
|
||||
if require_prefix:
|
||||
from zhenxun.utils.utils import infer_plugin_namespace
|
||||
|
||||
ns = infer_plugin_namespace(default="global")
|
||||
if ns and ns not in ("global", "unknown"):
|
||||
if not tool_name.startswith(f"{ns}_"):
|
||||
tool_name = f"{ns}_{tool_name}"
|
||||
|
||||
from zhenxun.services.ai.tools.core.tool import FunctionTool
|
||||
from zhenxun.services.ai.tools.engine.registry import tool_provider_manager
|
||||
from zhenxun.services.log import logger
|
||||
|
||||
func_tool = FunctionTool(
|
||||
func=func,
|
||||
name=tool_name,
|
||||
description=tool_desc,
|
||||
settings=base_settings,
|
||||
)
|
||||
if auto_register:
|
||||
tool_provider_manager.register_tool(func_tool)
|
||||
logger.debug(f"已按命名空间隔离注册了工具(Callable): '{tool_name}'")
|
||||
|
||||
setattr(func_tool, "__tool_settings__", base_settings)
|
||||
return func_tool
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def with_cache(ttl: int = 3600, cache_function: Callable | None = None):
|
||||
"""开启极速缓存，阻止参数相同的重复请求发往底层。"""
|
||||
|
||||
from zhenxun.services.ai.tools.core.capabilities import CacheCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func,
|
||||
capabilities=[CacheCapability(ttl=ttl, cache_function=cache_function)],
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def silent():
|
||||
"""静默执行。工具执行过程与结果不会作为界面流渲染给用户，仅作大模型内部参考。"""
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, silent=True)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def direct_reply():
|
||||
"""直出模式。工具执行完毕后强制中断大模型的思考循环，将工具输出作为最终回答返回。"""
|
||||
|
||||
class DirectReplyCapability(AbstractCapability):
|
||||
async def wrap_tool_execute(self, context, tool_name, arguments, handler):
|
||||
result = await handler(arguments)
|
||||
from zhenxun.services.ai.tools.models import EndRunResult, ToolResult
|
||||
|
||||
if isinstance(result, ToolResult):
|
||||
if getattr(result, "is_error", False):
|
||||
return result
|
||||
return EndRunResult(output=result.output)
|
||||
return EndRunResult(output=result)
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, capabilities=[DirectReplyCapability()])
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def interactive():
|
||||
"""开启交互式参数补全。如果参数缺失或校验失败，
|
||||
会主动通过 Bot 向用户提问要求补全。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import InteractiveCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, capabilities=[InteractiveCapability()])
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def require_approval():
|
||||
"""高危操作标记。调用前将拦截并发送至群组要求超管人工审核。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import ApprovalCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, capabilities=[ApprovalCapability()])
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def fallback(tool_name: str):
|
||||
"""降级备用工具。主工具执行失败时自动路由至备用工具。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import FallbackCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func,
|
||||
capabilities=[FallbackCapability(fallback_tool_name=tool_name)],
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def before_execute(hook_func: Callable):
|
||||
"""生命周期拦截：在工具即将执行前触发，可在此篡改全局状态或通过依赖注入访问当前参数。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import LifecycleCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func, capabilities=[LifecycleCapability(before_execute=hook_func)]
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def after_execute(hook_func: Callable):
|
||||
"""生命周期拦截：在工具执行完毕后触发，可在此修改将发往大模型的返回结果。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import LifecycleCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func, capabilities=[LifecycleCapability(after_execute=hook_func)]
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def validate_args(hook_func: Callable):
|
||||
"""生命周期拦截：在工具反序列化校验前触发。如果校验失败直接抛出异常，将触发大模型重试机制。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import LifecycleCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func, capabilities=[LifecycleCapability(validate_args=hook_func)]
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def prepare_tool(hook_func: Callable):
|
||||
"""生命周期拦截：在向大模型渲染 JSON Schema 前触发，
|
||||
可在此动态修改该工具的定义或返回 None 对大模型隐藏。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import LifecycleCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func, capabilities=[LifecycleCapability(prepare_tool=hook_func)]
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def require_superuser():
|
||||
"""仅限超级管理员使用。若调用者无权限，该工具将直接对大模型隐藏。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import SuperuserCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, capabilities=[SuperuserCapability()])
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def require_admin_level(min_level: int = 1):
|
||||
"""仅限满足指定群聊权限等级的用户使用。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import AdminLevelCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(
|
||||
func,
|
||||
capabilities=[AdminLevelCapability(min_level)],
|
||||
metadata={"admin_level": min_level},
|
||||
)
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def require_group():
|
||||
"""限制该工具仅能在群聊环境中被大模型调用。"""
|
||||
from zhenxun.services.ai.tools.core.capabilities import GroupOnlyCapability
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, capabilities=[GroupOnlyCapability()])
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def require_minimum_gold(amount: int):
|
||||
"""需满足一定的金币余额才可调用，同时执行后会自动扣除该金币。"""
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, metadata={"cost_gold": amount})
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
def require_session_state(key: str, expected_value: Any = None):
|
||||
"""需要当前执行上下文中包含指定状态变量，否则隐藏工具"""
|
||||
|
||||
class StateDependencyCapability(AbstractCapability):
|
||||
async def prepare_tools(
|
||||
self, context: RunContext, tool_defs: list[Any]
|
||||
) -> list[Any]:
|
||||
val = context.state.get(key)
|
||||
if expected_value is not None:
|
||||
if val == expected_value:
|
||||
return tool_defs
|
||||
elif val is not None and val is not False:
|
||||
return tool_defs
|
||||
return []
|
||||
|
||||
def decorator(func: Callable):
|
||||
return _update_settings(func, capabilities=[StateDependencyCapability()])
|
||||
|
||||
return decorator
|
||||
|
||||
|
||||
class Rules:
|
||||
"""
|
||||
[命名空间] 大模型工具规则与权限装饰器聚合。
|
||||
用于控制工具的极速缓存、沙箱要求、前端静默以及人机交互审批等。
|
||||
"""
|
||||
|
||||
sandbox = staticmethod(require_sandbox)
|
||||
"""环境：声明执行该工具所需的物理沙箱及 pip/npm 包依赖"""
|
||||
|
||||
approval = staticmethod(require_approval)
|
||||
"""高危：拦截执行，并在群内发起人工审批 (HITL) 确认"""
|
||||
|
||||
superuser = staticmethod(require_superuser)
|
||||
"""权限：仅允许被超级管理员触发时，该工具才对大模型可见"""
|
||||
|
||||
admin_level = staticmethod(require_admin_level)
|
||||
"""权限：要求触发用户的群等级达到指定级别"""
|
||||
|
||||
group_only = staticmethod(require_group)
|
||||
"""环境：限制该工具只有在群聊场景下才可被调用"""
|
||||
|
||||
minimum_gold = staticmethod(require_minimum_gold)
|
||||
"""经济：要求用户满足金币余额，且执行后将自动扣除该金币"""
|
||||
|
||||
session_state = staticmethod(require_session_state)
|
||||
"""状态：要求当前会话上下文中包含指定的状态变量时才可用"""
|
||||
|
||||
before_execute = staticmethod(before_execute)
|
||||
"""拦截器：在工具正式执行前触发，可动态修改传入参数 (利用 DI 注入)"""
|
||||
|
||||
after_execute = staticmethod(after_execute)
|
||||
"""拦截器：在工具执行完毕后触发，可动态修改返回结果 (利用 DI 注入)"""
|
||||
|
||||
validate_args = staticmethod(validate_args)
|
||||
"""拦截器：在工具参数校验前触发，校验失败抛出异常直接由大模型重试"""
|
||||
|
||||
prepare_tool = staticmethod(prepare_tool)
|
||||
"""拦截器：向大模型渲染 JSON Schema 前触发，可篡改工具定义对象"""
|
||||
|
||||
cache = staticmethod(with_cache)
|
||||
"""性能：开启极速缓存，参数相同时直接返回上次结果，免去重复计算"""
|
||||
|
||||
silent = staticmethod(silent)
|
||||
"""UI：静默执行，执行过程与结果不以气泡形式发送给用户，仅供大模型参考"""
|
||||
|
||||
interactive = staticmethod(interactive)
|
||||
"""交互：开启交互式参数补全，必填参数缺失时自动向用户提问补全"""
|
||||
|
||||
fallback = staticmethod(fallback)
|
||||
"""容错：执行失败时透明降级重定向至备用工具"""
|
||||
|
||||
direct_reply = staticmethod(direct_reply)
|
||||
"""流控：直出模式，执行后直接将结果发给用户并强制中断大模型后续思考"""
|
||||
|
||||
|
||||
__all__ = [
|
||||
"Rules",
|
||||
"tool",
|
||||
]
|
||||
@@ -0,0 +1,226 @@
|
||||
from abc import ABC, abstractmethod
|
||||
from collections.abc import Callable
|
||||
import inspect
|
||||
import json
|
||||
import re
|
||||
from typing import Annotated, Any, get_args, get_origin, get_type_hints
|
||||
|
||||
from pydantic import BaseModel, Field, create_model
|
||||
from pydantic.fields import FieldInfo
|
||||
|
||||
from zhenxun.services.ai.run.context import RunContext
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.utils import PermissionUtils
|
||||
from zhenxun.utils.pydantic_compat import model_json_schema
|
||||
|
||||
|
||||
class FieldPermission(ABC):
|
||||
"""字段级权限校验基类/协议"""
|
||||
|
||||
@abstractmethod
|
||||
async def check(self, context: RunContext) -> bool:
|
||||
"""返回当前上下文（用户）是否有权使用该字段"""
|
||||
pass
|
||||
|
||||
|
||||
class RequireSuperUser(FieldPermission):
|
||||
"""仅限超级管理员可见的字段参数"""
|
||||
|
||||
async def check(self, context: RunContext) -> bool:
|
||||
return await PermissionUtils.check_superuser(context)
|
||||
|
||||
|
||||
class RequireAdminLevel(FieldPermission):
|
||||
"""仅限满足群等级要求的管理员可见的字段参数"""
|
||||
|
||||
def __init__(self, min_level: int = 1):
|
||||
self.min_level = min_level
|
||||
|
||||
async def check(self, context: RunContext) -> bool:
|
||||
return await PermissionUtils.check_admin_level(context, self.min_level)
|
||||
|
||||
|
||||
def _parse_docstring(docstring: str | None) -> tuple[str, dict[str, str]]:
|
||||
"""解析文档字符串，解耦提取主描述和参数描述"""
|
||||
if not docstring:
|
||||
return "", {}
|
||||
|
||||
lines = docstring.strip().splitlines()
|
||||
main_desc_lines = []
|
||||
params: dict[str, str] = {}
|
||||
|
||||
section_header = re.compile(r"^\s*(?:Args|Arguments|Parameters|参数)\s*[:：]\s*$")
|
||||
return_header = re.compile(r"^\s*(?:Returns|Return|返回)\s*[:：]\s*$")
|
||||
param_pattern = re.compile(r"^\s*(\**\w+)(?:\s*\(.*?\))?\s*[:：]\s*(.*)")
|
||||
|
||||
current_section = "main"
|
||||
last_param = None
|
||||
|
||||
for line in lines:
|
||||
stripped = line.strip()
|
||||
if not stripped:
|
||||
if current_section == "main":
|
||||
main_desc_lines.append("")
|
||||
continue
|
||||
|
||||
if section_header.match(line):
|
||||
current_section = "params"
|
||||
continue
|
||||
elif return_header.match(line):
|
||||
current_section = "returns"
|
||||
continue
|
||||
|
||||
if current_section == "main":
|
||||
main_desc_lines.append(line.strip())
|
||||
elif current_section == "params":
|
||||
match = param_pattern.match(line)
|
||||
if match:
|
||||
param_name = match.group(1).lstrip("*")
|
||||
param_desc = match.group(2).strip()
|
||||
params[param_name] = param_desc
|
||||
last_param = param_name
|
||||
elif last_param and line.startswith(" ") and stripped:
|
||||
params[last_param] += f" {stripped}"
|
||||
|
||||
main_desc = "\n".join(main_desc_lines).strip()
|
||||
return main_desc, params
|
||||
|
||||
|
||||
def build_tool_model(
|
||||
func: Callable, strict: bool = False
|
||||
) -> tuple[dict, type[BaseModel]]:
|
||||
"""利用 pydantic.create_model 从函数签名动态构建绝对严谨的 JSON Schema 及验证模型"""
|
||||
sig = inspect.signature(func)
|
||||
type_hints = get_type_hints(func, include_extras=True)
|
||||
_, doc_params = _parse_docstring(func.__doc__)
|
||||
|
||||
field_definitions = {}
|
||||
|
||||
for name, param in sig.parameters.items():
|
||||
if name in ("self", "cls", "args", "kwargs"):
|
||||
continue
|
||||
|
||||
if DependencyInjector.can_resolve_statically(param):
|
||||
continue
|
||||
|
||||
anno = type_hints.get(name, Any)
|
||||
desc = doc_params.get(name, "")
|
||||
default_val = param.default
|
||||
|
||||
user_desc = None
|
||||
if isinstance(default_val, FieldInfo) and default_val.description:
|
||||
user_desc = default_val.description
|
||||
elif get_origin(anno) is Annotated:
|
||||
for arg in get_args(anno)[1:]:
|
||||
if isinstance(arg, FieldInfo) and arg.description:
|
||||
user_desc = arg.description
|
||||
break
|
||||
|
||||
final_desc = user_desc or desc
|
||||
|
||||
if isinstance(default_val, FieldInfo):
|
||||
field_info = default_val
|
||||
if not field_info.description and final_desc:
|
||||
field_info.description = final_desc
|
||||
field_definitions[name] = (anno, field_info)
|
||||
else:
|
||||
if default_val is inspect.Parameter.empty:
|
||||
field_info = Field(..., description=final_desc)
|
||||
else:
|
||||
field_info = Field(default=default_val, description=final_desc)
|
||||
field_definitions[name] = (anno, field_info)
|
||||
|
||||
try:
|
||||
DynamicModel = create_model(
|
||||
f"DynamicToolModel_{func.__name__}", **field_definitions
|
||||
)
|
||||
schema_def = model_json_schema(DynamicModel, mode="serialization")
|
||||
except Exception as e:
|
||||
error_msg = str(e)
|
||||
raise ValueError(
|
||||
f"无法为工具 '{func.__name__}' 生成合法的 JSON Schema。\n"
|
||||
"原因：函数的参数中包含了大模型无法解析的复杂类型"
|
||||
"（如 Bot, Event, 自定义类等）。\n"
|
||||
"💡 修复建议：如果该参数是底层框架依赖（如需要用到 nonebot 的 Bot），"
|
||||
"请务必使用 `Inject.XXX` 进行注解声明（例如 `bot: Inject.Bot`），"
|
||||
"这样系统会自动将其隐藏，不会发给大模型。\n"
|
||||
f"底层报错：{error_msg}"
|
||||
) from e
|
||||
|
||||
schema_def.pop("title", None)
|
||||
if strict:
|
||||
schema_def["additionalProperties"] = False
|
||||
|
||||
return schema_def, DynamicModel
|
||||
|
||||
|
||||
def build_schema_hint(args_schema: type[BaseModel] | None) -> str:
|
||||
"""
|
||||
构建友好的人类可读 Schema 提示，供大模型在参数错误时进行自愈反思。
|
||||
"""
|
||||
if args_schema is None:
|
||||
return ""
|
||||
try:
|
||||
schema = model_json_schema(args_schema)
|
||||
props = schema.get("properties", {})
|
||||
req = schema.get("required", [])
|
||||
|
||||
hint = (
|
||||
f"\n\n💡 [系统提示] 该工具期望的正确 JSON 参数格式为:\n"
|
||||
f"```json\n{json.dumps(props, ensure_ascii=False, indent=2)}\n```\n"
|
||||
f"必填字段: {req}"
|
||||
)
|
||||
return hint
|
||||
except Exception:
|
||||
return ""
|
||||
|
||||
|
||||
async def prune_schema_by_permissions(
|
||||
model_class: type[BaseModel], context: RunContext, schema: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
"""根据当前运行时上下文 (RunContext) 动态裁剪无权限的 Schema 字段"""
|
||||
properties = schema.get("properties", {})
|
||||
required = schema.get("required", [])
|
||||
fields_to_remove = []
|
||||
|
||||
fields = getattr(
|
||||
model_class, "model_fields", getattr(model_class, "__fields__", {})
|
||||
)
|
||||
|
||||
for field_name, field_info in fields.items():
|
||||
for meta in field_info.metadata:
|
||||
if isinstance(meta, FieldPermission):
|
||||
if not await meta.check(context):
|
||||
fields_to_remove.append(field_name)
|
||||
break
|
||||
|
||||
for field_name in fields_to_remove:
|
||||
properties.pop(field_name, None)
|
||||
if field_name in required:
|
||||
required.remove(field_name)
|
||||
|
||||
if "required" in schema and not required:
|
||||
schema.pop("required", None)
|
||||
|
||||
return schema
|
||||
|
||||
|
||||
async def check_field_permissions(
|
||||
model_class: type[BaseModel], kwargs: dict[str, Any], context: RunContext
|
||||
) -> None:
|
||||
"""验证传入的参数是否绕过了权限限制"""
|
||||
fields = getattr(
|
||||
model_class, "model_fields", getattr(model_class, "__fields__", {})
|
||||
)
|
||||
for field_name, field_info in fields.items():
|
||||
if field_name in kwargs:
|
||||
for meta in field_info.metadata:
|
||||
if isinstance(meta, FieldPermission):
|
||||
if not await meta.check(context):
|
||||
from zhenxun.services.ai.core.exceptions import ToolRetryError
|
||||
|
||||
raise ToolRetryError(
|
||||
f"权限拒绝：您当前的用户身份无权使用参数 '{field_name}'。"
|
||||
"请移除该参数后重新规划并调用此工具。"
|
||||
)
|
||||
break
|
||||
@@ -0,0 +1,441 @@
|
||||
from collections.abc import Callable
|
||||
import hashlib
|
||||
import inspect
|
||||
import json
|
||||
from typing import Any, Literal
|
||||
|
||||
from pydantic import BaseModel, ValidationError
|
||||
|
||||
from zhenxun.services.ai.core.exceptions import (
|
||||
NeedsInputException,
|
||||
ToolFatalError,
|
||||
ToolRetryError,
|
||||
)
|
||||
from zhenxun.services.ai.core.models import ToolDefinition
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
from zhenxun.services.ai.tools.models import (
|
||||
ResolvedToolPayload,
|
||||
ToolOptions,
|
||||
ToolResult,
|
||||
)
|
||||
from zhenxun.services.log import logger
|
||||
from zhenxun.utils.pydantic_compat import model_dump, model_json_schema, model_validate
|
||||
|
||||
from .schema import (
|
||||
_parse_docstring,
|
||||
build_schema_hint,
|
||||
build_tool_model,
|
||||
check_field_permissions,
|
||||
prune_schema_by_permissions,
|
||||
)
|
||||
|
||||
_tool_runner_class: type | None = None
|
||||
|
||||
|
||||
def register_tool_runner(runner_class: type) -> None:
|
||||
global _tool_runner_class
|
||||
_tool_runner_class = runner_class
|
||||
|
||||
|
||||
class BaseTool:
|
||||
"""
|
||||
面向对象的工具基类。支持多模态契约与纯 Pydantic V2 参数验证。
|
||||
|
||||
参数:
|
||||
name: 工具名称。大模型将基于此识别并调用。如果不提供，默认使用类名。
|
||||
description: 工具的说明文档。大模型会根据此描述理解工具用途。
|
||||
settings: 配置选项（包含缓存、拦截、中间件等）。
|
||||
"""
|
||||
|
||||
name: str
|
||||
description: str
|
||||
settings: ToolOptions
|
||||
execution_side: Literal["client", "server"] = "client"
|
||||
current_usage_count: int = 0
|
||||
_dynamic_def: Any = None
|
||||
args_schema: type[BaseModel] | None = None
|
||||
_base_schema: dict[str, Any] | None = None
|
||||
_param_model: Any = None
|
||||
parent_toolkit: Any = None
|
||||
|
||||
@property
|
||||
def metadata(self) -> dict[str, Any]:
|
||||
return self.settings.metadata
|
||||
|
||||
@metadata.setter
|
||||
def metadata(self, value: dict[str, Any]):
|
||||
self.settings.metadata = value
|
||||
|
||||
def get_execute_target(self) -> Callable:
|
||||
"""获取依赖注入和实际执行的目标函数。子类可重写（如 FunctionTool）。"""
|
||||
if not hasattr(self, "run"):
|
||||
raise NotImplementedError(
|
||||
f"工具 {self.__class__.__name__} 未实现 run 方法。"
|
||||
)
|
||||
return self.run
|
||||
|
||||
def get_signature_target(self) -> Callable:
|
||||
"""获取依赖注入和 Schema 生成的原始函数目标。子类可重写。"""
|
||||
return self.get_execute_target()
|
||||
|
||||
async def run(self, **kwargs: Any) -> Any:
|
||||
"""供第三方开发者重写的核心执行逻辑。完美支持 Inject 依赖注入。"""
|
||||
raise NotImplementedError("子类必须实现 run 方法")
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
name: str | None = None,
|
||||
description: str | None = None,
|
||||
settings: ToolOptions | None = None,
|
||||
):
|
||||
"""
|
||||
初始化工具基类。
|
||||
|
||||
参数:
|
||||
name: 工具名，供大模型识别调用，默认取类名。
|
||||
description: 工具功能说明，供大模型理解，默认取 __doc__ 说明。
|
||||
settings: 工具的个性化配置选项（例如缓存时间、依赖中间件等），默认 None。
|
||||
"""
|
||||
self.name = name or getattr(self, "name", self.__class__.__name__)
|
||||
self.description = description or getattr(
|
||||
self, "description", self.__doc__ or "未提供描述"
|
||||
)
|
||||
self.settings = settings or getattr(self, "settings", ToolOptions())
|
||||
self.args_schema = self.settings.args_schema or getattr(
|
||||
self.__class__, "args_schema", None
|
||||
)
|
||||
self.current_usage_count = 0
|
||||
|
||||
class_meta = getattr(self.__class__, "metadata", {})
|
||||
if class_meta and not isinstance(class_meta, property):
|
||||
self.settings.metadata.update(class_meta)
|
||||
|
||||
def clone_with_options(self, override: Any) -> "BaseTool":
|
||||
"""创建当前工具的浅拷贝，并覆盖 ToolOptions 和基本属性"""
|
||||
import copy
|
||||
|
||||
new_tool = copy.copy(self)
|
||||
|
||||
if hasattr(override, "to_tool_options"):
|
||||
override_settings = override.to_tool_options()
|
||||
else:
|
||||
override_settings = getattr(
|
||||
override, "options", getattr(override, "settings", None)
|
||||
)
|
||||
|
||||
if override_settings:
|
||||
new_tool.settings = self.settings.merge(override_settings)
|
||||
|
||||
new_name = getattr(override, "new_name", None)
|
||||
if new_name:
|
||||
new_tool.name = new_name
|
||||
|
||||
new_desc = getattr(override, "description", None)
|
||||
if new_desc:
|
||||
new_tool.description = new_desc
|
||||
|
||||
return new_tool
|
||||
|
||||
async def _handle_validation_error(self, e: ValidationError, kwargs: dict) -> None:
|
||||
"""
|
||||
将 Pydantic 参数校验失败转化为 ToolRetryError 或 NeedsInputException
|
||||
"""
|
||||
error_msgs = []
|
||||
for err in e.errors():
|
||||
loc = ".".join(str(x) for x in err["loc"]) or "root"
|
||||
msg = err.get("msg", "")
|
||||
ctx = err.get("ctx", {})
|
||||
ctx_str = f" (期望要求: {ctx})" if ctx else ""
|
||||
error_msgs.append(f"参数字段 `{loc}`: {msg}{ctx_str}")
|
||||
|
||||
err_msg = "\n".join(error_msgs)
|
||||
validation_model = getattr(self, "args_schema", None) or getattr(
|
||||
self, "_param_model", None
|
||||
)
|
||||
schema_hint = build_schema_hint(validation_model)
|
||||
|
||||
from zhenxun.services.ai.tools.core.capabilities import InteractiveCapability
|
||||
|
||||
if any(
|
||||
isinstance(c, InteractiveCapability) for c in self.settings.capabilities
|
||||
):
|
||||
first_error = e.errors()[0]
|
||||
field_name = (
|
||||
str(first_error["loc"][-1]) if first_error.get("loc") else "unknown"
|
||||
)
|
||||
field_desc = f"参数验证失败: {first_error['msg']}"
|
||||
|
||||
raise NeedsInputException(field_name, field_desc, kwargs)
|
||||
|
||||
raise ToolRetryError(
|
||||
f"参数验证未通过，请严格根据以下错误信息修正参数后重试：\n{err_msg}\n"
|
||||
f"（附：你刚才传入的非法参数为 {kwargs}）{schema_hint}"
|
||||
)
|
||||
|
||||
async def get_definition(
|
||||
self, context: RunContext | None = None
|
||||
) -> ToolDefinition | None:
|
||||
"""获取工具的 JSON Schema 定义。支持动态修改 Schema 甚至隐藏工具。"""
|
||||
if hasattr(self, "_dynamic_def") and self._dynamic_def is not None:
|
||||
return self._dynamic_def
|
||||
|
||||
args_schema = getattr(self, "args_schema", None)
|
||||
if args_schema is not None:
|
||||
if context is not None:
|
||||
base_schema = model_json_schema(args_schema)
|
||||
schema = await prune_schema_by_permissions(
|
||||
args_schema, context, base_schema
|
||||
)
|
||||
else:
|
||||
schema = model_json_schema(args_schema)
|
||||
elif getattr(self, "_base_schema", None) is not None:
|
||||
schema = (
|
||||
self._base_schema.copy()
|
||||
if isinstance(self._base_schema, dict)
|
||||
else {"type": "object", "properties": {}}
|
||||
)
|
||||
else:
|
||||
schema = {"type": "object", "properties": {}}
|
||||
|
||||
if getattr(self.settings, "require_intent", False):
|
||||
if "properties" not in schema:
|
||||
schema["properties"] = {}
|
||||
if "_intent" not in schema["properties"]:
|
||||
new_props = {
|
||||
"_intent": {
|
||||
"type": "string",
|
||||
"description": (
|
||||
"调用此工具前，必须在此字段简述你的意图、目的或思考过程"
|
||||
),
|
||||
}
|
||||
}
|
||||
new_props.update(schema["properties"])
|
||||
schema["properties"] = new_props
|
||||
|
||||
if "required" not in schema:
|
||||
schema["required"] = []
|
||||
if "_intent" not in schema["required"]:
|
||||
schema["required"].insert(0, "_intent")
|
||||
|
||||
tool_def = ToolDefinition(
|
||||
name=self.name,
|
||||
description=self.description,
|
||||
parameters=schema,
|
||||
metadata=self.settings.metadata.copy(),
|
||||
)
|
||||
|
||||
if context and self.settings.capabilities:
|
||||
from zhenxun.services.ai.capabilities import (
|
||||
CombinedCapability,
|
||||
)
|
||||
|
||||
combined_cap = CombinedCapability(self.settings.capabilities)
|
||||
defs = await combined_cap.prepare_tools(context, [tool_def])
|
||||
if not defs:
|
||||
return None
|
||||
tool_def = defs[0]
|
||||
|
||||
return tool_def
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
"""实现 ToolResolvable 协议，将自身解析为标准 Payload"""
|
||||
import copy
|
||||
|
||||
definition = await self.get_definition(context)
|
||||
if definition is None:
|
||||
return ResolvedToolPayload()
|
||||
|
||||
run_scoped_tool = copy.copy(self)
|
||||
run_scoped_tool._dynamic_def = definition
|
||||
if not hasattr(run_scoped_tool, "name"):
|
||||
setattr(run_scoped_tool, "name", definition.name)
|
||||
|
||||
return ResolvedToolPayload(tools=[run_scoped_tool])
|
||||
|
||||
def _generate_cache_key(self, arguments: dict[str, Any]) -> str:
|
||||
"""
|
||||
根据工具名称和参数生成绝对唯一的缓存 Key。
|
||||
通过对字典 key 进行排序并转化为 json 字符串，
|
||||
保证参数顺序不同但内容相同时 Hash 结果一致。
|
||||
"""
|
||||
args_str = json.dumps(arguments, sort_keys=True, ensure_ascii=False)
|
||||
key_str = f"{self.name}:{args_str}"
|
||||
return hashlib.md5(key_str.encode("utf-8")).hexdigest()
|
||||
|
||||
async def validate_args(
|
||||
self, kwargs: dict[str, Any], context: RunContext | None = None
|
||||
) -> dict[str, Any]:
|
||||
"""验证参数，返回序列化后的合法字典。如果校验失败则抛出异常。"""
|
||||
validation_model = getattr(self, "args_schema", None) or getattr(
|
||||
self, "_param_model", None
|
||||
)
|
||||
if validation_model:
|
||||
if context:
|
||||
await check_field_permissions(validation_model, kwargs, context)
|
||||
try:
|
||||
validated_model = model_validate(validation_model, kwargs)
|
||||
return model_dump(validated_model, exclude_unset=True)
|
||||
except ValidationError as e:
|
||||
await self._handle_validation_error(e, kwargs)
|
||||
return kwargs
|
||||
|
||||
async def execute(
|
||||
self, context: RunContext | None = None, **kwargs: Any
|
||||
) -> ToolResult:
|
||||
"""工具执行的总入口，负责组装和调度中间件管道"""
|
||||
context_to_pass = context or RunContext()
|
||||
|
||||
try:
|
||||
return await self._core_execution(context_to_pass, **kwargs)
|
||||
except Exception as e:
|
||||
from zhenxun.services.ai.core.exceptions import ControlFlowExit
|
||||
|
||||
if not isinstance(e, ControlFlowExit):
|
||||
logger.error(f"工具 {self.name} 执行抛出异常，将交由底层引擎处理: {e}")
|
||||
raise
|
||||
|
||||
async def _core_execution(self, context: RunContext, **kwargs: Any) -> ToolResult:
|
||||
"""核心执行流水线 (Core Execution Pipeline)"""
|
||||
_retries = context.run.tool_retries.get(self.name, 0)
|
||||
|
||||
if (
|
||||
self.settings.max_usage_count is not None
|
||||
and self.current_usage_count >= self.settings.max_usage_count
|
||||
):
|
||||
raise ToolFatalError(
|
||||
f"工具 '{self.name}' 已达到最大调用次数上限 ({self.settings.max_usage_count})" # noqa: E501
|
||||
)
|
||||
self.current_usage_count += 1
|
||||
|
||||
if _tool_runner_class is None:
|
||||
raise ToolFatalError(
|
||||
f"工具 '{self.name}' 运行时错误：未注册 ToolRunner 执行器。"
|
||||
)
|
||||
|
||||
runner = _tool_runner_class()
|
||||
final_result = await runner.run(tool=self, context=context, **kwargs)
|
||||
|
||||
if not final_result.is_error:
|
||||
context.run.tool_retries[self.name] = 0
|
||||
|
||||
return final_result
|
||||
|
||||
|
||||
class ServerSideTool(BaseTool):
|
||||
"""
|
||||
云端原生工具的抽象基类。
|
||||
代表那些由各大模型厂商在云端原生实现的能力（如 Google Search, Code Execution）。
|
||||
此类工具只产生 Schema 提交给大模型用于触发路由，禁止在本地执行。
|
||||
"""
|
||||
|
||||
execution_side: Literal["client", "server"] = "server"
|
||||
type_id: str = ""
|
||||
|
||||
async def execute(
|
||||
self, context: RunContext | None = None, **kwargs: Any
|
||||
) -> ToolResult:
|
||||
raise ToolFatalError(
|
||||
f"[{self.name}] 是服务端工具，禁止在本地层执行引擎中运行。"
|
||||
)
|
||||
|
||||
async def get_definition(
|
||||
self, context: RunContext | None = None
|
||||
) -> ToolDefinition | None:
|
||||
if hasattr(self, "_dynamic_def") and self._dynamic_def is not None:
|
||||
return self._dynamic_def
|
||||
return ToolDefinition(
|
||||
name=self.name,
|
||||
description=self.description,
|
||||
parameters={"type": "object", "properties": {}},
|
||||
metadata=self.settings.metadata.copy(),
|
||||
)
|
||||
|
||||
|
||||
class FunctionTool(BaseTool):
|
||||
"""
|
||||
将普通 Python 函数包装为 BaseTool 的实现。
|
||||
|
||||
参数:
|
||||
func: 实际执行的 Python 异步或同步函数。
|
||||
name: 覆盖函数名的工具名称。
|
||||
description: 覆盖函数 docstring 的工具描述。
|
||||
settings: 配置选项。
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
func: Callable,
|
||||
name: str | None = None,
|
||||
description: str | None = None,
|
||||
settings: ToolOptions | None = None,
|
||||
):
|
||||
"""
|
||||
初始化函数式包装工具。
|
||||
|
||||
参数:
|
||||
func: 被包装的底层 Python 同步或异步函数。
|
||||
name: 覆盖函数名的自定义工具名，默认 None。
|
||||
description: 覆盖 docstring 的自定义工具描述，默认 None。
|
||||
settings: 覆盖默认选项的自定义工具配置项，默认 None。
|
||||
"""
|
||||
super().__init__(name=name, description=description, settings=settings)
|
||||
|
||||
self._original_func = func
|
||||
from zhenxun.services.ai.utils.utils import wrap_to_async
|
||||
|
||||
self.__name__ = self.name
|
||||
self._func = wrap_to_async(func)
|
||||
self._schema_built = False
|
||||
|
||||
main_desc, _ = _parse_docstring(self._original_func.__doc__)
|
||||
if not description or description == "未提供描述":
|
||||
self.description = main_desc or "未提供描述"
|
||||
|
||||
def get_execute_target(self) -> Callable:
|
||||
"""FunctionTool 的执行目标和依赖注入目标是其包装的原始函数"""
|
||||
return self._func
|
||||
|
||||
def get_signature_target(self) -> Callable:
|
||||
return self._original_func
|
||||
|
||||
async def run(self, **kwargs: Any) -> Any:
|
||||
"""保持接口完整性，但实际执行由 _core_execution 导向 _func"""
|
||||
is_async_gen = getattr(
|
||||
self._func, "_is_async_gen", False
|
||||
) or inspect.isasyncgenfunction(self._func)
|
||||
if is_async_gen:
|
||||
res = []
|
||||
async for chunk in self._func(**kwargs):
|
||||
res.append(chunk)
|
||||
return res
|
||||
return await self._func(**kwargs)
|
||||
|
||||
def _ensure_schema(self):
|
||||
"""JIT 懒加载：推迟到第一次请求定义或验证参数时再构建 Schema (耗时操作)"""
|
||||
if not self._schema_built:
|
||||
if self.args_schema:
|
||||
self._base_schema = model_json_schema(self.args_schema)
|
||||
self._param_model = self.args_schema
|
||||
else:
|
||||
schema, model = build_tool_model(
|
||||
self.get_signature_target(), strict=self.settings.strict
|
||||
)
|
||||
self._base_schema = schema
|
||||
self._param_model = model
|
||||
self._schema_built = True
|
||||
|
||||
async def get_definition(
|
||||
self, context: RunContext | None = None
|
||||
) -> ToolDefinition | None:
|
||||
self._ensure_schema()
|
||||
return await super().get_definition(context)
|
||||
|
||||
async def validate_args(
|
||||
self, kwargs: dict[str, Any], context: RunContext | None = None
|
||||
) -> dict[str, Any]:
|
||||
self._ensure_schema()
|
||||
return await super().validate_args(kwargs, context=context)
|
||||
|
||||
def __call__(self, *args: Any, **kwargs: Any) -> Any:
|
||||
"""允许像普通函数一样被直接调用。对其他插件完全透明。"""
|
||||
return self._original_func(*args, **kwargs)
|
||||
@@ -0,0 +1,272 @@
|
||||
from collections.abc import Callable
|
||||
import copy
|
||||
from typing import Any, ClassVar
|
||||
|
||||
from zhenxun.services.ai.core.protocols.tool import ToolExecutable
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.tools.models import (
|
||||
ResolvedToolPayload,
|
||||
ToolkitConfig,
|
||||
ToolOptions,
|
||||
)
|
||||
from zhenxun.utils.pydantic_compat import (
|
||||
model_copy,
|
||||
model_dump,
|
||||
)
|
||||
|
||||
from .tool import BaseTool, FunctionTool
|
||||
|
||||
|
||||
class BaseToolkit:
|
||||
"""
|
||||
状态工具箱基类。继承此类的对象可以维持自身状态，
|
||||
其内部被 @tool 标记的方法将被自动解析为工具。
|
||||
"""
|
||||
|
||||
default_instructions: str = ""
|
||||
config: ToolkitConfig
|
||||
_default_config: ClassVar[ToolkitConfig] = ToolkitConfig()
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
prefix: str | None = None,
|
||||
include: list[str] | None = None,
|
||||
exclude: list[str] | None = None,
|
||||
shared_options: ToolOptions | None = None,
|
||||
config: ToolkitConfig | None = None,
|
||||
tools: list[Callable | BaseTool | ToolExecutable] | None = None,
|
||||
instructions: str | None = None,
|
||||
**kwargs: Any,
|
||||
):
|
||||
"""
|
||||
初始化工具箱实例，装配并隔离工具组件。
|
||||
|
||||
参数:
|
||||
prefix: 工具名称的前缀。如果不指定，则不添加前缀。
|
||||
include: 允许注册的工具名白名单，仅在此列表中的工具才会被加载。
|
||||
exclude: 排除注册的工具名黑名单，在此列表中的工具将被忽略。
|
||||
shared_options: 所有子工具默认继承的高阶配置项 (ToolOptions)。
|
||||
config: (可选) 显式传递的全局配置对象。若传入此项，将覆盖上述所有独立配置。
|
||||
tools: 除了带有 @tool 装饰器的方法外，要额外动态注入的独立工具列表。
|
||||
instructions: 当前工具箱实例的系统提示词补充说明。
|
||||
"""
|
||||
if config is not None:
|
||||
merged_dict = {
|
||||
**model_dump(self._default_config, exclude_unset=True),
|
||||
**model_dump(config, exclude_unset=True),
|
||||
}
|
||||
self.config = ToolkitConfig(**merged_dict)
|
||||
else:
|
||||
self.config = ToolkitConfig(
|
||||
prefix=prefix,
|
||||
include=include,
|
||||
exclude=exclude,
|
||||
shared_options=shared_options,
|
||||
)
|
||||
|
||||
if self.config.prefix is None:
|
||||
self.config.prefix = ""
|
||||
|
||||
self._instance_filter: Callable[[BaseTool], bool] | None = None
|
||||
self._injected_tools: list[BaseTool] = []
|
||||
self._cached_tools: dict[str, BaseTool] | None = None
|
||||
self._instance_instructions = (
|
||||
instructions
|
||||
if instructions is not None
|
||||
else getattr(self, "default_instructions", "")
|
||||
)
|
||||
|
||||
if tools:
|
||||
for t in tools:
|
||||
if isinstance(t, BaseTool):
|
||||
self._injected_tools.append(t)
|
||||
elif callable(t):
|
||||
tool_name = getattr(
|
||||
t, "__tool_name__", getattr(t, "__name__", "unnamed_tool")
|
||||
)
|
||||
tool_desc = getattr(t, "__tool_desc__", "未提供描述")
|
||||
settings = model_copy(
|
||||
getattr(t, "__tool_settings__", ToolOptions())
|
||||
)
|
||||
|
||||
func_tool = FunctionTool(
|
||||
func=t,
|
||||
name=f"{self.config.prefix}{tool_name}",
|
||||
description=tool_desc,
|
||||
settings=settings,
|
||||
)
|
||||
self._injected_tools.append(func_tool)
|
||||
|
||||
def _apply_global_settings(
|
||||
self, original_name: str, settings: ToolOptions
|
||||
) -> ToolOptions:
|
||||
if self.config.shared_options:
|
||||
settings = self.config.shared_options.merge(settings)
|
||||
|
||||
return settings
|
||||
|
||||
async def before_llm_request(
|
||||
self, context: RunContext, messages: list[Any]
|
||||
) -> None:
|
||||
"""
|
||||
LLM 请求发起前的拦截钩子。允许动态修改消息列表（如在尾部注入最新状态）。
|
||||
|
||||
参数:
|
||||
context: 当前 Agent 的运行时上下文。
|
||||
messages: 即将发往底层 LLM 的完整消息历史列表，支持就地修改。
|
||||
"""
|
||||
pass
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
"""实现 ToolResolvable 协议，递归解析内部工具并返回标准 Payload"""
|
||||
tools_dict = await self.get_tools(context)
|
||||
resolved_tools = []
|
||||
|
||||
for t in tools_dict.values():
|
||||
if hasattr(t, "resolve"):
|
||||
payload = await t.resolve(context)
|
||||
if payload and payload.tools:
|
||||
for rt in payload.tools:
|
||||
rt.parent_toolkit = self
|
||||
resolved_tools.extend(payload.tools)
|
||||
else:
|
||||
t.parent_toolkit = self
|
||||
resolved_tools.append(t)
|
||||
|
||||
injected_prompts = []
|
||||
if instructions := self.get_instructions():
|
||||
injected_prompts.append(instructions)
|
||||
|
||||
return ResolvedToolPayload(
|
||||
tools=resolved_tools, injected_prompts=injected_prompts, toolkits=[self]
|
||||
)
|
||||
|
||||
async def get_tools(self, context: RunContext | None = None) -> dict[str, BaseTool]:
|
||||
if self._cached_tools is not None:
|
||||
return self._cached_tools
|
||||
|
||||
tools_dict: dict[str, BaseTool] = {}
|
||||
for t in self._injected_tools:
|
||||
t.parent_toolkit = self
|
||||
tools_dict[t.name] = t
|
||||
|
||||
import inspect
|
||||
|
||||
for name, member in inspect.getmembers(self.__class__):
|
||||
if hasattr(member, "__toolkit_tool__"):
|
||||
bound_tool = getattr(self, name)
|
||||
original_name = getattr(member, "__tool_original_name__", name)
|
||||
|
||||
if (
|
||||
self.config.include is not None
|
||||
and original_name not in self.config.include
|
||||
):
|
||||
continue
|
||||
if (
|
||||
self.config.exclude is not None
|
||||
and original_name in self.config.exclude
|
||||
):
|
||||
continue
|
||||
|
||||
final_tool_name = f"{self.config.prefix}{original_name}"
|
||||
bound_tool.name = final_tool_name
|
||||
|
||||
bound_tool.settings = self._apply_global_settings(
|
||||
original_name, bound_tool.settings
|
||||
)
|
||||
bound_tool.parent_toolkit = self
|
||||
tools_dict[final_tool_name] = bound_tool
|
||||
|
||||
if self._instance_filter:
|
||||
tools_dict = {
|
||||
name: t for name, t in tools_dict.items() if self._instance_filter(t)
|
||||
}
|
||||
self._cached_tools = tools_dict
|
||||
return tools_dict
|
||||
|
||||
def get_instructions(self) -> str | None:
|
||||
"""
|
||||
获取工具箱的系统提示词说明。
|
||||
"""
|
||||
text = self._instance_instructions
|
||||
if not text:
|
||||
return None
|
||||
class_name = self.__class__.__name__
|
||||
tag_name = (
|
||||
f"{self.config.prefix}{class_name}_Instructions"
|
||||
if self.config.prefix
|
||||
else f"{class_name}_Instructions"
|
||||
)
|
||||
return f"<{tag_name}>\n{text}\n</{tag_name}>"
|
||||
|
||||
def prefixed(self, prefix: str) -> "BaseToolkit":
|
||||
new_tk = copy.copy(self)
|
||||
new_tk.config = model_copy(self.config, deep=True)
|
||||
current_prefix = new_tk.config.prefix or ""
|
||||
new_tk.config.prefix = f"{current_prefix}{prefix}"
|
||||
new_tk._cached_tools = None
|
||||
return new_tk
|
||||
|
||||
def filtered(self, filter_func: Callable[[BaseTool], bool]) -> "BaseToolkit":
|
||||
new_tk = copy.copy(self)
|
||||
new_tk.config = model_copy(self.config, deep=True)
|
||||
old_filter = self._instance_filter
|
||||
if old_filter:
|
||||
new_tk._instance_filter = lambda t: old_filter(t) and filter_func(t)
|
||||
else:
|
||||
new_tk._instance_filter = filter_func
|
||||
new_tk._cached_tools = None
|
||||
return new_tk
|
||||
|
||||
|
||||
class CompositeToolkit(BaseToolkit):
|
||||
"""
|
||||
聚合工具箱 (Composite Toolkit)。
|
||||
将一组独立的 Toolkit 组合在一起，统一其生命周期并合并其工具。
|
||||
可以为其指定统一的 prefix、全局标签或拦截器，底层会自动向内部的所有 Toolkit 透传。
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
toolkits: list[BaseToolkit],
|
||||
config: ToolkitConfig | None = None,
|
||||
**kwargs: Any,
|
||||
):
|
||||
super().__init__(config=config, **kwargs)
|
||||
self.toolkits = toolkits
|
||||
|
||||
async def before_llm_request(
|
||||
self, context: RunContext, messages: list[Any]
|
||||
) -> None:
|
||||
for tk in self.toolkits:
|
||||
await DependencyInjector.invoke(
|
||||
tk.before_llm_request, {"messages": messages}, context
|
||||
)
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
payload = ResolvedToolPayload()
|
||||
prefix = self.config.prefix or ""
|
||||
|
||||
for tk in self.toolkits:
|
||||
active_tk = tk
|
||||
if prefix:
|
||||
active_tk = active_tk.prefixed(prefix)
|
||||
if self._instance_filter:
|
||||
active_tk = active_tk.filtered(self._instance_filter)
|
||||
|
||||
child_payload = await active_tk.resolve(context)
|
||||
|
||||
for tool in child_payload.tools:
|
||||
if self.config.shared_options:
|
||||
tool.settings = self.config.shared_options.merge(tool.settings)
|
||||
|
||||
payload.tools.extend(child_payload.tools)
|
||||
payload.injected_prompts.extend(child_payload.injected_prompts)
|
||||
payload.toolkits.extend(child_payload.toolkits)
|
||||
|
||||
payload.toolkits.append(self)
|
||||
if instructions := self.get_instructions():
|
||||
payload.injected_prompts.append(instructions)
|
||||
|
||||
return payload
|
||||
Reference in New Issue
Block a user