sycommon-python-lib 0.2.10a8__tar.gz → 0.2.10a10__tar.gz

{sycommon_python_lib-0.2.10a8 → sycommon_python_lib-0.2.10a10}/PKG-INFO

@@ -1,24 +1,24 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.10a8
+Version: 0.2.10a10
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: aio-pika==10.0.1
-Requires-Dist: aiohttp==3.14.3
+Requires-Dist: aio-pika==10.1.0
+Requires-Dist: aiohttp==3.14.4
 Requires-Dist: aiomysql==0.3.2
-Requires-Dist: anyio==4.14.2
+Requires-Dist: anyio==4.15.1
 Requires-Dist: decorator==5.3.1
-Requires-Dist: deepagents==0.7.6
-Requires-Dist: elasticsearch==9.5.0
-Requires-Dist: fastapi==0.141.1
+Requires-Dist: deepagents==0.7.23
+Requires-Dist: elasticsearch==9.5.1
+Requires-Dist: fastapi==0.143.0
 Requires-Dist: jinja2==3.1.6
 Requires-Dist: kafka-python==3.0.11
-Requires-Dist: langchain==1.3.18
-Requires-Dist: langchain-core==1.6.1
-Requires-Dist: langchain-openai==1.6.0
-Requires-Dist: langfuse==4.15.1
-Requires-Dist: langgraph==1.2.11
+Requires-Dist: langchain==1.4.4
+Requires-Dist: langchain-core==1.6.9
+Requires-Dist: langchain-openai==1.7.0
+Requires-Dist: langfuse==4.17.0
+Requires-Dist: langgraph==1.2.14
 Requires-Dist: langgraph-checkpoint-postgres==3.1.2
 Requires-Dist: langgraph-checkpoint-redis==0.5.2
 Requires-Dist: ldap3==2.9.1
@@ -27,24 +27,24 @@ Requires-Dist: mysql-connector-python==26.7.0
 Requires-Dist: nacos-sdk-python<3.0,==2.0.11
 Requires-Dist: psutil==7.2.2
 Requires-Dist: pyxxl==0.4.8
-Requires-Dist: pydantic==2.13.5
-Requires-Dist: python-dotenv==1.2.3
+Requires-Dist: pydantic==2.14.0
+Requires-Dist: python-dotenv==1.2.4
 Requires-Dist: python-multipart==0.0.32
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: redis==7.4.0
-Requires-Dist: sentry-sdk[fastapi]==2.68.1
-Requires-Dist: sqlalchemy[asyncio]==2.0.52
-Requires-Dist: starlette[full]==1.6.0
+Requires-Dist: sentry-sdk[fastapi]==2.71.0
+Requires-Dist: sqlalchemy[asyncio]==2.1.4
+Requires-Dist: starlette[full]==1.7.0
 Requires-Dist: tiktoken==0.14.0
-Requires-Dist: uvicorn==0.52.4
+Requires-Dist: uvicorn==0.54.0
 Requires-Dist: wecom-aibot-python-sdk==1.0.2
 Requires-Dist: twine==7.0.0
 Requires-Dist: minio==7.2.20
 Requires-Dist: langchain-mcp-adapters==0.3.2
 Requires-Dist: fastapi-mcp==0.4.0
-Requires-Dist: psycopg[binary,pool]==3.3.5
-Requires-Dist: agent-client-protocol==0.11.0
-Requires-Dist: langchain-acp==1.7.0
+Requires-Dist: psycopg[binary,pool]==3.3.6
+Requires-Dist: agent-client-protocol==0.12.1
+Requires-Dist: langchain-acp==1.10.0
 Requires-Dist: pypinyin==0.55.0
 
 # sycommon-python-lib

{sycommon_python_lib-0.2.10a8 → sycommon_python_lib-0.2.10a10}/pyproject.toml

@@ -1,25 +1,25 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.10a8"
+version = "0.2.10a10"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "aio-pika==10.0.1",
-    "aiohttp==3.14.3",
+    "aio-pika==10.1.0",
+    "aiohttp==3.14.4",
     "aiomysql==0.3.2",
-    "anyio==4.14.2",
+    "anyio==4.15.1",
     "decorator==5.3.1",
-    "deepagents==0.7.6",
-    "elasticsearch==9.5.0",
-    "fastapi==0.141.1",
+    "deepagents==0.7.23",
+    "elasticsearch==9.5.1",
+    "fastapi==0.143.0",
     "jinja2==3.1.6",
     "kafka-python==3.0.11",
-    "langchain==1.3.18", 
-    "langchain-core==1.6.1",
-    "langchain-openai==1.6.0",
-    "langfuse==4.15.1",
-    "langgraph==1.2.11",
+    "langchain==1.4.4", 
+    "langchain-core==1.6.9",
+    "langchain-openai==1.7.0",
+    "langfuse==4.17.0",
+    "langgraph==1.2.14",
     "langgraph-checkpoint-postgres==3.1.2",
     "langgraph-checkpoint-redis==0.5.2",
     "ldap3==2.9.1",
@@ -28,29 +28,29 @@ dependencies = [
     "nacos-sdk-python==2.0.11,<3.0",
     "psutil==7.2.2",
     "pyxxl==0.4.8",
-    "pydantic==2.13.5",
-    "python-dotenv==1.2.3",
+    "pydantic==2.14.0",
+    "python-dotenv==1.2.4",
     "python-multipart==0.0.32",
     "pyyaml==6.0.3",
     "redis==7.4.0",
-    "sentry-sdk[fastapi]==2.68.1",
-    "sqlalchemy[asyncio]==2.0.52",
-    "starlette[full]==1.6.0",
+    "sentry-sdk[fastapi]==2.71.0",
+    "sqlalchemy[asyncio]==2.1.4",
+    "starlette[full]==1.7.0",
     "tiktoken==0.14.0",
-    "uvicorn==0.52.4",
+    "uvicorn==0.54.0",
     "wecom-aibot-python-sdk==1.0.2",
     "twine==7.0.0",
     "minio==7.2.20",
     "langchain-mcp-adapters==0.3.2",
     "fastapi-mcp==0.4.0",
-    "psycopg[binary,pool]==3.3.5",
-    "agent-client-protocol==0.11.0",
-    "langchain-acp==1.7.0",
+    "psycopg[binary,pool]==3.3.6",
+    "agent-client-protocol==0.12.1",
+    "langchain-acp==1.10.0",
     "pypinyin==0.55.0",
 ]
 
 [tool.setuptools]
-packages = {find = {where = ["src"], exclude = ["*.__pycache__", "*.__pycache__.*"]}}
+packages = {find = {where = ["src"], exclude = ["*.__pycache__", "*.__pycache__.*", "*.tests", "*.tests.*"]}}
 package-data = {command = ["templates/**/*", "templates/**/.*"], sycommon = ["llm/tiktoken_cache/*"]}
 
 [build-system]

{sycommon_python_lib-0.2.10a8 → sycommon_python_lib-0.2.10a10}/src/sycommon/agent/sandbox/file_ops.py

@@ -682,18 +682,24 @@ class FileOperationsMixin:
 
     @staticmethod
     def _parse_glob_response(result: dict, path: str) -> GlobResult:
-        """解析服务端 glob 响应 GlobResponse{matches, error, truncated}。
+        """解析服务端 glob 响应 GlobResponse{matches, error, truncated, truncation_reason}。
 
-        对齐 0.7.7 _parse_glob_output 的硬错误原则：error 非空即硬失败
+        对齐 0.7.23 _parse_glob_output 的硬错误原则：error 非空即硬失败
         （matches=None），绝不把失败静默成空结果——模型会把空列表当成
         「文件不存在」的证据。truncated 只标记部分结果，matches 仍有效。
+        truncation_reason 透传（budget/unreadable）：下游 FilesystemMiddleware
+        按 reason 选提示词，unreadable 不区分会被当 budget → 模型无效重试。
         """
         error = result.get("error")
         if error:
             return GlobResult(matches=None, error=f"Path '{path}': {error}")
         matches = [FileInfo(**item) for item in result.get("matches", [])]
+        reason = result.get("truncation_reason")
+        if reason not in ("budget", "unreadable"):
+            reason = None
         return GlobResult(
-            matches=matches, truncated=bool(result.get("truncated", False)))
+            matches=matches, truncated=bool(result.get("truncated", False)),
+            truncation_reason=reason)
 
     # ============== 树形目录 ==============
 

{sycommon_python_lib-0.2.10a8 → sycommon_python_lib-0.2.10a10}/src/sycommon/agent/skills_retry_patch.py

@@ -40,6 +40,12 @@ class RetrySkillsMiddleware(_ORIG_MIDDLEWARE):
     """
 
     async def abefore_agent(self, state, runtime, config):
+        # deepagents 0.7.23 语义:state 里 skills_metadata=None 是显式重载请求
+        # (上游判断从 "in state" 改为 "is not None")。必须透传给 super(),
+        # 否则下方 `or []` 会把 None 吞成空列表、误判为"真零技能"而吃掉重载。
+        if state.get("skills_metadata", "__missing__") is None:
+            return await super().abefore_agent(state, runtime, config)
+
         # 未加载过 → 走上游逻辑(会 fall through 到正常加载)
         if "skills_metadata" not in state:
             return await super().abefore_agent(state, runtime, config)
@@ -60,8 +66,10 @@ class RetrySkillsMiddleware(_ORIG_MIDDLEWARE):
         logger.warning(
             "[SkillsRetry] 检测到缓存为空的技能列表(加载曾失败),"
             "本会话轮次重新加载 skills: %s", self.sources)
-        # 清掉旧值让上游 super() 不再命中 "skills_metadata" in state
-        # (dict 可变,删 key 即可;state 是 langgraph 传入的 dict 视图)
+        # 清掉旧值让上游不再命中缓存判断
+        # (dict 可变,删 key 即可;state 是 langgraph 传入的 dict 视图。
+        #  0.7.6 判断 "skills_metadata" in state / 0.7.23 判断 is not None,
+        #  删 key 两种版本都能穿过)
         try:
             state.pop("skills_metadata", None)
             state.pop("skills_load_errors", None)

{sycommon_python_lib-0.2.10a8 → sycommon_python_lib-0.2.10a10}/src/sycommon/agent/summarization_utils.py

@@ -21,7 +21,8 @@ from langchain_core.messages.utils import count_tokens_approximately
 
 if TYPE_CHECKING:
     from langchain_core.language_models import BaseChatModel
-    from deepagents.backends.protocol import BACKEND_TYPES
+    # deepagents 0.7.6 用 BACKEND_TYPES,0.7.23 起移除,统一为 BackendProtocol
+    from deepagents.backends.protocol import BackendProtocol
 
 logger = logging.getLogger(__name__)
 
@@ -376,7 +377,7 @@ logger.info("[SummarizationUtils] 防御性补丁已应用: DEFAULT_SUMMARY_PROM
 def build_summarization_middleware(
     model: BaseChatModel,
     model_name: str,
-    backend: "BACKEND_TYPES",
+    backend: "BackendProtocol",
     *,
     trigger_fraction: float = 0.60,
     keep_fraction: float = 0.10,

sycommon_python_lib-0.2.10a10/src/sycommon/health/readiness.py

@@ -0,0 +1,394 @@
+import asyncio
+import time
+
+from fastapi import FastAPI, APIRouter
+from fastapi.responses import JSONResponse
+from starlette.concurrency import run_in_threadpool
+
+from sycommon.logging.kafka_log import SYLogger
+
+# DB/Redis 拨测超时（秒）；MQ 通道往返探活略宽
+PROBE_TIMEOUT_SECONDS = 3.0
+MQ_PROBE_TIMEOUT_SECONDS = 5.0
+
+# 拨测结果 TTL 缓存（秒）：K8s/Nacos/LB 多源轮询直接命中缓存，
+# 避免故障期间探针流量放大成对依赖的额外负载
+PROBE_CACHE_TTL_SECONDS = 2.0
+
+# 等拨测锁超时（秒）：底层库吞取消语义的兜底，防端点整体 wedged。
+# 预算必须覆盖最慢合法路径再加余量：MQ 撞换池窗口的兜底重探最坏
+# 2×MQ_PROBE_TIMEOUT —— 写小了会把正常慢探测误判成 wedged 答 stale
+# （对齐 Go lib fca8ee1 锁预算修复：TTL + 2×MQ + 余量）。
+LOCK_WAIT_TIMEOUT_SECONDS = (
+    PROBE_CACHE_TTL_SECONDS + 2 * MQ_PROBE_TIMEOUT_SECONDS + 5.0)
+
+
+def _skipped(reason: str) -> dict:
+    return {"status": "SKIPPED", "details": {"reason": reason}}
+
+
+def _err_type_only(exc: BaseException) -> str:
+    """error 字段只回显异常类型名，不回显消息。
+
+    mysql/redis/amqp 的异常消息普遍内嵌 host、username 甚至密码片段
+    （如 "Access denied for user 'svc'@'10.1.2.3' (using password: YES)"），
+    拨测端点无鉴权可被任意网络可达方访问，详情只进日志不进响应。
+    """
+    return type(exc).__name__
+
+
+async def _probe_sync_engine(engine) -> None:
+    """同步 engine 的 SELECT 1（丢线程池，避免阻塞事件循环）。
+
+    与 DatabaseConnector.test_connection 同款（database_service.py:183），
+    只读不写。text 在函数内导入：middleware 链不应硬依赖 sqlalchemy
+    （纯 MQ/web 项目可能未装 DB 依赖栈）。
+    """
+    from sqlalchemy import text
+
+    def _do_probe() -> None:
+        with engine.connect() as connection:
+            connection.scalar(text("SELECT 1"))
+
+    await run_in_threadpool(_do_probe)
+
+
+async def _probe_async_engine(engine) -> None:
+    """异步 engine 的 SELECT 1（只读不写）。"""
+    from sqlalchemy import text
+
+    async with engine.connect() as connection:
+        await connection.execute(text("SELECT 1"))
+
+
+async def _timed_probe(coro, timeout: float, probe_name: str) -> dict:
+    """单组件拨测统一包裹：计时 + 超时 + 异常→DOWN，互不影响其他组件。
+
+    error 只含异常类型名（详见 _err_type_only）；完整异常进 WARNING 日志。
+    """
+    start = time.monotonic()
+    try:
+        await asyncio.wait_for(coro, timeout=timeout)
+    except asyncio.TimeoutError:
+        return {
+            "status": "DOWN",
+            "details": {
+                "probe": probe_name,
+                "error": "probe timeout",
+                "latency_ms": round((time.monotonic() - start) * 1000, 1),
+            },
+        }
+    except Exception as e:
+        # 日志侧同样只留异常类型名：消息内嵌 host/user/密码片段
+        # （credential-log-defense 姿态），集中式 Kafka 日志可被
+        # 有 topic 权限者读取，与响应侧同标准
+        SYLogger.warning(
+            f"[READINESS] probe={probe_name} failed: {type(e).__name__}")
+        return {
+            "status": "DOWN",
+            "details": {
+                "probe": probe_name,
+                "error": _err_type_only(e),
+                "latency_ms": round((time.monotonic() - start) * 1000, 1),
+            },
+        }
+    return {
+        "status": "UP",
+        "details": {
+            "probe": probe_name,
+            "latency_ms": round((time.monotonic() - start) * 1000, 1),
+        },
+    }
+
+
+def _declared(component: str) -> bool:
+    """项目是否「声明」使用了某组件（Services.plugins 入参）。
+
+    区分「没用」与「声明了但初始化静默失败」：setup_database 在 Nacos
+    共享配置缺 datasource 段时不报错留 engine=None，RedisService.init
+    缺 redis.yml 时记日志禁用——声明了却没起来不该报 SKIPPED 放行流量
+    （对齐 Go lib readiness: errDBNotInitialised → DOWN）。
+    """
+    try:
+        from sycommon.services import Services
+        return bool(Services.__dict__.get(f"_enable_{component}", False))
+    except Exception:
+        return False
+
+
+async def _check_database() -> dict:
+    """数据库拨测：sync/async engine 任一存在即探测（SELECT 1，只读）。
+
+    引擎在启动时由 setup_database 按 app.yaml Name → Nacos 共享配置建立。
+    未声明使用数据库 → SKIPPED；声明了但 engine 为 None（配置缺失/
+    初始化静默失败）→ DOWN，不放行流量。两类 engine 并存时都探，
+    任一 DOWN 即 DOWN，响应里各带 type 标注。
+    """
+    from sycommon.database.async_database_service import AsyncDatabaseService
+    from sycommon.database.database_service import DatabaseService
+
+    sync_engine = None
+    async_engine = None
+    try:
+        sync_engine = DatabaseService.engine()
+    except Exception:
+        sync_engine = None
+    try:
+        async_engine = AsyncDatabaseService.engine()
+    except Exception:
+        async_engine = None
+
+    if sync_engine is None and async_engine is None:
+        if _declared("database"):
+            return {
+                "status": "DOWN",
+                "details": {
+                    "reason": "database declared but engine not initialized"},
+            }
+        return _skipped("database engine not initialized")
+
+    labels = []
+    probe_coros = []
+    if sync_engine is not None:
+        labels.append("sync")
+        probe_coros.append(_probe_sync_engine(sync_engine))
+    if async_engine is not None:
+        labels.append("async")
+        probe_coros.append(_probe_async_engine(async_engine))
+
+    results = await asyncio.gather(*(
+        _timed_probe(coro, PROBE_TIMEOUT_SECONDS, "SELECT 1")
+        for coro in probe_coros))
+    for label, result in zip(labels, results):
+        result["details"]["type"] = label
+
+    # 双 engine 并存：任意 DOWN 都保留另一路结果供排查（半瘫时
+    # 运维能看到哪半是好的）。engines 详情写入「返回的那个」结果：
+    # DOWN 时返回第一个 DOWN 项，UP 时返回 results[0]
+    down_result = next(
+        (r for r in results if r["status"] == "DOWN"), None)
+    returned = down_result if down_result is not None else results[0]
+    if len(results) == 2:
+        engines = {}
+        for label, r in zip(labels, results):
+            entry = {"status": r["status"],
+                     "latency_ms": r["details"].get("latency_ms")}
+            if r["status"] == "DOWN":
+                entry["error"] = r["details"].get(
+                    "error", r["details"].get("reason"))
+            engines[label] = entry
+        returned["details"]["engines"] = engines
+    return returned
+
+
+async def _check_redis() -> dict:
+    """Redis 拨测：已初始化才 PING（未初始化时不得触发懒初始化）。
+
+    声明了 redis 但未初始化（redis.yml 缺失被静默禁用）→ DOWN。
+    """
+    from sycommon.database.redis_service import RedisService
+
+    try:
+        initialized = RedisService.is_initialized()
+    except Exception:
+        initialized = False
+
+    if not initialized:
+        if _declared("redis"):
+            return {
+                "status": "DOWN",
+                "details": {
+                    "reason": "redis declared but not initialized"},
+            }
+        return _skipped("redis not initialized")
+
+    async def _probe_redis_ping() -> None:
+        # RedisService.ping 内部异常时返回 False（不抛出），
+        # 显式转 DOWN；_ensure_initialized 的异常由 _timed_probe 兜底
+        if not await RedisService.ping():
+            raise RuntimeError("redis ping failed")
+
+    return await _timed_probe(
+        _probe_redis_ping(), PROBE_TIMEOUT_SECONDS, "PING")
+
+
+async def _check_mq() -> dict:
+    """MQ 拨测：mq.yml 已加载才探测；连接池未就绪 → DOWN（readiness 语义）。
+
+    探测用 pool.probe_connectivity()（真实通道往返、无状态机副作用），
+    不用 is_alive()（与 15s 监控共享心跳计数/告警，且 3-strike 期间
+    返回 True 对 readiness 是假阳）。
+
+    pool 引用经基类读取：init 写子类遮蔽、_rebuild_dead_pool 只写基类
+    （防状态分叉），两条链路并存时子类遮蔽可能是已关闭的旧池——统一
+    从 RabbitMQCoreService 读拿「当前真实池」，杜绝重建后永久误 DOWN。
+    探测失败时若怀疑撞上 reload/rebuild 换池窗口，重读一次再验：
+    旧池已关闭且新池就绪说明是换池瞬间的假阴性。
+    """
+    from sycommon.rabbitmq.rabbitmq_service import RabbitMQService
+    from sycommon.rabbitmq.rabbitmq_service_core import RabbitMQCoreService
+
+    try:
+        configured = RabbitMQService.is_configured()
+    except Exception:
+        configured = False
+    if not configured:
+        if _declared("mq"):
+            return {
+                "status": "DOWN",
+                "details": {
+                    "reason": "mq declared but not configured "
+                              "(mq.yml missing or host empty)"},
+            }
+        return _skipped("mq not configured")
+
+    try:
+        def _current_pool():
+            # 经基类取当前真实池（绕开子类遮蔽的分叉）
+            return RabbitMQCoreService.__dict__.get(
+                "_connection_pool", None)
+
+        pool = _current_pool()
+        if pool is None or not getattr(pool, "_initialized", False):
+            return {
+                "status": "DOWN",
+                "details": {"reason": "connection pool not initialized"},
+            }
+        result = await _timed_probe(
+            _probe_mq_pool_alive(pool), MQ_PROBE_TIMEOUT_SECONDS,
+            "channel probe")
+        if result["status"] == "DOWN":
+            # 撞上 reload/rebuild 换池窗口的兜底：重读当前池，
+            # 新池已就绪则视为换池瞬间假阴性，重探一次
+            pool2 = _current_pool()
+            if pool2 is not None and pool2 is not pool \
+                    and getattr(pool2, "_initialized", False):
+                result = await _timed_probe(
+                    _probe_mq_pool_alive(pool2), MQ_PROBE_TIMEOUT_SECONDS,
+                    "channel probe")
+        return result
+    except Exception as e:
+        # 同 _timed_probe：异常消息可能内嵌基础设施信息，只留类型名
+        SYLogger.warning(
+            f"[READINESS] mq check failed: {type(e).__name__}")
+        return {
+            "status": "DOWN",
+            "details": {"error": _err_type_only(e)},
+        }
+
+
+async def _probe_mq_pool_alive(pool) -> None:
+    """MQ 池真实连通性：临时通道往返（不触碰心跳/告警状态机）。"""
+    if not await pool.probe_connectivity(timeout=MQ_PROBE_TIMEOUT_SECONDS):
+        raise RuntimeError("mq connection not alive")
+
+
+def setup_readiness_handler(app: FastAPI):
+    """挂载 GET /actuator/health/readiness：按需拨测 DB/Redis/MQ。
+
+    组件是否「在用」由各服务单例运行时状态判定（零配置）：
+    - database: DatabaseService/AsyncDatabaseService engine 存在
+    - redis:    RedisService.is_initialized()
+    - mq:       RabbitMQService.is_configured()（mq.yml 已加载）
+
+    在用组件任一 DOWN → HTTP 503；SKIPPED 不影响。
+    结果带 PROBE_CACHE_TTL_SECONDS 缓存：多探针源（K8s/Nacos/LB）轮询
+    时直接命中，避免故障期间探针流量放大成对依赖的额外负载。
+    缓存命中并发去重：同窗口内并发请求共享同一轮拨测（_cache_lock）。
+    """
+    readiness_router = APIRouter()
+    # 模块级缓存（同类 app 多实例共享单例状态，缓存同域）
+    cached: dict = {"at": 0.0, "body": None, "status_code": 200}
+    cache_lock = asyncio.Lock()
+
+    def _cache_valid() -> bool:
+        return cached["body"] is not None \
+            and time.monotonic() - cached["at"] < PROBE_CACHE_TTL_SECONDS
+
+    async def _acquire_probe_turn() -> bool:
+        """获取本轮拨测权。锁带超时：底层库吞取消语义（aiormq 有界写
+        队列满时 CancelledError 可被吞）会让在飞拨测永不返回，锁超时
+        兜底防后续请求全体卡死，端点 wedged 直到重启。"""
+        try:
+            await asyncio.wait_for(
+                cache_lock.acquire(), timeout=LOCK_WAIT_TIMEOUT_SECONDS)
+            return True
+        except TimeoutError:
+            return False
+
+    def _release_probe_turn() -> None:
+        if cache_lock.locked():
+            cache_lock.release()
+
+    def _serve_cache() -> "JSONResponse":
+        return JSONResponse(
+            status_code=cached["status_code"], content=cached["body"])
+
+    async def _run_probes() -> tuple:
+        # 单组件异常/导入失败不得炸掉整个 gather（否则取消兄弟任务）；
+        # gather return_exceptions + 逐个兜底
+        results = await asyncio.gather(
+            _check_database(), _check_redis(), _check_mq(),
+            return_exceptions=True)
+        names = ("database", "redis", "mq")
+        components = {}
+        for name, res in zip(names, results):
+            if isinstance(res, BaseException):
+                # 未预期的异常（含懒导入失败）：该组件 DOWN，其余照常；
+                # 日志只留类型名（消息可能内嵌基础设施信息）
+                SYLogger.warning(
+                    f"[READINESS] {name} check crashed: "
+                    f"{type(res).__name__}")
+                components[name] = {
+                    "status": "DOWN",
+                    "details": {"error": type(res).__name__},
+                }
+            else:
+                components[name] = res
+        status = "DOWN" if any(
+            c["status"] == "DOWN" for c in components.values()) else "UP"
+        if status == "DOWN":
+            down = {k: v for k, v in components.items()
+                    if v["status"] == "DOWN"}
+            SYLogger.warning(f"[READINESS] 依赖拨测 DOWN: {down}")
+        return status, {
+            "status": status, "components": components}
+
+    @readiness_router.get("/actuator/health/readiness")
+    async def readiness():
+        # 快路径：TTL 窗口内直接答缓存
+        if _cache_valid():
+            return _serve_cache()
+
+        # 并发去重：同窗口内并发请求共享同一轮拨测，避免惊群。
+        # 锁带超时（_acquire_probe_turn）：极端场景下底层 close 路径
+        # 吞掉取消会让在飞拨测永不返回，超时兜底防端点整体 wedged。
+        if not await _acquire_probe_turn():
+            # 等锁超时：上一轮拨测卡死。有 stale 缓存就答 stale，
+            # 没有就只能 DOWN（总比无限挂起好）
+            if cached["body"] is not None:
+                return _serve_cache()
+            return JSONResponse(
+                status_code=503,
+                content={"status": "DOWN", "components": {
+                    "readiness": {"status": "DOWN",
+                                  "details": {"error": "probe wedged"}}}})
+        try:
+            # 双检：等锁期间别的请求可能已刷新缓存
+            if _cache_valid():
+                return _serve_cache()
+            status, body = await _run_probes()
+            # 缓存时间戳记「探测完成时刻」，配 _cache_valid 的 < TTL 判定，
+            # 生效窗口恰为 TTL。此前写 at = now + TTL 再配 < TTL 判定，
+            # 实际窗口是 2×TTL（写读双方各加一次），且锁等待期的并发请求
+            # 更容易拿到过新鲜化窗口的旧结论（对齐 Go lib 精确 TTL 语义）。
+            cached["body"] = body
+            cached["status_code"] = 503 if status == "DOWN" else 200
+            cached["at"] = time.monotonic()
+            return JSONResponse(
+                status_code=cached["status_code"], content=body)
+        finally:
+            _release_probe_turn()
+
+    app.include_router(readiness_router)
+    return app