mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-13 16:10:05 +08:00
♻️ refactor(core): 重构 AI 能力与定时任务调度系统 (#2148)
* ♻️ refactor(core): 重构 AI 能力与定时任务调度系统 - 【AI 能力与工具】重构 Capability 注册与管理机制，引入 CapabilityManager 统一管理 - 移除全局能力注册表，改用声明式装饰器 `@capability` 进行解耦注册 - 重构工具解析器链，使用统一的 BaseToolResolver 代替原有的多个特定解析器 - 增强工具查询过滤，支持通配符匹配、工具箱过滤和排除标签 - 【定时任务调度】重构定时任务管理器，引入 SchedulerRegistry 统一管理任务元数据 - 引入 JobConfig 聚合定时任务配置，支持用户维度的定时任务调度 - 重构执行分发器，支持并发限制、串行间隔和随机延迟打散 - 【运行上下文】引入 ScheduledDeps 以支持后台和定时任务环境下的依赖注入 - 优化 RunContext，支持从定时任务上下文快速构造，并提供 emit 辅助方法 - 【日志与监控】引入 AILoggerProxy，实现 AI 各模块的专属日志输出 - 将各模块的全局 logger 替换为对应的模块专属日志代理 - 【其他优化】修复 Pydantic V1 兼容层中 model_validator 的装饰器兼容性问题 - 在非交互式环境（如定时任务）中自动隐藏 HITL 交互工具以节省 Token * ♻️ refactor(core): 优化内部导入路径并提升 Pydantic 兼容性 - 【重构】将 `services/ai` 模块内的绝对导入重构为相对导入，优化包结构 - 【重构】移除不必要的 `if TYPE_CHECKING` 保护，通过 `from __future__ import annotations` 直接导入类型 - 【清理】清理 `core/messages/types.py` 中未使用的 `AssistantContentUnion` 等联合类型定义 - 【优化】在 `utils/pydantic_compat.py` 中新增 `model_rebuild` 兼容函数，统一 Pydantic V1/V2 的模型重建逻辑 - 【优化】将部分函数内部的延迟导入提升至模块顶部，规范代码结构 * ♻️ refactor(imports): 优化导入路径为相对导入并清理冗余导入 - 【重构】将 AI 服务相关模块中的绝对导入路径修改为相对导入，提升模块内聚性与可移植性 - 【清理】移除多处函数内部或类方法中未使用的冗余导入，避免循环引用和资源浪费 - 【格式化】微调部分工具装饰器和返回语句的格式与尾随逗号 * 🚨 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
0b32d69c9c
commit
922d092650
@@ -6,7 +6,7 @@ import asyncio
|
||||
from contextlib import asynccontextmanager
|
||||
import inspect
|
||||
import json
|
||||
from typing import TYPE_CHECKING, Any, cast
|
||||
from typing import Any, cast
|
||||
|
||||
import json_repair
|
||||
from nonebot.adapters import Message as PlatformMessage
|
||||
@@ -26,8 +26,9 @@ from zhenxun.services.ai.core.stream_events import (
|
||||
UserCustomEvent,
|
||||
)
|
||||
from zhenxun.services.ai.message_builder import MessageBuilder
|
||||
from zhenxun.services.ai.run.context import RunContext
|
||||
from zhenxun.services.ai.run.context import RunContext, set_run_context
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.tools.core.tool import BaseTool, register_tool_runner
|
||||
from zhenxun.services.ai.tools.models import (
|
||||
StateSyncResult,
|
||||
ToolOptions,
|
||||
@@ -35,11 +36,9 @@ from zhenxun.services.ai.tools.models import (
|
||||
ToolResultChunk,
|
||||
ValidatedToolCall,
|
||||
)
|
||||
from zhenxun.services.log import logger
|
||||
from zhenxun.services.ai.utils.logger import log_tool as logger
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from zhenxun.services.ai.tools.core.tool import BaseTool
|
||||
from zhenxun.services.ai.tools.engine.registry import ToolCollection
|
||||
from .registry import ToolCollection
|
||||
|
||||
|
||||
class ToolExecutor:
|
||||
@@ -49,6 +48,7 @@ class ToolExecutor:
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
"""初始化工具执行器。"""
|
||||
pass
|
||||
|
||||
def _get_combined_capability(
|
||||
@@ -126,8 +126,7 @@ class ToolExecutor:
|
||||
arguments, parsed_successfully = parsed, True
|
||||
logger.debug(
|
||||
"⚒️ 成功修复损坏的工具参数: "
|
||||
f"{args_str} -> {repaired_str}",
|
||||
"ToolExecutor",
|
||||
f"{args_str} -> {repaired_str}"
|
||||
)
|
||||
except Exception:
|
||||
pass
|
||||
@@ -145,7 +144,7 @@ class ToolExecutor:
|
||||
tool_name: str,
|
||||
executable: Any,
|
||||
event_bus: EventBus | None,
|
||||
available_tools: "ToolCollection | dict[str, Any] | None" = None,
|
||||
available_tools: ToolCollection | dict[str, Any] | None = None,
|
||||
) -> RunContext:
|
||||
"""准备/克隆工具调用所使用的隔离 RunContext"""
|
||||
safe_context = (
|
||||
@@ -163,7 +162,7 @@ class ToolExecutor:
|
||||
async def validate_tool_call(
|
||||
self,
|
||||
tool_call: ToolCallPart,
|
||||
available_tools: "ToolCollection | dict[str, Any] | None",
|
||||
available_tools: ToolCollection | dict[str, Any] | None,
|
||||
context: RunContext | None = None,
|
||||
event_bus: EventBus | None = None,
|
||||
) -> ValidatedToolCall:
|
||||
@@ -213,8 +212,6 @@ class ToolExecutor:
|
||||
|
||||
async def inner_validate(args_inner):
|
||||
if isinstance(args_inner, dict) and hasattr(executable, "validate_args"):
|
||||
import inspect
|
||||
|
||||
sig = inspect.signature(executable.validate_args)
|
||||
if "context" in sig.parameters:
|
||||
return await executable.validate_args(
|
||||
@@ -247,7 +244,7 @@ class ToolExecutor:
|
||||
async def execute_tool_call(
|
||||
self,
|
||||
validated: ValidatedToolCall,
|
||||
available_tools: "ToolCollection | dict[str, Any] | None",
|
||||
available_tools: ToolCollection | dict[str, Any] | None,
|
||||
context: RunContext | None = None,
|
||||
model_name: str | None = None,
|
||||
max_retries: int = 0,
|
||||
@@ -285,8 +282,6 @@ class ToolExecutor:
|
||||
available_tools,
|
||||
)
|
||||
|
||||
from zhenxun.services.ai.run.context import set_run_context
|
||||
|
||||
combined_cap = self._get_combined_capability(executable, safe_context)
|
||||
|
||||
async def inner_handler(args_inner: dict) -> Any:
|
||||
@@ -322,7 +317,7 @@ class ToolExecutor:
|
||||
async def execute_batch(
|
||||
self,
|
||||
tool_calls: list[ToolCallPart],
|
||||
available_tools: "ToolCollection | dict[str, Any] | None",
|
||||
available_tools: ToolCollection | dict[str, Any] | None,
|
||||
context: RunContext | None = None,
|
||||
model_name: str | None = None,
|
||||
max_retries: int = 0,
|
||||
@@ -415,11 +410,12 @@ class ToolExecutor:
|
||||
|
||||
class ToolExecutionPolicy:
|
||||
"""
|
||||
工具执行策略 (Strategy Pattern)。
|
||||
工具执行策略。
|
||||
负责解析工具私有配置与系统全局配置，决定最大重试次数、Fallback 路由目标等流转行为。
|
||||
"""
|
||||
|
||||
def __init__(self, tool: BaseTool, global_max_retries: int = 0):
|
||||
"""初始化工具执行策略。"""
|
||||
self.tool = tool
|
||||
self.settings: ToolOptions = getattr(tool, "settings", ToolOptions())
|
||||
self.metadata: dict[str, Any] = (
|
||||
@@ -449,6 +445,7 @@ class ToolRunner(ABC):
|
||||
async def run(
|
||||
self, tool: BaseTool, context: RunContext, **kwargs: Any
|
||||
) -> ToolResult:
|
||||
"""执行工具调用的抽象方法。"""
|
||||
pass
|
||||
|
||||
|
||||
@@ -461,6 +458,7 @@ class NativeToolRunner(ToolRunner):
|
||||
async def run(
|
||||
self, tool: BaseTool, context: RunContext, **kwargs: Any
|
||||
) -> ToolResult:
|
||||
"""运行原生 Python 函数工具并返回结果。"""
|
||||
target_func = tool.get_execute_target()
|
||||
signature_target = tool.get_signature_target()
|
||||
|
||||
@@ -498,8 +496,8 @@ class NativeToolRunner(ToolRunner):
|
||||
if tool and hasattr(tool, "settings")
|
||||
else False
|
||||
)
|
||||
if context.run.event_bus and not is_silent:
|
||||
await context.run.event_bus.emit(
|
||||
if not is_silent:
|
||||
await context.run.emit(
|
||||
ToolStreamChunkEvent(
|
||||
tool_name=tool.name,
|
||||
content=chunk_obj.content,
|
||||
@@ -521,8 +519,7 @@ class NativeToolRunner(ToolRunner):
|
||||
else res
|
||||
)
|
||||
parts = await MessageBuilder.unimsg_to_llm_parts(uni_msg)
|
||||
if context and context.run.event_bus:
|
||||
await context.run.event_bus.emit(UserCustomEvent(display=uni_msg))
|
||||
await context.run.emit(UserCustomEvent(display=uni_msg))
|
||||
final_result = ToolResult(output=parts)
|
||||
else:
|
||||
final_result = ToolResult(output=res)
|
||||
@@ -530,6 +527,4 @@ class NativeToolRunner(ToolRunner):
|
||||
return final_result
|
||||
|
||||
|
||||
from zhenxun.services.ai.tools.core.tool import register_tool_runner
|
||||
|
||||
register_tool_runner(NativeToolRunner)
|
||||
|
||||
@@ -1,122 +1,76 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
import asyncio
|
||||
from collections.abc import Callable, Iterable
|
||||
import inspect
|
||||
from typing import Any, Generic, SupportsIndex, TypeVar, cast, overload
|
||||
from typing_extensions import Self
|
||||
|
||||
from nonebot.utils import is_coroutine_callable
|
||||
|
||||
from zhenxun.services.ai.core.exceptions import ConfigurationException
|
||||
from zhenxun.services.ai.core.protocols.tool import (
|
||||
ToolExecutable,
|
||||
ToolProvider,
|
||||
ToolResolvable,
|
||||
)
|
||||
from zhenxun.services.ai.run.context import RunContext
|
||||
from zhenxun.services.ai.tools.core.tool import FunctionTool
|
||||
from zhenxun.services.ai.tools.core.toolkit import BaseToolkit
|
||||
from zhenxun.services.ai.tools.models import Query, ResolvedToolPayload
|
||||
from zhenxun.services.log import logger
|
||||
from zhenxun.services.ai.utils.logger import log_tool as logger
|
||||
from zhenxun.services.ai.utils.utils import parse_routing_string
|
||||
from zhenxun.utils.utils import infer_plugin_namespace
|
||||
|
||||
T = TypeVar("T", bound=ToolExecutable)
|
||||
|
||||
|
||||
class ToolCollection(list[T], Generic[T]):
|
||||
"""支持按索引和按名称获取的工具集合 (List + Dict)"""
|
||||
class ToolCollection(Generic[T]):
|
||||
"""不可变的工具集合"""
|
||||
|
||||
def __init__(self, iterable: Iterable[T] | None = None):
|
||||
"""初始化工具集合。"""
|
||||
super().__init__(iterable or [])
|
||||
self._tuple: tuple[T, ...] = tuple(iterable) if iterable else ()
|
||||
self._name_cache: dict[str, T] = {}
|
||||
self._build_name_cache()
|
||||
|
||||
def _build_name_cache(self) -> None:
|
||||
"""构建工具名称小写到工具实例的映射缓存。"""
|
||||
self._name_cache = {}
|
||||
for tool in self:
|
||||
self._name_cache.clear()
|
||||
for tool in self._tuple:
|
||||
name = getattr(tool, "name", None)
|
||||
if name:
|
||||
self._name_cache[name.lower()] = tool
|
||||
|
||||
def __iter__(self):
|
||||
"""获取工具元组的迭代器。"""
|
||||
return iter(self._tuple)
|
||||
|
||||
def __len__(self):
|
||||
"""获取工具集合中的工具数量。"""
|
||||
return len(self._tuple)
|
||||
|
||||
def __bool__(self):
|
||||
"""检查工具集合是否非空。"""
|
||||
return bool(self._tuple)
|
||||
|
||||
@overload
|
||||
def __getitem__(self, key: SupportsIndex) -> T: ...
|
||||
|
||||
@overload
|
||||
def __getitem__(self, key: slice) -> list[T]: ...
|
||||
def __getitem__(self, key: slice) -> tuple[T, ...]: ...
|
||||
|
||||
@overload
|
||||
def __getitem__(self, key: str) -> T: ...
|
||||
|
||||
def __getitem__(self, key: Any) -> Any:
|
||||
"""按索引、切片或名称获取工具。"""
|
||||
if isinstance(key, str):
|
||||
return self._name_cache[key.lower()]
|
||||
return super().__getitem__(key)
|
||||
|
||||
@overload
|
||||
def __setitem__(self, key: SupportsIndex, value: T) -> None: ...
|
||||
|
||||
@overload
|
||||
def __setitem__(self, key: slice, value: Iterable[T]) -> None: ...
|
||||
|
||||
@overload
|
||||
def __setitem__(self, key: str, value: T) -> None: ...
|
||||
|
||||
def __setitem__(self, key: Any, value: Any) -> None:
|
||||
if isinstance(key, str):
|
||||
name = key.lower()
|
||||
if name in self._name_cache:
|
||||
old_tool = self._name_cache[name]
|
||||
try:
|
||||
idx = super().index(old_tool)
|
||||
super().__setitem__(idx, value)
|
||||
except ValueError:
|
||||
super().append(value)
|
||||
else:
|
||||
super().append(value)
|
||||
self._name_cache[name] = value
|
||||
else:
|
||||
super().__setitem__(key, value)
|
||||
self._name_cache[value.name.lower()] = value
|
||||
return self._tuple[key]
|
||||
|
||||
def get(self, key: str, default: Any = None) -> T | Any:
|
||||
"""通过名称获取工具，若不存在则返回默认值。"""
|
||||
return self._name_cache.get(key.lower(), default)
|
||||
|
||||
def append(self, object: T) -> None:
|
||||
"""向集合中添加工具，并更新名称缓存。"""
|
||||
name = object.name
|
||||
if name.lower() in self._name_cache:
|
||||
old_tool = self._name_cache[name.lower()]
|
||||
try:
|
||||
idx = super().index(old_tool)
|
||||
super().__setitem__(idx, object)
|
||||
except ValueError:
|
||||
super().append(object)
|
||||
else:
|
||||
super().append(object)
|
||||
self._name_cache[name.lower()] = object
|
||||
|
||||
def extend(self, iterable: Iterable[T]) -> None:
|
||||
"""批量添加工具到集合中。"""
|
||||
for t in iterable:
|
||||
self.append(t)
|
||||
|
||||
def remove(self, value: T) -> None:
|
||||
"""从集合中移除指定工具，并同步更新缓存。"""
|
||||
super().remove(value)
|
||||
name = getattr(value, "name", None)
|
||||
if name and name.lower() in self._name_cache:
|
||||
del self._name_cache[name.lower()]
|
||||
|
||||
def pop(self, index: SupportsIndex = -1) -> T:
|
||||
"""弹出指定位置的工具，并从缓存中移除。"""
|
||||
tool = super().pop(index)
|
||||
name = getattr(tool, "name", None)
|
||||
if name and name.lower() in self._name_cache:
|
||||
del self._name_cache[name.lower()]
|
||||
return tool
|
||||
|
||||
def filter_by_names(self, names: list[str] | None = None) -> "ToolCollection[T]":
|
||||
"""根据名称列表筛选并返回新的工具子集合。"""
|
||||
if names is None:
|
||||
@@ -129,11 +83,6 @@ class ToolCollection(list[T], Generic[T]):
|
||||
]
|
||||
)
|
||||
|
||||
def clear(self) -> None:
|
||||
"""清空集合及所有名称缓存。"""
|
||||
super().clear()
|
||||
self._name_cache.clear()
|
||||
|
||||
def keys(self):
|
||||
"""获取所有工具名称缓存的键。"""
|
||||
return self._name_cache.keys()
|
||||
@@ -147,155 +96,231 @@ class ToolCollection(list[T], Generic[T]):
|
||||
return self._name_cache.items()
|
||||
|
||||
|
||||
class _StringResolver:
|
||||
"""字符串格式的工具路由解析器。
|
||||
class LocalToolProvider(ToolProvider):
|
||||
"""本地工具提供者。统一管理基于 @tool 注册的普通函数或工具箱。"""
|
||||
|
||||
负责解析像 'ns.tool_name'、'ns.*' 或 'ns.#tag' 的语法路由。
|
||||
"""
|
||||
def __init__(self):
|
||||
"""初始化本地工具提供者。"""
|
||||
self._namespaced_tools: dict[str, list[Any]] = {}
|
||||
|
||||
def __init__(
|
||||
self, name: str, manager: "ToolProviderManager", default_namespace: str
|
||||
):
|
||||
"""初始化字符串路由解析器。"""
|
||||
self.name = name
|
||||
self.manager = manager
|
||||
self.default_namespace = default_namespace
|
||||
def register_tool(self, tool: ToolExecutable, namespace: str):
|
||||
"""向指定命名空间注册单一工具。"""
|
||||
if namespace not in self._namespaced_tools:
|
||||
self._namespaced_tools[namespace] = []
|
||||
self._namespaced_tools[namespace].append(tool)
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
"""解析字符串路由并返回匹配的工具载荷。"""
|
||||
if self.name in self.manager._macro_resolvers:
|
||||
resolver = self.manager._macro_resolvers[self.name]
|
||||
resolved = (
|
||||
await resolver() if is_coroutine_callable(resolver) else resolver()
|
||||
)
|
||||
return await self.manager._normalize_to_resolver(
|
||||
resolved, self.default_namespace
|
||||
).resolve(context)
|
||||
def register_toolkit(self, toolkit: Any, namespace: str):
|
||||
"""向指定命名空间注册工具箱。"""
|
||||
if namespace not in self._namespaced_tools:
|
||||
self._namespaced_tools[namespace] = []
|
||||
self._namespaced_tools[namespace].append(toolkit)
|
||||
|
||||
s = self.name
|
||||
async def initialize(self) -> None:
|
||||
"""初始化本地工具提供者。"""
|
||||
pass
|
||||
|
||||
if "." in s:
|
||||
ns, target = s.split(".", 1)
|
||||
else:
|
||||
ns = self.default_namespace
|
||||
target = s
|
||||
async def discover_tools(self) -> dict[str, ToolExecutable]:
|
||||
"""发现并获取所有注册的本地工具。"""
|
||||
res = {}
|
||||
for tools in self._namespaced_tools.values():
|
||||
for t in tools:
|
||||
name = getattr(t, "name", getattr(t, "__class__", type).__name__)
|
||||
res[name] = t
|
||||
return res
|
||||
|
||||
from zhenxun.services.ai.tools.models import Query
|
||||
async def get_tool_executable(
|
||||
self, name: str, config: dict[str, Any]
|
||||
) -> ToolExecutable | None:
|
||||
"""根据名称获取本地工具实例。"""
|
||||
tools = await self.discover_tools()
|
||||
return tools.get(name)
|
||||
|
||||
if target == "*":
|
||||
query = Query(namespace=ns)
|
||||
elif target.startswith("#"):
|
||||
tags = [t for t in target.split("#") if t]
|
||||
query = Query(tags=tags, namespace=ns)
|
||||
else:
|
||||
query = Query(name=target, namespace=ns)
|
||||
|
||||
logger.debug(f"🔍 [StringRouter] 语法解析: '{self.name}' -> {query}")
|
||||
return await _QueryResolver(
|
||||
query, self.manager, self.default_namespace
|
||||
).resolve(context)
|
||||
|
||||
|
||||
class _QueryResolver:
|
||||
"""Query 查询对象格式的工具路由解析器。
|
||||
|
||||
负责根据 namespace、标签或工具名称检索匹配的工具。
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self, query: Query, manager: "ToolProviderManager", default_namespace: str
|
||||
):
|
||||
"""初始化查询对象路由解析器。"""
|
||||
self.query = query
|
||||
self.manager = manager
|
||||
self.default_namespace = default_namespace
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
"""执行查询以解析并返回匹配的工具载荷。"""
|
||||
payload = ResolvedToolPayload()
|
||||
async def query_tools(self, query: Query) -> list[ToolExecutable]:
|
||||
"""根据查询条件检索本地工具。"""
|
||||
matched_tools = []
|
||||
target_namespace = query.namespace
|
||||
namespaces_to_search = []
|
||||
|
||||
target_namespace = self.query.namespace or self.default_namespace
|
||||
|
||||
if target_namespace == "global":
|
||||
namespaces_to_search = list(self.manager._namespaced_tools.keys())
|
||||
namespaces_to_search = self.get_all_namespaces()
|
||||
elif target_namespace:
|
||||
namespaces_to_search = [target_namespace]
|
||||
else:
|
||||
raise ValueError(f"Query 对象必须显式指定 namespace 作用域: {self.query}")
|
||||
namespaces_to_search = self.get_all_namespaces()
|
||||
|
||||
for ns in namespaces_to_search:
|
||||
if ns in self.manager._namespaced_tools:
|
||||
for tool in self.manager._namespaced_tools[ns]:
|
||||
if self.query.match(tool):
|
||||
p = await tool.resolve(context)
|
||||
if p:
|
||||
payload.tools.extend(p.tools)
|
||||
payload.injected_prompts.extend(p.injected_prompts)
|
||||
payload.toolkits.extend(p.toolkits)
|
||||
for tool in self.get_tools_by_namespace(ns):
|
||||
if query.match(tool):
|
||||
matched_tools.append(tool)
|
||||
|
||||
if self.query.name and not payload.tools and not self.query.tags:
|
||||
specific = await self.manager.resolve_specific_tools([self.query.name])
|
||||
for t in specific:
|
||||
if self.query.match(t):
|
||||
payload.tools.append(t)
|
||||
return matched_tools
|
||||
|
||||
def get_tools_by_namespace(self, namespace: str) -> list[Any]:
|
||||
"""获取指定命名空间下的所有工具和工具箱。"""
|
||||
return self._namespaced_tools.get(namespace, [])
|
||||
|
||||
def get_all_namespaces(self) -> list[str]:
|
||||
"""获取所有已注册工具的命名空间列表。"""
|
||||
return list(self._namespaced_tools.keys())
|
||||
|
||||
|
||||
class BaseToolResolver(ABC):
|
||||
"""工具载荷解析器抽象基类协议 (责任链模式)"""
|
||||
|
||||
@abstractmethod
|
||||
def match(self, item: Any) -> bool:
|
||||
"""判断解析器是否匹配当前工具对象。"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
async def resolve(
|
||||
self,
|
||||
item: Any,
|
||||
manager: "ToolProviderManager",
|
||||
default_namespace: str,
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
"""解析工具对象并返回其载荷。"""
|
||||
pass
|
||||
|
||||
|
||||
class ProtocolResolver(BaseToolResolver):
|
||||
"""处理已经实现了 ToolResolvable 协议的对象"""
|
||||
|
||||
def match(self, item: Any) -> bool:
|
||||
"""检查是否实现 ToolResolvable 协议。"""
|
||||
return hasattr(item, "resolve")
|
||||
|
||||
async def resolve(
|
||||
self,
|
||||
item: Any,
|
||||
manager: "ToolProviderManager",
|
||||
default_namespace: str,
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
"""直接调用对象的 resolve 方法进行解析。"""
|
||||
return await item.resolve(context)
|
||||
|
||||
|
||||
class StringRoutingResolver(BaseToolResolver):
|
||||
"""处理带语法的路由字符串"""
|
||||
|
||||
def match(self, item: Any) -> bool:
|
||||
"""检查是否为非宏的路由字符串。"""
|
||||
return isinstance(item, str)
|
||||
|
||||
async def resolve(
|
||||
self,
|
||||
item: Any,
|
||||
manager: "ToolProviderManager",
|
||||
default_namespace: str,
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
s = cast(str, item)
|
||||
parsed_args = parse_routing_string(s, default_namespace)
|
||||
query = Query(**parsed_args)
|
||||
|
||||
logger.debug(f"🔍 [StringRouter] 语法解析: '{item}' -> {query}")
|
||||
return await manager._resolve_single(query, default_namespace, context)
|
||||
|
||||
|
||||
class QueryResolver(BaseToolResolver):
|
||||
"""处理 Query 查询对象"""
|
||||
|
||||
def match(self, item: Any) -> bool:
|
||||
"""检查对象是否为 Query 实例。"""
|
||||
return isinstance(item, Query)
|
||||
|
||||
async def resolve(
|
||||
self,
|
||||
item: Any,
|
||||
manager: "ToolProviderManager",
|
||||
default_namespace: str,
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
query = cast(Query, item)
|
||||
payload = ResolvedToolPayload()
|
||||
|
||||
if query.namespace == "*":
|
||||
query.namespace = "global"
|
||||
elif not query.namespace:
|
||||
query.namespace = default_namespace
|
||||
|
||||
matched_tools = await manager.local_provider.query_tools(query)
|
||||
for tool in matched_tools:
|
||||
if hasattr(tool, "resolve"):
|
||||
resolvable_tool = cast(ToolResolvable, tool)
|
||||
p = await resolvable_tool.resolve(context)
|
||||
if p:
|
||||
for t in p.tools:
|
||||
if query.match(t):
|
||||
payload.tools.append(t)
|
||||
payload.injected_prompts.extend(p.injected_prompts)
|
||||
for tk in p.toolkits:
|
||||
if tk not in payload.toolkits:
|
||||
payload.toolkits.append(tk)
|
||||
else:
|
||||
payload.tools.append(tool)
|
||||
|
||||
return payload
|
||||
|
||||
|
||||
class _CallableResolver:
|
||||
"""普通 Python 函数/可调用对象格式的工具路由解析器。
|
||||
class CallableResolver(BaseToolResolver):
|
||||
"""处理普通 Python 函数"""
|
||||
|
||||
负责将其包装为 FunctionTool 实例。
|
||||
"""
|
||||
def match(self, item: Any) -> bool:
|
||||
"""检查对象是否为可调用对象。"""
|
||||
return callable(item)
|
||||
|
||||
def __init__(self, func: Callable, manager: "ToolProviderManager"):
|
||||
"""初始化可调用对象路由解析器。"""
|
||||
self.func = func
|
||||
self.manager = manager
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
"""将可调用对象转换为函数工具并返回其解析载荷。"""
|
||||
async def resolve(
|
||||
self,
|
||||
item: Any,
|
||||
manager: "ToolProviderManager",
|
||||
default_namespace: str,
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
func = cast(Callable, item)
|
||||
for candidate in (
|
||||
getattr(self.func, "__tool_name__", None),
|
||||
getattr(self.func, "__name__", None),
|
||||
getattr(func, "__tool_name__", None),
|
||||
getattr(func, "__name__", None),
|
||||
):
|
||||
if candidate:
|
||||
for ns_tools in self.manager._namespaced_tools.values():
|
||||
if t := ns_tools.get(candidate):
|
||||
return await t.resolve(context)
|
||||
from zhenxun.services.ai.tools.core.tool import FunctionTool
|
||||
for ns in manager.local_provider.get_all_namespaces():
|
||||
for t in manager.local_provider.get_tools_by_namespace(ns):
|
||||
if getattr(t, "name", None) == candidate:
|
||||
return await t.resolve(context)
|
||||
|
||||
t = FunctionTool(func=self.func)
|
||||
t = FunctionTool(func=func)
|
||||
return await t.resolve(context)
|
||||
|
||||
|
||||
class _TypeAdapterResolver:
|
||||
"""基于自定义类型映射注册的工具路由解析器。负责调用对应类型的解析函数。"""
|
||||
class DictToolResolver(BaseToolResolver):
|
||||
"""处理字典类型的动态/按需工具配置解析器"""
|
||||
|
||||
def __init__(
|
||||
def match(self, item: Any) -> bool:
|
||||
"""检查对象是否为配置字典。"""
|
||||
return isinstance(item, dict)
|
||||
|
||||
async def resolve(
|
||||
self,
|
||||
item: Any,
|
||||
resolver_func: Callable,
|
||||
manager: "ToolProviderManager",
|
||||
default_namespace: str,
|
||||
):
|
||||
"""初始化类型适配器解析器。"""
|
||||
self.item = item
|
||||
self.resolver_func = resolver_func
|
||||
self.manager = manager
|
||||
self.default_namespace = default_namespace
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
config = cast(dict, item)
|
||||
name = config.get("name")
|
||||
if not name:
|
||||
raise ConfigurationException("工具配置字典必须包含 'name' 字段。")
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
"""执行类型适配器函数并解析返回对应的工具载荷。"""
|
||||
resolved = (
|
||||
await self.resolver_func(self.item)
|
||||
if is_coroutine_callable(self.resolver_func)
|
||||
else self.resolver_func(self.item)
|
||||
)
|
||||
return await self.manager._normalize_to_resolver(
|
||||
resolved, self.default_namespace
|
||||
).resolve(context)
|
||||
for provider in manager._providers:
|
||||
executable = await provider.get_tool_executable(name, config)
|
||||
if executable:
|
||||
return await manager._resolve_single(
|
||||
executable, default_namespace, context
|
||||
)
|
||||
|
||||
raise ConfigurationException(f"没有为 ad-hoc 工具 '{name}' 找到合适的提供者。")
|
||||
|
||||
|
||||
class ToolProviderManager:
|
||||
@@ -314,25 +339,23 @@ class ToolProviderManager:
|
||||
if hasattr(self, "_initialized") and self._initialized:
|
||||
return
|
||||
|
||||
self._providers: list[ToolProvider] = []
|
||||
self._namespaced_tools: dict[str, ToolCollection] = {}
|
||||
self._resolved_tools: ToolCollection | None = None
|
||||
self.local_provider = LocalToolProvider()
|
||||
self._providers: list[ToolProvider] = [self.local_provider]
|
||||
self._init_lock = asyncio.Lock()
|
||||
self._init_promise: asyncio.Task | None = None
|
||||
self._initialized = True
|
||||
|
||||
self._macro_resolvers: dict[str, Callable] = {}
|
||||
self._type_resolvers: dict[type, Callable] = {}
|
||||
self._resolvers: list[BaseToolResolver] = [
|
||||
ProtocolResolver(),
|
||||
QueryResolver(),
|
||||
StringRoutingResolver(),
|
||||
DictToolResolver(),
|
||||
CallableResolver(),
|
||||
]
|
||||
|
||||
def register_macro_resolver(self, macro_str: str, resolver_func: Callable) -> None:
|
||||
"""注册宏解析器函数。"""
|
||||
self._macro_resolvers[macro_str] = resolver_func
|
||||
|
||||
def register_type_resolver(
|
||||
self, target_type: type, resolver_func: Callable
|
||||
) -> None:
|
||||
"""注册特定类型的工具解析函数。"""
|
||||
self._type_resolvers[target_type] = resolver_func
|
||||
def register_resolver(self, resolver: BaseToolResolver) -> None:
|
||||
"""注册自定义的工具载荷解析器（插在兜底的 CallableResolver 之前）。"""
|
||||
self._resolvers.insert(-1, resolver)
|
||||
|
||||
def register(self, provider: ToolProvider):
|
||||
"""注册一个新的 ToolProvider。"""
|
||||
@@ -342,21 +365,26 @@ class ToolProviderManager:
|
||||
|
||||
def register_tool(self, tool: ToolExecutable):
|
||||
"""注册由 @tool 生成的单一工具"""
|
||||
ns = infer_plugin_namespace()
|
||||
if ns not in self._namespaced_tools:
|
||||
self._namespaced_tools[ns] = ToolCollection()
|
||||
self._namespaced_tools[ns].append(tool)
|
||||
self._resolved_tools = None
|
||||
ns = infer_plugin_namespace(default="global")
|
||||
self.local_provider.register_tool(tool, ns)
|
||||
tags = getattr(getattr(tool, "settings", None), "tags", [])
|
||||
tag_str = f" | Tags: {tags}" if tags else ""
|
||||
tool_name = getattr(tool, "name", "unknown")
|
||||
logger.debug(f"已注册工具: '{tool_name}' -> Namespace: '{ns}'{tag_str}")
|
||||
|
||||
def register_toolkit(self, toolkit: Any) -> None:
|
||||
"""
|
||||
注册一个完整的 Toolkit 实例，使其可通过智能字符串路由（Tag或Name）被动态发现。
|
||||
"""
|
||||
ns = infer_plugin_namespace()
|
||||
if ns not in self._namespaced_tools:
|
||||
self._namespaced_tools[ns] = ToolCollection()
|
||||
self._namespaced_tools[ns].append(toolkit)
|
||||
self._resolved_tools = None
|
||||
ns = infer_plugin_namespace(default="global")
|
||||
self.local_provider.register_toolkit(toolkit, ns)
|
||||
tk_name = getattr(toolkit, "__class__", type).__name__
|
||||
|
||||
config = getattr(toolkit, "config", None)
|
||||
shared_options = getattr(config, "shared_options", None) if config else None
|
||||
tags = getattr(shared_options, "tags", []) if shared_options else []
|
||||
tag_str = f" | Tags: {tags}" if tags else ""
|
||||
logger.debug(f"已注册工具箱: '{tk_name}' -> Namespace: '{ns}'{tag_str}")
|
||||
|
||||
async def initialize(self) -> None:
|
||||
"""懒加载初始化所有已注册的 ToolProvider。"""
|
||||
@@ -375,28 +403,11 @@ class ToolProviderManager:
|
||||
await asyncio.gather(*init_tasks, return_exceptions=True)
|
||||
logger.info("所有工具提供者初始化完成。")
|
||||
|
||||
async def discover_tools(
|
||||
self,
|
||||
allowed_servers: list[str] | None = None,
|
||||
excluded_servers: list[str] | None = None,
|
||||
def _process_discovery_results(
|
||||
self, results: list[Any], provider_indices: list[int]
|
||||
) -> dict[str, ToolExecutable]:
|
||||
"""向所有已初始化的 ToolProvider 并发执行工具发现。"""
|
||||
discover_tasks = []
|
||||
provider_indices = []
|
||||
for i, provider in enumerate(self._providers):
|
||||
sig = inspect.signature(provider.discover_tools)
|
||||
params_to_pass = {}
|
||||
if "allowed_servers" in sig.parameters:
|
||||
params_to_pass["allowed_servers"] = allowed_servers
|
||||
if "excluded_servers" in sig.parameters:
|
||||
params_to_pass["excluded_servers"] = excluded_servers
|
||||
|
||||
discover_tasks.append(provider.discover_tools(**params_to_pass))
|
||||
provider_indices.append(i)
|
||||
|
||||
results = await asyncio.gather(*discover_tasks, return_exceptions=True)
|
||||
|
||||
provider_tools = {}
|
||||
"""处理并合并来自多个工具提供者的并发发现结果"""
|
||||
provider_tools: dict[str, ToolExecutable] = {}
|
||||
for result_idx, provider_result in enumerate(results):
|
||||
provider = self._providers[provider_indices[result_idx]]
|
||||
provider_name = provider.__class__.__name__
|
||||
@@ -406,7 +417,7 @@ class ToolProviderManager:
|
||||
f"提供者 '{provider_name}' 发现了 {len(provider_result)} 个工具。"
|
||||
)
|
||||
for name, executable in provider_result.items():
|
||||
if provider_tools.get(name):
|
||||
if name in provider_tools:
|
||||
logger.warning(
|
||||
f"发现重复的工具名称 '{name}'，后发现的将覆盖前者。"
|
||||
)
|
||||
@@ -417,106 +428,29 @@ class ToolProviderManager:
|
||||
)
|
||||
return provider_tools
|
||||
|
||||
async def _query_engine(
|
||||
self,
|
||||
names: list[str] | None = None,
|
||||
allowed_servers: list[str] | None = None,
|
||||
excluded_servers: list[str] | None = None,
|
||||
include_providers: bool = True,
|
||||
) -> ToolCollection:
|
||||
"""统一查询引擎：收敛所有本地与云端的工具检索逻辑"""
|
||||
await self.initialize()
|
||||
resolved = ToolCollection()
|
||||
async def discover_tools(self) -> dict[str, ToolExecutable]:
|
||||
"""向所有已初始化的 ToolProvider 并发执行工具发现。"""
|
||||
discover_tasks = []
|
||||
provider_indices = []
|
||||
for i, provider in enumerate(self._providers):
|
||||
discover_tasks.append(provider.discover_tools())
|
||||
provider_indices.append(i)
|
||||
|
||||
for ns_tools in self._namespaced_tools.values():
|
||||
for t in ns_tools:
|
||||
if names and t.name not in names:
|
||||
continue
|
||||
resolved.append(t)
|
||||
results = await asyncio.gather(*discover_tasks, return_exceptions=True)
|
||||
provider_tools = self._process_discovery_results(results, provider_indices)
|
||||
return provider_tools
|
||||
|
||||
if not include_providers:
|
||||
return resolved
|
||||
|
||||
if names:
|
||||
missing_names = [n for n in names if not resolved.get(n)]
|
||||
for name in missing_names:
|
||||
config = {"name": name}
|
||||
for provider in self._providers:
|
||||
try:
|
||||
if executable := await provider.get_tool_executable(
|
||||
name, config
|
||||
):
|
||||
resolved.append(executable)
|
||||
break
|
||||
except Exception as exc:
|
||||
logger.error(
|
||||
f"provider '{provider.__class__.__name__}'"
|
||||
f"解析工具 '{name}' 出错: {exc}"
|
||||
)
|
||||
else:
|
||||
provider_tools = await self.discover_tools(
|
||||
allowed_servers, excluded_servers
|
||||
)
|
||||
for t in provider_tools.values():
|
||||
resolved.append(t)
|
||||
|
||||
return resolved
|
||||
|
||||
async def get_resolved_tools(
|
||||
self,
|
||||
allowed_servers: list[str] | None = None,
|
||||
excluded_servers: list[str] | None = None,
|
||||
namespaces: list[str] | None = None,
|
||||
) -> ToolCollection:
|
||||
"""获取已解析完成的所有可用工具集合。"""
|
||||
has_filters = (
|
||||
allowed_servers is not None
|
||||
or excluded_servers is not None
|
||||
or namespaces is not None
|
||||
async def _resolve_single(
|
||||
self, item: Any, default_namespace: str, context: RunContext | None
|
||||
) -> ResolvedToolPayload:
|
||||
"""通过责任链解析单个工具意图并返回载荷"""
|
||||
for r in self._resolvers:
|
||||
if r.match(item):
|
||||
return await r.resolve(item, self, default_namespace, context)
|
||||
raise TypeError(
|
||||
f"严格协议校验失败: 工具对象 {type(item)} 必须实现 ToolResolvable 协议 "
|
||||
"(包含 resolve 方法)。如果你想注册普通函数，请使用 @tool 装饰器。"
|
||||
)
|
||||
if not has_filters and self._resolved_tools is not None:
|
||||
return self._resolved_tools
|
||||
|
||||
tools = await self._query_engine(
|
||||
allowed_servers=allowed_servers, excluded_servers=excluded_servers
|
||||
)
|
||||
|
||||
if not has_filters:
|
||||
self._resolved_tools = tools
|
||||
return tools
|
||||
|
||||
async def resolve_specific_tools(self, tool_names: list[str]) -> ToolCollection:
|
||||
"""根据名称列表检索并返回特定的工具集合。"""
|
||||
return await self._query_engine(names=tool_names, include_providers=True)
|
||||
|
||||
async def get_function_tools(
|
||||
self, names: list[str] | None = None
|
||||
) -> ToolCollection:
|
||||
"""获取本地注册的所有函数工具集合。"""
|
||||
return await self._query_engine(names=names, include_providers=False)
|
||||
|
||||
def _normalize_to_resolver(self, item: Any, default_ns: str) -> Any:
|
||||
"""将任意工具配置或定义包装为标准的多态解析器对象。"""
|
||||
if hasattr(item, "resolve"):
|
||||
return item
|
||||
|
||||
if isinstance(item, Query):
|
||||
return _QueryResolver(item, self, default_ns)
|
||||
if isinstance(item, str):
|
||||
return _StringResolver(item, self, default_ns)
|
||||
if type(item) in self._type_resolvers:
|
||||
return _TypeAdapterResolver(
|
||||
item, self._type_resolvers[type(item)], self, default_ns
|
||||
)
|
||||
if callable(item):
|
||||
return _CallableResolver(item, self)
|
||||
|
||||
if not hasattr(item, "resolve"):
|
||||
raise TypeError(
|
||||
f"严格协议校验失败: 工具对象 {type(item)} 必须实现 ToolResolvable 协议 "
|
||||
"(包含 resolve 方法)。如果你想注册普通函数，请使用 @tool 装饰器。"
|
||||
)
|
||||
return item
|
||||
|
||||
async def resolve_tools(
|
||||
self,
|
||||
@@ -547,14 +481,7 @@ class ToolProviderManager:
|
||||
|
||||
_flatten(tool_definitions)
|
||||
|
||||
resolvers = [self._normalize_to_resolver(t, namespace) for t in defs]
|
||||
|
||||
for i, r in enumerate(resolvers):
|
||||
if asyncio.iscoroutine(r):
|
||||
r = await r
|
||||
resolvers[i] = self._normalize_to_resolver(r, namespace)
|
||||
|
||||
tasks = [r.resolve(context) for r in resolvers]
|
||||
tasks = [self._resolve_single(t, namespace, context) for t in defs]
|
||||
payloads = await asyncio.gather(*tasks, return_exceptions=False)
|
||||
|
||||
final_payload = ResolvedToolPayload()
|
||||
@@ -568,34 +495,10 @@ class ToolProviderManager:
|
||||
for t in p.tools:
|
||||
if not getattr(t, "parent_toolkit", None):
|
||||
t.parent_toolkit = global_toolkit
|
||||
final_payload.tools.append(t)
|
||||
|
||||
final_payload.injected_prompts.extend(p.injected_prompts)
|
||||
final_payload.toolkits.extend(p.toolkits)
|
||||
final_payload.merge(p)
|
||||
|
||||
final_payload.tools = ToolCollection(final_payload.tools)
|
||||
return final_payload
|
||||
|
||||
|
||||
tool_provider_manager = ToolProviderManager()
|
||||
|
||||
|
||||
async def _dict_ad_hoc_resolver(config: dict):
|
||||
"""针对字典类型的 ad-hoc 工具配置的类型解析器。"""
|
||||
name = config.get("name")
|
||||
if not name:
|
||||
raise ConfigurationException(
|
||||
"工具配置字典必须包含 'name' 字段。",
|
||||
)
|
||||
|
||||
for provider in tool_provider_manager._providers:
|
||||
executable = await provider.get_tool_executable(name, config)
|
||||
if executable:
|
||||
return executable
|
||||
|
||||
raise ConfigurationException(
|
||||
f"没有为 ad-hoc 工具 '{name}' 找到合适的提供者。",
|
||||
)
|
||||
|
||||
|
||||
tool_provider_manager.register_type_resolver(dict, _dict_ad_hoc_resolver)
|
||||
|
||||
Reference in New Issue
Block a user