|
|
@@ -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`（运行时由命令行控制） |
|
|
|
+
|
|
|
+---
|
|
|
+## 结语
|
