✨ 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>
2026-10-07 04:40:00 +08:00 · 2026-07-03 08:53:56 +08:00
parent bdc1374848
commit 80fc5b86a7
223 changed files with 41885 additions and 10006 deletions
@@ -0,0 +1,181 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+import heapq
+import time
+from typing import Any
+
+from nonebot.utils import is_coroutine_callable
+
+from zhenxun.services.log import logger
+
+
+class LifespanManager:
+    """
+    高精度资源生命周期调度器
+    """
+
+    def __init__(self):
+        self._resources: dict[
+            Any,
+            tuple[
+                float,
+                float,
+                Callable[[Any], Awaitable[Any] | Any],
+                Callable[[], Awaitable[bool] | bool] | None,
+            ],
+        ] = {}
+        self._heap: list[tuple[float, Any]] = []
+        self._lock = asyncio.Lock()
+        self._wakeup_event = asyncio.Event()
+        self._watchdog_task: asyncio.Task | None = None
+
+    def _ensure_watchdog(self):
+        """确保后台看门狗任务正在运行"""
+        if self._watchdog_task is None or self._watchdog_task.done():
+            self._watchdog_task = asyncio.create_task(self._watchdog_loop())
+
+    async def register(
+        self,
+        resource_id: Any,
+        ttl: float,
+        cleanup_callback: Callable,
+        is_busy_callback: Callable[[], Awaitable[bool] | bool] | None = None,
+    ):
+        """
+        将资源注册到生命周期管理器中。
+
+        参数:
+            resource_id: 资源的唯一标识符 (可以是字符串、数字或其他 Hashable 对象)。
+            ttl: 资源的存活时间 (秒)。
+            cleanup_callback: 资源过期时触发的回调函数，接收 resource_id 作为唯一参数。
+            is_busy_callback: (可选) 延迟存活探针。在触发清理前调用，若返回 True 则放弃清理并自动续期。
+        """  # noqa: E501
+        if ttl <= 0:
+            await self.unregister(resource_id)
+            return
+        async with self._lock:
+            expire_time = time.time() + ttl
+            self._resources[resource_id] = (
+                expire_time,
+                ttl,
+                cleanup_callback,
+                is_busy_callback,
+            )
+            heapq.heappush(self._heap, (expire_time, resource_id))
+            self._wakeup_event.set()
+
+        self._ensure_watchdog()
+
+    async def touch(self, resource_id: Any, ttl: float):
+        """刷新资源的存活时间，为其续命"""
+        if ttl <= 0:
+            await self.unregister(resource_id)
+            return
+        async with self._lock:
+            if resource_id in self._resources:
+                _, original_ttl, cb, is_busy = self._resources[resource_id]
+                expire_time = time.time() + ttl
+                self._resources[resource_id] = (expire_time, original_ttl, cb, is_busy)
+                heapq.heappush(self._heap, (expire_time, resource_id))
+                self._wakeup_event.set()
+
+    async def unregister(self, resource_id: Any):
+        """主动从管理器中注销资源 (不再触发超时回收)"""
+        async with self._lock:
+            self._resources.pop(resource_id, None)
+
+    async def _watchdog_loop(self):
+        """核心看门狗循环"""
+        try:
+            while True:
+                await self._wakeup_event.wait()
+                self._wakeup_event.clear()
+
+                while True:
+                    async with self._lock:
+                        if not self._heap:
+                            break
+                        expire_time, res_id = self._heap[0]
+
+                        if (
+                            res_id not in self._resources
+                            or self._resources[res_id][0] != expire_time
+                        ):
+                            heapq.heappop(self._heap)
+                            continue
+
+                    now = time.time()
+                    sleep_time = expire_time - now
+
+                    if sleep_time > 0:
+                        try:
+                            await asyncio.wait_for(
+                                self._wakeup_event.wait(), timeout=sleep_time
+                            )
+                            self._wakeup_event.clear()
+                            continue
+                        except asyncio.TimeoutError:
+                            pass
+
+                    async with self._lock:
+                        if (
+                            res_id not in self._resources
+                            or self._resources[res_id][0] != expire_time
+                        ):
+                            continue
+                        _, original_ttl, cb, is_busy = self._resources[res_id]
+
+                    is_active = False
+                    if is_busy is not None:
+                        try:
+                            res = is_busy()
+                            if isinstance(res, Awaitable):
+                                is_active = await res
+                            else:
+                                is_active = res
+                        except Exception as e:
+                            logger.error(
+                                f"执行资源存活探针失败: {e}", command="LifespanManager"
+                            )
+
+                    if is_active:
+                        logger.debug(
+                            f"探针检测到资源 '{res_id}' 仍在忙碌，"
+                            f"已自动续期 ({original_ttl}s)。",
+                            command="LifespanManager",
+                        )
+                        await self.touch(res_id, original_ttl)
+                        continue
+
+                    async with self._lock:
+                        if (
+                            res_id in self._resources
+                            and self._resources[res_id][0] == expire_time
+                        ):
+                            self._resources.pop(res_id)
+                            heapq.heappop(self._heap)
+                        else:
+                            continue
+
+                    logger.info(
+                        f"♻️ 资源 '{res_id}' 闲置超时，触发自动回收。",
+                        command="LifespanManager",
+                    )
+                    try:
+                        if is_coroutine_callable(cb):
+                            await cb(res_id)
+                        else:
+                            cb(res_id)
+                    except Exception as e:
+                        logger.error(
+                            f"回收资源 '{res_id}' 时发生业务异常: {e}",
+                            command="LifespanManager",
+                        )
+
+        except asyncio.CancelledError:
+            pass
+
+    async def stop(self):
+        """停止生命周期管理器"""
+        if self._watchdog_task:
+            self._watchdog_task.cancel()
@@ -15,8 +15,6 @@ def _truncate_base64_string(value: str, threshold: int = 256) -> str:
        prefix = next((p for p in prefixes if value.startswith(p)), "base64")
        return f"[{prefix}_data_omitted_len={len(value)}]"

-    # 清理嵌入在普通文本中的超长 base64/data URI，
-    # 例如: "声音 -> base64://AAAA..."
    embedded_patterns = (
        (re.compile(r"base64://[A-Za-z0-9+/=\s]{80,}"), "base64"),
        (
@@ -31,12 +29,6 @@ def _truncate_base64_string(value: str, threshold: int = 256) -> str:
                value,
            )

-    if len(value) > 1000:
-        return f"[long_string_omitted_len={len(value)}] {value[:20]}...{value[-20:]}"
-
-    if len(value) > 2000:
-        return f"[long_string_omitted_len={len(value)}] {value[:50]}...{value[-20:]}"
-
    return value


@@ -50,10 +42,26 @@ def _truncate_vector_list(vector: list, threshold: int = 10) -> list:
 def _recursive_sanitize_any(obj: Any) -> Any:
    """递归清洗任何对象中的长字符串"""
    if isinstance(obj, dict):
-        return {k: _recursive_sanitize_any(v) for k, v in obj.items()}
+        sanitized_dict = {}
+        for k, v in obj.items():
+            if (
+                k in ("data", "b64_json", "inlineData", "image_base64", "b64_data")
+                and isinstance(v, str)
+                and len(v) > 512
+            ):
+                sanitized_dict[k] = f"[raw_base64_data_omitted_key={k}_len={len(v)}]"
+            else:
+                sanitized_dict[k] = _recursive_sanitize_any(v)
+        return sanitized_dict
    elif isinstance(obj, list):
        return [_recursive_sanitize_any(v) for v in obj]
    elif isinstance(obj, str):
+        if len(obj) > 2048 and set(obj).issubset(
+            set(
+                "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=\r\n\t"
+            )
+        ):
+            return f"[heuristic_base64_omitted_len={len(obj)}]"
        return _truncate_base64_string(obj)
    return obj

@@ -114,10 +122,47 @@ def _sanitize_nonebot_message(message: Message) -> Message:

 def _sanitize_openai_response(response_json: dict) -> dict:
    """净化OpenAI兼容API的响应体。"""
+    from zhenxun.services.ai.config import (
+        DebugLogOptions,
+        get_llm_config,
+    )
+
+    debug_conf = get_llm_config().debug_log
+    if isinstance(debug_conf, bool):
+        debug_conf = DebugLogOptions(
+            show_tools=debug_conf, show_schema=debug_conf, show_safety=debug_conf
+        )
+
    try:
-        sanitized_json = copy.deepcopy(response_json)
+        sanitized_json = _recursive_sanitize_any(copy.deepcopy(response_json))
+
+        if "tools" in sanitized_json and not debug_conf.show_tools:
+            tools = sanitized_json["tools"]
+            if isinstance(tools, list):
+                tool_names = []
+                for t in tools:
+                    if isinstance(t, dict):
+                        name = None
+                        if "function" in t and isinstance(t["function"], dict):
+                            name = t["function"].get("name")
+                        if not name and "name" in t:
+                            name = t.get("name")
+                        if not name and "type" in t:
+                            name = t.get("type")
+                        tool_names.append(name or "unknown")
+                sanitized_json["tools"] = (
+                    f"<{len(tool_names)} tools hidden: {', '.join(tool_names)}>"
+                )
+
+        if not debug_conf.show_safety:
+            for safety_key in ("content_filters", "prompt_annotations"):
+                if safety_key in sanitized_json:
+                    sanitized_json[safety_key] = "<Safety Ratings Hidden>"
+
        if "choices" in sanitized_json and isinstance(sanitized_json["choices"], list):
            for choice in sanitized_json["choices"]:
+                if not debug_conf.show_safety and "content_filter_results" in choice:
+                    choice["content_filter_results"] = "<Safety Ratings Hidden>"
                if "message" in choice and isinstance(choice["message"], dict):
                    message = choice["message"]
                    if "images" in message and isinstance(message["images"], list):
@@ -160,6 +205,14 @@ def _sanitize_openai_response(response_json: dict) -> dict:
                            image_url = part.get("image_url")
                            if isinstance(image_url, str):
                                part["image_url"] = _truncate_base64_string(image_url)
+        if "output" in sanitized_json and isinstance(sanitized_json["output"], list):
+            for item in sanitized_json["output"]:
+                if isinstance(item, dict) and "encrypted_content" in item:
+                    content_val = item["encrypted_content"]
+                    if isinstance(content_val, str) and len(content_val) > 64:
+                        item["encrypted_content"] = (
+                            f"[encrypted_content_omitted_len={len(content_val)}]"
+                        )
        return sanitized_json
    except Exception:
        return response_json
@@ -167,7 +220,7 @@ def _sanitize_openai_response(response_json: dict) -> dict:

 def _sanitize_openai_request(body: dict) -> dict:
    """净化OpenAI兼容API的请求体，主要截断图片base64。"""
-    from zhenxun.services.llm.config.providers import (
+    from zhenxun.services.ai.config import (
        DebugLogOptions,
        get_llm_config,
    )
@@ -191,6 +244,8 @@ def _sanitize_openai_request(body: dict) -> dict:
                            name = t["function"].get("name")
                        if not name and "name" in t:
                            name = t.get("name")
+                        if not name and "type" in t:
+                            name = t.get("type")
                        tool_names.append(name or "unknown")
                sanitized_json["tools"] = (
                    f"<{len(tool_names)} tools hidden: {', '.join(tool_names)}>"
@@ -212,11 +267,26 @@ def _sanitize_openai_request(body: dict) -> dict:

 def _sanitize_gemini_response(response_json: dict) -> dict:
    """净化Gemini API的响应体，处理文本和图片生成两种格式。"""
-    from zhenxun.services.llm.config.providers import get_llm_config
+    from zhenxun.services.ai.config import (
+        DebugLogOptions,
+        get_llm_config,
+    )
+
+    debug_conf = get_llm_config().debug_log
+    if isinstance(debug_conf, bool):
+        debug_conf = DebugLogOptions(
+            show_tools=debug_conf, show_schema=debug_conf, show_safety=debug_conf
+        )

-    debug_mode = get_llm_config().debug_log
    try:
-        sanitized_json = copy.deepcopy(response_json)
+        sanitized_json = _recursive_sanitize_any(copy.deepcopy(response_json))
+
+        if "thoughtSignature" in sanitized_json:
+            sig = sanitized_json["thoughtSignature"]
+            if isinstance(sig, str) and len(sig) > 64:
+                sanitized_json["thoughtSignature"] = (
+                    f"[signature_omitted_len={len(sig)}]"
+                )

        def _process_candidates(candidates_list: list):
            """辅助函数，用于处理任何 candidates 列表。"""
@@ -235,13 +305,21 @@ def _sanitize_gemini_response(response_json: dict) -> dict:
                                    content["parts"][i]["inlineData"]["data"] = (
                                        f"[base64_data_omitted_len={len(data)}]"
                                    )
-                            if "thoughtSignature" in part:
-                                signature = part.get("thoughtSignature", "")
-                                if isinstance(signature, str) and len(signature) > 256:
-                                    content["parts"][i]["thoughtSignature"] = (
+                            if (
+                                "thoughtSignature" in part
+                                or "thought_signature" in part
+                            ):
+                                sig_key = (
+                                    "thoughtSignature"
+                                    if "thoughtSignature" in part
+                                    else "thought_signature"
+                                )
+                                signature = part.get(sig_key, "")
+                                if isinstance(signature, str) and len(signature) > 64:
+                                    content["parts"][i][sig_key] = (
                                        f"[signature_omitted_len={len(signature)}]"
                                    )
-                if not debug_mode and isinstance(candidate, dict):
+                if not debug_conf.show_safety and isinstance(candidate, dict):
                    if "safetyRatings" in candidate:
                        candidate["safetyRatings"] = "<Safety Ratings Hidden>"

@@ -261,7 +339,7 @@ def _sanitize_gemini_response(response_json: dict) -> dict:
                if "values" in embedding and isinstance(embedding["values"], list):
                    embedding["values"] = _truncate_vector_list(embedding["values"])

-        if not debug_mode and "promptFeedback" in sanitized_json:
+        if not debug_conf.show_safety and "promptFeedback" in sanitized_json:
            prompt_feedback = sanitized_json.get("promptFeedback") or {}
            if isinstance(prompt_feedback, dict) and "safetyRatings" in prompt_feedback:
                prompt_feedback["safetyRatings"] = "<Safety Ratings Hidden>"
@@ -274,7 +352,7 @@ def _sanitize_gemini_response(response_json: dict) -> dict:

 def _sanitize_gemini_request(body: dict) -> dict:
    """净化Gemini API的请求体，进行结构转换和总结。"""
-    from zhenxun.services.llm.config.providers import (
+    from zhenxun.services.ai.config import (
        DebugLogOptions,
        get_llm_config,
    )
@@ -286,21 +364,20 @@ def _sanitize_gemini_request(body: dict) -> dict:
        )

    try:
-        sanitized_body = copy.deepcopy(body)
+        sanitized_body = _recursive_sanitize_any(copy.deepcopy(body))
        if "tools" in sanitized_body and not debug_conf.show_tools:
-            tool_summary = []
+            tool_names = []
            for tool_group in sanitized_body["tools"]:
-                if (
-                    isinstance(tool_group, dict)
-                    and "functionDeclarations" in tool_group
-                ):
-                    declarations = tool_group["functionDeclarations"]
-                    if isinstance(declarations, list):
-                        for func in declarations:
-                            if isinstance(func, dict):
-                                tool_summary.append(func.get("name", "unknown"))
+                if isinstance(tool_group, dict):
+                    for key, value in tool_group.items():
+                        if key == "functionDeclarations" and isinstance(value, list):
+                            for func in value:
+                                if isinstance(func, dict):
+                                    tool_names.append(func.get("name", "unknown"))
+                        else:
+                            tool_names.append(key)
            sanitized_body["tools"] = (
-                f"<{len(tool_summary)} functions hidden: {', '.join(tool_summary)}>"
+                f"<{len(tool_names)} tools hidden: {', '.join(tool_names)}>"
            )

        if not debug_conf.show_safety and "safetySettings" in sanitized_body:
@@ -319,7 +396,6 @@ def _sanitize_gemini_request(body: dict) -> dict:
        ):
            for content_item in sanitized_body["contents"]:
                if "parts" in content_item and isinstance(content_item["parts"], list):
-                    media_summary = []
                    new_parts = []
                    for part in content_item["parts"]:
                        if "inlineData" in part and isinstance(
@@ -330,7 +406,9 @@ def _sanitize_gemini_request(body: dict) -> dict:
                                mime_type = part["inlineData"].get(
                                    "mimeType", "unknown"
                                )
-                                media_summary.append(f"{mime_type} ({len(data)} chars)")
+                                new_parts.append(
+                                    {"text": f"[多模态图片/文件: {mime_type}]"}
+                                )
                                continue
                        new_parts.append(part)

@@ -341,13 +419,6 @@ def _sanitize_gemini_request(body: dict) -> dict:
                                    f"[signature_omitted_len={len(sig)}]"
                                )

-                    if media_summary:
-                        summary_text = (
-                            f"[多模态内容: {len(media_summary)}个文件 - "
-                            f"{', '.join(media_summary)}]"
-                        )
-                        new_parts.insert(0, {"text": summary_text})
-
                    content_item["parts"] = new_parts
        return sanitized_body
    except Exception:
@@ -368,7 +439,7 @@ def sanitize_for_logging(data: Any, context: str | None = None) -> Any:
    if context == "nonebot_message":
        if isinstance(data, Message):
            return _sanitize_nonebot_message(data)
-    elif context == "openai_response":
+    elif context in ("openai_response", "openai_responses_response"):
        if isinstance(data, dict):
            return _sanitize_openai_response(data)
    elif context == "gemini_response":
@@ -377,7 +448,7 @@ def sanitize_for_logging(data: Any, context: str | None = None) -> Any:
    elif context == "gemini_request":
        if isinstance(data, dict):
            return _sanitize_gemini_request(data)
-    elif context == "openai_request":
+    elif context in ("openai_request", "openai_responses_request"):
        if isinstance(data, dict):
            return _sanitize_openai_request(data)
    elif context == "ui_html":
@@ -24,8 +24,40 @@ T = TypeVar("T", bound=BaseModel)
 V = TypeVar("V")


+import typing
+
+if typing.TYPE_CHECKING:
+    _T_TA = TypeVar("_T_TA")
+
+    class TypeAdapter(typing.Generic[_T_TA]):
+        def __init__(self, type_: Any, **kwargs: Any): ...
+        def validate_python(self, obj: Any) -> _T_TA: ...
+
+    def model_validator(*args: Any, **kwargs: Any) -> Any: ...
+else:
+    try:
+        from pydantic import TypeAdapter, model_validator
+    except ImportError:
+
+        class TypeAdapter:
+            def __init__(self, type_: Any, **kwargs: Any):
+                self.type_ = type_
+
+            def validate_python(self, obj: Any) -> Any:
+                from nonebot.compat import type_validate_python
+
+                return type_validate_python(self.type_, obj)
+
+        def model_validator(*args: Any, **kwargs: Any) -> Any:
+            def decorator(func: Any) -> Any:
+                return func
+
+            return decorator
+
+
 __all__ = [
    "PYDANTIC_V2",
+    "TypeAdapter",
    "_dump_pydantic_obj",
    "_is_pydantic_type",
    "compat_computed_field",
@@ -37,6 +69,7 @@ __all__ = [
    "model_fields",
    "model_json_schema",
    "model_validate",
+    "model_validator",
    "parse_as",
    "type_validate_json",
    "type_validate_python",
@@ -265,3 +265,50 @@ def win_on_rm_error(
    except Exception:
        # 仍失败则记录调试日志并忽略，交由上层继续处理
        logger.debug(f"删除失败重试仍失败: {path}")
+
+
+def infer_plugin_namespace(
+    default: str = "global",
+) -> str:
+    """
+    智能推断调用者所在的插件命名空间。
+    """
+    import inspect
+
+    from nonebot.plugin import get_plugin_by_module_name
+    from nonebot.plugin.manager import _current_plugin
+
+    plugin = _current_plugin.get()
+    if plugin:
+        return plugin.name
+
+    try:
+        stack = inspect.stack()
+        for frame_info in stack[1:]:
+            module = inspect.getmodule(frame_info.frame)
+            if not module:
+                continue
+            m_name = module.__name__
+
+            if m_name.startswith("zhenxun.services.") or m_name.startswith(
+                "zhenxun.utils."
+            ):
+                continue
+
+            plugin = get_plugin_by_module_name(m_name)
+            if plugin:
+                return plugin.name
+
+            parts = m_name.split(".")
+            for keyword in ("plugins", "builtin_plugins"):
+                if keyword in parts:
+                    idx = parts.index(keyword)
+                    if len(parts) > idx + 1:
+                        return parts[idx + 1]
+
+            continue
+
+    except Exception:
+        pass
+
+    return default