✨ 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>

zhenxun/services/ai/run/ui.py

@@ -0,0 +1,83 @@
+from typing import TYPE_CHECKING, Any
+
+from nonebot_plugin_alconna import UniMessage
+
+from zhenxun.services.ai.core.stream_events import ToolStreamChunkEvent, UserCustomEvent
+
+if TYPE_CHECKING:
+    from zhenxun.services.ai.run.context import RunContext
+
+
+class UIController:
+    """前端 UI 富交互流式控制器 (按需生成模式)"""
+
+    def __init__(self, context: "RunContext"):
+        self.context = context
+
+    @property
+    def tool_name(self) -> str:
+        """从上下文中动态获取当前调用的工具名"""
+        return getattr(self.context.call, "tool_name", "UnknownTool")
+
+    @property
+    def _event_bus(self) -> Any | None:
+        """从运行时上下文中获取底层的事件发射器"""
+        return getattr(self.context.run, "event_bus", None)
+
+    async def send_text(self, text: str, status: str = "running") -> None:
+        """向前端流式反馈执行进度文本"""
+        if self._event_bus:
+            await self._event_bus.emit(
+                ToolStreamChunkEvent(
+                    tool_name=self.tool_name, content=text, metadata={"status": status}
+                )
+            )
+
+    async def send_image(self, image: bytes | str) -> None:
+        """向前端发送富文本图片气泡（字节流或 URL）"""
+        if self._event_bus:
+            display_msg = UniMessage()
+            if isinstance(image, bytes):
+                display_msg = display_msg.image(raw=image)
+            else:
+                display_msg = display_msg.image(url=image)
+            await self._event_bus.emit(UserCustomEvent(display=display_msg))
+
+    async def send_display(self, display: Any) -> None:
+        """向前端发送任意展示载体"""
+        if self._event_bus and display is not None:
+            await self._event_bus.emit(UserCustomEvent(display=display))
+
+    @staticmethod
+    async def handle_control_flow_exit_display(
+        e: BaseException, context: "RunContext | None", reply_to: bool = False
+    ) -> None:
+        """统一处理 ControlFlowExit 异常带来的 UI 反馈逻辑"""
+        from zhenxun.services.ai.core.exceptions import ControlFlowExit
+
+        if not isinstance(e, ControlFlowExit):
+            return
+
+        display_msg = getattr(e, "display", None) or getattr(e, "display_content", None)
+        if not display_msg:
+            return
+
+        try:
+            from nonebot_plugin_alconna import UniMessage
+
+            bot = context.get_bot() if context else None
+            event = context.get_event() if context else None
+
+            if bot and event:
+                if isinstance(display_msg, UniMessage):
+                    await display_msg.send(event, bot=bot, reply_to=reply_to)
+                else:
+                    await bot.send(event, str(display_msg))
+            else:
+                from zhenxun.utils.message import MessageUtils
+
+                await MessageUtils.build_message(str(display_msg)).send(
+                    reply_to=reply_to
+                )
+        except Exception:
+            pass