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

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

@@ -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 → sycommon_python_lib-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.3a12"
+version = "0.2.4"
 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,19 @@ 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",
+    "psycopg[binary,pool]>=3.3.4",
 ]
 
 [tool.setuptools]

{sycommon_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4}/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.4}/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.4/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.4/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.4/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.4}/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.3a12 → sycommon_python_lib-0.2.4}/src/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_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4}/src/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_python_lib-0.2.3a12 → sycommon_python_lib-0.2.4}/src/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_python_lib-0.2.4/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}"