mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-16 01:30:03 +08:00
♻️ refactor(tools): 重构工具装饰器系统并优化沙箱与文档注释 (#2147)
* ♻️ refactor(ai): 重构 AI 服务模块并完善文档注释 - 【重构】统一清理并优化所有 AI 服务模块文件的导入语句，将其移至文件顶部 - 【重构】重构 `hooks.py` 中的 `Hooks` 派发逻辑，使用通用管道函数消除重复代码，并引入 `HookPoint` 描述符 - 【重构】重构工具装饰器实现，新增 `toolkit` 类装饰器，优化 `BaseToolkit` 配置合并与前缀处理 - 【功能】Docker 沙箱容器创建时支持自动注入系统代理环境变量并配置 `ExtraHosts` - 【功能】Jupyter 服务启动前自动清理旧进程并初始化临时目录权限 - 【修复】优化 Pydantic 结构化输出校验失败时的错误信息提取，提供更详细的字段级错误反馈 - 【修复】在 `api.py` 中避免将 `ModelRetry` 和 `ControlFlowExit` 异常错误地包装为 `LLMException` - 【文档】为 AI 服务、沙箱、工具链、工作流等核心模块补充完整的 Docstring 和类型注释 * 📝 docs(ai): 补全核心模块文档注释并清理冗余代码 - 补全 `run/context`、`run/hooks` 和 `tools/engine/registry` 中类与方法的中文文档注释 - 清理 `tools/providers/builtin/sandbox` 中未使用的 `PythonPluginProtocol` 协议及相关导入 - 规范化部分代码的格式与尾随逗号 * ♻️ refactor!(flow): 重构 Task 为 AgentTask 并优化工作流元数据定义 - 【Breaking Change】将 `Task` 重命名为 `AgentTask` 以避免命名冲突 - 更新 Agent、Team、Workflow 等模块中的类型声明与相关逻辑 - 引入 `AutoNodeMeta` 强类型元数据，替换工作流装饰器中的裸字典定义 - 将 `StepMeta`、`ConditionMeta` 和 `RouterMeta` 统一移动至 `types.py` - 优化 `RunnableNode` 对上游 `AgentTask` 的处理与拼接逻辑 - 调整团队协作策略中 `FinishAction` 的返回值为完整结果对象 * ♻️ refactor(workflow): 移除人工确认机制并重构错误策略 - 移除工作流节点的人工确认（HITL）与挂起继续机制 - 删除 `auto` 自动化工作流及相关装饰器文件 - 将错误处理策略类从 `types.py` 拆分并移动到新文件 `policies.py` - 优化节点执行失败时的异常信息格式化输出 - 移除 `WorkflowRunResult` 和 `StepOutput` 中与挂起相关的状态字段 * 🚨 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
80fc5b86a7
commit
0b32d69c9c
@@ -13,6 +13,7 @@ from nonebot.adapters import Message as PlatformMessage
|
||||
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
from zhenxun.services.ai.core.exceptions import (
|
||||
ControlFlowExit,
|
||||
ToolFatalError,
|
||||
ToolRetryError,
|
||||
)
|
||||
@@ -24,11 +25,14 @@ from zhenxun.services.ai.core.stream_events import (
|
||||
ToolStreamChunkEvent,
|
||||
UserCustomEvent,
|
||||
)
|
||||
from zhenxun.services.ai.message_builder import MessageBuilder
|
||||
from zhenxun.services.ai.run.context import RunContext
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.tools.models import (
|
||||
StateSyncResult,
|
||||
ToolOptions,
|
||||
ToolResult,
|
||||
ToolResultChunk,
|
||||
ValidatedToolCall,
|
||||
)
|
||||
from zhenxun.services.log import logger
|
||||
@@ -144,8 +148,6 @@ class ToolExecutor:
|
||||
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
|
||||
@@ -256,8 +258,6 @@ class ToolExecutor:
|
||||
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
|
||||
|
||||
@@ -303,16 +303,12 @@ class ToolExecutor:
|
||||
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):
|
||||
@@ -394,8 +390,6 @@ class ToolExecutor:
|
||||
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):
|
||||
@@ -438,8 +432,6 @@ class ToolExecutionPolicy:
|
||||
"""
|
||||
计算当前工具的绝对最大重试次数。
|
||||
优先使用工具级配置 (ToolOptions.max_retries)，如果未设置，则使用全局配置。
|
||||
由于重试机制是保证 Agent 稳定性的防线，
|
||||
即使全局为 0，底层默认也会给予至少 1 次的机会。
|
||||
"""
|
||||
tool_retries = getattr(self.settings, "max_retries", None)
|
||||
if tool_retries is not None:
|
||||
@@ -496,8 +488,6 @@ class NativeToolRunner(ToolRunner):
|
||||
if isinstance(chunk, ToolResult):
|
||||
res = chunk
|
||||
else:
|
||||
from zhenxun.services.ai.tools.models import ToolResultChunk
|
||||
|
||||
chunk_obj = (
|
||||
chunk
|
||||
if isinstance(chunk, ToolResultChunk)
|
||||
@@ -525,8 +515,6 @@ class NativeToolRunner(ToolRunner):
|
||||
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)
|
||||
|
||||
@@ -26,6 +26,7 @@ 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()
|
||||
@@ -79,9 +80,11 @@ class ToolCollection(list[T], Generic[T]):
|
||||
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()]
|
||||
@@ -95,16 +98,19 @@ class ToolCollection(list[T], Generic[T]):
|
||||
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:
|
||||
@@ -112,6 +118,7 @@ class ToolCollection(list[T], Generic[T]):
|
||||
return tool
|
||||
|
||||
def filter_by_names(self, names: list[str] | None = None) -> "ToolCollection[T]":
|
||||
"""根据名称列表筛选并返回新的工具子集合。"""
|
||||
if names is None:
|
||||
return self
|
||||
return ToolCollection(
|
||||
@@ -123,16 +130,20 @@ class ToolCollection(list[T], Generic[T]):
|
||||
)
|
||||
|
||||
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()
|
||||
|
||||
|
||||
@@ -145,11 +156,13 @@ class _StringResolver:
|
||||
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 = (
|
||||
@@ -192,11 +205,13 @@ class _QueryResolver:
|
||||
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 = []
|
||||
|
||||
@@ -235,10 +250,12 @@ class _CallableResolver:
|
||||
"""
|
||||
|
||||
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),
|
||||
@@ -263,12 +280,14 @@ class _TypeAdapterResolver:
|
||||
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)
|
||||
@@ -285,11 +304,13 @@ 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
|
||||
|
||||
@@ -304,11 +325,13 @@ class ToolProviderManager:
|
||||
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):
|
||||
@@ -445,6 +468,7 @@ class ToolProviderManager:
|
||||
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
|
||||
@@ -462,11 +486,13 @@ class ToolProviderManager:
|
||||
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:
|
||||
|
||||
Reference in New Issue
Block a user