feat(增强调试工具): 在WiredTableDebugUtils类中添加resolve_debug_output_dir方法，优化调试选项合并逻辑，支持默认子目录配置，提升调试输出路径的灵活性和可维护性。

ocr_tools/universal_doc_parser/models/adapters/wired_table/debug_utils.py

@@ -3,6 +3,7 @@
 
 提供调试选项管理和路径生成功能。
 """
+from pathlib import Path
 from typing import Dict, Any, Optional
 from dataclasses import dataclass
 
@@ -12,6 +13,7 @@ class WiredTableDebugOptions:
     """调试选项数据类"""
     enabled: bool = False
     output_dir: Optional[str] = None
+    subdir: str = "table_recognition_wired"
     save_table_lines: bool = False
     save_connected_components: bool = False
     save_grid_structure: bool = False
@@ -22,86 +24,83 @@ class WiredTableDebugOptions:
 
 class WiredTableDebugUtils:
     """调试工具类"""
-    
+
     @staticmethod
     def merge_debug_options(
         config: Dict[str, Any],
-        override: Optional[Dict[str, Any]] = None
+        override: Optional[Dict[str, Any]] = None,
+        *,
+        default_subdir: str = "table_recognition_wired",
     ) -> WiredTableDebugOptions:
         """
         合并调试选项
-        
+
         Args:
             config: 配置字典
             override: 覆盖选项字典
-            
+            default_subdir: 未配置 subdir 时的默认值
+
         Returns:
             合并后的调试选项
         """
         debug_config = config.get("debug_options", {})
         if not isinstance(debug_config, dict):
-            # 兼容旧配置：如果不是字典，尝试作为 boolean 或 fall back
             debug_config = {}
 
         opts = WiredTableDebugOptions(
             enabled=bool(debug_config.get("enabled", False)),
             output_dir=debug_config.get("output_dir"),
+            subdir=str(debug_config.get("subdir") or default_subdir),
             save_table_lines=bool(debug_config.get("save_table_lines", False)),
-            save_connected_components=bool(debug_config.get("save_connected_components", False)),
+            save_connected_components=bool(
+                debug_config.get("save_connected_components", False)
+            ),
             save_grid_structure=bool(debug_config.get("save_grid_structure", False)),
             save_text_overlay=bool(debug_config.get("save_text_overlay", False)),
             image_format=str(debug_config.get("image_format", "png")),
             prefix=str(debug_config.get("prefix", "")),
         )
-        
+
         if override and isinstance(override, dict):
-            # 覆盖层允许临时启用或指定目录
             for k, v in override.items():
-                if hasattr(opts, k):
+                if hasattr(opts, k) and v is not None:
                     setattr(opts, k, v)
-        
+
         return opts
-    
+
+    @staticmethod
+    def resolve_debug_output_dir(
+        opts: Optional[WiredTableDebugOptions],
+    ) -> Optional[Path]:
+        """``{output_dir}/debug/{subdir}/``，与 layout/ocr module debug 一致。"""
+        if not opts or not opts.enabled or not opts.output_dir:
+            return None
+        from ocr_utils.module_debug_viz import resolve_module_debug_dir
+
+        return resolve_module_debug_dir(
+            opts.output_dir, opts.subdir or "table_recognition_wired"
+        )
+
     @staticmethod
     def debug_is_on(
         flag: str,
-        opts: Optional[WiredTableDebugOptions] = None
+        opts: Optional[WiredTableDebugOptions] = None,
     ) -> bool:
-        """
-        检查调试标志是否启用
-        
-        Args:
-            flag: 调试标志名称
-            opts: 调试选项（可选）
-            
-        Returns:
-            是否启用
-        """
         if not opts or not opts.enabled:
             return False
         if not opts.output_dir:
             return False
         return bool(getattr(opts, flag, False))
-    
+
     @staticmethod
     def debug_path(
         name: str,
-        opts: Optional[WiredTableDebugOptions] = None
+        opts: Optional[WiredTableDebugOptions] = None,
     ) -> Optional[str]:
-        """
-        生成调试文件路径
-        
-        Args:
-            name: 文件名（不含扩展名）
-            opts: 调试选项（可选）
-            
-        Returns:
-            完整文件路径，如果未启用则返回 None
-        """
-        if not opts or not opts.output_dir:
+        debug_dir = WiredTableDebugUtils.resolve_debug_output_dir(opts)
+        if debug_dir is None:
             return None
-        
-        prefix = (opts.prefix + "_") if opts.prefix else ""
-        ext = opts.image_format or "png"
-        return f"{opts.output_dir}/{prefix}{name}.{ext}"
 
+        prefix = (opts.prefix + "_") if opts and opts.prefix else ""
+        ext = (opts.image_format if opts else None) or "png"
+        return str(debug_dir / f"{prefix}{name}.{ext}")