sycommon-python-lib 0.2.10a12__tar.gz → 0.2.10a13__tar.gz

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.10a12
+Version: 0.2.10a13
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.10a12"
+version = "0.2.10a13"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon/logging/async_sql_logger.py

@@ -1,6 +1,7 @@
 from sqlalchemy import event
 from sycommon.logging.kafka_log import SYLogger
 from sycommon.logging.log_masker import masker as _log_masker
+import json
 import time
 
 
@@ -38,7 +39,7 @@ class AsyncSQLTraceLogger:
                 }
 
                 # 注意：SYLogger.info 必须是线程安全的或非阻塞的，否则可能影响异步性能
-                SYLogger.info(f"SQL执行: {sql_log}")
+                SYLogger.info(f"SQL执行: {json.dumps(sql_log, ensure_ascii=False, default=str)}")
             except Exception as e:
                 SYLogger.error(f"SQL日志处理失败: {str(e)}")
 

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon/logging/kafka_log.py

@@ -117,6 +117,166 @@ def _strip_impl(node, depth, seen):
     return node
 
 
+# 🔑 2026-10-16 框架帧谓词与 Java 对齐编码 helpers(对齐 go-lib alpha.28)。
+# 请求/响应日志由 sycommon/middleware/traceid.py 闭包发起,starlette
+# BaseHTTPMiddleware 的 call_next 链与 uvicorn 帧都是框架帧 — 不跳则
+# className 恒落 traceid.py/middleware.py(平台渲染 [py: N],同 Go go:238)。
+# 🔴 注意: /sycommon/logging/ 整目录跳帧对 SQL 链过狠 —
+# sql_logger/async_sql_logger 的事件闭包(after_cursor_execute)是收口层,
+# 其上全是 sqlalchemy 引擎帧;跳过闭包继续穿透常常耗尽窗口落 kafka 兜底。
+# SQL 链把闭包当"最深可回收帧": 见 _log 抓帧的 _caller 兜底分支。
+_FRAME_PATH_MARKERS = (
+    "/sycommon/logging/",          # 本包(_log/公开方法/桥接)
+    "/sycommon/middleware/",       # 本库中间件(traceid.py 请求/响应收口)
+    "/sycommon/services",          # Services 插件装配层
+    "/site-packages/starlette/",   # ASGI 框架(BaseHTTPMiddleware.call_next/router)
+    "/site-packages/uvicorn/",     # ASGI 服务器帧
+    "/site-packages/fastapi/",     # 路由分发帧
+    "/site-packages/loguru/",      # sink 回灌链
+    "/site-packages/sqlalchemy/",  # ORM 事件/引擎帧(wxcoach SQL 链实测落 event.__call__)
+    "/lib/python3",                # 标准库 asyncio/runners(内置路由无 endpoint 的兜底链)
+    "/site-packages/anyio/",       # starlette 依赖的异步原语帧
+    "/sycommon/database",          # 本库 DB 封装层
+)
+
+
+def _is_framework_frame(module_path: str) -> bool:
+    """帧是否属于框架层(日志/中间件/ASGI/ORM),抓帧时应跳过。
+
+    sqlalchemy 的 cython/generated cache wrapper 帧文件名是
+    "<sqlalchemy generated cache() wrapper ...>"(非路径形态,路径
+    谓词不命中)— 以 '<' 开头的生成代码帧一并视为框架帧。
+    """
+    if module_path.endswith("/logging/__init__.py"):
+        return True
+    if module_path.lstrip().startswith("<"):
+        return True  # 生成代码帧(sqlalchemy cache wrapper 等)
+    return any(m in module_path for m in _FRAME_PATH_MARKERS)
+
+
+def _caller_file_from_path(module_path: str) -> str:
+    """路径最后一段文件名(traceid.py),旧 className 形态兜底用。"""
+    return module_path.rsplit("/", 1)[-1]
+
+
+def _package_two_segments(module_path: str) -> str:
+    """Java 对齐 className: 模块路径最后两段(sycommon/wecom)。
+
+    平台头部列按 Java 习惯取 className 最后一个 '.' 后的段当短类名
+    (starter-log 字节码: classShortName=className.substring(lastIndexOf('.')+1));
+    Python 文件名(traceid.py)取段得 'py' → 渲染 [py: N] 无信息量。
+    模块路径两段(以 '/' 分层)取段后得包名 → [wecom: N],与 Go
+    alpha.28 的 internal/wecom 同语义。venv 路径(site-packages)剥到
+    包名为止;无路径分隔(单文件)返回空由调用方回退。
+    """
+    parts = [p for p in module_path.replace("\\", "/").split("/") if p]
+    # 剥 site-packages 前缀后的真实包路径(找不到标记则全路径)
+    if "site-packages" in parts:
+        parts = parts[parts.index("site-packages") + 1:]
+    # 去文件名:取目录段(_log 拿到的 module_path 含文件名)
+    if parts and parts[-1].endswith(".py"):
+        parts = parts[:-1]
+    if len(parts) >= 2:
+        return "/".join(parts[-2:])
+    if len(parts) == 1:
+        return parts[0]
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# print 接管(2026-10-16,默认全开):业务代码的裸 print 一并进 Kafka 上报
+# ---------------------------------------------------------------------------
+# 形态对齐 Go 侧 RedirectStandardLog(stdlib log 全收口):Python 的"裸输出
+# 习惯"是 print,存量代码大量调试/巡检 print 原先只落容器 stdout 不上报,
+# 平台检索不到。接管后走 SYLogger._log 同一条管线(信封/调用点帧/
+# BoundedKafkaSink 有界队列),className/method/line 定位业务帧。
+#
+# 三道防线(没有它们就是事故):
+#   1. 回环防护:日志系统自身路径(sycommon/logging + _print_in_log 哨兵)
+#      直写原生 stdout,不回灌 — 否则 DEV_LOG 镜像 print → _log → 再镜像
+#      无限递归(Go 侧 JSON 套娃的同族坑);
+#   2. 显式 file= 定向(stderr/f=...)不接管,print 的定向语义保留;
+#   3. 单条体积上限(与 msg 819200 同限)+ 空行丢弃。
+_print_orig = None
+_print_in_log = False
+
+
+def _is_print_source_internal(module_path: str) -> bool:
+    """print 调用方是否属于日志系统(回环源)。"""
+    if module_path.endswith("/logging/__init__.py"):
+        return True
+    return "/sycommon/logging/" in module_path
+
+
+def _captured_print(*args, sep=" ", end="\n", file=None, flush=False):
+    """builtins.print 的接管实现。
+
+    业务帧的 print → SYLogger._log(text, INFO) 进 Kafka;日志系统内部与
+    显式定向的 print 原样放行(原生 stdout)。
+    """
+    global _print_in_log
+    if _print_in_log:
+        _print_orig(*args, sep=sep, end=end, file=file, flush=flush)
+        return
+    # 显式定向(非默认 stdout)不接管 — print(f, file=stderr) 语义保留
+    if file is not None and file is not sys.stdout:
+        _print_orig(*args, sep=sep, end=end, file=file, flush=flush)
+        return
+
+    text = sep.join(_safe_str(a) for a in args)
+    if not text.strip():
+        _print_orig(*args, sep=sep, end=end, file=file, flush=flush)
+        return
+
+    # 内部判定只看【直接调用方】stack()[1]:
+    # 日志系统的 print(DEV_LOG 信封镜像/producer 自愈提示)调用方就是
+    # sycommon/logging 一眼可辨 → 放行原生 stdout。
+    # 🔴 不能用"沿栈穿透找业务帧"(抓帧谓词的逻辑):业务 → SYLogger.info
+    # → _log → print(镜像) 链里穿透必命中业务帧,镜像会被当业务 print
+    # 再上报 — 整个信封 dict 作为 msg 双投+嵌套+中文双重转义
+    # (wxcoach 实测 17:26 抓出,2026-10-16 修)。
+    try:
+        import inspect as _inspect
+        _direct = _inspect.stack()[1].filename.replace("\\", "/")
+        if _is_print_source_internal(_direct):
+            _print_orig(*args, sep=sep, end=end, file=file, flush=flush)
+            return
+    except Exception:
+        # 抓栈失败宁可放行(漏报优于误报双投)
+        _print_orig(*args, sep=sep, end=end, file=file, flush=flush)
+        return
+
+    # 上报进 Kafka(经 _log 信封 — className/method/line 自动富化 + 限长,
+    # _log 内部 mask_string 已有体量防线,此处不再重复截断)。
+    # 原生 stdout 不再写(容器 stdout 静默纪律与 SYLogger.info 一致,
+    # DEV_LOG 镜像由 _log 内部处理)。
+    _print_in_log = True
+    try:
+        SYLogger._log(text, "INFO")
+    finally:
+        _print_in_log = False
+
+
+def _install_print_capture():
+    """接管 builtins.print(幂等)。setup_logger 装配期调用。"""
+    global _print_orig
+    if _print_orig is not None:
+        return
+    import builtins
+    _print_orig = builtins.print
+    builtins.print = _captured_print
+
+
+def _uninstall_print_capture():
+    """恢复原生 print。close/热重建期对称调用,防接管悬挂。"""
+    global _print_orig
+    if _print_orig is None:
+        return
+    import builtins
+    builtins.print = _print_orig
+    _print_orig = None
+
+
 def _safe_str(msg) -> str:
     """str() 的安全版：repr 若含凭证关键词（Request/scope 误传）则整体替换。
 
@@ -401,7 +561,18 @@ class KafkaSink:
                     file_name = _cf
             caller_fn = (msg_obj or {}).get("_caller_fn") or ""
             caller_line = (msg_obj or {}).get("_caller_line") or 0
-            if logger_name and logger_name != file_name:
+            # 🔘 中间件路由定位优先(协程断栈链的稳定业务定位)
+            _route_handler = (msg_obj or {}).get("_handler") or ""
+            if _route_handler:
+                caller_fn = _route_handler
+            # 🔑 2026-10-16 Java 对齐编码(对齐 go-lib alpha.28 javaStyleClassName):
+            # className = 模块路径最后两段(sycommon/wecom),平台按 '.' 取段
+            # 得 wecom → 渲染 [wecom: N];旧文件名形态(traceid.py)渲染 [py: N]。
+            # _caller_pkg 由 _log 抓帧时写正文(队列存活),缺失回退旧形态。
+            _caller_pkg = (msg_obj or {}).get("_caller_pkg") or ""
+            if _caller_pkg:
+                class_name = _caller_pkg
+            elif logger_name and logger_name != file_name:
                 class_name = f"{file_name}:{logger_name}"
             else:
                 class_name = file_name
@@ -418,7 +589,13 @@ class KafkaSink:
             #   - msg/detail：Java limitLength 防大包被 Kafka 拒收 —— msg 819200,
             #     detail 102400(100KB,starter-log appendToKafka 字节码确认;
             #     2026-10-10 修正:此前 detail 也按 819200,超长堆栈大包与 Java 不一致)
-            _class_short = file_name.rsplit(".", 1)[0] if "." in file_name else file_name
+            # 🔑 2026-10-16 Java 对齐: classShortName 取 className 最后一段
+            # (internal/wecom → wecom);旧文件名主干形态(traceid → py 剥扩展)
+            # 保留兜底。对齐 go-lib alpha.28 classShortOf。
+            if _caller_pkg:
+                _class_short = _caller_pkg.rsplit("/", 1)[-1]
+            else:
+                _class_short = file_name.rsplit(".", 1)[0] if "." in file_name else file_name
             # 🔑 msg 对齐 Java getFormattedMessage(纯消息文本,2026-10-10):
             # record.message 是 _log 塞的 log_json 信封(内含 trace_id/message/
             # level/... 元键)——此前整包落 msg 字段,平台显示双层 JSON;
@@ -777,6 +954,10 @@ class KafkaLogger(metaclass=SingletonMeta):
         # sys.excepthook 只管主线程；工作线程的未捕获异常走 threading.excepthook
         threading.excepthook = KafkaLogger._handle_thread_exception
 
+        # 🔑 print 接管(2026-10-16 默认全开):业务裸 print 一并进 Kafka —
+        # 平台可检索;回环/定向/体积三防线见 _captured_print。
+        _install_print_capture()
+
         # 注册 asyncio 异常处理器，捕获未处理的 Task 异常
         KafkaLogger._setup_asyncio_exception_handler()
 
@@ -903,6 +1084,8 @@ class KafkaLogger(metaclass=SingletonMeta):
 
     @staticmethod
     def close():
+        # print 接管对称恢复(热重建 reload 会重新 setup — 不恢复则双跳)
+        _uninstall_print_capture()
         if KafkaLogger._sink_instance is None:
             return
         # 先移除 loguru sink（按 add() 返回的 handler id），停止后台线程往 sink 写入
@@ -1089,19 +1272,37 @@ class SYLogger:
         # (_log 每条日志必经)用 inspect 抓真实业务帧写进正文,消费侧优先读。
         # 栈形:业务 → SYLogger.info/warning/... → _log → 此处;跳过本帧、
         # _log、公开方法帧(深度自适应:回溯到 sycommon.logging 之外的首帧)。
-        _caller_file, _caller_fn, _caller_line = "", "", 0
+        # 🔑 2026-10-16 对齐 go-lib alpha.28: 谓词同时跳过本库中间件帧与
+        # web 框架帧 —— 请求/响应日志由 traceid.py 中间件闭包发起(同 Go
+        # 的 TraceIDMiddleware go:238 形态),starlette 的 BaseHTTPMiddleware
+        # call_next 帧与 sycommon/middleware 帧都是框架帧,不跳则 className
+        # 恒落 traceid.py / middleware.py(平台 [py: N] 无信息量)。
+        _caller_file, _caller_fn, _caller_line, _caller_pkg = "", "", "", ""
+        _last_skip = None  # 最后跳过的本库日志层帧(SQL 收口闭包兜底用)
         try:
             import inspect as _inspect
-            for _f in _inspect.stack()[2:8]:
+            for _f in _inspect.stack()[2:20]:
                 _mod = _f.filename.replace("\\", "/")
-                if "/sycommon/logging/" in _mod or _mod.endswith("/logging/__init__.py"):
+                if _is_framework_frame(_mod):
+                    if "/sycommon/logging/" in _mod and "kafka_log" not in _mod:
+                        _last_skip = _f
                     continue
-                _caller_file = _f.filename.rsplit("/", 1)[-1]
-                _caller_fn = _f.function
+                _caller_file, _caller_fn = _caller_file_from_path(_mod), _f.function
                 _caller_line = _f.lineno
+                _caller_pkg = _package_two_segments(_mod) or _caller_file_from_path(_mod)
                 break
+            else:
+                # 窗口耗尽(全框架帧): SQL 链回退到事件闭包帧(如
+                # after_cursor_execute @ async_sql_logger.py:39)—
+                # 定位到 SQL 收口层,优于 kafka:0 无信息量形态。
+                if _last_skip is not None:
+                    _mod = _last_skip.filename.replace("\\", "/")
+                    _caller_file = _caller_file_from_path(_mod)
+                    _caller_fn = _last_skip.function
+                    _caller_line = _last_skip.lineno
+                    _caller_pkg = _package_two_segments(_mod) or _caller_file
         except Exception:
-            pass
+            _caller_pkg = ""
 
         # 单条开关裁决：严格布尔判定，非布尔值（None/exec 等）一律跟随全局
         if enabled is False:
@@ -1126,6 +1327,16 @@ class SYLogger:
         # 🔒 凭证兜底：任何进入日志的对象（含误传的 Request/scope/headers）先剥离
         # 敏感结构。这是白名单(traceid.py)之后的第二道防线——即使业务代码把整个
         # request 对象传进日志，ASGI scope 里的 authorization/cookie/token 也不会落盘。
+        # 🔑 2026-10-16 中间件路由定位提升(对齐 go-lib handlerFields):
+        # traceid.py 中间件把 handler/handler_pkg 塞进 message dict;
+        # _log 在此提升为信封级 _handler_pkg/_handler 键(队列存活),
+        # write 消费侧优先用它构建 className/method — BaseHTTPMiddleware
+        # call_next 起 task,handler 帧与中间件闭包栈不连续(协程边界,
+        # 同 Go goroutine 断栈),栈解析到不了业务帧,路由定位是唯一稳定源。
+        _route_pkg, _route_handler = "", ""
+        if isinstance(msg, dict):
+            _route_pkg = msg.pop("handler_pkg", "") or ""
+            _route_handler = msg.pop("handler", "") or ""
         msg = _strip_sensitive_payload(msg)
 
         # 序列化消息：dict/list 先脱敏（按字段名/子串/长度/总量裁剪），再转 JSON
@@ -1163,10 +1374,23 @@ class SYLogger:
         if _caller_file:
             # 调用点帧正文键(className/method/line 的队列存活通道):
             # BoundedKafkaSink str 化后 record.file 兜底 'kafka'/line=0,
-            # KafkaSink.write 优先读这三个键。
+            # KafkaSink.write 优先读这些键。_caller_pkg = Java 对齐的
+            # className(模块路径最后两段,2026-10-16 — 平台按 '.' 取段
+            # 渲染短名,旧文件名 traceid.py 会渲染成 [py: N])。
             log_dict["_caller_file"] = _caller_file
             log_dict["_caller_fn"] = _caller_fn
             log_dict["_caller_line"] = _caller_line
+            if _caller_pkg:
+                log_dict["_caller_pkg"] = _caller_pkg
+        # 🔘 中间件路由定位(2026-10-16,对齐 go-lib handlerFields):
+        # 协程断栈链(BaseHTTPMiddleware call_next 起 task)栈解析到不了
+        # 业务帧,_handler_pkg/_handler 是唯一稳定定位;_caller_pkg 被
+        # 路由定位优先覆盖(栈帧在断栈链上只会落 asyncio/引擎帧)。
+        if _route_pkg:
+            log_dict["_handler_pkg"] = _route_pkg
+            log_dict["_caller_pkg"] = _route_pkg
+        if _route_handler:
+            log_dict["_handler"] = _route_handler
         if _ctx.get("tenant_id"):
             log_dict["_tenant_id"] = _ctx["tenant_id"]
         if _ctx.get("user_id"):

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon/logging/log_masker.py

@@ -30,6 +30,7 @@
     - sycommon.synacos.nacos_config_manager            -> 配置热更新时调 reload()
 """
 import json
+import re
 from datetime import datetime
 from decimal import Decimal
 from typing import Any, Optional
@@ -225,8 +226,15 @@ class LogMasker(metaclass=SingletonMeta):
         return kept + [f"...[{len(items) - n} items truncated]..."]
 
     # ------------------------------------------------------------------ sanitize
-    def _sanitize_value(self, value: Any, key: Any, depth: int = 0) -> Any:
-        """对单个值脱敏。key 仅供字段名匹配，dict 内部递归时按真实 key 传入。"""
+    def _sanitize_value(self, value: Any, key: Any, depth: int = 0,
+                        full: bool = False) -> Any:
+        """对单个值脱敏。key 仅供字段名匹配，dict 内部递归时按真实 key 传入。
+
+        full=True: 不做叶子 maxLength 折叠与超长 list 摘要(SQL 参数展示全量)，
+        字段级 mask/drop 仍生效；整条防线由 _log 的 maxSize(Kafka 单条上限)
+        兜底。折叠对 SQL 参数是双重伤害: 中段丢失之外,截断会把 \\uXXXX
+        转义对从中间切断,展示解码后残留悬空 \\u54 片段(2026-10-16 实测)。
+        """
         # 1. 先按 key 决定动作（脱敏在最外层命中即生效，不深入）
         action = self._match_action(key)
         if action == "drop":
@@ -241,7 +249,7 @@ class LogMasker(metaclass=SingletonMeta):
             value = value.isoformat()
 
         if isinstance(value, str):
-            return self._truncate_str(value)
+            return value if full else self._truncate_str(value)
         if value is None or isinstance(value, (bool, int, float)):
             return value
 
@@ -253,24 +261,32 @@ class LogMasker(metaclass=SingletonMeta):
         if isinstance(value, dict):
             out = {}
             for k, v in value.items():
-                sv = self._sanitize_value(v, k, depth + 1)
+                sv = self._sanitize_value(v, k, depth + 1, full=full)
                 if sv is _DROP:
                     continue
                 out[k] = sv
             return out
 
-        # 5. list：超长摘要，否则逐项递归
+        # 5. list：full 不摘要逐项递归；否则超长摘要
         if isinstance(value, (list, tuple)):
-            return self._summarize_list(list(value), key)
+            items = list(value)
+            if full:
+                return [self._sanitize_value(v, _child_key(key, i), depth + 1,
+                                             full=full)
+                        for i, v in enumerate(items)]
+            return self._summarize_list(items, key)
 
         # 6. 兜底：不可识别对象，转字符串后截断，避免 json.dumps 失败
         return self._truncate_str(str(value))
 
-    def sanitize(self, value: Any, key: Any = None) -> Any:
-        """对外入口。未启用时直接原样返回（含 Decimal/datetime 规整）。"""
+    def sanitize(self, value: Any, key: Any = None, full: bool = False) -> Any:
+        """对外入口。未启用时直接原样返回（含 Decimal/datetime 规整）。
+
+        full=True 语义见 _sanitize_value —— 展示全量不折叠（SQL 参数用）。
+        """
         if not self.enabled:
             return _normalize_scalar_only(value)
-        result = self._sanitize_value(value, key, depth=0)
+        result = self._sanitize_value(value, key, depth=0, full=full)
         # 顶层不允许返回 _DROP
         if result is _DROP:
             return None
@@ -346,11 +362,53 @@ class LogMasker(metaclass=SingletonMeta):
         return False
 
     def serialize_params(self, params: Any) -> Any:
-        """SQL 参数序列化入口：脱敏 + Decimal/datetime 规整，单次遍历。
+        r"""SQL 参数序列化入口：脱敏 + Decimal/datetime 规整 + \u 展示解码。
 
         供 sql_logger / async_sql_logger 复用，替代原先两处重复实现。
+        full=True 全量展示: 参数值不按 maxLength 折叠(截断会把 \uXXXX 转义对
+        从中间切断,展示解码后残留悬空 \u 片段;且 SQL 排障要看完整参数,
+        2026-10-16 用户明确要求不折叠)。字段级脱敏照常,maxSize 整条防线
+        在 _log 收口仍兜底(防 Kafka 单条超限)。
+        """
+        cleaned = self.sanitize(params, full=True)
+        return self._decode_escaped_tree(cleaned)
+
+    def _decode_escaped_tree(self, value: Any) -> Any:
+        """递归对树内所有字符串叶子做 \\uXXXX 展示解码。"""
+        if isinstance(value, str):
+            return self._decode_escaped_unicode(value)
+        if isinstance(value, dict):
+            return {k: self._decode_escaped_tree(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self._decode_escaped_tree(v) for v in value]
+        return value
+
+    _ESCAPED_UNICODE_RE = re.compile(r"\\u([0-9a-fA-F]{4})")
+
+    def _decode_escaped_unicode(self, value: Any) -> Any:
+        """字符串值内的 \\uXXXX 转义解码为可读中文(展示层修复)。
+
+        SQLAlchemy JSON 列绑定参数时 json.dumps 默认 ensure_ascii=True —
+        中文以 \\u660e\\u786e 形态入库/入参数;SQL 日志如实展示导致平台
+        不可读(2026-10-16 wxcoach ext_json 实测)。只解码【字符串叶子】。
+
+        按对替换而非整串 unicode_escape: 真实参数里混有非法转义对
+        (如截断的 \\u4fd\\ 后跟引号)时,整串 decode 抛异常 → 原样返回,
+        合法对也全留下(17:59 ext_json 仍全编码的根因)。逐对处理:
+        合法 4 位十六进制对解码,非法序列(含字面 \\\\u)原样保留。
         """
-        return self.sanitize(params)
+        if not isinstance(value, str) or "\\u" not in value:
+            return value
+        if not value.isascii():
+            return value  # 已含可读中文,无需也不应再动
+
+        def _sub(m: "re.Match[str]") -> str:
+            try:
+                return chr(int(m.group(1), 16))
+            except Exception:
+                return m.group(0)
+
+        return self._ESCAPED_UNICODE_RE.sub(_sub, value)
 
     def mask_placeholder(self, value: Any) -> str:
         """整条掩码占位：命中 maskLinePatterns 时，把 message 正文替换为此占位。

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon/logging/sql_logger.py

@@ -2,6 +2,7 @@ from sqlalchemy import event
 from sqlalchemy.engine import Engine
 from sycommon.logging.kafka_log import SYLogger
 from sycommon.logging.log_masker import masker as _log_masker
+import json
 import time
 
 
@@ -28,7 +29,7 @@ class SQLTraceLogger:
                     "execution_time_ms": round(execution_time, 2),
                 }
 
-                SYLogger.info(f"SQL执行: {sql_log}")
+                SYLogger.info(f"SQL执行: {json.dumps(sql_log, ensure_ascii=False, default=str)}")
             except Exception as e:
                 SYLogger.error(f"SQL日志处理失败: {str(e)}")
 

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon/middleware/traceid.py

@@ -211,6 +211,26 @@ def setup_trace_id_handler(app):
         }
         # 直接传 dict：由 SYLogger._log 统一走 LogMasker 脱敏/裁剪
         # （此前先 json.dumps 成字符串，会绕过按字段名的脱敏，导致大字段原样落盘）
+        # 🔑 2026-10-16 路由级定位(对齐 go-lib alpha.28 handlerFields):
+        # BaseHTTPMiddleware 的 call_next 起 task,handler 帧与中间件闭包
+        # 栈不连续(协程边界,同 Go goroutine 断栈)— 栈解析到不了业务帧。
+        # request.scope["route"] 是路由匹配的请求级事实,跨协程稳定。
+        _handler_ctx = {}
+        _route = request.scope.get("route")
+        _ep = getattr(_route, "endpoint", None) if _route else None
+        _route_path = getattr(_route, "path", "") or request.scope.get("path", "")
+        if _ep is not None:
+            _ep_mod = getattr(_ep, "__module__", "") or ""
+            _pkg = "/".join(_ep_mod.split(".")[-2:]) if _ep_mod else ""
+            _handler_ctx["handler"] = f"{_ep_mod}.{getattr(_ep, '__name__', '')} (PATH {_route_path})"
+            if _pkg:
+                _handler_ctx["handler_pkg"] = _pkg
+            request_message["handler"] = _handler_ctx["handler"]
+            if _pkg:
+                request_message["handler_pkg"] = _pkg
+        else:
+            _handler_ctx["handler"] = ""
+            _handler_ctx["handler_pkg"] = ""
         SYLogger.info(request_message)
 
         # 标记位：默认认为会发生异常
@@ -435,6 +455,22 @@ def setup_trace_id_handler(app):
                 "response_body": response_log_body,
             }
             # response_body 已是字符串：交给 SYLogger 的 mask_string 兜底截断（maxSize）
+            # 🔑 路由级定位(2026-10-16,对齐 go-lib alpha.28 handlerFields):
+            # BaseHTTPMiddleware 在路由匹配**之前**执行,request 段
+            # scope["route"] 为空;call_next 返回后 scope 已被下游填充 —
+            # 在此重读 scope 拿 endpoint(协程断栈链的稳定业务定位)。
+            _route = request.scope.get("route")
+            _ep = getattr(_route, "endpoint", None) if _route else None
+            _route_path = getattr(_route, "path", "") or request.scope.get("path", "")
+            if _ep is not None:
+                _ep_mod = getattr(_ep, "__module__", "") or ""
+                _pkg = "/".join(_ep_mod.split(".")[-2:]) if _ep_mod else ""
+                response_message["handler"] = (
+                    f"{_ep_mod}.{getattr(_ep, '__name__', '')} (PATH {_route_path})")
+                if _pkg:
+                    response_message["handler_pkg"] = _pkg
+            elif _handler_ctx.get("handler"):
+                response_message["handler"] = _handler_ctx["handler"]
             SYLogger.info(response_message)
 
             # 兜底：确保 Header 必有 TraceId

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon_python_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.10a12
+Version: 0.2.10a13
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.10a12 → sycommon_python_lib-0.2.10a13}/src/sycommon_python_lib.egg-info/SOURCES.txt

@@ -351,16 +351,19 @@ src/sycommon_python_lib.egg-info/top_level.txt
 tests/test_acp_tool.py
 tests/test_asyncio_logging.py
 tests/test_config_change_notifier.py
+tests/test_frame_alignment.py
 tests/test_hotreload_snapshot.py
 tests/test_kafka_upie_fix.py
 tests/test_llm_apikey_contextvar.py
 tests/test_log_masker.py
+tests/test_print_capture.py
 tests/test_resilient_pg_saver.py
 tests/test_sandbox_path_guard.py
 tests/test_sensitive_guard.py
 tests/test_simple_chat_agent.py
 tests/test_skill_regex_upgrade.py
 tests/test_skill_write_guard.py
+tests/test_sql_params_full.py
 tests/test_streaming_e2e.py
 tests/test_summary_echo_break_loop.py
 tests/test_sycli.py
@@ -368,5 +371,6 @@ tests/test_sylogger_fixes.py
 tests/test_sync_skills_to_sandbox.py
 tests/test_time_utils.py
 tests/test_traceid_omit_base64.py
+tests/test_unicode_decode_regress.py
 tests/test_upload_concurrency.py
 tests/test_upload_e2e_http.py