✨ 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/core/protocols/__init__.py

@@ -0,0 +1,11 @@
+"""
+AI 服务协议统一导出
+"""
+
+from .tool import ToolExecutable, ToolProvider, ToolResolvable
+
+__all__ = [
+    "ToolExecutable",
+    "ToolProvider",
+    "ToolResolvable",
+]

zhenxun/services/ai/core/protocols/llm.py

@@ -0,0 +1,76 @@
+from typing import Protocol, runtime_checkable
+
+from zhenxun.services.ai.core.messages import (
+    AudioResponse,
+    ChatRequest,
+    ChatResponse,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    ImageRequest,
+    ImageResponse,
+    RerankRequest,
+    RerankResponse,
+    SpeechRequest,
+)
+from zhenxun.services.ai.core.models import CancellationToken
+
+
+@runtime_checkable
+class SupportsChat(Protocol):
+    """支持文本/多模态对话生成的协议"""
+
+    async def generate_response(
+        self,
+        request: ChatRequest,
+        cancellation_token: CancellationToken | None = None,
+    ) -> ChatResponse:
+        """生成文本或多模态对话的回复。"""
+        ...
+
+
+@runtime_checkable
+class SupportsTextEmbedding(Protocol):
+    """支持文本/多模态向量嵌入的协议"""
+
+    async def generate_embeddings(
+        self,
+        request: EmbeddingRequest,
+    ) -> EmbeddingResponse:
+        """生成文本或多模态向量嵌入。"""
+        ...
+
+
+@runtime_checkable
+class SupportsSpeechSynthesis(Protocol):
+    """支持文本转语音(TTS)的协议"""
+
+    async def generate_speech(
+        self,
+        request: SpeechRequest,
+    ) -> AudioResponse:
+        """将文本转换为语音（TTS）。"""
+        ...
+
+
+@runtime_checkable
+class SupportsReranking(Protocol):
+    """支持文档交叉注意力重排的协议"""
+
+    async def rerank(
+        self,
+        request: RerankRequest,
+    ) -> RerankResponse:
+        """对候选文档进行交叉注意力重排。"""
+        ...
+
+
+@runtime_checkable
+class SupportsImageGeneration(Protocol):
+    """支持图像生成与编辑的协议"""
+
+    async def generate_image(
+        self,
+        request: ImageRequest,
+    ) -> ImageResponse:
+        """根据请求生成或编辑图像。"""
+        ...

zhenxun/services/ai/core/protocols/middleware.py

@@ -0,0 +1,23 @@
+"""
+LLM 中间件协议定义
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from zhenxun.services.ai.core.models import LLMContext, TReq, TRes
+
+
+class NextCall(Protocol[TReq, TRes]):
+    """中间件管道中下一个节点（或最终执行函数）的调用签名"""
+
+    async def __call__(self, context: LLMContext[TReq, TRes], /) -> TRes: ...
+
+
+class LLMMiddleware(Protocol[TReq, TRes]):
+    """LLM 中间件函数的调用签名，遵循洋葱模型嵌套包裹设计"""
+
+    async def __call__(
+        self, context: LLMContext[TReq, TRes], next_call: NextCall[TReq, TRes], /
+    ) -> TRes: ...

zhenxun/services/ai/core/protocols/tool.py

@@ -0,0 +1,84 @@
+"""
+工具执行与管理协议定义
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from zhenxun.services.ai.core.models import ToolDefinition
+
+if TYPE_CHECKING:
+    from zhenxun.services.ai.run import RunContext
+    from zhenxun.services.ai.tools.models import (
+        ResolvedToolPayload,
+        ToolResult,
+    )
+
+
+class ToolExecutable(Protocol):
+    """
+    一个协议，定义了所有可被LLM调用的工具必须实现的行为。
+    """
+
+    name: str
+    """工具的名称标识"""
+
+    async def get_definition(
+        self, context: "RunContext | None" = None
+    ) -> ToolDefinition | None:
+        """
+        异步地获取一个结构化的工具定义。如果返回 None，则该工具对大模型不可见。
+        """
+        ...
+
+    async def execute(
+        self, context: "RunContext | None" = None, **kwargs: Any
+    ) -> ToolResult:
+        """
+        异步执行工具并返回一个结构化的结果。
+        """
+        ...
+
+
+@runtime_checkable
+class ToolResolvable(Protocol):
+    """
+    鸭子类型解析协议。任何实现了此协议的对象，
+    都可以直接被 Agent 或 LLM 的 tools 参数接收。
+    """
+
+    async def resolve(
+        self, context: "RunContext | None" = None
+    ) -> "ResolvedToolPayload": ...
+
+
+class ToolProvider(Protocol):
+    """
+    一个协议，定义了"工具提供者"的行为。
+    工具提供者负责发现或实例化具体的 ToolExecutable 对象。
+    """
+
+    async def initialize(self) -> None:
+        """
+        异步初始化提供者。
+        """
+        ...
+
+    async def discover_tools(
+        self,
+        allowed_servers: list[str] | None = None,
+        excluded_servers: list[str] | None = None,
+    ) -> dict[str, ToolExecutable]:
+        """
+        异步发现此提供者提供的所有工具。
+        """
+        ...
+
+    async def get_tool_executable(
+        self, name: str, config: dict[str, Any]
+    ) -> ToolExecutable | None:
+        """
+        如果此提供者能处理名为 'name' 的工具，则返回一个可执行实例。
+        """
+        ...