sycommon-python-lib 0.2.3a12__tar.gz → 0.2.4a0__tar.gz

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.3a12
+Version: 0.2.4a0
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,17 +8,18 @@ Requires-Dist: aio-pika>=9.6.2
 Requires-Dist: aiohttp>=3.13.5
 Requires-Dist: aiomysql>=0.3.2
 Requires-Dist: anyio>=4.12.1
-Requires-Dist: decorator>=5.2.1
+Requires-Dist: decorator>=5.3.0
 Requires-Dist: deepagents>=0.6.1
 Requires-Dist: elasticsearch>=9.4.0
 Requires-Dist: fastapi>=0.136.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: kafka-python>=2.3.1
-Requires-Dist: langchain>=1.3.0
+Requires-Dist: langchain>=1.3.1
 Requires-Dist: langchain-core>=1.4.0
 Requires-Dist: langchain-openai>=1.2.1
 Requires-Dist: langfuse>=4.6.1
 Requires-Dist: langgraph>=1.2.0
+Requires-Dist: langgraph-checkpoint-postgres>=3.1.0
 Requires-Dist: langgraph-checkpoint-redis>=0.4.1
 Requires-Dist: ldap3>=2.9.1
 Requires-Dist: loguru>=0.7.3
@@ -28,17 +29,18 @@ Requires-Dist: psutil>=7.2.2
 Requires-Dist: pyxxl>=0.4.6
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: python-dotenv>=1.2.2
-Requires-Dist: python-multipart>=0.0.28
+Requires-Dist: python-multipart>=0.0.29
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: redis>=7.3.0
 Requires-Dist: sentry-sdk[fastapi]>=2.60.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0.48
 Requires-Dist: starlette[full]>=1.0.0
-Requires-Dist: tiktoken>=0.12.0
-Requires-Dist: uvicorn>=0.46.0
+Requires-Dist: tiktoken>=0.13.0
+Requires-Dist: uvicorn>=0.47.0
 Requires-Dist: wecom-aibot-python-sdk>=1.0.2
 Requires-Dist: twine>=6.2.0
 Requires-Dist: minio>=7.2.20
+Requires-Dist: langchain-mcp-adapters>=0.2.2
 
 # sycommon-python-lib
 

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4a0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.3a12"
+version = "0.2.4a0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,17 +9,18 @@ dependencies = [
     "aiohttp>=3.13.5",
     "aiomysql>=0.3.2",
     "anyio>=4.12.1",
-    "decorator>=5.2.1",
+    "decorator>=5.3.0",
     "deepagents>=0.6.1",
     "elasticsearch>=9.4.0",
     "fastapi>=0.136.1",
     "jinja2>=3.1.6",
     "kafka-python>=2.3.1",
-    "langchain>=1.3.0",
+    "langchain>=1.3.1",
     "langchain-core>=1.4.0",
     "langchain-openai>=1.2.1",
     "langfuse>=4.6.1",
     "langgraph>=1.2.0",
+    "langgraph-checkpoint-postgres>=3.1.0",
     "langgraph-checkpoint-redis>=0.4.1",
     "ldap3>=2.9.1",
     "loguru>=0.7.3",
@@ -29,17 +30,18 @@ dependencies = [
     "pyxxl>=0.4.6",
     "pydantic>=2.13.4",
     "python-dotenv>=1.2.2",
-    "python-multipart>=0.0.28",
+    "python-multipart>=0.0.29",
     "pyyaml>=6.0.3",
     "redis>=7.3.0",
     "sentry-sdk[fastapi]>=2.60.0",
     "sqlalchemy[asyncio]>=2.0.48",
     "starlette[full]>=1.0.0",
-    "tiktoken>=0.12.0",
-    "uvicorn>=0.46.0",
+    "tiktoken>=0.13.0",
+    "uvicorn>=0.47.0",
     "wecom-aibot-python-sdk>=1.0.2",
     "twine>=6.2.0",
     "minio>=7.2.20",
+    "langchain-mcp-adapters>=0.2.2",
 ]
 
 [tool.setuptools]

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4a0}/src/sycommon/agent/__init__.py

@@ -105,6 +105,18 @@ from sycommon.agent.chat_events import (
     error_event,
     cancelled_event,
 )
+from sycommon.agent.mcp import (
+    MCPToolStatus,
+    MCPServerConfig,
+    MCPServerCreateRequest,
+    MCPServerUpdateRequest,
+    MCPServerTestRequest,
+    MCPServerTestResult,
+    load_mcp_tools,
+    test_mcp_connection,
+    sanitize_name,
+)
+from sycommon.database.pg_checkpoint_service import PgCheckpointService
 
 __all__ = [
     # 沙箱
@@ -147,4 +159,18 @@ __all__ = [
     "done_event",
     "error_event",
     "cancelled_event",
+
+    # MCP 工具集成
+    "MCPToolStatus",
+    "MCPServerConfig",
+    "MCPServerCreateRequest",
+    "MCPServerUpdateRequest",
+    "MCPServerTestRequest",
+    "MCPServerTestResult",
+    "load_mcp_tools",
+    "test_mcp_connection",
+    "sanitize_name",
+
+    # PG Checkpoint 服务
+    "PgCheckpointService",
 ]

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4a0}/src/sycommon/agent/deep_agent.py

@@ -613,8 +613,12 @@ async def create_deep_agent(
 
     # 创建 checkpointer
     if checkpointer is None:
-        from langgraph.checkpoint.memory import MemorySaver
-        checkpointer = MemorySaver()
+        from sycommon.database.pg_checkpoint_service import PgCheckpointService
+        if PgCheckpointService.is_initialized():
+            checkpointer = await PgCheckpointService.get_checkpointer()
+        else:
+            from langgraph.checkpoint.memory import MemorySaver
+            checkpointer = MemorySaver()
 
     tid = thread_id or user_id
     agent_config = {"configurable": {"thread_id": tid}}

sycommon_python_lib-0.2.4a0/src/sycommon/agent/mcp/__init__.py

@@ -0,0 +1,30 @@
+"""MCP 工具集成模块
+
+提供 MCP 服务器连接、工具发现和加载功能。
+"""
+
+from sycommon.agent.mcp.models import (
+    MCPToolStatus,
+    MCPServerConfig,
+    MCPServerCreateRequest,
+    MCPServerUpdateRequest,
+    MCPServerTestRequest,
+    MCPServerTestResult,
+)
+from sycommon.agent.mcp.tool_loader import (
+    load_mcp_tools,
+    test_mcp_connection,
+    sanitize_name,
+)
+
+__all__ = [
+    "MCPToolStatus",
+    "MCPServerConfig",
+    "MCPServerCreateRequest",
+    "MCPServerUpdateRequest",
+    "MCPServerTestRequest",
+    "MCPServerTestResult",
+    "load_mcp_tools",
+    "test_mcp_connection",
+    "sanitize_name",
+]

sycommon_python_lib-0.2.4a0/src/sycommon/agent/mcp/models.py

@@ -0,0 +1,56 @@
+"""MCP 服务器配置数据模型"""
+
+from typing import Optional, List
+from pydantic import BaseModel
+
+
+class MCPToolStatus(BaseModel):
+    """MCP 工具可用状态"""
+    tool_name: str
+    description: Optional[str] = None
+    available: bool = True
+    last_check_at: Optional[str] = None
+    last_error: Optional[str] = None
+
+
+class MCPServerConfig(BaseModel):
+    id: str
+    user_id: Optional[str] = None
+    name: str
+    server_url: str
+    description: Optional[str] = None
+    headers: Optional[dict] = None
+    enabled: bool = True
+    sanitized_name: str = ""
+    created_at: str
+    updated_at: str
+    tools: Optional[List[MCPToolStatus]] = None
+    server_status: Optional[str] = None
+    server_error: Optional[str] = None
+
+
+class MCPServerCreateRequest(BaseModel):
+    name: str
+    server_url: str
+    description: Optional[str] = None
+    headers: Optional[dict] = None
+    enabled: bool = True
+
+
+class MCPServerUpdateRequest(BaseModel):
+    name: Optional[str] = None
+    server_url: Optional[str] = None
+    description: Optional[str] = None
+    headers: Optional[dict] = None
+    enabled: Optional[bool] = None
+
+
+class MCPServerTestRequest(BaseModel):
+    server_url: str
+    headers: Optional[dict] = None
+
+
+class MCPServerTestResult(BaseModel):
+    success: bool
+    tools: Optional[list] = None
+    error: Optional[str] = None

sycommon_python_lib-0.2.4a0/src/sycommon/agent/mcp/tool_loader.py

@@ -0,0 +1,174 @@
+"""MCP 工具加载器
+
+使用 langchain-mcp-adapters 官方库连接远程 MCP 服务器，
+发现工具并作为 LangChain BaseTool 注入 Agent。
+"""
+
+import re
+import hashlib
+from typing import List, Optional, Callable, Awaitable
+
+from langchain_core.tools import BaseTool
+
+from sycommon.logging.kafka_log import SYLogger
+from sycommon.agent.mcp.models import MCPServerConfig
+
+
+def sanitize_name(name: str) -> str:
+    """将名称转为合法的标识符，中文等非ASCII字符做 transliterate"""
+    sanitized = re.sub(r'[^a-zA-Z0-9_]', '_', name).strip('_')
+    if not sanitized:
+        h = hashlib.md5(name.encode()).hexdigest()[:8]
+        sanitized = f"mcp_{h}"
+    return sanitized
+
+
+def wrap_tool_with_error_handler(
+    tool: BaseTool,
+    server_config_id: str,
+    server_name: str,
+    original_tool_name: str,
+    on_tool_success: Optional[Callable[[str, str], Awaitable[None]]] = None,
+    on_tool_error: Optional[Callable[[str, str, str], Awaitable[None]]] = None,
+) -> BaseTool:
+    """包装 MCP 工具的 coroutine，捕获连接/超时等异常，返回友好的错误信息而非抛出异常。
+
+    Args:
+        on_tool_success: 异步回调 (server_config_id, tool_name) -> None
+        on_tool_error: 异步回调 (server_config_id, tool_name, error_msg) -> None
+    """
+    original_coroutine = tool.coroutine
+    tool_name = tool.name
+
+    async def _safe_coroutine(*args, **kwargs):
+        try:
+            result = await original_coroutine(*args, **kwargs)
+            if on_tool_success:
+                try:
+                    await on_tool_success(server_config_id, original_tool_name)
+                except Exception:
+                    pass
+            return result
+        except Exception as e:
+            err_type = type(e).__name__
+            err_msg = str(e)[:500]
+            SYLogger.warning(f"[MCP] 工具 '{tool_name}' 调用失败 ({err_type}): {err_msg}")
+
+            if on_tool_error:
+                try:
+                    await on_tool_error(server_config_id, original_tool_name, f"{err_type}: {err_msg}")
+                except Exception:
+                    pass
+
+            friendly_msg = (
+                f"MCP 工具调用失败：工具 '{tool_name}' (服务器: {server_name}) 当前不可用。\n"
+                f"错误类型: {err_type}\n"
+                f"可能原因: MCP 服务器未启动、网络不可达或连接超时。\n"
+                f"请尝试不使用该工具继续完成任务，或联系管理员检查 MCP 服务 '{server_name}'。"
+            )
+            return [friendly_msg]
+
+    tool.coroutine = _safe_coroutine
+    return tool
+
+
+async def load_mcp_tools(
+    configs: List[MCPServerConfig],
+    on_tool_success: Optional[Callable[[str, str], Awaitable[None]]] = None,
+    on_tool_error: Optional[Callable[[str, str, str], Awaitable[None]]] = None,
+    on_batch_available: Optional[Callable[[str, list], Awaitable[None]]] = None,
+    on_server_failure: Optional[Callable[[str, str], Awaitable[None]]] = None,
+) -> List[BaseTool]:
+    """加载 MCP 工具列表
+
+    接受 MCPServerConfig 列表，逐个服务器连接并加载工具。
+
+    Args:
+        configs: MCP 服务器配置列表（仅 enabled 的会被处理）
+        on_tool_success: 单个工具调用成功回调
+        on_tool_error: 单个工具调用失败回调
+        on_batch_available: 服务器连接成功后批量标记工具可用回调 (config_id, tool_names)
+        on_server_failure: 服务器连接失败回调 (config_id, error_msg)
+    """
+    enabled_configs = [c for c in configs if c.enabled]
+    if not enabled_configs:
+        return []
+
+    all_tools = []
+    for config in enabled_configs:
+        try:
+            from langchain_mcp_adapters.client import MultiServerMCPClient
+
+            key = sanitize_name(config.name)
+            client_config = {
+                key: {
+                    "url": config.server_url,
+                    "transport": "streamable_http",
+                    **({"headers": config.headers} if config.headers else {}),
+                }
+            }
+
+            client = MultiServerMCPClient(client_config)
+            tools = await client.get_tools()
+
+            original_names = []
+            for tool in tools:
+                original_name = tool.name
+                original_names.append(original_name)
+                tool.name = f"mcp__{key}__{original_name}"
+                if tool.description and not tool.description.startswith("[MCP"):
+                    tool.description = f"[MCP:{config.name}] {tool.description}"
+                wrap_tool_with_error_handler(
+                    tool, config.id, config.name, original_name,
+                    on_tool_success=on_tool_success,
+                    on_tool_error=on_tool_error,
+                )
+
+            all_tools.extend(tools)
+
+            if on_batch_available:
+                try:
+                    await on_batch_available(config.id, original_names)
+                except Exception as e:
+                    SYLogger.warning(f"[MCP] 写入工具状态失败: {e}")
+
+            SYLogger.info(f"[MCP] 服务器 '{config.name}' 加载了 {len(tools)} 个工具")
+
+        except Exception as e:
+            SYLogger.warning(f"[MCP] 服务器 '{config.name}' ({config.server_url}) 连接失败，跳过: {e}")
+            if on_server_failure:
+                try:
+                    await on_server_failure(config.id, str(e)[:300])
+                except Exception:
+                    pass
+
+    if all_tools:
+        SYLogger.info(f"[MCP] 共加载 {len(all_tools)} 个 MCP 工具")
+    return all_tools
+
+
+async def test_mcp_connection(server_url: str, headers: dict = None) -> dict:
+    """测试 MCP 服务器连接，返回发现的工具列表"""
+    try:
+        from langchain_mcp_adapters.client import MultiServerMCPClient
+
+        client_config = {
+            "test": {
+                "url": server_url,
+                "transport": "streamable_http",
+                **({"headers": headers} if headers else {}),
+            }
+        }
+
+        client = MultiServerMCPClient(client_config)
+        tools = await client.get_tools()
+
+        return {
+            "success": True,
+            "tools": [{"name": t.name, "description": t.description or ""} for t in tools],
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4a0}/src/sycommon/agent/multi_agent_team.py

@@ -574,8 +574,12 @@ async def create_multi_agent_team(
 
     # 创建 checkpointer
     if checkpointer is None:
-        from langgraph.checkpoint.memory import MemorySaver
-        checkpointer = MemorySaver()
+        from sycommon.database.pg_checkpoint_service import PgCheckpointService
+        if PgCheckpointService.is_initialized():
+            checkpointer = await PgCheckpointService.get_checkpointer()
+        else:
+            from langgraph.checkpoint.memory import MemorySaver
+            checkpointer = MemorySaver()
 
     tid = thread_id or user_id
     agent_config = {"configurable": {"thread_id": tid}}

sycommon_python_lib-0.2.4a0/src/sycommon/config/PgConfig.py

@@ -0,0 +1,54 @@
+from pydantic import BaseModel, Field
+
+
+class PgConfig(BaseModel):
+    """PostgreSQL 配置"""
+    host: str = Field(default="localhost", description="PG 主机地址")
+    port: int = Field(default=5432, description="PG 端口")
+    dbname: str = Field(default="postgres", description="数据库名")
+    user: str = Field(default="postgres", description="用户名")
+    password: str = Field(default="", description="密码")
+    min_pool_size: int = Field(default=2, description="连接池最小连接数")
+    max_pool_size: int = Field(default=10, description="连接池最大连接数")
+
+    @classmethod
+    def from_dict(cls, config: dict) -> "PgConfig":
+        """从字典解析配置
+
+        支持两种格式：
+        1. 扁平格式: {"host": "...", "port": 5432, ...}
+        2. Spring 格式: {"spring": {"datasource": {"url": "jdbc:postgresql://...", ...}}}
+        """
+        spring = config.get("spring", {})
+        if spring:
+            ds = spring.get("datasource", {})
+            url = ds.get("url", "")
+            return cls._from_jdbc_url(url, ds.get("username", ""), ds.get("password", ""))
+
+        return cls(
+            host=config.get("host", "localhost"),
+            port=config.get("port", 5432),
+            dbname=config.get("dbname", config.get("database", "postgres")),
+            user=config.get("user", config.get("username", "postgres")),
+            password=config.get("password", ""),
+            min_pool_size=config.get("min_pool_size", 2),
+            max_pool_size=config.get("max_pool_size", 10),
+        )
+
+    @classmethod
+    def _from_jdbc_url(cls, url: str, username: str, password: str) -> "PgConfig":
+        """从 JDBC URL 解析配置"""
+        # jdbc:postgresql://host:port/dbname
+        if "://" in url:
+            url = url.split("://", 1)[1]
+        parts = url.split("/")
+        dbname = parts[1] if len(parts) > 1 else "postgres"
+        host_port = parts[0].split(":")
+        host = host_port[0]
+        port = int(host_port[1]) if len(host_port) > 1 else 5432
+        return cls(host=host, port=port, dbname=dbname, user=username, password=password)
+
+    @property
+    def dsn(self) -> str:
+        """生成 psycopg 连接字符串"""
+        return f"host={self.host} port={self.port} dbname={self.dbname} user={self.user} password={self.password}"

sycommon_python_lib-0.2.4a0/src/sycommon/database/pg_checkpoint_service.py

@@ -0,0 +1,124 @@
+"""
+PostgreSQL Checkpoint 服务
+
+为 LangGraph Agent 提供 PostgreSQL 持久化 checkpoint 存储。
+使用 AsyncPostgresSaver，适配 FastAPI 的异步环境。
+
+用法：
+    # 通过 Services.plugins 自动初始化
+    Services.plugins(app, pg_checkpoint_service=True)
+
+    # 或手动初始化
+    await PgCheckpointService.setup({"host": "10.10.6.203", "port": 5432, ...})
+
+    # 获取 checkpointer
+    checkpointer = await PgCheckpointService.get_checkpointer()
+"""
+import logging
+from typing import Optional, Any
+
+from sycommon.config.Config import SingletonMeta
+from sycommon.config.PgConfig import PgConfig
+
+
+class PgCheckpointService(metaclass=SingletonMeta):
+    """PostgreSQL Checkpoint 服务（单例）"""
+    _checkpointer: Optional[Any] = None
+    _initialized: bool = False
+    _config: Optional[PgConfig] = None
+    _pool: Optional[Any] = None
+
+    def __init__(self):
+        pass
+
+    @classmethod
+    async def setup(cls, config: Optional[dict] = None):
+        """初始化 PG Checkpoint 服务
+
+        Args:
+            config: 配置字典。不传则尝试从 Nacos 读取 pg.yml。
+        """
+        if cls._initialized:
+            return
+
+        try:
+            if config is None:
+                try:
+                    from sycommon.config.Config import Config
+                    config = Config().config.get('llm', {}).get('PostgreSQL')
+                    if not config:
+                        logging.info("未从 Nacos 获取到 PostgreSQL 配置，PG Checkpoint 服务将禁用")
+                        return
+                    logging.info("从 Nacos 获取 PostgreSQL 配置成功")
+                except Exception as e:
+                    logging.info(f"从 Nacos 读取 PostgreSQL 配置失败: {e}，PG Checkpoint 服务将禁用")
+                    return
+
+            cls._config = PgConfig.from_dict(config)
+
+            from psycopg_pool import AsyncConnectionPool
+            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+            conn_string = cls._config.dsn
+
+            cls._pool = AsyncConnectionPool(
+                conninfo=conn_string,
+                min_size=cls._config.min_pool_size,
+                max_size=cls._config.max_pool_size,
+                open=False,
+                kwargs={"autocommit": True, "prepare_threshold": 0},
+            )
+
+            await cls._pool.open()
+
+            cls._checkpointer = AsyncPostgresSaver(cls._pool)
+            await cls._checkpointer.setup()
+
+            cls._initialized = True
+            logging.info(
+                f"PgCheckpointService 初始化成功，地址: {cls._config.host}:{cls._config.port}/{cls._config.dbname}"
+            )
+
+        except Exception as e:
+            logging.error(f"PgCheckpointService 初始化失败: {e}", exc_info=True)
+            # 清理可能已创建的连接池
+            if cls._pool:
+                try:
+                    await cls._pool.close()
+                except Exception:
+                    pass
+                cls._pool = None
+            cls._checkpointer = None
+
+    @classmethod
+    async def get_checkpointer(cls) -> Any:
+        """获取 AsyncPostgresSaver 实例
+
+        Returns:
+            AsyncPostgresSaver 实例
+
+        Raises:
+            RuntimeError: 如果服务未初始化
+        """
+        if not cls._initialized or not cls._checkpointer:
+            raise RuntimeError("PgCheckpointService 未初始化，请先调用 PgCheckpointService.setup()")
+        return cls._checkpointer
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        """检查是否已初始化"""
+        return cls._initialized
+
+    @classmethod
+    async def close(cls):
+        """关闭 PG 连接池"""
+        if cls._pool:
+            try:
+                await cls._pool.close()
+                logging.info("PgCheckpointService 连接池已关闭")
+            except Exception as e:
+                logging.error(f"关闭 PgCheckpointService 连接池失败: {e}")
+            finally:
+                cls._pool = None
+                cls._checkpointer = None
+                cls._initialized = False

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4a0}/src/sycommon/llm/get_llm.py

@@ -1,4 +1,3 @@
-import os
 from sycommon.llm.llm_logger import LLMLogger
 from langchain.chat_models import init_chat_model
 from sycommon.config.LLMConfig import LLMConfig
@@ -160,7 +159,7 @@ def get_llm(
         "model_provider": llmConfig.provider,
         "model": llmConfig.model,
         "base_url": llmConfig.baseUrl,
-        "api_key": os.environ.get("LLM_API_KEY") or llmConfig.apiKey or "-",
+        "api_key": llmConfig.apiKey or "-",
         "callbacks": callbacks,
         "temperature": temperature,
         "streaming": streaming,