sycommon-python-lib 0.2.10a15__tar.gz → 0.2.10a17__tar.gz

{sycommon_python_lib-0.2.10a15 → sycommon_python_lib-0.2.10a17}/PKG-INFO

@@ -1,25 +1,25 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.10a15
+Version: 0.2.10a17
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: aio-pika==10.1.0
-Requires-Dist: aiohttp==3.14.4
+Requires-Dist: aio-pika==10.1.1
+Requires-Dist: aiohttp==3.14.5
 Requires-Dist: aiomysql==0.3.2
 Requires-Dist: anyio==4.15.1
 Requires-Dist: decorator==5.3.1
-Requires-Dist: deepagents==0.7.23
+Requires-Dist: deepagents==0.7.28
 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.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: langchain==1.4.6
+Requires-Dist: langchain-core==1.6.12
+Requires-Dist: langchain-openai==1.7.2
+Requires-Dist: langfuse==5.0.2
+Requires-Dist: langgraph==1.2.16
+Requires-Dist: langgraph-checkpoint-postgres==3.2.0
 Requires-Dist: langgraph-checkpoint-redis==0.5.2
 Requires-Dist: ldap3==2.9.1
 Requires-Dist: loguru==0.7.3
@@ -27,14 +27,14 @@ 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.14.0
+Requires-Dist: pydantic==2.14.1
 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.71.0
-Requires-Dist: sqlalchemy[asyncio]==2.1.4
-Requires-Dist: starlette[full]==1.7.0
+Requires-Dist: sentry-sdk[fastapi]==2.72.0
+Requires-Dist: sqlalchemy[asyncio]==2.1.5
+Requires-Dist: starlette[full]==1.9.0
 Requires-Dist: tiktoken==0.14.0
 Requires-Dist: uvicorn==0.54.0
 Requires-Dist: wecom-aibot-python-sdk==1.0.2

{sycommon_python_lib-0.2.10a15 → sycommon_python_lib-0.2.10a17}/pyproject.toml

@@ -1,26 +1,26 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.10a15"
+version = "0.2.10a17"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "aio-pika==10.1.0",
-    "aiohttp==3.14.4",
+    "aio-pika==10.1.1",
+    "aiohttp==3.14.5",
     "aiomysql==0.3.2",
     "anyio==4.15.1",
     "decorator==5.3.1",
-    "deepagents==0.7.23",
+    "deepagents==0.7.28",
     "elasticsearch==9.5.1",
     "fastapi==0.143.0",
     "jinja2==3.1.6",
     "kafka-python==3.0.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",
+    "langchain==1.4.6", 
+    "langchain-core==1.6.12",
+    "langchain-openai==1.7.2",
+    "langfuse==5.0.2",
+    "langgraph==1.2.16",
+    "langgraph-checkpoint-postgres==3.2.0",
     "langgraph-checkpoint-redis==0.5.2",
     "ldap3==2.9.1",
     "loguru==0.7.3",
@@ -28,14 +28,14 @@ dependencies = [
     "nacos-sdk-python==2.0.11,<3.0",
     "psutil==7.2.2",
     "pyxxl==0.4.8",
-    "pydantic==2.14.0",
+    "pydantic==2.14.1",
     "python-dotenv==1.2.4",
     "python-multipart==0.0.32",
     "pyyaml==6.0.3",
     "redis==7.4.0",
-    "sentry-sdk[fastapi]==2.71.0",
-    "sqlalchemy[asyncio]==2.1.4",
-    "starlette[full]==1.7.0",
+    "sentry-sdk[fastapi]==2.72.0",
+    "sqlalchemy[asyncio]==2.1.5",
+    "starlette[full]==1.9.0",
     "tiktoken==0.14.0",
     "uvicorn==0.54.0",
     "wecom-aibot-python-sdk==1.0.2",

{sycommon_python_lib-0.2.10a15 → sycommon_python_lib-0.2.10a17}/src/sycommon/agent/sandbox/file_ops.py

@@ -755,12 +755,17 @@ class FileOperationsMixin:
         glob: str = None,
         *,
         max_count: int = None,
+        exclude_dirs: list[str] | None = None,
     ) -> GrepResult:
         """搜索文件内容
 
         max_count 对齐 deepagents 0.7.1：None=不限；设为 int 时服务端 `head -n N+1`
         早停，超出则返回前 N 条并置 truncated=True。框架反射签名发现支持后直接透传。
 
+        exclude_dirs 对齐 deepagents 0.7.28 grep_exclude_dirs：None=服务端默认
+        （.git/node_modules）；[] = 不排除。类属性 grep_exclude_dirs 同名语义，
+        供框架/上层按 BaseSandbox 惯例读取。
+
         错误前缀对齐 BaseSandbox._parse_grep_output："Path '<path>': <reason>"。
         """
         try:
@@ -772,6 +777,7 @@ class FileOperationsMixin:
                 "path": path,
                 "glob": glob,
                 "max_count": max_count,
+                "exclude_dirs": exclude_dirs,
             })
             # GrepResponse: {"matches": [...], "partial_error": "...", "error": "...", "truncated": bool}
             matches = [GrepMatch(**item) for item in result.get("matches", [])]
@@ -806,11 +812,15 @@ class FileOperationsMixin:
         *,
         max_count: int = None,
         timeout: int = None,
+        exclude_dirs: list[str] | None = None,
     ) -> GrepResult:
         """异步搜索文件内容
 
         max_count 对齐 deepagents 0.7.1：服务端早停 + truncated 标志。
 
+        exclude_dirs 对齐 deepagents 0.7.28 grep_exclude_dirs：None=服务端默认
+        （.git/node_modules）；[] = 不排除。
+
         对齐 deepagents 0.7.1 BaseSandbox.agrep：用 asyncio.wait_for 包裹
         远程调用，超时返回 "grep timed out after Ns. Try a more specific
         pattern or a narrower path."，避免大仓库 grep 拖垮整条 async 链。
@@ -829,6 +839,7 @@ class FileOperationsMixin:
                         "path": path,
                         "glob": glob,
                         "max_count": max_count,
+                        "exclude_dirs": exclude_dirs,
                     }, timeout=grep_timeout),
                     timeout=grep_timeout,
                 )

{sycommon_python_lib-0.2.10a15 → sycommon_python_lib-0.2.10a17}/src/sycommon/agent/sandbox/http_sandbox_backend.py

@@ -235,6 +235,14 @@ class HTTPSandboxBackend(FileOperationsMixin, BaseSandbox):
     # 生产 Linux 沙箱走 bash heredoc 执行命令（见 _build_execute_command），必然满足。
     enable_capture_offload = True
 
+    # 对齐 deepagents 0.7.28 BaseSandbox.grep_exclude_dirs：grep/agrep 默认跳过的
+    # 目录名（服务端 /v1/sandbox/grep 用 --exclude-dir 实现）。我们的 grep 走 HTTP
+    # 而非 BaseSandbox 的 shell 命令路径，BaseSandbox 的新 grep 实现不会生效，
+    # 但类属性保持同名同义：FilesystemMiddleware/上层框架按 BaseSandbox 惯例反射
+    # 读取时语义一致；调用方可用 exclude_dirs=None（服务端默认，即本属性内容）
+    # 或 [] （不排除）覆盖。服务端默认清单见 sandbox.py _DEFAULT_GREP_EXCLUDE_DIRS。
+    grep_exclude_dirs = (".git", "node_modules")
+
     """
 
     支持两种模式:

sycommon_python_lib-0.2.10a17/src/sycommon/alert/__init__.py

@@ -0,0 +1,32 @@
+"""sycommon.alert — 对齐 Java shengye-platform-alert-sdk(jar 反编译)。
+
+用法(对齐 Java AlertSdk/BizAlertSdk 静态调用):
+    from sycommon.alert import alert_sdk
+    alert_sdk.fatal("标题")                        # AlertSdk.fatal(title)
+    alert_sdk.critical("标题", "详情", e)           # AlertSdk.critical(title, detail, e)
+    alert_sdk.biz_warn("TPL001", "标题", "详情")    # BizAlertSdk.warn(templateNo, title, detail)
+
+    # @XxxAlert 注解等价(AlertAspect)
+    from sycommon.alert.guard import fatal_alert
+    @fatal_alert("任务失败", "TPL001")
+    async def run(): ...
+
+    # 监控接线(服务启动时一次;sy-alert.monitor.enable 控制)
+    from sycommon.alert.bridge import init_alert_monitors
+    await init_alert_monitors()
+"""
+from sycommon.alert import alert_sdk  # noqa: F401  (统一门面)
+from sycommon.alert.ao import AlertAo  # noqa: F401
+from sycommon.alert.sdk import (alert, alert_access_url, alert_async,  # noqa: F401
+                                start, stop)
+
+__all__ = [
+    "AlertAo",
+    "alert",
+    "alert_async",
+    "alert_access_url",
+    "start",
+    "stop",
+    "alert_sdk",
+]
+

sycommon_python_lib-0.2.10a17/src/sycommon/alert/alert_sdk.py

@@ -0,0 +1,71 @@
+"""alert_sdk.py — Java AlertSdk / BizAlertSdk 静态门面的 Python 形态。
+
+Java 侧 AlertSdk.fatal(...)/critical(...)/warn(...)/info(...) 与
+BizAlertSdk.fatal(templateNo, ...) 的重载统一坍缩为关键字参数版:
+fatal(title, detail="", err=None) / biz_fatal(template_no, title, detail="", err=None)。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from sycommon.alert import api
+
+
+class AlertSdk:
+    """对齐 Java com.shengyecapital.alert.AlertSdk 静态方法集。
+
+    fatal/critical/warn/info 既可类方法调用(AlertSdk.fatal(...)),也提供
+    模块级同名单名:from sycommon.alert import alert_sdk; alert_sdk.fatal(...)。
+    """
+
+    @staticmethod
+    def fatal(title: str, detail: str = "", err: Optional[Exception] = None) -> None:
+        api.fatal(title, detail, err)
+
+    @staticmethod
+    def critical(title: str, detail: str = "", err: Optional[Exception] = None) -> None:
+        api.critical(title, detail, err)
+
+    @staticmethod
+    def warn(title: str, detail: str = "", err: Optional[Exception] = None) -> None:
+        api.warn(title, detail, err)
+
+    @staticmethod
+    def info(title: str, detail: str = "") -> None:
+        """对齐 AlertSdk.info(title)/(title, detail) — Java 无 Throwable 重载。"""
+        api.info(title, detail)
+
+
+class BizAlertSdk:
+    """对齐 Java com.shengyecapital.alert.BizAlertSdk(templateNo 前缀)。"""
+
+    @staticmethod
+    def fatal(template_no: str, title: str, detail: str = "",
+              err: Optional[Exception] = None) -> None:
+        api.biz_fatal(template_no, title, detail, err)
+
+    @staticmethod
+    def critical(template_no: str, title: str, detail: str = "",
+                 err: Optional[Exception] = None) -> None:
+        api.biz_critical(template_no, title, detail, err)
+
+    @staticmethod
+    def warn(template_no: str, title: str, detail: str = "",
+             err: Optional[Exception] = None) -> None:
+        api.biz_warn(template_no, title, detail, err)
+
+    @staticmethod
+    def info(template_no: str, title: str, detail: str = "") -> None:
+        """对齐 BizAlertSdk.info(templateNo, title)/(…, detail) — 无 Throwable 重载。"""
+        api.biz_info(template_no, title, detail)
+
+
+# 模块级单名快捷形态(Java AlertSdk.fatal 静态直呼的最短 Python 形态)。
+fatal = AlertSdk.fatal
+critical = AlertSdk.critical
+warn = AlertSdk.warn
+info = AlertSdk.info
+biz_fatal = BizAlertSdk.fatal
+biz_critical = BizAlertSdk.critical
+biz_warn = BizAlertSdk.warn
+biz_info = BizAlertSdk.info

sycommon_python_lib-0.2.10a17/src/sycommon/alert/ao.py

@@ -0,0 +1,91 @@
+"""ao.py — AlertAo 值对象,对齐 Java com.shengyecapital.alert.vo.AlertAo(jar 反编译)。
+
+字段/优先级/比较序/getKeyMsg 与 Java 字节码逐条对齐:
+  - calc_priority: fatal=100 / critical=50 / warn=20 / 其余 0;
+  - compareTo: priority 升序 → time 升序 → id 升序(队列 first=最低最旧=驱逐
+    候选,poll 最高优先先发);
+  - get_key_msg: [level serviceName templateNo alertTime title] 非空则以单个
+    前导空格拼接,detail 非空则追加 " detail=" + detail(常量池 #231=b' ' /
+    #238=b' detail=' — 2026-10-19 常量池解析确认)。
+
+JSON 序列化字段名为 Java getter 驼峰(hutool JSONUtil.toJsonStr),null 字段
+不输出(hutool 默认忽略 null)→ Pydantic exclude_none 同形。
+"""
+from __future__ import annotations
+
+from typing import ClassVar, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AlertAo(BaseModel):
+    """告警值对象(Java vo.AlertAo 15 字段)。"""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    LEVEL_INFO: ClassVar[str] = "info"
+    LEVEL_WARN: ClassVar[str] = "warn"
+    LEVEL_CRITICAL: ClassVar[str] = "critical"
+    LEVEL_FATAL: ClassVar[str] = "fatal"
+
+    priority: int = 0
+    level: Optional[str] = None
+    serviceName: Optional[str] = None
+    serviceGroup: Optional[str] = None
+    templateNo: Optional[str] = None
+    title: Optional[str] = None
+    detail: Optional[str] = None
+    ip: Optional[str] = None
+    traceId: Optional[str] = None
+    env: Optional[str] = None
+    alertTime: Optional[str] = None
+    errorMsg: Optional[str] = None
+    time: Optional[int] = None  # 入队毫秒时间戳
+    id: int = 0
+
+    def calc_priority(self) -> None:
+        """对齐 Java calcPriority():fatal→100 / critical→50 / warn→20 / 其他 0。"""
+        if self.level == self.LEVEL_FATAL:
+            self.priority = 100
+        elif self.level == self.LEVEL_CRITICAL:
+            self.priority = 50
+        elif self.level == self.LEVEL_WARN:
+            self.priority = 20
+        else:
+            self.priority = 0
+
+    def compare_to(self, other: "AlertAo") -> int:
+        """对齐 Java compareTo:None→1;priority 升序→time 升序→id 升序。"""
+        if other is None:
+            return 1
+        if self.priority != other.priority:
+            return -1 if self.priority < other.priority else 1
+        st = self.time if self.time is not None else 0
+        ot = other.time if other.time is not None else 0
+        if st != ot:
+            return -1 if st < ot else 1
+        return (self.id > other.id) - (self.id < other.id)
+
+    def get_key_msg(self) -> str:
+        """对齐 Java getKeyMsg():前导单空格 join,detail 段 " detail="。"""
+        parts: list[str] = []
+        for f in (self.level, self.serviceName, self.templateNo,
+                  self.alertTime, self.title):
+            if f:
+                parts.append(" " + f)
+        if self.detail:
+            parts.append(" detail=" + self.detail)
+        return "".join(parts)
+
+    def to_wire(self) -> dict:
+        """出站 JSON 形态(hutool 默认:camel 字段 + 忽略 null)。"""
+        return self.model_dump(exclude_none=True)
+
+
+def get_count_string(batch: list[AlertAo]) -> str:
+    """对齐 Java InnerSdk.getCountString:按级别计数拼一条汇总。"""
+    fatal = sum(1 for a in batch if a.level == AlertAo.LEVEL_FATAL)
+    critical = sum(1 for a in batch if a.level == AlertAo.LEVEL_CRITICAL)
+    warn = sum(1 for a in batch if a.level == AlertAo.LEVEL_WARN)
+    info = sum(1 for a in batch if a.level == AlertAo.LEVEL_INFO)
+    return f"致命{fatal}条 严重{critical}条 告警{warn}条 信息{info}条"

sycommon_python_lib-0.2.10a17/src/sycommon/alert/api.py

@@ -0,0 +1,69 @@
+"""api.py — 对齐 Java com.shengyecapital.alert.AlertSdk / BizAlertSdk 门面。
+
+Java AlertSdk 重载矩阵(每级 4 个):fatal/critical/warn ×
+(title)/(title,Throwable)/(title,detail)/(title,detail,Throwable);
+info × (title)/(title,detail)。BizAlertSdk 同形但首参 templateNo。
+全部经 _alert_inner 组 AlertAo(level/title/detail/errorMsg=get_msg)→ InnerSdk.alert。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from sycommon.alert.ao import AlertAo
+from sycommon.alert.sdk import alert
+from sycommon.alert.sdk_selfcheck import get_msg
+
+LEVEL_INFO = AlertAo.LEVEL_INFO
+LEVEL_WARN = AlertAo.LEVEL_WARN
+LEVEL_CRITICAL = AlertAo.LEVEL_CRITICAL
+LEVEL_FATAL = AlertAo.LEVEL_FATAL
+
+
+def _alert_inner(level: str, template_no: str, title: str, detail: str,
+                 err: Optional[Exception]) -> None:
+    ao = AlertAo(level=level, templateNo=template_no or None,
+                 title=title or None, detail=detail or None)
+    if err is not None:
+        ao.errorMsg = get_msg(err)
+    alert(ao)
+
+
+# ---------------- AlertSdk ----------------
+
+def fatal(title: str, detail: str = "", err: Optional[Exception] = None) -> None:
+    _alert_inner(LEVEL_FATAL, "", title, detail, err)
+
+
+def critical(title: str, detail: str = "", err: Optional[Exception] = None) -> None:
+    _alert_inner(LEVEL_CRITICAL, "", title, detail, err)
+
+
+def warn(title: str, detail: str = "", err: Optional[Exception] = None) -> None:
+    _alert_inner(LEVEL_WARN, "", title, detail, err)
+
+
+def info(title: str, detail: str = "") -> None:
+    """对齐 AlertSdk.info(title)/(title, detail) — Java 无 Throwable 重载。"""
+    _alert_inner(LEVEL_INFO, "", title, detail, None)
+
+
+# ---------------- BizAlertSdk ----------------
+
+def biz_fatal(template_no: str, title: str, detail: str = "",
+              err: Optional[Exception] = None) -> None:
+    _alert_inner(LEVEL_FATAL, template_no, title, detail, err)
+
+
+def biz_critical(template_no: str, title: str, detail: str = "",
+                 err: Optional[Exception] = None) -> None:
+    _alert_inner(LEVEL_CRITICAL, template_no, title, detail, err)
+
+
+def biz_warn(template_no: str, title: str, detail: str = "",
+             err: Optional[Exception] = None) -> None:
+    _alert_inner(LEVEL_WARN, template_no, title, detail, err)
+
+
+def biz_info(template_no: str, title: str, detail: str = "") -> None:
+    """对齐 BizAlertSdk.info(templateNo, title)/(…, detail) — 无 Throwable 重载。"""
+    _alert_inner(LEVEL_INFO, template_no, title, detail, None)

sycommon_python_lib-0.2.10a17/src/sycommon/alert/bridge.py

@@ -0,0 +1,49 @@
+"""bridge.py — alert 包对外接线 helpers(对齐 Go 侧 infra/alert/bridge.go)。
+
+与 Java ApplicationContextInitializer 自动挂监控不同:显式接线。
+服务启动(事件循环就绪后)await init_alert_monitors() 一次,按
+sy-alert.monitor.enable 决定是否挂 GC/DB 池扫描;DB 饱和度数据源经
+register_db_stats 由 SQLAlchemy engine.pool.status() 提供。
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+
+from sycommon.alert.monitor import register_db_stats, start_monitors
+from sycommon.logging.kafka_log import SYLogger
+
+
+def _sqlalchemy_pool_stats() -> dict:
+    """SQLAlchemy engine.pool.status() → {'in_use', 'max_open'}。
+
+    status() 形如 "Pool size: 10  Connections in pool: 2 Current Overflow: -8
+    Checked Out Connections: 0";in_use=checkedout,max_open=pool_size+max_overflow
+    (overflow 为负表示空闲位未用满)。engine 未初始化返回空 dict。
+    """
+    try:
+        from sycommon.database.database_service import DatabaseService
+        engine = DatabaseService.engine()
+        if engine is None:
+            return {}
+        m = re.search(r"Checked Out Connections:\s*(\d+)", engine.pool.status())
+        if not m:
+            return {}
+        in_use = int(m.group(1))
+        pool_size = getattr(engine.pool, 'size', lambda: 0)()
+        max_overflow = getattr(engine.pool, '_max_overflow', 0)
+        return {"in_use": in_use, "max_open": pool_size + max_overflow}
+    except Exception as e:  # noqa: BLE001
+        SYLogger.warning(f"[alert] 读取数据库连接池状态失败: {e}")
+        return {}
+
+
+async def init_alert_monitors() -> None:
+    """启动默认监控(GC + 连接池饱和度)。engine 未初始化时跳过池监控。"""
+    stats = _sqlalchemy_pool_stats()
+    if stats:
+        register_db_stats(_sqlalchemy_pool_stats)
+    start_monitors()
+
+
+__all__ = ["init_alert_monitors", "register_db_stats"]

sycommon_python_lib-0.2.10a17/src/sycommon/alert/env.py

@@ -0,0 +1,144 @@
+"""env.py — 对齐 Java com.shengyecapital.alert.config.AlertEnv + AlertLocalIpUtil。
+
+Java 侧取值链(ApplicationContextInitializer):appName←spring.application.name、
+activeProfile←spring.cloud.nacos.config.namespace、sy-alert.* 配置经 Spring
+Environment getProperty。Python 等价映射:Config()(app.yaml+nacos 共享配置落地)、
+env 兜底;appName=Config Name(与 sso_token.app_name 同源);profile=
+Config Nacos.namespaceId(env 兜底 MODE/ENV)。
+"""
+from __future__ import annotations
+
+import os
+import socket
+import threading
+from typing import Optional
+
+_local = threading.local()
+
+
+def _cfg():
+    try:
+        from sycommon.config.Config import Config
+        return Config()
+    except Exception:
+        return None
+
+
+def app_name_of_sdk() -> str:
+    """对齐 Java AlertEnv.getAppName(spring.application.name)。"""
+    cfg = _cfg()
+    if cfg is not None:
+        return cfg.config.get('Name', '') or ''
+    return ''
+
+
+def active_profile() -> str:
+    """对齐 Java AlertEnv.getActiveProfile(spring.cloud.nacos.config.namespace)。
+
+    测试可注入 _local.profile;生产链:Config Nacos.namespaceId → env MODE/ENV。
+    """
+    injected = getattr(_local, 'profile', None)
+    if injected is not None:
+        return injected
+    cfg = _cfg()
+    if cfg is not None:
+        ns = cfg.config.get('Nacos', {}).get('namespaceId', '')
+        if ns:
+            return ns
+    return os.getenv('MODE') or os.getenv('ENV') or ''
+
+
+def set_active_profile_for_test(profile: str) -> None:
+    """线程内注入 profile(测试用;空串恢复)。"""
+    _local.profile = profile or None
+
+
+def get_property(key: str, default: str = '') -> str:
+    """对齐 Java AlertEnv.getProperty(key, def) 的【配置源覆盖面】。
+
+    Java getProperty = Spring Environment.getProperty:统一抽象全部配置源 —
+    application.yml / nacos 配置中心(任一 dataId 同键)/ 系统属性 / 环境变量
+    (relaxed binding:SY_ALERT_MONITOR_ENABLE ↔ sy-alert.monitor.enable)。
+
+    Python 等价覆盖面(优先序对齐 Spring:nacos 各 dataId → 本地 yml → 环境变量):
+      1. Config.read_key_layered 逐层下钻:项目 dataId(==Name)优先,其余
+         sharedConfigs 声明序(common.yml 等),本地 app.yaml 段兜底 — 与
+         Go ReadKeyLayered / Spring 逐属性覆盖一致(项目 dataId 只覆盖自己
+         写了的键,共享受保护的键自动落到下层);
+      2. 环境变量:key 点号/横线→下划线大写(sy-alert.monitor.enable →
+         SY_ALERT_MONITOR_ENABLE,等价 Spring relaxed binding)。
+    """
+    from sycommon.config.Config import Config
+    trimmed = key[len('sy-alert.'):] if key.startswith('sy-alert.') else key
+    try:
+        cfg = Config()
+        v, ok = cfg.read_key_layered('sy-alert', *trimmed.split('.'))
+        if ok and v is not None and v != '':
+            return str(v)
+    except Exception:
+        pass
+    env_key = key.replace('.', '_').replace('-', '_').upper()
+    env_val = os.getenv(env_key) or os.getenv(env_key.lower())
+    if env_val:
+        return env_val
+    return default
+
+
+def get_bool(key: str, default: bool) -> bool:
+    """对齐 Java getBoolean 字节码:非空时仅 equalsIgnoreCase('true') 为真,
+    其余任何值(含 'false'/'1'/'yes')都 False;空时返回 default。"""
+    v = get_property(key, '')
+    if v == '':
+        return default
+    return v.strip().lower() == 'true'
+
+
+def get_int(key: str, default: int) -> int:
+    try:
+        return int(get_property(key, ''))
+    except (TypeError, ValueError):
+        return default
+
+
+def get_float(key: str, default: float) -> float:
+    try:
+        return float(get_property(key, ''))
+    except (TypeError, ValueError):
+        return default
+
+
+_ip_cache: Optional[str] = None
+_ip_lock = threading.Lock()
+
+
+def local_ip() -> str:
+    """对齐 Java AlertLocalIpUtil.getLocalIp():本机非环回 IPv4,进程内缓存。"""
+    global _ip_cache
+    with _ip_lock:
+        if _ip_cache is not None:
+            return _ip_cache
+    ip = _lookup_local_ip()
+    with _ip_lock:
+        _ip_cache = ip
+    return ip
+
+
+def _lookup_local_ip() -> str:
+    try:
+        hostname = socket.gethostname()
+        # k8s pod 场景 hostname 即 pod ip 或可解析;优先 UDP connect 法(不发包)。
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            s.settimeout(0)
+            s.connect(('10.255.255.255', 1))
+            return s.getsockname()[0]
+        finally:
+            s.close()
+    except Exception:
+        pass
+    try:
+        for info in socket.getaddrinfo(hostname, None, socket.AF_INET):
+            return info[4][0]
+    except Exception:
+        pass
+    return ''