✨ 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-21 20:20:05 +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,99 @@
+from typing import Any
+
+from pydantic import BaseModel, Field, create_model
+
+from zhenxun.services.ai.run import RunContext
+from zhenxun.services.ai.tools.core.tool import BaseTool
+from zhenxun.services.ai.tools.models import HandoffResult, ToolResult
+
+
+class HandoffTool(BaseTool):
+    """
+    触发控制权移交 (Handoff) 信号的底层工具。
+    当大模型调用此工具时，当前 Agent 执行流将被立即熔断并向外抛出 ToolHandoff 信号。
+    """
+
+    def __init__(
+        self,
+        target_name: str,
+        target_description: str,
+        input_schema: type[BaseModel] | Any | None = None,
+    ):
+        super().__init__(
+            name=f"transfer_to_{target_name}",
+            description=(
+                f"将对话控制权移交给 {target_name}。专长/职责：{target_description}"
+            ),
+        )
+        self.target_name = target_name
+
+        actual_schema = None
+        if input_schema:
+            from zhenxun.services.ai.core.options import BaseOutputDefinition
+
+            if isinstance(input_schema, BaseOutputDefinition):
+                actual_schema = input_schema.type_
+            else:
+                actual_schema = input_schema
+
+        if actual_schema:
+            fields: dict[str, Any] = {
+                "reason": (str, Field(..., description="移交的原因或简要状态说明")),
+            }
+            schema_fields = getattr(
+                actual_schema, "model_fields", getattr(actual_schema, "__fields__", {})
+            )
+            for k, v in schema_fields.items():
+                fields[k] = (v.annotation, v)
+            self.args_schema = create_model(
+                f"DynamicHandoffArgs_{target_name}", **fields
+            )
+        else:
+
+            class DefaultHandoffArgs(BaseModel):
+                reason: str = Field(..., description="移交的原因或简要状态说明")
+                context_data: Any = Field(
+                    default="",
+                    description="你需要传递给下一个负责人的所有核心数据",
+                )
+
+            self.args_schema = DefaultHandoffArgs
+
+    async def execute(
+        self, context: RunContext | None = None, **kwargs: Any
+    ) -> ToolResult:
+        reason = kwargs.pop("reason", "")
+
+        if "context_data" in kwargs and len(kwargs) == 1:
+            context_data = kwargs["context_data"]
+        else:
+            context_data = kwargs
+
+        if context:
+            counts = context.session.shared_state.setdefault("__handoff_counts__", {})
+            counts[self.target_name] = counts.get(self.target_name, 0) + 1
+            if counts[self.target_name] > 3:
+                return ToolResult(
+                    output=(
+                        f"❌ 系统拦截：检测到严重的踢皮球现象！\n"
+                        f"你所在的团队已经连续 {counts[self.target_name]} 次将任务"
+                        f"移交给 {self.target_name}，\n"
+                        "但问题仍未解决。请立刻改变策略，"
+                        "由你亲自处理或得出最终结论，严禁再次移交！"
+                    )
+                ).as_error()
+
+        from zhenxun.services.ai.core.messages import HandoffEvent
+
+        if context:
+            context.run.add_event(
+                HandoffEvent(
+                    target=self.target_name,
+                    reason=reason,
+                    context_data=context_data,
+                )
+            )
+
+        return HandoffResult(
+            target=self.target_name, reason=reason, context_data=context_data
+        )