fiuai-sdk-python 0.11.9__tar.gz → 0.12.0__tar.gz

fiuai_sdk_python-0.12.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- 新增结构化错误处理: `ApiError` model + `FiuaiErrorCode` 枚举
+  - `ApiError` 字段: `code` / `type` / `message` / `detail` / `context` / `http_status_code` / `traceback`
+  - `FiuaiErrorCode` 提供稳定错误码枚举 (跨语言/跨版本不变), 与 frappe 二开侧 codes.py 对齐
+- `ApiResponse` 新增字段:
+  - `error: ApiError | None` - 主错误 (errors[0] 规整后)
+  - `errors: list[ApiError]` - 所有错误项
+  - `warnings: list[str]` - 非错误的提示文案
+  - `raw: dict` - 原始 frappe response (调试用)
+- SDK 内置兜底解析器 `error_parsers.py`, 服务端没补 `errors[].context` 时自动从 frappe 异常字符串提取 doctype/name/fields
+- 网络层异常 (`response=None` / 非 JSON / 非 dict body) 也统一走 `ApiError`, code 为 `NETWORK_ERROR` / `API_INVALID_JSON` / `API_NO_RESPONSE`
+- frappe `messages[]` 中红色友好文案 (启发式: indicator=red / title=错误 / 文本以"错误:"开头 / raise_exception 标记) 自动合并到主 `ApiError.message`
+
+### Changed
+- `parse_response` 重写, 返回的 `ApiResponse` 始终包含结构化 `error` 字段, 一定不会抛异常
+- `_is_api_success` 修复: `data is None` 不再判失败, `delete` / `cancel` 等正常返回 None 的接口不会被误判
+
+### Deprecated
+- `ApiResponse.error_code` / `ApiResponse.error_message` 改为派生 property, 访问触发 `DeprecationWarning`
+  - 迁移路径:
+    - `resp.error_message[0]` → `resp.error.message`
+    - `resp.error_code[0]` → `resp.error.code`
+  - 下个 major 版本将移除
+
+### Removed
+- N/A
+
+### Fixed
+- `parse_response` 在 HTTP 502/504 等代理层 HTML 错误时不再 silent fallback, 返回 code=`API_INVALID_JSON` 的结构化 ApiError
+- `_extract_error_info` 中无意义的 try/except 包装移除
+
+### Security
+- N/A
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release
+- Basic SDK structure and functionality

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiuai_sdk_python
-Version: 0.11.9
+Version: 0.12.0
 Summary: FiuAI Python SDK - 企业级AI服务集成开发工具包
 Project-URL: Homepage, https://github.com/fiuai/fiuai-sdk-python
 Project-URL: Documentation, https://github.com/fiuai/fiuai-sdk-python#readme

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fiuai_sdk_python"
-version = "0.11.9"
+version = "0.12.0"
 description = "FiuAI Python SDK - 企业级AI服务集成开发工具包"
 readme = "README.md"
 requires-python = ">=3.12"

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.12.0}/src/fiuai_sdk_python/__init__.py

@@ -10,6 +10,13 @@ from .context import (
     is_current_context_valid,
     get_trace_id,
 )
+from .error_code import (
+    EXCEPTION_TO_CODE,
+    FiuaiErrorCode,
+    exception_to_code,
+    status_code_to_code,
+)
+from .resp import ApiError, ApiResponse, parse_response
 
 __version__ = "0.11.6"
 
@@ -25,4 +32,11 @@ __all__ = [
     'get_current_missing_fields',
     'is_current_context_valid',
     'get_trace_id',
+    'ApiError',
+    'ApiResponse',
+    'parse_response',
+    'FiuaiErrorCode',
+    'EXCEPTION_TO_CODE',
+    'exception_to_code',
+    'status_code_to_code',
 ]

fiuai_sdk_python-0.12.0/src/fiuai_sdk_python/_resp_helpers.py

@@ -0,0 +1,163 @@
+# -- coding: utf-8 --
+# Project: fiuai_sdk_python
+# Created Date: 2026-05-09
+# Author: liming
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+"""
+resp.py 的内部 helper 集合.
+
+不是公开 API, 不要从外部直接 import. 拆出来仅为了控制 resp.py 行数 (单文件 < 400 行规约).
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from httpx import Response
+
+logger = logging.getLogger(__name__)
+
+
+# --------------------------------------------------------------------------
+# 响应体读取 (用于 JSON 解析失败时的日志/预览)
+# --------------------------------------------------------------------------
+
+
+def get_response_body_preview(response: Response, max_chars: int = 300) -> str:
+    """安全读取响应体前若干字符, 用于错误信息预览. 兼容编码问题及中文."""
+    try:
+        raw = response.content
+        if not raw:
+            return ""
+        text = raw.decode("utf-8", errors="replace").strip()
+        if len(text) > max_chars:
+            text = text[:max_chars] + "..."
+        return text
+    except Exception:
+        return ""
+
+
+def get_response_body_for_log(response: Response, max_chars: int = 2000) -> str:
+    """安全读取完整响应体用于日志, 避免编码异常, 支持中文."""
+    try:
+        raw = response.content
+        if not raw:
+            return "(empty)"
+        text = raw.decode("utf-8", errors="replace").strip()
+        if len(text) > max_chars:
+            text = text[:max_chars] + "...(truncated)"
+        return text
+    except Exception as ex:
+        return f"(decode error: {ex})"
+
+
+# --------------------------------------------------------------------------
+# 业务成功判定
+# --------------------------------------------------------------------------
+
+
+def is_api_success(response_data: Dict[str, Any]) -> bool:
+    """判断 API 业务是否成功.
+
+    与旧版的差异:
+    - 不再要求"必须有 data 才算成功". delete/cancel 等接口正常返回 None 不会被误判
+    - 仅依据 errors / exc / http_status_code (frappe 内嵌) 判定
+    """
+    if not isinstance(response_data, dict):
+        return False
+    if response_data.get("errors"):
+        return False
+    if response_data.get("exc"):
+        return False
+    inner_status = response_data.get("http_status_code")
+    if inner_status is not None:
+        try:
+            return 200 <= int(inner_status) < 300
+        except (TypeError, ValueError):
+            return False
+    return True
+
+
+def extract_success_data(response_data: Dict[str, Any]) -> Any:
+    """从成功响应中提取数据. 优先 data 字段, 其次 messages 字段."""
+    data = response_data.get("data")
+    if data is not None:
+        return data
+    messages = response_data.get("messages")
+    if messages is not None:
+        return messages
+    return None
+
+
+# --------------------------------------------------------------------------
+# messages 红色 / warning 启发式分流
+# --------------------------------------------------------------------------
+
+
+_RED_INDICATOR = "red"
+_ERROR_TITLES = {"错误", "Error", "ERROR"}
+# frappe _get_missing_mandatory_fields() 等默认友好文案的前缀, 用于启发式判定:
+# "Error: Value missing for ..." / "错误: ..." / "错误：..." (中文全角冒号)
+_ERROR_TEXT_PREFIXES = ("错误:", "错误：", "Error:", "ERROR:", "error:")
+
+
+def _is_error_message(msg: Dict[str, Any]) -> bool:
+    """判定一条 message 是否是错误补充文案 (vs 普通提示).
+
+    frappe 在调用 ``frappe.throw`` / ``MandatoryError`` 时, 默认 msgprint 不设
+    indicator 也不设 title, 但 message 文本本身会以 ``错误:`` / ``Error:`` 开头.
+    所以判定要走多重启发式:
+    1. ``indicator == "red"``
+    2. ``title in {"错误", "Error", "ERROR"}``
+    3. ``raise_exception`` 标记
+    4. message 文本以错误前缀开头
+    """
+    if (msg.get("indicator") or "").strip().lower() == _RED_INDICATOR:
+        return True
+    if (msg.get("title") or "").strip() in _ERROR_TITLES:
+        return True
+    if msg.get("raise_exception"):
+        return True
+    text = (msg.get("message") or "").strip()
+    return text.startswith(_ERROR_TEXT_PREFIXES)
+
+
+def split_messages(raw_messages: Any) -> tuple[List[str], List[str]]:
+    """把 frappe messages[] 拆成 (error_texts, warning_texts).
+
+    判定基于 ``_is_error_message`` 多重启发式 (indicator=red / title=错误 / message
+    文本以 "错误:" / "Error:" 开头 / raise_exception 标记). 命中即归错误文案,
+    否则进 warnings.
+    """
+    error_texts: List[str] = []
+    warnings: List[str] = []
+    if not isinstance(raw_messages, list):
+        return error_texts, warnings
+
+    for msg in raw_messages:
+        if not isinstance(msg, dict):
+            text = str(msg).strip()
+            if text:
+                warnings.append(text)
+            continue
+        text = (msg.get("message") or "").strip()
+        if not text:
+            continue
+        if _is_error_message(msg):
+            error_texts.append(text)
+        else:
+            warnings.append(text)
+
+    return error_texts, warnings
+
+
+def merge_error_message(primary: str, extras: List[str]) -> str:
+    """把 frappe messages 里的友好文案合并到主错误 message, 去重去空."""
+    pieces: List[str] = []
+    if primary:
+        pieces.append(primary)
+    for extra in extras:
+        if extra and extra not in pieces:
+            pieces.append(extra)
+    return "; ".join(pieces)

fiuai_sdk_python-0.12.0/src/fiuai_sdk_python/error_code.py

@@ -0,0 +1,145 @@
+# -- coding: utf-8 --
+# Project: fiuai_sdk_python
+# Created Date: 2026-05-09
+# Author: liming
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+"""
+统一错误码定义.
+
+设计原则:
+- 错误码本身是稳定枚举字符串, 不随 i18n / frappe 异常类名变化
+- 与 frappe 二开侧 frappe/fiuai_utils/api/error/codes.py 保持一一对应
+- SDK 在没有服务端规整的旧 frappe 上仍能凭 frappe 异常类名兜底映射出错误码
+
+调用方使用方式:
+    from fiuai_sdk_python.error_code import FiuaiErrorCode, exception_to_code
+
+    if resp.error and resp.error.code == FiuaiErrorCode.MANDATORY_FIELD_MISSING:
+        ...
+"""
+
+from enum import StrEnum
+
+
+class FiuaiErrorCode(StrEnum):
+    """业务错误码枚举.
+
+    命名约定: 大写下划线, 语义明确, 不带前缀.
+    新增错误码时必须同步 frappe/fiuai_utils/api/error/codes.py.
+    """
+
+    MANDATORY_FIELD_MISSING = "MANDATORY_FIELD_MISSING"
+    LINK_INVALID = "LINK_INVALID"
+    LINK_EXISTS = "LINK_EXISTS"
+    DUPLICATE_ENTRY = "DUPLICATE_ENTRY"
+    DOC_NOT_FOUND = "DOC_NOT_FOUND"
+    TIMESTAMP_MISMATCH = "TIMESTAMP_MISMATCH"
+    DOCSTATUS_TRANSITION_ERROR = "DOCSTATUS_TRANSITION_ERROR"
+    UPDATE_AFTER_SUBMIT = "UPDATE_AFTER_SUBMIT"
+    CANCELLED_LINK = "CANCELLED_LINK"
+
+    PERMISSION_DENIED = "PERMISSION_DENIED"
+    AUTHENTICATION_ERROR = "AUTHENTICATION_ERROR"
+    CSRF_TOKEN_ERROR = "CSRF_TOKEN_ERROR"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+
+    INTERNAL_VALIDATION_ERROR = "INTERNAL_VALIDATION_ERROR"
+    INTERNAL_API_ERROR = "INTERNAL_API_ERROR"
+
+    NETWORK_ERROR = "NETWORK_ERROR"
+    API_NO_RESPONSE = "API_NO_RESPONSE"
+    API_INVALID_JSON = "API_INVALID_JSON"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+    SERVER_ERROR = "SERVER_ERROR"
+
+    UNKNOWN = "UNKNOWN"
+
+
+# Frappe 异常类名 -> FiuaiErrorCode 映射. 用于 SDK 在服务端没补 code 时兜底
+# Key 必须是 frappe 异常的 __name__, 见 frappe/exceptions.py
+EXCEPTION_TO_CODE: dict[str, FiuaiErrorCode] = {
+    "MandatoryError": FiuaiErrorCode.MANDATORY_FIELD_MISSING,
+    "LinkValidationError": FiuaiErrorCode.LINK_INVALID,
+    "LinkExistsError": FiuaiErrorCode.LINK_EXISTS,
+    "CancelledLinkError": FiuaiErrorCode.CANCELLED_LINK,
+    "DuplicateEntryError": FiuaiErrorCode.DUPLICATE_ENTRY,
+    "UniqueValidationError": FiuaiErrorCode.DUPLICATE_ENTRY,
+    "DoesNotExistError": FiuaiErrorCode.DOC_NOT_FOUND,
+    "PageDoesNotExistError": FiuaiErrorCode.DOC_NOT_FOUND,
+    "TimestampMismatchError": FiuaiErrorCode.TIMESTAMP_MISMATCH,
+    "DocstatusTransitionError": FiuaiErrorCode.DOCSTATUS_TRANSITION_ERROR,
+    "UpdateAfterSubmitError": FiuaiErrorCode.UPDATE_AFTER_SUBMIT,
+    "PermissionError": FiuaiErrorCode.PERMISSION_DENIED,
+    "AuthenticationError": FiuaiErrorCode.AUTHENTICATION_ERROR,
+    "SessionExpired": FiuaiErrorCode.AUTHENTICATION_ERROR,
+    "CSRFTokenError": FiuaiErrorCode.CSRF_TOKEN_ERROR,
+    "TooManyRequestsError": FiuaiErrorCode.RATE_LIMIT_EXCEEDED,
+    "RateLimitExceededError": FiuaiErrorCode.RATE_LIMIT_EXCEEDED,
+    "ValidationError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "DataError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "InvalidStatusError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "EmptyTableError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "InvalidEmailAddressError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "InvalidNameError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "InvalidPhoneNumberError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "InvalidSignatureError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "NonNegativeError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "CharacterLengthExceededError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "CannotChangeConstantError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "MappingMismatchError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "FrappeTypeError": FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    "InReadOnlyMode": FiuaiErrorCode.SERVICE_UNAVAILABLE,
+    "SessionStopped": FiuaiErrorCode.SERVICE_UNAVAILABLE,
+}
+
+# HTTP 状态码兜底映射. 仅在 frappe 没返回 errors[].type 或 type 不在表里时用
+STATUS_CODE_TO_CODE: dict[int, FiuaiErrorCode] = {
+    400: FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    401: FiuaiErrorCode.AUTHENTICATION_ERROR,
+    403: FiuaiErrorCode.PERMISSION_DENIED,
+    404: FiuaiErrorCode.DOC_NOT_FOUND,
+    409: FiuaiErrorCode.DUPLICATE_ENTRY,
+    410: FiuaiErrorCode.SERVICE_UNAVAILABLE,
+    415: FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    417: FiuaiErrorCode.INTERNAL_VALIDATION_ERROR,
+    429: FiuaiErrorCode.RATE_LIMIT_EXCEEDED,
+    500: FiuaiErrorCode.SERVER_ERROR,
+    502: FiuaiErrorCode.NETWORK_ERROR,
+    503: FiuaiErrorCode.SERVICE_UNAVAILABLE,
+    504: FiuaiErrorCode.NETWORK_ERROR,
+    508: FiuaiErrorCode.SERVER_ERROR,
+}
+
+
+def exception_to_code(exception_type: str | None) -> FiuaiErrorCode:
+    """根据 frappe 异常类名返回对应错误码, 找不到返回 UNKNOWN.
+
+    Args:
+        exception_type: frappe 异常类名, 例如 "MandatoryError"
+
+    Returns:
+        FiuaiErrorCode: 对应的稳定错误码
+    """
+    if not exception_type:
+        return FiuaiErrorCode.UNKNOWN
+    return EXCEPTION_TO_CODE.get(exception_type, FiuaiErrorCode.UNKNOWN)
+
+
+def status_code_to_code(http_status_code: int | None) -> FiuaiErrorCode:
+    """根据 HTTP 状态码兜底返回错误码.
+
+    用在 frappe 没返回结构化 errors 时 (例如代理层 502/504, 或 frappe 老版本).
+
+    Args:
+        http_status_code: HTTP 状态码
+
+    Returns:
+        FiuaiErrorCode: 兜底错误码
+    """
+    if http_status_code is None:
+        return FiuaiErrorCode.UNKNOWN
+    if 200 <= http_status_code < 300:
+        return FiuaiErrorCode.UNKNOWN
+    return STATUS_CODE_TO_CODE.get(http_status_code, FiuaiErrorCode.SERVER_ERROR)

fiuai_sdk_python-0.12.0/src/fiuai_sdk_python/error_parsers.py

@@ -0,0 +1,122 @@
+# -- coding: utf-8 --
+# Project: fiuai_sdk_python
+# Created Date: 2026-05-09
+# Author: liming
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+"""
+Frappe 异常字符串 -> 结构化 context 的兜底解析器.
+
+Frappe v15 在 errors[] 数组里只塞 type/message 字符串, 不带结构化字段.
+SDK 这里用正则把高频的 frappe 异常字符串解析成 dict, 给业务侧拿到 doctype / name / fields.
+
+如果服务端 (frappe 二开层 normalizer) 已经写好 errors[].context 结构化字段,
+SDK 不会再走兜底, 直接用服务端的 context.
+
+设计原则:
+- 解析失败永远返回空 dict, 不抛异常 (兜底必须健壮)
+- 仅覆盖 frappe 原生异常常见字符串格式, 不做猜测式正则
+"""
+
+import re
+from typing import Any
+
+# MandatoryError: 来自 frappe/model/document.py:994
+#   raise frappe.MandatoryError(
+#       "[{doctype}, {name}]: {fields}".format(...)
+#   )
+# 实际字符串: "[Item, 7384919604195962880]: stock_uom"
+# 多字段: "[Item, 7384919604195962880]: stock_uom, item_group"
+_MANDATORY_RE = re.compile(
+    r"^\s*\[\s*(?P<doctype>[^,\]]+)\s*,\s*(?P<name>[^\]]+)\s*\]\s*:\s*(?P<fields>.+?)\s*$"
+)
+
+# DuplicateEntryError: 来自 frappe/model/base_document.py:675
+#   raise frappe.DuplicateEntryError(self.doctype, self.name, e)
+# str(exc) 一般会输出: "('Item', 'Test Item', IntegrityError(...))" (NameError 子类)
+# 也可能是 frappe.throw 包装后的 HTML 文案, 这里仅尝试 tuple 形式
+_DUPLICATE_RE = re.compile(
+    r"^\s*\(\s*['\"](?P<doctype>[^'\"]+)['\"]\s*,\s*['\"](?P<name>[^'\"]+)['\"]"
+)
+
+# LinkValidationError / LinkExistsError: 没有稳定字符串格式 (大多是 _() 翻译过的 HTML),
+# 不做正则解析, 仅返回原文给上层做日志
+
+
+def parse_mandatory_error_message(message: str) -> dict[str, Any]:
+    """解析 MandatoryError 字符串提取 doctype / name / fields.
+
+    Args:
+        message: errors[].message 字符串, 例如 "[Item, 7384919604195962880]: stock_uom"
+
+    Returns:
+        dict: {"doctype": str, "name": str, "fields": list[str]} 或 {} (解析失败)
+    """
+    if not message or not isinstance(message, str):
+        return {}
+
+    m = _MANDATORY_RE.match(message)
+    if not m:
+        return {}
+
+    fields = [f.strip() for f in m.group("fields").split(",") if f.strip()]
+    return {
+        "doctype": m.group("doctype").strip(),
+        "name": m.group("name").strip(),
+        "fields": fields,
+    }
+
+
+def parse_duplicate_entry_error_message(message: str) -> dict[str, Any]:
+    """解析 DuplicateEntryError 字符串提取 doctype / name.
+
+    Args:
+        message: errors[].message 字符串
+
+    Returns:
+        dict: {"doctype": str, "name": str} 或 {}
+    """
+    if not message or not isinstance(message, str):
+        return {}
+
+    m = _DUPLICATE_RE.match(message)
+    if not m:
+        return {}
+
+    return {
+        "doctype": m.group("doctype").strip(),
+        "name": m.group("name").strip(),
+    }
+
+
+# 异常类名 -> 解析器函数 路由表
+# 服务端没补 context 时, SDK 自动按 type 选解析器
+_PARSER_MAP = {
+    "MandatoryError": parse_mandatory_error_message,
+    "DuplicateEntryError": parse_duplicate_entry_error_message,
+    "UniqueValidationError": parse_duplicate_entry_error_message,
+}
+
+
+def parse_error_context(exception_type: str | None, message: str | None) -> dict[str, Any]:
+    """根据异常类型选解析器, 兜底返回空 dict.
+
+    Args:
+        exception_type: frappe 异常类名
+        message: errors[].message 字符串
+
+    Returns:
+        dict: 结构化 context, 解析失败返回 {}
+    """
+    if not exception_type or not message:
+        return {}
+
+    parser = _PARSER_MAP.get(exception_type)
+    if parser is None:
+        return {}
+
+    try:
+        return parser(message)
+    except Exception:
+        return {}

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.12.0}/src/fiuai_sdk_python/pkg/cache/redis_manager.py

@@ -6,7 +6,7 @@
 # Email: lmlala@aliyun.com
 # Copyright (c) 2025 FiuAI
 
-from typing import Dict, List, Set, Tuple, Type
+from typing import Dict, List, Set
 
 from pydantic import BaseModel, Field
 from redis import ConnectionPool as SyncConnectionPool
@@ -20,6 +20,17 @@ from ...utils.text import safe_str
 logger = get_logger(__name__)
 
 
+def _import_langgraph_redis_savers():
+    try:
+        from langgraph.checkpoint.redis import AsyncRedisSaver, RedisSaver
+    except ImportError as exc:
+        raise ImportError(
+            "LangGraph Redis checkpoint is optional; install the SDK with extra [langgraph], "
+            "for example: pip install 'fiuai_sdk_python[langgraph]'"
+        ) from exc
+    return RedisSaver, AsyncRedisSaver
+
+
 class RedisDBConfig(BaseModel):
     name: str = Field(description="连接名称")
     host: str = Field(description="Redis主机")
@@ -114,7 +125,7 @@ class RedisManager:
 
     def setup_langgraph_checkpoint(self, db_name: str):
         """按需初始化 LangGraph checkpoint (仅 Agent 场景需要, lazy import)"""
-        from langgraph.checkpoint.redis import RedisSaver
+        RedisSaver, _ = _import_langgraph_redis_savers()
 
         pool = self._sync_pools.get(db_name)
         if not pool:
@@ -127,7 +138,7 @@ class RedisManager:
 
     async def setup_langgraph_checkpoint_async(self, db_name: str):
         """异步版 LangGraph checkpoint 初始化"""
-        from langgraph.checkpoint.redis import AsyncRedisSaver
+        _, AsyncRedisSaver = _import_langgraph_redis_savers()
 
         pool = self._async_pools.get(db_name)
         if not pool: