mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-14 00:20:06 +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,3 @@
|
||||
from .runtime import ContextUtils, PermissionUtils
|
||||
|
||||
__all__ = ["ContextUtils", "PermissionUtils"]
|
||||
@@ -0,0 +1,166 @@
|
||||
from typing import Any
|
||||
|
||||
from nonebot.adapters import Bot, Event
|
||||
|
||||
from zhenxun.services.ai.utils.scope import ScopeBuilder
|
||||
|
||||
|
||||
class ContextUtils:
|
||||
"""
|
||||
从底层依赖容器 (deps) 中提取运行环境信息的纯静态工具类。
|
||||
|
||||
"""
|
||||
|
||||
@staticmethod
|
||||
def extract_user_id(deps: Any) -> str | None:
|
||||
if not deps:
|
||||
return None
|
||||
if hasattr(deps, "user_id") and getattr(deps, "user_id") is not None:
|
||||
return str(getattr(deps, "user_id"))
|
||||
event = getattr(deps, "event", None)
|
||||
if event:
|
||||
try:
|
||||
return str(event.get_user_id())
|
||||
except Exception:
|
||||
return (
|
||||
str(getattr(event, "user_id", ""))
|
||||
or str(getattr(event, "sender_id", ""))
|
||||
or None
|
||||
)
|
||||
return None
|
||||
|
||||
@staticmethod
|
||||
def extract_group_id(deps: Any) -> str | None:
|
||||
if not deps:
|
||||
return None
|
||||
if hasattr(deps, "group_id") and getattr(deps, "group_id") is not None:
|
||||
return str(getattr(deps, "group_id"))
|
||||
event = getattr(deps, "event", None)
|
||||
if event:
|
||||
return str(getattr(event, "group_id", "")) or None
|
||||
return None
|
||||
|
||||
@staticmethod
|
||||
def extract_platform(deps: Any) -> str:
|
||||
if not deps:
|
||||
return "unknown"
|
||||
if hasattr(deps, "platform") and getattr(deps, "platform") is not None:
|
||||
return str(getattr(deps, "platform"))
|
||||
bot = getattr(deps, "bot", None)
|
||||
if bot:
|
||||
from zhenxun.utils.platform import PlatformUtils
|
||||
|
||||
return PlatformUtils.get_platform(bot)
|
||||
return "unknown"
|
||||
|
||||
@staticmethod
|
||||
def extract_concurrency_lock_id(
|
||||
context: Any, scope: Any, default_session_id: str
|
||||
) -> str:
|
||||
from zhenxun.services.ai.flow.base import ConcurrencyScope
|
||||
|
||||
scope = scope or ConcurrencyScope.GROUP
|
||||
|
||||
ns = getattr(getattr(context, "session", None), "namespace", "global")
|
||||
ns_suffix = f"_{ns}" if ns and ns != "global" else ""
|
||||
|
||||
if scope == ConcurrencyScope.GLOBAL:
|
||||
return f"lock_global{ns_suffix}"
|
||||
elif scope == ConcurrencyScope.GROUP:
|
||||
gid = ContextUtils.extract_group_id(getattr(context, "deps", None))
|
||||
uid = ContextUtils.extract_user_id(getattr(context, "deps", None))
|
||||
return (
|
||||
f"lock_group_{gid}{ns_suffix}" if gid else f"lock_user_{uid}{ns_suffix}"
|
||||
)
|
||||
elif scope == ConcurrencyScope.USER:
|
||||
uid = ContextUtils.extract_user_id(getattr(context, "deps", None))
|
||||
return (
|
||||
f"lock_user_{uid}{ns_suffix}"
|
||||
if uid
|
||||
else f"lock_default_user{ns_suffix}"
|
||||
)
|
||||
else:
|
||||
return f"lock_session_{default_session_id}"
|
||||
|
||||
@staticmethod
|
||||
def generate_session_meta(
|
||||
bot: Bot,
|
||||
event: Event,
|
||||
scope_builder: ScopeBuilder | None = None,
|
||||
prefix: str = "",
|
||||
namespace: str | None = None,
|
||||
agent_name: str | None = None,
|
||||
) -> Any:
|
||||
"""根据事件和隔离级别，自动提取生成基于路径作用域的 SessionMetadata"""
|
||||
from zhenxun.services.ai.context.memory.types import (
|
||||
Isolation,
|
||||
SessionMetadata,
|
||||
)
|
||||
from zhenxun.services.ai.run.context import NoneBotDeps
|
||||
|
||||
if scope_builder is None:
|
||||
scope_builder = Isolation.AGENT_USER()
|
||||
|
||||
deps = NoneBotDeps(bot=bot, event=event)
|
||||
selector = scope_builder.resolve(
|
||||
deps=deps,
|
||||
prefix=prefix,
|
||||
default_namespace=namespace,
|
||||
default_agent=agent_name,
|
||||
)
|
||||
|
||||
parts = selector.get_scope_parts()
|
||||
session_id = selector.scope_prefix
|
||||
scope_prefix = selector.scope_prefix
|
||||
|
||||
all_scopes = {"/"}
|
||||
current_path = ""
|
||||
for part in parts:
|
||||
current_path += f"/{part}"
|
||||
all_scopes.add(current_path)
|
||||
|
||||
accessible_scopes = list(all_scopes)
|
||||
accessible_scopes.sort(key=lambda x: len(x.split("/")))
|
||||
|
||||
return SessionMetadata(
|
||||
session_id=session_id,
|
||||
scope_prefix=scope_prefix,
|
||||
accessible_scopes=accessible_scopes,
|
||||
selector=selector,
|
||||
isolation_level=scope_builder,
|
||||
)
|
||||
|
||||
|
||||
class PermissionUtils:
|
||||
"""运行时权限校验通用工具类"""
|
||||
|
||||
@staticmethod
|
||||
async def check_superuser(context: Any) -> bool:
|
||||
bot = context.get_bot()
|
||||
event = context.get_event()
|
||||
if bot and event:
|
||||
from nonebot.permission import SUPERUSER
|
||||
|
||||
return await SUPERUSER(bot, event)
|
||||
return False
|
||||
|
||||
@staticmethod
|
||||
async def check_admin_level(context: Any, min_level: int) -> bool:
|
||||
if await PermissionUtils.check_superuser(context):
|
||||
return True
|
||||
|
||||
user_id = context.get_user_id()
|
||||
group_id = context.get_group_id()
|
||||
if not user_id:
|
||||
return False
|
||||
|
||||
from zhenxun.services.cache.runtime_cache import LevelUserMemoryCache
|
||||
|
||||
global_user, group_users = await LevelUserMemoryCache.get_levels(
|
||||
user_id, group_id
|
||||
)
|
||||
user_level = global_user.user_level if global_user else 0
|
||||
if group_id and group_users:
|
||||
user_level = max(user_level, group_users.user_level)
|
||||
|
||||
return user_level >= min_level
|
||||
@@ -0,0 +1,226 @@
|
||||
from collections.abc import Callable
|
||||
import re
|
||||
from typing import Any, Generic, TypeVar
|
||||
from typing_extensions import Self
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class ScopeSelector(BaseModel):
|
||||
"""领域驱动：统一的作用域与实体资源选择器"""
|
||||
|
||||
base_prefix: str | None = None
|
||||
"""基础路径前缀。"""
|
||||
session_id: str | None = None
|
||||
"""特定的会话 ID，如指定则绕过前缀拼接，直接作为统一路径。"""
|
||||
platform: str | None = None
|
||||
"""目标平台标识（如 'qq'）。"""
|
||||
group_id: str | None = None
|
||||
"""目标群组 ID。"""
|
||||
user_id: str | None = None
|
||||
"""目标用户 ID。"""
|
||||
namespace: str | None = None
|
||||
"""插件命名空间标识。"""
|
||||
agent_name: str | None = None
|
||||
"""具体智能体标识。"""
|
||||
bot_id: str | None = None
|
||||
"""触发环境的 Bot ID。"""
|
||||
custom_dimensions: dict[str, str] = Field(default_factory=dict)
|
||||
"""动态的自定义隔离维度字典。"""
|
||||
|
||||
def get_scope_parts(self) -> list[str]:
|
||||
"""获取标准化的路径分段"""
|
||||
parts = []
|
||||
if self.base_prefix:
|
||||
clean = self.base_prefix.strip("/")
|
||||
if clean:
|
||||
parts.append(clean)
|
||||
if self.platform:
|
||||
parts.append(f"p_{self.platform}")
|
||||
if self.bot_id:
|
||||
parts.append(f"b_{self.bot_id}")
|
||||
if self.group_id:
|
||||
parts.append(f"g_{self.group_id}")
|
||||
if self.user_id:
|
||||
parts.append(f"u_{self.user_id}")
|
||||
if self.namespace:
|
||||
parts.append(f"ns_{self.namespace}")
|
||||
if self.agent_name:
|
||||
parts.append(f"ag_{self.agent_name}")
|
||||
for k, v in self.custom_dimensions.items():
|
||||
parts.append(f"{k}_{v}")
|
||||
return parts
|
||||
|
||||
@property
|
||||
def scope_prefix(self) -> str:
|
||||
"""统一的路径生成逻辑"""
|
||||
if self.session_id:
|
||||
return self.session_id
|
||||
parts = self.get_scope_parts()
|
||||
return "/" + "/".join(parts) if parts else "/"
|
||||
|
||||
|
||||
T_Builder = TypeVar("T_Builder", bound="BaseScopeBuilder")
|
||||
|
||||
|
||||
class BaseScopeBuilder(Generic[T_Builder]):
|
||||
"""
|
||||
泛型化作用域构建器基类 (Fluent Builder)。
|
||||
为继承 of 子类提供极简的链式调用 API，用于快速指定平台、群组、用户等。
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
self._selector = ScopeSelector()
|
||||
|
||||
def bot(self, b: str) -> Self:
|
||||
"""指定目标 Bot ID"""
|
||||
self._selector.bot_id = b
|
||||
return self
|
||||
|
||||
def platform(self, p: str) -> Self:
|
||||
"""指定目标平台标识 (如 'qq')"""
|
||||
self._selector.platform = p
|
||||
return self
|
||||
|
||||
def group(self, g: str) -> Self:
|
||||
"""指定目标群组 ID"""
|
||||
self._selector.group_id = g
|
||||
return self
|
||||
|
||||
def user(self, u: str) -> Self:
|
||||
"""指定目标用户 ID"""
|
||||
self._selector.user_id = u
|
||||
return self
|
||||
|
||||
def namespace(self, ns: str) -> Self:
|
||||
"""指定插件命名空间 (如 'rpg_game')"""
|
||||
self._selector.namespace = ns
|
||||
return self
|
||||
|
||||
def agent(self, a: str) -> Self:
|
||||
"""指定具体的 Agent 智能体名称"""
|
||||
self._selector.agent_name = a
|
||||
return self
|
||||
|
||||
def session(self, sid: str) -> Self:
|
||||
"""直接指定完整的 Session ID 绕过前缀拼接"""
|
||||
self._selector.session_id = sid
|
||||
return self
|
||||
|
||||
def current(self, bot: Any = None, event: Any = None) -> Self:
|
||||
"""自动提取当前触发上下文的特征，匹配当前用户/群组"""
|
||||
from zhenxun.services.ai.run.context import NoneBotDeps
|
||||
from zhenxun.services.ai.utils.runtime import ContextUtils
|
||||
|
||||
deps = (
|
||||
NoneBotDeps(bot=bot, event=event)
|
||||
if bot and event
|
||||
else NoneBotDeps.get_current()
|
||||
)
|
||||
if deps:
|
||||
self._selector.platform = ContextUtils.extract_platform(deps)
|
||||
bot_inst = getattr(deps, "bot", None)
|
||||
if bot_inst and hasattr(bot_inst, "self_id"):
|
||||
self._selector.bot_id = str(bot_inst.self_id)
|
||||
self._selector.group_id = ContextUtils.extract_group_id(deps)
|
||||
self._selector.user_id = ContextUtils.extract_user_id(deps)
|
||||
return self
|
||||
|
||||
|
||||
def normalize_scope_path(path: str) -> str:
|
||||
"""标准化作用域路径，消除多余的斜杠并确保以 / 开头"""
|
||||
if not path or path == "/":
|
||||
return "/"
|
||||
path = re.sub(r"/+", "/", path)
|
||||
if not path.startswith("/"):
|
||||
path = "/" + path
|
||||
if len(path) > 1:
|
||||
path = path.rstrip("/")
|
||||
return path
|
||||
|
||||
|
||||
class ScopeBuilder:
|
||||
"""流式作用域声明构建器，用于在顶层配置并在底层延迟提取具体的维度值"""
|
||||
|
||||
def __init__(self):
|
||||
"""初始化作用域声明构建器。"""
|
||||
self._dims: set[str] = set()
|
||||
self._customs: dict[str, Callable[[Any], str | None]] = {}
|
||||
|
||||
def bot(self) -> Self:
|
||||
"""声明隔离维度包含 Bot ID。"""
|
||||
self._dims.add("bot")
|
||||
return self
|
||||
|
||||
def platform(self) -> Self:
|
||||
"""声明隔离维度包含平台类型。"""
|
||||
self._dims.add("platform")
|
||||
return self
|
||||
|
||||
def group(self) -> Self:
|
||||
"""声明隔离维度包含群组 ID。"""
|
||||
self._dims.add("group")
|
||||
return self
|
||||
|
||||
def user(self) -> Self:
|
||||
"""声明隔离维度包含用户 ID。"""
|
||||
self._dims.add("user")
|
||||
return self
|
||||
|
||||
def namespace(self) -> Self:
|
||||
"""声明隔离维度包含插件命名空间。"""
|
||||
self._dims.add("namespace")
|
||||
return self
|
||||
|
||||
def agent(self) -> Self:
|
||||
"""声明隔离维度包含智能体名称。"""
|
||||
self._dims.add("agent")
|
||||
return self
|
||||
|
||||
def custom(
|
||||
self, key: str, value_extractor: str | Callable[[Any], str | None]
|
||||
) -> Self:
|
||||
"""声明自定义的隔离维度及值提取器。"""
|
||||
if isinstance(value_extractor, str):
|
||||
self._customs[key] = lambda _: value_extractor
|
||||
else:
|
||||
self._customs[key] = value_extractor
|
||||
return self
|
||||
|
||||
def resolve(
|
||||
self,
|
||||
deps: Any,
|
||||
prefix: str = "",
|
||||
default_namespace: str | None = None,
|
||||
default_agent: str | None = None,
|
||||
) -> ScopeSelector:
|
||||
"""解析当前上下文依赖并生成作用域选择器实例。"""
|
||||
from zhenxun.services.ai.utils.runtime import ContextUtils
|
||||
from zhenxun.utils.utils import infer_plugin_namespace
|
||||
|
||||
selector = ScopeSelector(base_prefix=prefix)
|
||||
if "platform" in self._dims:
|
||||
selector.platform = ContextUtils.extract_platform(deps)
|
||||
if "bot" in self._dims:
|
||||
bot_inst = getattr(deps, "bot", None)
|
||||
if bot_inst and hasattr(bot_inst, "self_id"):
|
||||
selector.bot_id = str(bot_inst.self_id)
|
||||
if "group" in self._dims:
|
||||
selector.group_id = ContextUtils.extract_group_id(deps)
|
||||
if "user" in self._dims:
|
||||
selector.user_id = ContextUtils.extract_user_id(deps)
|
||||
if "namespace" in self._dims:
|
||||
selector.namespace = (
|
||||
default_namespace
|
||||
or getattr(deps, "namespace", None)
|
||||
or infer_plugin_namespace(default="global")
|
||||
)
|
||||
if "agent" in self._dims:
|
||||
selector.agent_name = default_agent
|
||||
|
||||
for k, extractor in self._customs.items():
|
||||
val = extractor(deps)
|
||||
if val is not None:
|
||||
selector.custom_dimensions[k] = str(val)
|
||||
|
||||
return selector
|
||||
@@ -0,0 +1,57 @@
|
||||
import asyncio
|
||||
from collections.abc import Callable
|
||||
import functools
|
||||
import inspect
|
||||
import threading
|
||||
|
||||
|
||||
def wrap_to_async(func: Callable) -> Callable:
|
||||
"""
|
||||
将任意类型的函数（同步、异步、同步生成器、异步生成器）统一包装为异步执行形态。
|
||||
确保不会阻塞主线程，并保留原函数的元数据和签名。
|
||||
"""
|
||||
if getattr(func, "__is_async_wrapper__", False):
|
||||
return func
|
||||
|
||||
if inspect.isasyncgenfunction(func) or inspect.iscoroutinefunction(func):
|
||||
return func
|
||||
|
||||
if inspect.isgeneratorfunction(func):
|
||||
|
||||
async def async_gen_wrapper(*args, **kwargs):
|
||||
loop = asyncio.get_running_loop()
|
||||
q = asyncio.Queue()
|
||||
_sentinel = object()
|
||||
|
||||
def _sync_runner():
|
||||
try:
|
||||
for item in func(*args, **kwargs):
|
||||
asyncio.run_coroutine_threadsafe(q.put(item), loop).result()
|
||||
asyncio.run_coroutine_threadsafe(q.put(_sentinel), loop).result()
|
||||
except Exception as e:
|
||||
asyncio.run_coroutine_threadsafe(q.put(e), loop).result()
|
||||
|
||||
t = threading.Thread(target=_sync_runner)
|
||||
t.start()
|
||||
|
||||
while True:
|
||||
item = await q.get()
|
||||
if item is _sentinel:
|
||||
break
|
||||
if isinstance(item, Exception):
|
||||
raise item
|
||||
yield item
|
||||
|
||||
functools.update_wrapper(async_gen_wrapper, func)
|
||||
setattr(async_gen_wrapper, "__is_async_wrapper__", True)
|
||||
setattr(async_gen_wrapper, "_is_async_gen", True)
|
||||
return async_gen_wrapper
|
||||
|
||||
async def async_wrapper(*args, **kwargs):
|
||||
p_func = functools.partial(func, *args, **kwargs)
|
||||
return await asyncio.to_thread(p_func)
|
||||
|
||||
functools.update_wrapper(async_wrapper, func)
|
||||
setattr(async_wrapper, "__is_async_wrapper__", True)
|
||||
setattr(async_wrapper, "_is_coroutine", True)
|
||||
return async_wrapper
|
||||
Reference in New Issue
Block a user