ocr_platform/docs/ocr_tools/universal_doc_parser/debug参数控制.md

当前问题诊断

共 5 处断裂点：

#	问题	位置
1	--debug CLI 参数从未传进 pipeline.debug_mode	main_v2.py：yaml 有 output 块时，debug 参数被完全丢弃
2	_process_all_elements 调用时没有穿透 debug_mode	pipeline_manager_v2.py：element_processors 看不到 pipeline 层的 debug 状态
3	element_processors 构建子模块 debug_options 时漏掉了 enabled	只注入了 output_dir/prefix，子模块即使拿到路径也不会输出
4	新旧两套系统（debug_mode vs debug_options.enabled）无统一激活入口	base.py 做了兼容读取但没有统一写入
5	streaming 模式完全不传播 debug_mode	pipeline_manager_v2_streaming.py

---

建议设计：单一开关 → 逐层传播

核心原则：命令行 --debug 是唯一的顶层开关，向下覆盖 yaml 配置。

第一层：main_v2.py — 写入 pipeline.debug_mode

# process_single_input 中，创建 pipeline 后立即覆盖 debug_mode
pipeline = _create_pipeline(...)

# 命令行 --debug 优先级高于 yaml
if debug:
    pipeline.debug_mode = True
    # 同步覆盖 output 配置
    pipeline.config.setdefault('output', {})['debug_mode'] = True

第二层：pipeline_manager_v2.py — 向子模块传播

在 _process_all_elements 调用处加入 debug 参数传递（pipeline → element_processors）：

processed_elements, discarded_elements = self._process_all_elements(
    ...
    debug_mode=self.debug_mode,   # ← 补充这一项
    output_dir=output_dir,
)

第三层：element_processors.py — 构建 debug_options 时加上 enabled

# 当前（缺失 enabled）
debug_opts_override = {'output_dir': output_dir, 'prefix': basename}

# 修正后
debug_opts_override = {
    'enabled': debug_mode,        # ← 缺失的这一项
    'output_dir': output_dir,
    'prefix': basename,
}

yaml 配置建议：debug_options 应只配置保存内容，不配 enabled

各子模块的 debug_options 只负责描述"调试时保存什么"，enabled 动态注入：

# ✅ 推荐：只描述保存项，enabled 由运行时控制
table_recognition_wired:
  debug_options:
    output_dir: null        # null = 随输出目录
    save_table_lines: true
    save_grid_structure: true
    save_text_overlay: true

# ❌ 不推荐：hardcode enabled: true，会绕过命令行开关
table_recognition_wired:
  debug_options:
    enabled: true           # 这会永远开启，无法被命令行关闭

---

推荐的完整控制层级

命令行 --debug
    ↓ 写入
pipeline.debug_mode（覆盖 yaml output.debug_mode）
    ↓ 注入（已有）
layout_detector.debug_mode
    ↓ 注入（待补）
element_processors(debug_mode=...)
    ↓ 构建（待补 enabled 字段）
wired_table.recognize(debug_options={'enabled': debug_mode, ...})
table_classifier.classify(debug_options={'enabled': debug_mode, ...})

--log_level 与 debug 是独立维度，不需要联动，按现有设计保持即可。

---

需要修改的文件清单

文件	改动
main_v2.py	--debug 写入 pipeline.debug_mode
pipeline_manager_v2.py	_process_all_elements 传入 debug_mode
core/element_processors.py	接收并向子模块传递 debug_mode，构建 debug_options 时加 enabled
pipeline_manager_v2_streaming.py	同步补充 debug_mode 传播（与 v2 保持一致）
yaml 配置文件	各模块 debug_options.enabled 改为 false（运行时由命令行控制）

---

结语