✨ 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-09 13:50: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,131 @@
+import os
+from pathlib import Path
+import re
+from typing import Any
+
+from zhenxun.services.ai.tools.core.decorators import tool
+from zhenxun.services.ai.tools.models import ToolResult
+from zhenxun.services.log import logger
+
+from .base import BaseKnowledge
+
+
+class FileSystemKnowledge(BaseKnowledge):
+    """
+    纯文本文件系统知识库。
+    零依赖，无需向量数据库。通过大模型原生工具 (grep, list, read) 让其自主翻阅本地文件。
+    """
+
+    default_instructions = (
+        "## 本地文件知识库\n"
+        "你拥有访问本地专业文档的权限。在回答问题前，请遵循以下流程：\n"
+        "1. **搜索**：优先使用 `search_knowledge_files` 通过关键词查找相关内容。\n"
+        "2. **概览**：如果需要了解文件结构，使用 `list_knowledge_files`。\n"
+        "3. **阅读**：找到目标后，使用 `read_knowledge_file` 获取完整上下文。\n"
+        "**核心原则**：严禁凭空捏造事实，必须基于文件内容提取信息。"
+    )
+
+    def __init__(
+        self,
+        base_dir: str | Path,
+        allowed_extensions: tuple[str, ...] | None = None,
+        **kwargs: Any,
+    ):
+        """
+        初始化文本文件系统知识库。
+
+        参数:
+            base_dir: 知识库对应的本地根目录路径。
+            allowed_extensions: 允许读取和检索的文件后缀元组，
+                默认支持 txt, md, json, csv, yaml, log。
+            **kwargs: 透传给父类 BaseKnowledge 的额外参数。
+        """
+        super().__init__(**kwargs)
+        self.base_dir = Path(base_dir).resolve()
+        self.allowed_extensions = allowed_extensions or (
+            ".txt",
+            ".md",
+            ".json",
+            ".csv",
+            ".yaml",
+            ".log",
+        )
+        if not self.base_dir.exists():
+            logger.warning(f"[FileSystemKnowledge] 警告：目录不存在 {self.base_dir}")
+            self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    def _is_safe_path(self, target_path: Path) -> bool:
+        """安全检查：防止跨目录访问"""
+        try:
+            return target_path.resolve().is_relative_to(self.base_dir)
+        except Exception:
+            return False
+
+    @tool(
+        name="search_knowledge_files",
+        description="在知识库中搜索包含指定关键词的文件内容和上下文。",
+    )
+    async def search_knowledge_files(self, keyword: str) -> ToolResult:
+        """扫描所有文本文件，返回包含关键词的行及上下文。"""
+        results = []
+        try:
+            pattern = re.compile(re.escape(keyword), re.IGNORECASE)
+        except Exception:
+            return ToolResult(output=f"无效的搜索关键词: {keyword}").as_error()
+
+        for root, _, files in os.walk(self.base_dir):
+            for file in files:
+                if not file.endswith(self.allowed_extensions):
+                    continue
+
+                file_path = Path(root) / file
+                try:
+                    content = file_path.read_text(encoding="utf-8", errors="ignore")
+                    lines = content.splitlines()
+
+                    matches = []
+                    for i, line in enumerate(lines):
+                        if pattern.search(line):
+                            start = max(0, i - 1)
+                            end = min(len(lines), i + 2)
+                            context = "\n".join(lines[start:end])
+                            matches.append(context)
+
+                    if matches:
+                        rel_path = file_path.relative_to(self.base_dir).as_posix()
+                        match_text = "\n---\n".join(matches[:5])
+                        results.append(f"📁 文件: {rel_path}\n{match_text}")
+                except Exception:
+                    continue
+
+        if not results:
+            return ToolResult(output=f"未找到包含 '{keyword}' 的内容。尝试更换关键词。")
+
+        final_output = "\n\n======\n\n".join(results[:10])
+        return ToolResult(output=final_output)
+
+    @tool(name="list_knowledge_files", description="列出知识库中所有可用的文档路径。")
+    async def list_knowledge_files(self) -> ToolResult:
+        files = []
+        for root, _, filenames in os.walk(self.base_dir):
+            for filename in filenames:
+                file_path = Path(root) / filename
+                rel_path = file_path.relative_to(self.base_dir).as_posix()
+                files.append(rel_path)
+
+        if not files:
+            return ToolResult(output="知识库当前为空。")
+        return ToolResult(output="可用文件列表:\n" + "\n".join(files))
+
+    @tool(
+        name="read_knowledge_file", description="读取知识库中指定文件的完整文本内容。"
+    )
+    async def read_knowledge_file(self, file_path: str) -> ToolResult:
+        target = (self.base_dir / file_path).resolve()
+        if not self._is_safe_path(target):
+            return ToolResult(output="❌ 安全拦截：越权访问").as_error()
+        if not target.is_file():
+            return ToolResult(output=f"❌ 文件不存在: {file_path}").as_error()
+
+        content = target.read_text(encoding="utf-8", errors="ignore")
+        return ToolResult(output=content)