feat(debug_mode): 添加调试模式文档，描述当前问题及建议设计

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

@@ -0,0 +1,109 @@
+## 当前问题诊断
+
+**共 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
+
+```python
+# 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）：
+
+```python
+processed_elements, discarded_elements = self._process_all_elements(
+    ...
+    debug_mode=self.debug_mode,   # ← 补充这一项
+    output_dir=output_dir,
+)
+```
+
+### 第三层：element_processors.py — 构建 debug_options 时加上 enabled
+
+```python
+# 当前（缺失 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` 动态注入：
+
+```yaml
+# ✅ 推荐：只描述保存项，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`（运行时由命令行控制） |
+
+---
+## 结语