sycommon-python-lib 0.2.3a12__py3-none-any.whl → 0.2.4__py3-none-any.whl

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/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/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/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/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/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/agent/sandbox/http_sandbox_backend.py

@@ -37,6 +37,11 @@ except ImportError:
     _SSL_CONTEXT = ssl.create_default_context()
 
 
+def _read_file_safe(path: str) -> bytes:
+    with open(path, "rb") as f:
+        return f.read()
+
+
 class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
     """
     通过 HTTP API 连接远程沙箱容器
@@ -210,6 +215,24 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
             nacos_group=group,
         )
 
+    @classmethod
+    async def afrom_nacos(
+        cls,
+        service_name: str,
+        user_id: str,
+        group: str = "DEFAULT_GROUP",
+        version: str = None,
+        timeout: int = 180,
+        sync_dirs: List[tuple[str, str]] = None,
+        auto_sync: bool = False,
+        load_balance: bool = True,
+    ) -> "HTTPSandboxBackend":
+        """异步从 Nacos 服务发现创建后端实例"""
+        return await asyncio.to_thread(
+            cls.from_nacos,
+            service_name, user_id, group, version, timeout, sync_dirs, auto_sync, load_balance,
+        )
+
     # ============== 内部方法 - 同步版本 ==============
 
     def _refresh_from_nacos_and_switch_sync(self) -> bool:
@@ -565,7 +588,7 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
             else:
                 # 单文件
                 SYLogger.info(f"[Sandbox] 上传单文件: {local_path}")
-                content = await asyncio.to_thread(lambda: open(local_dir, "rb").read())
+                content = await asyncio.to_thread(lambda p: _read_file_safe(p), local_dir)
                 upload_results = await self.aupload_files([(remote_path, content)], timeout=timeout)
                 if upload_results[0].error:
                     results[local_path] = {"success": 0, "failed": 1, "errors": [{"path": remote_path, "error": upload_results[0].error}]}
@@ -669,7 +692,8 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
             def _read_batch():
                 items = []
                 for sandbox_path, local_file in batch_files:
-                    content = open(local_file, "rb").read()
+                    with open(local_file, "rb") as f:
+                        content = f.read()
                     items.append((sandbox_path, content))
                 return items
             batch_items = await asyncio.to_thread(_read_batch)
@@ -1037,7 +1061,7 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                 SYLogger.info(f"[Sandbox] 异步目录上传完成: {local_path}, 成功={result['success']}, 失败={result['failed']}")
             else:
                 SYLogger.info(f"[Sandbox] 异步上传单文件: {local_path}")
-                content = await asyncio.to_thread(lambda: open(local_dir, "rb").read())
+                content = await asyncio.to_thread(lambda p: _read_file_safe(p), local_dir)
                 upload_results = await self.aupload_files([(remote_path, content)], timeout=timeout)
                 if upload_results[0].error:
                     results[local_path] = {"success": 0, "failed": 1, "errors": [{"path": remote_path, "error": upload_results[0].error}]}

sycommon/agent/sandbox/minio_sync.py

@@ -162,7 +162,7 @@ class MinioSyncService(metaclass=SingletonMeta):
             return None
 
     def get_presigned_url(self, object_key: str, expires_days: int = 7) -> Optional[str]:
-        """生成预签名下载 URL"""
+        """生成预签名下载 URL（同步）"""
         if not self._client:
             return None
         try:
@@ -177,8 +177,12 @@ class MinioSyncService(metaclass=SingletonMeta):
                 f"[MinIO] Presigned URL failed: {object_key}, error={e}")
             return None
 
+    async def aget_presigned_url(self, object_key: str, expires_days: int = 7) -> Optional[str]:
+        """异步生成预签名下载 URL"""
+        return await asyncio.to_thread(self.get_presigned_url, object_key, expires_days)
+
     def remove_object(self, object_key: str) -> bool:
-        """从 MinIO 删除文件"""
+        """从 MinIO 删除文件（同步）"""
         if not self._client:
             return False
         try:
@@ -189,12 +193,12 @@ class MinioSyncService(metaclass=SingletonMeta):
             SYLogger.warning(f"[MinIO] Delete failed: {object_key}, error={e}")
             return False
 
-    def remove_prefix(self, prefix: str) -> int:
-        """删除 MinIO 中指定前缀下的所有对象（用于目录删除）
+    async def aremove_object(self, object_key: str) -> bool:
+        """异步从 MinIO 删除文件"""
+        return await asyncio.to_thread(self.remove_object, object_key)
 
-        Returns:
-            删除的对象数量
-        """
+    def remove_prefix(self, prefix: str) -> int:
+        """删除 MinIO 中指定前缀下的所有对象（同步，用于目录删除）"""
         if not self._client:
             return 0
         try:
@@ -210,6 +214,10 @@ class MinioSyncService(metaclass=SingletonMeta):
             SYLogger.warning(f"[MinIO] Delete prefix failed: {prefix}, error={e}")
             return 0
 
+    async def aremove_prefix(self, prefix: str) -> int:
+        """异步删除 MinIO 中指定前缀下的所有对象"""
+        return await asyncio.to_thread(self.remove_prefix, prefix)
+
     # ============== 查找最近副本 ==============
 
     def find_latest_object_key(self, user_id: str, file_path: str) -> Optional[str]:
@@ -252,7 +260,7 @@ class MinioSyncService(metaclass=SingletonMeta):
             SYLogger.warning(f"[MinIO] find_latest failed: {e}")
         return None
 
-    async def afinf_latest_object_key(self, user_id: str, file_path: str) -> Optional[str]:
+    async def afind_latest_object_key(self, user_id: str, file_path: str) -> Optional[str]:
         """异步查找某个文件最近一天的 object key"""
         return await asyncio.to_thread(self.find_latest_object_key, user_id, file_path)
 
@@ -473,12 +481,17 @@ class MinioSyncService(metaclass=SingletonMeta):
             files_to_upload = []
             for rel_path in batch:
                 try:
-                    response = await asyncio.to_thread(
-                        self._client.get_object, self._bucket, f"{prefix}{rel_path}"
+                    def _download_object(bucket, key):
+                        resp = self._client.get_object(bucket, key)
+                        try:
+                            return resp.read()
+                        finally:
+                            resp.close()
+                            resp.release_conn()
+
+                    content = await asyncio.to_thread(
+                        _download_object, self._bucket, f"{prefix}{rel_path}"
                     )
-                    content = response.read()
-                    response.close()
-                    response.release_conn()
                     files_to_upload.append((f"/{rel_path}", content))
                 except Exception as e:
                     SYLogger.warning(f"[MinIO] 下载文件失败: {rel_path}, error={e}")

sycommon/agent/sandbox/sandbox_recovery.py

@@ -123,7 +123,7 @@ class SandboxRecoveryManager:
             bool: 切换成功返回 True，否则返回 False
         """
         # 优先使用底层已有的切换逻辑（会尝试迁移工作空间文件）
-        switched = await self.backend._refresh_from_nacos_and_switch()
+        switched = await asyncio.to_thread(self.backend._refresh_from_nacos_and_switch_sync)
 
         if switched:
             self._consecutive_failures = 0
@@ -149,7 +149,8 @@ class SandboxRecoveryManager:
                 SYLogger.error("[Sandbox] NacosService 未初始化")
                 return False
 
-            instances = nacos_manager.get_service_instances(
+            instances = await asyncio.to_thread(
+                nacos_manager.get_service_instances,
                 self.backend._nacos_service_name,
                 group=self.backend._nacos_group
             )

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/database/async_database_service.py

@@ -1,6 +1,21 @@
 from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
 from sqlalchemy import text
 
+# Fix: aiomysql's AsyncAdapt ping() requires 'reconnect' positional arg,
+# but SQLAlchemy's pymysql dialect calls ping() without it.
+# aiomysql asserts reconnect must be False (async reconnection is handled by pool).
+from sqlalchemy.dialects.mysql.pymysql import MySQLDialect_pymysql
+
+_original_do_ping = MySQLDialect_pymysql.do_ping
+
+def _patched_do_ping(self, dbapi_connection):
+    try:
+        return _original_do_ping(self, dbapi_connection)
+    except TypeError:
+        dbapi_connection.ping(reconnect=False)
+
+MySQLDialect_pymysql.do_ping = _patched_do_ping
+
 from sycommon.config.Config import SingletonMeta
 from sycommon.config.DatabaseConfig import DatabaseConfig, convert_dict_keys
 from sycommon.logging.kafka_log import SYLogger

sycommon/database/pg_checkpoint_service.py

@@ -0,0 +1,132 @@
+"""
+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,
+                    "keepalives": 1,
+                    "keepalives_idle": 30,
+                    "keepalives_interval": 10,
+                    "keepalives_count": 5,
+                },
+                check=AsyncConnectionPool.check_connection,
+            )
+
+            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/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,

sycommon/services.py

@@ -20,6 +20,7 @@ from sycommon.synacos.feign import close_all_feign_sessions
 from sycommon.synacos.feign_client import close_all_feign_client_sessions
 from sycommon.database.elasticsearch_service import ElasticsearchService
 from sycommon.database.redis_service import RedisService
+from sycommon.database.pg_checkpoint_service import PgCheckpointService
 from sycommon.database.database_service import DatabaseService
 from sycommon.xxljob.xxljob_service import XxlJobService
 
@@ -109,6 +110,7 @@ class Services(metaclass=SingletonMeta):
         # 可插拔服务开关（从类变量中继承 plugins() 阶段的设置）
         self._enable_es: bool = Services.__dict__.get('_enable_es', False)
         self._enable_redis: bool = Services.__dict__.get('_enable_redis', False)
+        self._enable_pg: bool = Services.__dict__.get('_enable_pg', False)
         self._enable_sandbox: bool = Services.__dict__.get('_enable_sandbox', False)
         self._enable_xxljob: bool = Services.__dict__.get('_enable_xxljob', False)
 
@@ -148,6 +150,7 @@ class Services(metaclass=SingletonMeta):
         rabbitmq_senders: Optional[List[RabbitMQSendConfig]] = None,
         elasticsearch_service: Optional[Callable[[dict], None]] = None,
         redis_service: Optional[Callable[[dict], None]] = None,
+        pg_checkpoint_service: Optional[Union[bool, dict]] = None,
         sandbox_service: bool = False,
         deep_agent_service: bool = False,
         multi_agent_service: bool = False,
@@ -193,6 +196,7 @@ class Services(metaclass=SingletonMeta):
         # 保存可插拔服务开关状态到类变量（实例创建时会被拷贝到实例变量）
         Services._enable_es = elasticsearch_service is not None
         Services._enable_redis = redis_service is not None
+        Services._enable_pg = pg_checkpoint_service is not None
         Services._enable_sandbox = sandbox_service or deep_agent_service or multi_agent_service
         Services._enable_xxljob = xxljob_service is not None
 
@@ -297,14 +301,19 @@ class Services(metaclass=SingletonMeta):
 
                 app_instance.state.services = instance
 
-                # 4. 启动沙箱后台清理任务（如果沙箱服务启用）
+                # 4. 初始化 PG Checkpoint 服务（如果启用）
+                if instance._enable_pg:
+                    pg_config = pg_checkpoint_service if isinstance(pg_checkpoint_service, dict) else None
+                    await PgCheckpointService.setup(pg_config)
+
+                # 5. 启动沙箱后台清理任务（如果沙箱服务启用）
                 if instance._enable_sandbox:
                     from sycommon.middleware.sandbox import _cleanup_finished_processes
                     sandbox_cleanup_task = asyncio.create_task(
                         _cleanup_finished_processes())
                     logging.info("沙箱后台清理任务已启动")
 
-                # 5. 执行用户定义的生命周期
+                # 6. 执行用户定义的生命周期
                 if cls._user_lifespan:
                     async with cls._user_lifespan(app_instance):
                         yield
@@ -472,6 +481,13 @@ class Services(metaclass=SingletonMeta):
                 except Exception as e:
                     logging.debug(f"关闭 RedisService 时发生异常: {e}")
 
+            # 关闭 PG Checkpoint 服务（仅当启用时）
+            if cls._instance and cls._instance._enable_pg:
+                try:
+                    await PgCheckpointService.close()
+                except Exception as e:
+                    logging.debug(f"关闭 PgCheckpointService 时发生异常: {e}")
+
             # 关闭 XXL-JOB 执行器（仅当启用时）
             if cls._instance and cls._instance._enable_xxljob:
                 try:

sycommon/synacos/feign.py

@@ -203,8 +203,11 @@ async def _feign_internal(service_name, api_path, method='GET', params=None, hea
                     raise TypeError(f"files 参数必须是字典或列表，实际为 {type(files)}")
             if file_path:
                 filename = os.path.basename(file_path)
-                with open(file_path, 'rb') as f:
-                    data.add_field('file', f, filename=filename)
+                def _read_file():
+                    with open(file_path, 'rb') as f:
+                        return f.read()
+                content = await asyncio.to_thread(_read_file)
+                data.add_field('file', content, filename=filename)
             # 移除Content-Type，让aiohttp自动处理
             headers.pop('Content-Type', None)
             async with session.request(

sycommon/synacos/feign_client.py

@@ -303,10 +303,13 @@ def feign_client(
                         for path in file_paths:
                             if not os.path.exists(path):
                                 raise FileNotFoundError(f"文件不存在: {path}")
-                            with open(path, "rb") as f:
-                                form_data.add_field(
-                                    meta.field_name, f.read(), filename=os.path.basename(path)
-                                )
+                            def _read_file(p: str) -> bytes:
+                                with open(p, "rb") as f:
+                                    return f.read()
+                            content = await asyncio.to_thread(_read_file, path)
+                            form_data.add_field(
+                                meta.field_name, content, filename=os.path.basename(path)
+                            )
                     # 处理表单字段（支持 Pydantic 模型）
                     form_params = {
                         n: m for n, m in param_meta.items() if isinstance(m, Form)}

{sycommon_python_lib-0.2.3a12.dist-info → sycommon_python_lib-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.3a12
+Version: 0.2.4
 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,19 @@ 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
+Requires-Dist: psycopg[binary,pool]>=3.3.4
 
 # sycommon-python-lib
 

{sycommon_python_lib-0.2.3a12.dist-info → sycommon_python_lib-0.2.4.dist-info}/RECORD

@@ -125,19 +125,22 @@ sycli/rl/strategy_generator.py,sha256=RzYkaj4jQ_5aNOuj1WA-SXIHfO5h1nTSSHmLZpO-gi
 sycli/rl/strategy_prompts.py,sha256=dwx291OnyywP6z7uKmoDPZNCC4MNrIyDANdAEO0evJs,2873
 sycli/skills/__init__.py,sha256=0o9HuaDSvN-z0JZwlDSwU7WxtchQn7f0OtluIMgtC0Q,212
 sycommon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sycommon/services.py,sha256=N6Z4D-qmdyGBZ5z72j2dtSfpXnrnWjEuSyKCgSIY0Cs,21332
-sycommon/agent/__init__.py,sha256=PXxUiDwdzxv3WQfD8R5MKXtV7qZPvbRc0wPxnS-ZsNQ,3752
+sycommon/services.py,sha256=UtWn36dPmB9g1CTKkNgzbU8M28iOkZd2BtdhvDZLfbk,22214
+sycommon/agent/__init__.py,sha256=mxceAeUifQ-DKvWp7ZEJIFlmOCb5wpYHPGQw3rwEN8I,4378
 sycommon/agent/agent_manager.py,sha256=UhhaekEumT7g4v_Z1UB4jTp13X0n8M8erYaQdkGGWkA,13620
 sycommon/agent/chat_events.py,sha256=bWAMWYIZ2L_yqUcn5jq9ius_lQxLHEv4zQLEqX6UaeM,13190
-sycommon/agent/deep_agent.py,sha256=kqurvSfs4mZAFr-_e2FwIif8J2voV4kSNxHfrBUDOeo,31486
-sycommon/agent/multi_agent_team.py,sha256=6Ba4MbdEDVuXe6iBE_Q84kzr5zJYLo_djdpkkwJhShg,26558
+sycommon/agent/deep_agent.py,sha256=WTGKWx0MxmiIbbrKPTbQl6on2w4LQRWtH0hdiViA-dE,31709
+sycommon/agent/multi_agent_team.py,sha256=NHmsUNwe3huguUUzbeoiOjgo9wh4-eXH0AjPDvm1dP4,26781
 sycommon/agent/summarization_utils.py,sha256=PRCIFtYBrH0bbSxsIc-qpC4iEXJzk72UuR7u5mQTt2w,7360
+sycommon/agent/mcp/__init__.py,sha256=iKrdDhIrFsNIkqG_kgcwNe-nOiM6uVfolKv44LfQ-FQ,636
+sycommon/agent/mcp/models.py,sha256=RBAIbGETNXkqD3wQZT7eKS4ozkgE9DQEneF1WKZf1C0,1355
+sycommon/agent/mcp/tool_loader.py,sha256=SEny14f7Bm9I17pT-9PJWMbhi9Ki77wvCR0KRNEJmyM,6428
 sycommon/agent/sandbox/__init__.py,sha256=jR7LlkD4J4Y6QYyRXQClkwmqDBCCPmycV_hQV9p9YHw,4621
 sycommon/agent/sandbox/file_ops.py,sha256=6ymRMM0WchM7G_YmF1ckrLjf5s_JCh1wrAp2g_-sg8k,23162
-sycommon/agent/sandbox/http_sandbox_backend.py,sha256=mjiTZnADvUq_rO05ewllo_eGDS4uTdD2e2GGYvBpF-Q,56150
-sycommon/agent/sandbox/minio_sync.py,sha256=r6tjoQA8AHNVG_hcHS3enfFnw-eTkW4r7jA7bwatsWc,19241
+sycommon/agent/sandbox/http_sandbox_backend.py,sha256=kwuPEmrOMyxfrRu20AEGqWD9t38L-DrtKSFp6CWt44o,56877
+sycommon/agent/sandbox/minio_sync.py,sha256=d1kuWllvyAvAMsFZCP0OdHEQtXN9BEIgHbupC31BjSk,20000
 sycommon/agent/sandbox/sandbox_pool.py,sha256=eMn8sLakCWf90l6ni2-333QM8oBdX1CflV-WzneFp_k,9133
-sycommon/agent/sandbox/sandbox_recovery.py,sha256=VDhFI1q9DzSs5B3s2gee1mTmXQoxs0UCXzDrqNQ7VBY,7295
+sycommon/agent/sandbox/sandbox_recovery.py,sha256=X-eDODx1tmGMh_iTngV6e1ppfDBHpTdkPreJusN5MHY,7358
 sycommon/agent/sandbox/session.py,sha256=TjzC3yFC-VaJ75UwCyL26QX4PRTGNNfQae1FKFuOsYI,2365
 sycommon/auth/__init__.py,sha256=W814cfHlLXFymmxeTi3pIreFb4nhKnQ7NY1H38x1Gic,974
 sycommon/auth/ldap_service.py,sha256=fOcpVov5LWJkBk62qbTaltks1c4la7JsbD104KfdBOI,10102
@@ -149,16 +152,18 @@ sycommon/config/EmbeddingConfig.py,sha256=gPKwiDYbeu1GpdIZXMmgqM7JqBIzCXi0yYuGRL
 sycommon/config/LLMConfig.py,sha256=pjMiUgsUaKHw6WNi3weL2ilE9nFua5MkXg96kgwtuzY,510
 sycommon/config/LangfuseConfig.py,sha256=t2LulAtnMUvIINOKHXNWlT5PtgNb7IuaHURjWlbma38,370
 sycommon/config/MQConfig.py,sha256=_RDcmIdyWKjmgM5ZnriOoI-DpaxgXs7CD0awdAD6z88,252
+sycommon/config/PgConfig.py,sha256=Hs9LwgIxSBxcFP16oq18N6Gq9hU2qVl4-7bPfd-ON_s,2333
 sycommon/config/RedisConfig.py,sha256=gIa4BS8L_HdmBg9Dkv3cuIK6CU9zt9RodZOJUuUlh5Y,5235
 sycommon/config/RerankerConfig.py,sha256=35sVwzus2IscvTHnCG63Orl2pC-pMsrVi6wAGDmOH3U,341
 sycommon/config/SentryConfig.py,sha256=OsLb3G9lTsCSZ7tWkcXWJHmvfILQopBxje5pjnkFJfo,320
 sycommon/config/XxlJobConfig.py,sha256=VSG6dn9ysfUVunOs7PqugyZUGJWmX_cEePz2ZCfqHtU,392
 sycommon/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sycommon/database/async_base_db_service.py,sha256=w6ONUiTtF4-bXRnkBt9QpL9BAy0XUDbQG7F9Hf2rfjw,1337
-sycommon/database/async_database_service.py,sha256=HZSV0ntVTteT-VZfkM9dwuld-gN5CY_T3lE5wwUpDck,4307
+sycommon/database/async_database_service.py,sha256=Cf3RaO3skP6IAJrkta-CRE-Q1NtjWLPLUe9hazB8LRM,4873
 sycommon/database/base_db_service.py,sha256=J5ELHMNeGfzA6zVcASPSPZ0XNKrRY3_gdGmVkZw3Mto,946
 sycommon/database/database_service.py,sha256=IMoJ9554dYkr6QfRofvNa0VR24U1WQDz_ATrg0-6EQ0,3857
 sycommon/database/elasticsearch_service.py,sha256=qm490GRlxZlYsQgyfyclSbARRP1-Tc4Lwav3lbPINvQ,3092
+sycommon/database/pg_checkpoint_service.py,sha256=LCwJ9ZADIXkE715Fi3ySkNDDwlY3PC6ZSi34ZYXzBbs,4418
 sycommon/database/redis_service.py,sha256=tPw8UgeuyYQBxWfPRjx7VqlSRFNxIsnR0WSGd36GaA8,20509
 sycommon/database/token_usage_db_service.py,sha256=_hoeB4lYPhDOlJLaUIHIl7z-DNpzsRYrPn5oboD1Y38,6254
 sycommon/health/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -171,7 +176,7 @@ sycommon/heartbeat_process/heartbeat_process_manager.py,sha256=24qUKs8qegdWHqcox
 sycommon/heartbeat_process/heartbeat_process_worker.py,sha256=duuAEFwda43Y6pZE8tOOspitlyxecaFsg1n1iH9jQDQ,16863
 sycommon/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sycommon/llm/embedding.py,sha256=Xwmg1HcgbdW7OcpYyzu8k7U-27rC5lzjIqbg221CcyY,19129
-sycommon/llm/get_llm.py,sha256=CQy_T3y4tLeWu3pn6LNbIdhByQVwhoD2pgk2rY3lUVo,7615
+sycommon/llm/get_llm.py,sha256=9F2EJhP3ujbk78h1jW8T9Jafb-79U2QAUutYaSbTHvY,7572
 sycommon/llm/llm_logger.py,sha256=LLXiESwDP5f8dB50nFabShVoLKv8UCf2ll69zo1FOso,3365
 sycommon/llm/llm_tokens.py,sha256=yGEessxfk5wRMrPGyWHhiiIIQFDVT23FSaqnwqHGCoY,4712
 sycommon/llm/llm_with_token_tracking.py,sha256=vrdH5LlXg1y2glDPJVawT9A-JoXL9qnvMfHAU3CNy70,12928
@@ -234,8 +239,8 @@ sycommon/sse/sse.py,sha256=OQ3ElV8WCi-AD3-e0nbiUF28Syf6GRpGztneWTn77EM,10356
 sycommon/synacos/__init__.py,sha256=Re9YKVjL62AZURejgSQ3-OvIiMXY-KeAAjIcRJ8PsO0,329
 sycommon/synacos/example.py,sha256=FOnBkvodR8WF_jf-RovM3ngVmvZQX6wKwMLscUTGn2M,8707
 sycommon/synacos/example2.py,sha256=yYuQscfHUIl1HLZ8kSRBuZpHUcNWZMi5H3Mb-LjYnvk,8136
-sycommon/synacos/feign.py,sha256=kWnKPyWNUGOTIsmdJvn_Ch7Nm5essjsnX4bS7udmlQQ,12468
-sycommon/synacos/feign_client.py,sha256=nD8Ar8n0NOy5wzaWKe_8MxV76-UuuoaBV_Q5BxOriTI,19736
+sycommon/synacos/feign.py,sha256=RU6p2gRP3LZoHYBBEUUY9z5KKzGiUmwj4qdo7aF9UNA,12610
+sycommon/synacos/feign_client.py,sha256=i6O20JWl1g2fjD-et7olFaO-0z2yEbKT8-pKluAHCgs,19917
 sycommon/synacos/nacos_client_base.py,sha256=iP5kLkBD2VOrx6X8v6_RnC9NWiBWmL6-Bgf493QOtxc,6899
 sycommon/synacos/nacos_config_manager.py,sha256=Swqsd9X2xO5-x2VfKUrq8HjzRJn8JBPDqyXazWlF-T4,6859
 sycommon/synacos/nacos_heartbeat_manager.py,sha256=LfimUKpG4KaqsVQl150sg3MLK8psanuUwQ07tjL3uBE,10963
@@ -260,8 +265,8 @@ sycommon/tools/syemail.py,sha256=BDFhgf7WDOQeTcjxJEQdu0dQhnHFPO_p3eI0-Ni3LhQ,561
 sycommon/tools/timing.py,sha256=OiiE7P07lRoMzX9kzb8sZU9cDb0zNnqIlY5pWqHcnkY,2064
 sycommon/xxljob/__init__.py,sha256=7eoBlQxv-B39IfRSCY2bkqdGYs1QRe1umAWd88VMEEM,86
 sycommon/xxljob/xxljob_service.py,sha256=JIEJaGXhqrTLcyxlyynSrsHg9bBnDNzX-D4qIWLRPUE,6815
-sycommon_python_lib-0.2.3a12.dist-info/METADATA,sha256=rYtKZ2a0grUZCW9fS8I4H9VLyq7-afwpNGILQvY2DPs,7740
-sycommon_python_lib-0.2.3a12.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-sycommon_python_lib-0.2.3a12.dist-info/entry_points.txt,sha256=gsR4SssKxDWjRU8ggidzNcdMXDPRSKRS7UaGyNP84Qg,92
-sycommon_python_lib-0.2.3a12.dist-info/top_level.txt,sha256=RgphKrg7nJyZ7irJqbxFr-5H2LUYTvI7ivoWZH2hcD0,29
-sycommon_python_lib-0.2.3a12.dist-info/RECORD,,
+sycommon_python_lib-0.2.4.dist-info/METADATA,sha256=EvJmf8i4ZkIwoaj0n_KVTUHnAeBGXKF2mI1kjU4EKnI,7877
+sycommon_python_lib-0.2.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sycommon_python_lib-0.2.4.dist-info/entry_points.txt,sha256=gsR4SssKxDWjRU8ggidzNcdMXDPRSKRS7UaGyNP84Qg,92
+sycommon_python_lib-0.2.4.dist-info/top_level.txt,sha256=RgphKrg7nJyZ7irJqbxFr-5H2LUYTvI7ivoWZH2hcD0,29
+sycommon_python_lib-0.2.4.dist-info/RECORD,,