mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-12 23:40:03 +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,7 @@
|
||||
from .executor import ToolExecutor
|
||||
from .registry import tool_provider_manager
|
||||
|
||||
__all__ = [
|
||||
"ToolExecutor",
|
||||
"tool_provider_manager",
|
||||
]
|
||||
@@ -0,0 +1,547 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
import ast
|
||||
import asyncio
|
||||
from contextlib import asynccontextmanager
|
||||
import inspect
|
||||
import json
|
||||
from typing import TYPE_CHECKING, Any, cast
|
||||
|
||||
import json_repair
|
||||
from nonebot.adapters import Message as PlatformMessage
|
||||
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
from zhenxun.services.ai.core.exceptions import (
|
||||
ToolFatalError,
|
||||
ToolRetryError,
|
||||
)
|
||||
from zhenxun.services.ai.core.messages import AnyLLMMessage, LLMMessage, ToolCallPart
|
||||
from zhenxun.services.ai.core.stream_events import (
|
||||
EventBus,
|
||||
ToolCallEndEvent,
|
||||
ToolCallStartEvent,
|
||||
ToolStreamChunkEvent,
|
||||
UserCustomEvent,
|
||||
)
|
||||
from zhenxun.services.ai.run.context import RunContext
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.tools.models import (
|
||||
ToolOptions,
|
||||
ToolResult,
|
||||
ValidatedToolCall,
|
||||
)
|
||||
from zhenxun.services.log import logger
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from zhenxun.services.ai.tools.core.tool import BaseTool
|
||||
from zhenxun.services.ai.tools.engine.registry import ToolCollection
|
||||
|
||||
|
||||
class ToolExecutor:
|
||||
"""
|
||||
全能工具执行器。
|
||||
负责接收工具调用请求，解析参数，触发回调，执行工具，并返回标准化的结果。
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
pass
|
||||
|
||||
def _get_combined_capability(
|
||||
self, executable: Any, context: RunContext
|
||||
) -> CombinedCapability:
|
||||
"""合并 Agent 上下文 (已包含 Global) 与 Tool 私有的 Capability"""
|
||||
tool_caps = getattr(getattr(executable, "settings", None), "capabilities", [])
|
||||
agent_caps = getattr(context, "capabilities", [])
|
||||
|
||||
all_caps = list(agent_caps)
|
||||
for c in tool_caps:
|
||||
if c not in all_caps:
|
||||
all_caps.append(c)
|
||||
return CombinedCapability(all_caps)
|
||||
|
||||
@asynccontextmanager
|
||||
async def _tool_stream_scope(
|
||||
self,
|
||||
event_bus: EventBus | None,
|
||||
tool_name: str,
|
||||
arguments: dict[str, Any],
|
||||
intent: str | None,
|
||||
):
|
||||
"""生命周期上下文管理器：接管事件流的发送与异常包装样板代码"""
|
||||
if event_bus:
|
||||
await event_bus.emit(
|
||||
ToolCallStartEvent(
|
||||
tool_name=tool_name, arguments=arguments, intent=intent
|
||||
)
|
||||
)
|
||||
result_box: dict[str, Any] = {}
|
||||
try:
|
||||
yield result_box
|
||||
finally:
|
||||
if event_bus and "result" in result_box:
|
||||
res = result_box["result"]
|
||||
await event_bus.emit(
|
||||
ToolCallEndEvent(
|
||||
tool_name=tool_name, result=res, is_error=res.is_error
|
||||
)
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _robust_parse_args(
|
||||
args_raw: str | dict[str, Any],
|
||||
) -> tuple[bool, dict[str, Any], str | None, str]:
|
||||
"""容错解析参数纯函数，返回 (是否成功, 解析后的字典, intent意图, 原始字符串)"""
|
||||
if isinstance(args_raw, dict):
|
||||
arguments = args_raw.copy()
|
||||
parsed_successfully = True
|
||||
args_str = json.dumps(args_raw, ensure_ascii=False)
|
||||
else:
|
||||
args_str = args_raw
|
||||
arguments = {}
|
||||
parsed_successfully = False
|
||||
if not args_str.strip():
|
||||
parsed_successfully = True
|
||||
else:
|
||||
try:
|
||||
parsed = json.loads(args_str)
|
||||
if isinstance(parsed, dict):
|
||||
arguments, parsed_successfully = parsed, True
|
||||
except json.JSONDecodeError:
|
||||
try:
|
||||
parsed = ast.literal_eval(args_str)
|
||||
if isinstance(parsed, dict):
|
||||
arguments, parsed_successfully = parsed, True
|
||||
except (ValueError, SyntaxError):
|
||||
try:
|
||||
repaired_str = str(
|
||||
json_repair.repair_json(args_str, skip_json_loads=True)
|
||||
)
|
||||
parsed = json.loads(repaired_str)
|
||||
if isinstance(parsed, dict):
|
||||
arguments, parsed_successfully = parsed, True
|
||||
logger.debug(
|
||||
"⚒️ 成功修复损坏的工具参数: "
|
||||
f"{args_str} -> {repaired_str}",
|
||||
"ToolExecutor",
|
||||
)
|
||||
except Exception:
|
||||
pass
|
||||
intent_str = None
|
||||
if parsed_successfully:
|
||||
_intent = arguments.pop("_intent", None)
|
||||
if _intent:
|
||||
intent_str = str(_intent)
|
||||
return parsed_successfully, arguments, intent_str, args_str
|
||||
|
||||
def _prepare_tool_context(
|
||||
self,
|
||||
context: RunContext | None,
|
||||
tool_call_id: str,
|
||||
tool_name: str,
|
||||
executable: Any,
|
||||
event_bus: EventBus | None,
|
||||
available_tools: "ToolCollection | dict[str, Any] | None" = None,
|
||||
) -> RunContext:
|
||||
"""准备/克隆工具调用所使用的隔离 RunContext"""
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
|
||||
safe_context = (
|
||||
context.clone_for_tool_call(tool_call_id, tool_name)
|
||||
if context
|
||||
else RunContext()
|
||||
)
|
||||
safe_context.run.event_bus = event_bus
|
||||
safe_context.call.tool_name = tool_name
|
||||
safe_context.call.current_tool = executable
|
||||
if available_tools is not None:
|
||||
safe_context.state["__available_tools"] = available_tools
|
||||
return safe_context
|
||||
|
||||
async def validate_tool_call(
|
||||
self,
|
||||
tool_call: ToolCallPart,
|
||||
available_tools: "ToolCollection | dict[str, Any] | None",
|
||||
context: RunContext | None = None,
|
||||
event_bus: EventBus | None = None,
|
||||
) -> ValidatedToolCall:
|
||||
"""验证单一工具调用，完成参数解析、类型检查与交互式补全(如果触发)。"""
|
||||
if not available_tools:
|
||||
available_tools = {}
|
||||
if not tool_call.tool_name:
|
||||
return ValidatedToolCall(
|
||||
call=tool_call,
|
||||
args_valid=False,
|
||||
validation_error=ToolRetryError("tool_call.tool_name 不能为空"),
|
||||
)
|
||||
|
||||
tool_name = tool_call.tool_name
|
||||
parsed_successfully, arguments, intent_str, arguments_str = (
|
||||
self._robust_parse_args(tool_call.args)
|
||||
)
|
||||
|
||||
if tool_call.args and not parsed_successfully:
|
||||
if context:
|
||||
context.run.tool_retries[tool_name] = (
|
||||
context.run.tool_retries.get(tool_name, 0) + 1
|
||||
)
|
||||
return ValidatedToolCall(
|
||||
call=tool_call,
|
||||
args_valid=False,
|
||||
validation_error=ToolRetryError(
|
||||
f"参数JSON解析失败，请检查 JSON 语法是否合法: {arguments_str}"
|
||||
),
|
||||
)
|
||||
elif intent_str:
|
||||
logger.info(f"🧠 [Agent Intent] 调用工具 {tool_name} 的意图: {intent_str}")
|
||||
|
||||
executable = available_tools.get(tool_name)
|
||||
if not executable or not hasattr(executable, "execute"):
|
||||
return ValidatedToolCall(
|
||||
call=tool_call,
|
||||
args_valid=False,
|
||||
validation_error=ToolRetryError(f"Tool '{tool_name}' not found."),
|
||||
)
|
||||
|
||||
safe_context = self._prepare_tool_context(
|
||||
context, tool_call.id, tool_name, executable, event_bus
|
||||
)
|
||||
|
||||
combined_cap = self._get_combined_capability(executable, safe_context)
|
||||
|
||||
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(
|
||||
args_inner, context=safe_context
|
||||
)
|
||||
return await executable.validate_args(args_inner)
|
||||
return args_inner
|
||||
|
||||
try:
|
||||
validated_args = await combined_cap.wrap_tool_validate(
|
||||
safe_context, tool_name, arguments, inner_validate
|
||||
)
|
||||
return ValidatedToolCall(
|
||||
call=tool_call,
|
||||
tool=executable,
|
||||
args_valid=True,
|
||||
validated_args=validated_args,
|
||||
intent=intent_str,
|
||||
)
|
||||
except BaseException as e:
|
||||
if isinstance(e, asyncio.CancelledError):
|
||||
raise e
|
||||
return ValidatedToolCall(
|
||||
call=tool_call,
|
||||
tool=executable,
|
||||
args_valid=False,
|
||||
validation_error=e,
|
||||
)
|
||||
|
||||
async def execute_tool_call(
|
||||
self,
|
||||
validated: ValidatedToolCall,
|
||||
available_tools: "ToolCollection | dict[str, Any] | None",
|
||||
context: RunContext | None = None,
|
||||
model_name: str | None = None,
|
||||
max_retries: int = 0,
|
||||
event_bus: EventBus | None = None,
|
||||
) -> tuple[ToolCallPart, ToolResult]:
|
||||
"""核心执行阶段。只接收已经通过 Validation 阶段的 ValidatedToolCall 载体。"""
|
||||
if not available_tools:
|
||||
available_tools = {}
|
||||
tool_name = validated.call.tool_name
|
||||
if not validated.args_valid or validated.tool is None:
|
||||
from zhenxun.services.ai.core.exceptions import ControlFlowExit
|
||||
|
||||
if isinstance(validated.validation_error, ControlFlowExit):
|
||||
raise validated.validation_error
|
||||
|
||||
err_msg = getattr(
|
||||
validated.validation_error, "message", str(validated.validation_error)
|
||||
)
|
||||
res = ToolResult(output=f"执行被拦截或参数错误: {err_msg}").as_error()
|
||||
if event_bus:
|
||||
await event_bus.emit(
|
||||
ToolCallEndEvent(
|
||||
tool_name=tool_name, result=res, is_error=res.is_error
|
||||
)
|
||||
)
|
||||
return validated.call, res
|
||||
|
||||
executable = validated.tool
|
||||
arguments = validated.validated_args or {}
|
||||
|
||||
safe_context = self._prepare_tool_context(
|
||||
context,
|
||||
validated.call.id,
|
||||
tool_name,
|
||||
executable,
|
||||
event_bus,
|
||||
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:
|
||||
return await executable.execute(context=safe_context, **args_inner)
|
||||
|
||||
async with self._tool_stream_scope(
|
||||
event_bus, tool_name, arguments, validated.intent
|
||||
) as box:
|
||||
with set_run_context(safe_context):
|
||||
try:
|
||||
result = await combined_cap.wrap_tool_execute(
|
||||
safe_context, tool_name, arguments, inner_handler
|
||||
)
|
||||
if not isinstance(result, ToolResult):
|
||||
result = ToolResult(output=result)
|
||||
|
||||
from zhenxun.services.ai.tools.models import StateSyncResult
|
||||
|
||||
if isinstance(result, StateSyncResult) and result.state_notice:
|
||||
if safe_context:
|
||||
safe_context.run.add_system_prompt(
|
||||
f"[系统通知(状态同步)]：{result.state_notice}"
|
||||
)
|
||||
except BaseException as e:
|
||||
from zhenxun.services.ai.core.exceptions import ControlFlowExit
|
||||
|
||||
if isinstance(e, ControlFlowExit):
|
||||
raise e
|
||||
if isinstance(e, asyncio.CancelledError):
|
||||
raise e
|
||||
logger.error(f"洋葱模型异常穿透: {e}")
|
||||
result = ToolResult(output=f"System Fatal Error: {e}").as_error()
|
||||
box["result"] = result
|
||||
|
||||
return validated.call, box["result"]
|
||||
|
||||
async def execute_batch(
|
||||
self,
|
||||
tool_calls: list[ToolCallPart],
|
||||
available_tools: "ToolCollection | dict[str, Any] | None",
|
||||
context: RunContext | None = None,
|
||||
model_name: str | None = None,
|
||||
max_retries: int = 0,
|
||||
event_bus: EventBus | None = None,
|
||||
) -> list[AnyLLMMessage]:
|
||||
"""批量并发执行多个工具调用。"""
|
||||
if not available_tools:
|
||||
available_tools = {}
|
||||
if not tool_calls:
|
||||
return []
|
||||
|
||||
val_tasks = [
|
||||
self.validate_tool_call(
|
||||
call,
|
||||
available_tools,
|
||||
context,
|
||||
event_bus=event_bus,
|
||||
)
|
||||
for call in tool_calls
|
||||
]
|
||||
validated_calls = await asyncio.gather(*val_tasks)
|
||||
|
||||
results: list[Any] = [None] * len(validated_calls)
|
||||
|
||||
async def _run_tool(index: int, val_call: ValidatedToolCall):
|
||||
try:
|
||||
res = await self.execute_tool_call(
|
||||
val_call,
|
||||
available_tools,
|
||||
context,
|
||||
model_name=model_name,
|
||||
max_retries=max_retries,
|
||||
event_bus=event_bus,
|
||||
)
|
||||
results[index] = res
|
||||
except Exception as e:
|
||||
results[index] = e
|
||||
|
||||
chunks: list[list[tuple[int, ValidatedToolCall]]] = []
|
||||
current_chunk: list[tuple[int, ValidatedToolCall]] = []
|
||||
|
||||
for i, val_call in enumerate(validated_calls):
|
||||
executable = getattr(val_call, "tool", None)
|
||||
concurrency_mode = getattr(
|
||||
getattr(executable, "settings", None), "concurrency", "shared"
|
||||
)
|
||||
|
||||
if concurrency_mode == "exclusive":
|
||||
if current_chunk:
|
||||
chunks.append(current_chunk)
|
||||
current_chunk = []
|
||||
chunks.append([(i, val_call)])
|
||||
else:
|
||||
current_chunk.append((i, val_call))
|
||||
|
||||
if current_chunk:
|
||||
chunks.append(current_chunk)
|
||||
|
||||
for chunk in chunks:
|
||||
await asyncio.gather(*[_run_tool(i, call) for i, call in chunk])
|
||||
|
||||
tool_messages: list[AnyLLMMessage] = []
|
||||
for index, result_pair in enumerate(results):
|
||||
original_call = tool_calls[index]
|
||||
func_name = original_call.tool_name
|
||||
|
||||
if isinstance(result_pair, BaseException):
|
||||
from zhenxun.services.ai.core.exceptions import ControlFlowExit
|
||||
|
||||
if isinstance(result_pair, ControlFlowExit):
|
||||
raise result_pair
|
||||
if isinstance(result_pair, asyncio.CancelledError):
|
||||
raise result_pair
|
||||
|
||||
logger.error(f"工具批量执行并发崩溃: {func_name}, 错误: {result_pair}")
|
||||
result_pair = (
|
||||
original_call,
|
||||
ToolResult(output=f"Crash: {result_pair}").as_error(),
|
||||
)
|
||||
|
||||
tool_call_result = cast(tuple[ToolCallPart, ToolResult], result_pair)
|
||||
_, tool_result = tool_call_result
|
||||
tool_messages.append(
|
||||
LLMMessage.tool_response(
|
||||
tool_call_id=original_call.id,
|
||||
function_name=func_name,
|
||||
result=tool_result.output,
|
||||
)
|
||||
)
|
||||
return tool_messages
|
||||
|
||||
|
||||
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] = (
|
||||
self.settings.metadata if self.settings else getattr(tool, "metadata", {})
|
||||
)
|
||||
self.global_max_retries = global_max_retries
|
||||
|
||||
@property
|
||||
def max_retries(self) -> int:
|
||||
"""
|
||||
计算当前工具的绝对最大重试次数。
|
||||
优先使用工具级配置 (ToolOptions.max_retries)，如果未设置，则使用全局配置。
|
||||
由于重试机制是保证 Agent 稳定性的防线，
|
||||
即使全局为 0，底层默认也会给予至少 1 次的机会。
|
||||
"""
|
||||
tool_retries = getattr(self.settings, "max_retries", None)
|
||||
if tool_retries is not None:
|
||||
return tool_retries
|
||||
return max(self.global_max_retries, 1)
|
||||
|
||||
|
||||
class ToolRunner(ABC):
|
||||
"""
|
||||
工具运行器基类协议。
|
||||
负责将参数请求物理落实为目标执行。
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
async def run(
|
||||
self, tool: BaseTool, context: RunContext, **kwargs: Any
|
||||
) -> ToolResult:
|
||||
pass
|
||||
|
||||
|
||||
class NativeToolRunner(ToolRunner):
|
||||
"""
|
||||
原生 Python 函数工具运行器。
|
||||
负责处理依赖注入 (DI)、异步包装、生成器流式收集以及框架级的多模态消息转换。
|
||||
"""
|
||||
|
||||
async def run(
|
||||
self, tool: BaseTool, context: RunContext, **kwargs: Any
|
||||
) -> ToolResult:
|
||||
target_func = tool.get_execute_target()
|
||||
signature_target = tool.get_signature_target()
|
||||
|
||||
if not target_func:
|
||||
return ToolResult(output="Error: 未找到有效的执行目标(run 方法)").as_error()
|
||||
|
||||
call_kwargs = dict(kwargs)
|
||||
|
||||
try:
|
||||
target_call_kwargs = await DependencyInjector.resolve_all(
|
||||
sig=inspect.signature(signature_target),
|
||||
call_kwargs=dict(call_kwargs),
|
||||
context=context,
|
||||
)
|
||||
except ValueError as e:
|
||||
logger.error(f"工具 {tool.name} 依赖注入失败: {e}", e=e)
|
||||
raise ToolFatalError(f"框架依赖注入失败: {e}")
|
||||
|
||||
is_async_gen = getattr(
|
||||
target_func, "_is_async_gen", False
|
||||
) or inspect.isasyncgenfunction(target_func)
|
||||
if is_async_gen:
|
||||
res = None
|
||||
async for chunk in target_func(**target_call_kwargs):
|
||||
if isinstance(chunk, ToolResult):
|
||||
res = chunk
|
||||
else:
|
||||
from zhenxun.services.ai.tools.models import ToolResultChunk
|
||||
|
||||
chunk_obj = (
|
||||
chunk
|
||||
if isinstance(chunk, ToolResultChunk)
|
||||
else ToolResultChunk(content=str(chunk))
|
||||
)
|
||||
is_silent = (
|
||||
getattr(tool.settings, "silent", False)
|
||||
if tool and hasattr(tool, "settings")
|
||||
else False
|
||||
)
|
||||
if context.run.event_bus and not is_silent:
|
||||
await context.run.event_bus.emit(
|
||||
ToolStreamChunkEvent(
|
||||
tool_name=tool.name,
|
||||
content=chunk_obj.content,
|
||||
metadata=chunk_obj.metadata,
|
||||
)
|
||||
)
|
||||
if res is None:
|
||||
res = ToolResult(output="Stream finished successfully.")
|
||||
else:
|
||||
res = await target_func(**target_call_kwargs)
|
||||
|
||||
if isinstance(res, ToolResult):
|
||||
final_result = res
|
||||
else:
|
||||
if str(type(res)).find("Message") != -1:
|
||||
from zhenxun.services.ai.message_builder import MessageBuilder
|
||||
|
||||
uni_msg = (
|
||||
MessageBuilder.message_to_unimessage(res)
|
||||
if isinstance(res, PlatformMessage)
|
||||
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))
|
||||
final_result = ToolResult(output=parts)
|
||||
else:
|
||||
final_result = ToolResult(output=res)
|
||||
|
||||
return final_result
|
||||
|
||||
|
||||
from zhenxun.services.ai.tools.core.tool import register_tool_runner
|
||||
|
||||
register_tool_runner(NativeToolRunner)
|
||||
@@ -0,0 +1,575 @@
|
||||
from __future__ import annotations
|
||||
|
||||
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,
|
||||
)
|
||||
from zhenxun.services.ai.run.context import RunContext
|
||||
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.utils.utils import infer_plugin_namespace
|
||||
|
||||
T = TypeVar("T", bound=ToolExecutable)
|
||||
|
||||
|
||||
class ToolCollection(list[T], Generic[T]):
|
||||
"""支持按索引和按名称获取的工具集合 (List + Dict)"""
|
||||
|
||||
def __init__(self, iterable: Iterable[T] | None = None):
|
||||
super().__init__(iterable or [])
|
||||
self._name_cache: dict[str, T] = {}
|
||||
self._build_name_cache()
|
||||
|
||||
def _build_name_cache(self) -> None:
|
||||
"""构建工具名称小写到工具实例的映射缓存。"""
|
||||
self._name_cache = {}
|
||||
for tool in self:
|
||||
name = getattr(tool, "name", None)
|
||||
if name:
|
||||
self._name_cache[name.lower()] = tool
|
||||
|
||||
@overload
|
||||
def __getitem__(self, key: SupportsIndex) -> T: ...
|
||||
|
||||
@overload
|
||||
def __getitem__(self, key: slice) -> list[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
|
||||
|
||||
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:
|
||||
return self
|
||||
return ToolCollection(
|
||||
[
|
||||
tool
|
||||
for name in names
|
||||
if (tool := self._name_cache.get(name.lower())) is not None
|
||||
]
|
||||
)
|
||||
|
||||
def clear(self) -> None:
|
||||
super().clear()
|
||||
self._name_cache.clear()
|
||||
|
||||
def keys(self):
|
||||
return self._name_cache.keys()
|
||||
|
||||
def values(self):
|
||||
return self._name_cache.values()
|
||||
|
||||
def items(self):
|
||||
return self._name_cache.items()
|
||||
|
||||
|
||||
class _StringResolver:
|
||||
"""字符串格式的工具路由解析器。
|
||||
|
||||
负责解析像 'ns.tool_name'、'ns.*' 或 'ns.#tag' 的语法路由。
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self, name: str, manager: "ToolProviderManager", default_namespace: str
|
||||
):
|
||||
self.name = name
|
||||
self.manager = manager
|
||||
self.default_namespace = default_namespace
|
||||
|
||||
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)
|
||||
|
||||
s = self.name
|
||||
|
||||
if "." in s:
|
||||
ns, target = s.split(".", 1)
|
||||
else:
|
||||
ns = self.default_namespace
|
||||
target = s
|
||||
|
||||
from zhenxun.services.ai.tools.models import Query
|
||||
|
||||
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()
|
||||
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())
|
||||
elif target_namespace:
|
||||
namespaces_to_search = [target_namespace]
|
||||
else:
|
||||
raise ValueError(f"Query 对象必须显式指定 namespace 作用域: {self.query}")
|
||||
|
||||
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)
|
||||
|
||||
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 payload
|
||||
|
||||
|
||||
class _CallableResolver:
|
||||
"""普通 Python 函数/可调用对象格式的工具路由解析器。
|
||||
|
||||
负责将其包装为 FunctionTool 实例。
|
||||
"""
|
||||
|
||||
def __init__(self, func: Callable, manager: "ToolProviderManager"):
|
||||
self.func = func
|
||||
self.manager = manager
|
||||
|
||||
async def resolve(self, context: RunContext | None = None) -> ResolvedToolPayload:
|
||||
for candidate in (
|
||||
getattr(self.func, "__tool_name__", None),
|
||||
getattr(self.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
|
||||
|
||||
t = FunctionTool(func=self.func)
|
||||
return await t.resolve(context)
|
||||
|
||||
|
||||
class _TypeAdapterResolver:
|
||||
"""基于自定义类型映射注册的工具路由解析器。负责调用对应类型的解析函数。"""
|
||||
|
||||
def __init__(
|
||||
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
|
||||
|
||||
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)
|
||||
|
||||
|
||||
class ToolProviderManager:
|
||||
"""工具提供者的中心化管理器，采用单例模式。"""
|
||||
|
||||
_instance: "ToolProviderManager | None" = None
|
||||
|
||||
def __new__(cls) -> Self:
|
||||
if cls._instance is None:
|
||||
cls._instance = super().__new__(cls)
|
||||
return cast(Self, cls._instance)
|
||||
|
||||
def __init__(self):
|
||||
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._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] = {}
|
||||
|
||||
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(self, provider: ToolProvider):
|
||||
"""注册一个新的 ToolProvider。"""
|
||||
if provider not in self._providers:
|
||||
self._providers.append(provider)
|
||||
logger.debug(f"已注册工具提供者: {provider.__class__.__name__}")
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
async def initialize(self) -> None:
|
||||
"""懒加载初始化所有已注册的 ToolProvider。"""
|
||||
if not self._init_promise:
|
||||
async with self._init_lock:
|
||||
if not self._init_promise:
|
||||
self._init_promise = asyncio.create_task(
|
||||
self._initialize_providers()
|
||||
)
|
||||
await self._init_promise
|
||||
|
||||
async def _initialize_providers(self) -> None:
|
||||
"""并发初始化所有已注册的工具提供者。"""
|
||||
logger.info(f"开始初始化 {len(self._providers)} 个工具提供者...")
|
||||
init_tasks = [provider.initialize() for provider in self._providers]
|
||||
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,
|
||||
) -> 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 = {}
|
||||
for result_idx, provider_result in enumerate(results):
|
||||
provider = self._providers[provider_indices[result_idx]]
|
||||
provider_name = provider.__class__.__name__
|
||||
|
||||
if isinstance(provider_result, dict):
|
||||
logger.debug(
|
||||
f"提供者 '{provider_name}' 发现了 {len(provider_result)} 个工具。"
|
||||
)
|
||||
for name, executable in provider_result.items():
|
||||
if provider_tools.get(name):
|
||||
logger.warning(
|
||||
f"发现重复的工具名称 '{name}'，后发现的将覆盖前者。"
|
||||
)
|
||||
provider_tools[name] = executable
|
||||
elif isinstance(provider_result, Exception):
|
||||
logger.error(
|
||||
f"提供者 '{provider_name}' 在发现工具时出错: {provider_result}"
|
||||
)
|
||||
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()
|
||||
|
||||
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)
|
||||
|
||||
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
|
||||
)
|
||||
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,
|
||||
tool_definitions: Iterable[Any] | None,
|
||||
namespace: str | None = None,
|
||||
context: RunContext | None = None,
|
||||
) -> ResolvedToolPayload:
|
||||
"""
|
||||
统一解析工具配置，全面采用多态解析器与并发聚合管线。
|
||||
"""
|
||||
if not tool_definitions:
|
||||
return ResolvedToolPayload()
|
||||
|
||||
if not namespace:
|
||||
namespace = infer_plugin_namespace()
|
||||
logger.debug(
|
||||
f"🔍 [StringRouter] 自动推断当前调用者所在插件为: '{namespace}'"
|
||||
)
|
||||
|
||||
defs = []
|
||||
|
||||
def _flatten(items):
|
||||
for item in items:
|
||||
if isinstance(item, list):
|
||||
_flatten(item)
|
||||
else:
|
||||
defs.append(item)
|
||||
|
||||
_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]
|
||||
payloads = await asyncio.gather(*tasks, return_exceptions=False)
|
||||
|
||||
final_payload = ResolvedToolPayload()
|
||||
global_toolkit = BaseToolkit(prefix="")
|
||||
|
||||
for p in payloads:
|
||||
if not p:
|
||||
continue
|
||||
p = cast(ResolvedToolPayload, p)
|
||||
|
||||
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.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