## 当前问题诊断

**共 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`（运行时由命令行控制） |

---
## 结语