✨ 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-16 01:30:03 +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,115 @@
+from collections import defaultdict
+from collections.abc import Awaitable, Callable
+
+from zhenxun.services.ai.flow.agent.models import AgentRunResources, AgentState
+from zhenxun.services.ai.run.models import AgentRunResult, HandoffPayload
+from zhenxun.services.ai.tools.models import ToolResult
+from zhenxun.services.log import logger
+from zhenxun.utils.pydantic_compat import model_construct
+from zhenxun.utils.utils import infer_plugin_namespace
+
+DirectiveHandlerFunc = Callable[
+    [AgentState, AgentRunResources, ToolResult], Awaitable[None]
+]
+
+
+class DirectiveManager:
+    """工具指令路由注册中心"""
+
+    def __init__(self):
+        self._handlers: dict[str, dict[str, DirectiveHandlerFunc]] = defaultdict(dict)
+
+    def register(
+        self, name: str, handler: DirectiveHandlerFunc, namespace: str = "global"
+    ) -> None:
+        self._handlers[namespace][name] = handler
+        logger.debug(f"已注册工具副作用指令: '{name}' -> Namespace: '{namespace}'")
+
+    def get_handler(
+        self, name: str, namespace: str = "global"
+    ) -> DirectiveHandlerFunc | None:
+        """优先从指定 namespace 找，找不到回退到 global"""
+        ns_dict = self._handlers.get(namespace, {})
+        if name in ns_dict:
+            return ns_dict[name]
+        return self._handlers.get("global", {}).get(name)
+
+
+directive_manager = DirectiveManager()
+
+
+def directive(name: str | None = None, namespace: str | None = None):
+    """
+    注册一个自定义工具副作用指令处理器的装饰器。
+
+    参数:
+        name: 指令的名称，如果不填则默认使用被装饰的函数名。
+        namespace: 插件命名空间，如果不填则基于代码调用栈自动推断。
+    """
+
+    def decorator(func: DirectiveHandlerFunc):
+        dir_name = name or func.__name__
+        ns = namespace if namespace is not None else infer_plugin_namespace()
+        directive_manager.register(dir_name, func, ns)
+        return func
+
+    return decorator
+
+
+@directive("submit_structured", namespace="global")
+async def handle_submit_structured(
+    state: AgentState, resources: AgentRunResources, tool_res: ToolResult
+) -> None:
+    parsed_obj = (
+        tool_res.directive.payload.get("parsed_obj") if tool_res.directive else None
+    )
+    logger.info("✅ 拦截到结构化结果提交，结束循环。")
+    state.is_finished = True
+    state.final_result = model_construct(
+        AgentRunResult,
+        output=None,
+        messages=state.messages,
+        structured_data=parsed_obj,
+        usage=state.usage,
+    )
+
+
+@directive("end_run", namespace="global")
+async def handle_end_run(
+    state: AgentState, resources: AgentRunResources, tool_res: ToolResult
+) -> None:
+    output = (
+        tool_res.directive.payload.get("output", tool_res.output)
+        if tool_res.directive
+        else tool_res.output
+    )
+    logger.debug("✅ 捕获到工具发出的终止信号，提前结束推理循环。")
+    state.is_finished = True
+    state.final_result = model_construct(
+        AgentRunResult,
+        output=output,
+        messages=state.messages,
+        usage=state.usage,
+    )
+
+
+@directive("handoff", namespace="global")
+async def handle_handoff(
+    state: AgentState, resources: AgentRunResources, tool_res: ToolResult
+) -> None:
+    payload = tool_res.directive.payload if tool_res.directive else {}
+    handoff = HandoffPayload(
+        target=payload.get("target", "unknown"),
+        reason=payload.get("reason", ""),
+        context_data=payload.get("context_data", ""),
+    )
+    output_text = f"已触发控制权移交 -> {handoff.target}。原因: {handoff.reason}"
+    logger.info(f"✅ 拦截到移交(Handoff)信号: 移交给 -> {handoff.target}。结束循环。")
+    state.is_finished = True
+    state.final_result = model_construct(
+        AgentRunResult,
+        output=output_text,
+        messages=state.messages,
+        usage=state.usage,
+        handoff=handoff,
+    )