docs: 更新 run.py 黑盒全流程说明与运行时注意要点

README.md

@@ -98,15 +98,17 @@ output/{プログラムID}/g{N}/{プログラムID}_g{N}.sql
 
 ```
 run.py
-  ├── 步骤1: cobol_testgen（白盒）
-  │     ├── 静态分析 + 测试数据生成
-  │     ├── 编译运行 COBOL 程序
-  │     └── gcov 覆盖率收集
+  ├── 步骤1: black-box-data-create（黑盒）
+  │     ├── 解析設計書 + COPY + DB定義
+  │     ├── LLM 生成 JSON/SQL
+  │     └── 输出到 output/{程序ID}/black_box/g{N}/
   │
-  └── 步骤2: black-box-data-create（黑盒）
-        ├── 解析設計書 + COPY + DB定義
-        ├── LLM 生成 JSON/SQL
-        └── 输出到 output/{程序ID}/g{N}/
+  └── 步骤2: cobol_testgen（白盒 + 黑盒比对）
+        ├── 静态分析 + 白盒测试数据生成
+        ├── 编译运行 COBOL + Java 比对（白盒组）
+        ├── 读取黑盒 JSON → 编译运行 + Java 比对（黑盒组）
+        ├── gcov 覆盖率收集（仅白盒）
+        └── 合并报告 output/{程序ID}/{程序ID}_测试报告.md
 ```
 
 ---
@@ -274,7 +276,7 @@ print(f'生成 {len(recs)} 条测试记录')
 
 ## 全流程数据生成（run.py）
 
-白盒+黑盒双管道一键执行：
+黑盒 LLM 数据生成 + 白盒/黑盒运行比对一键执行（**先黑盒 → 再白盒+黑盒**）：
 
 ```bash
 # 使用环境变量指定路径（推荐）
@@ -298,24 +300,38 @@ python run.py \
 | `--cpy` | ✓ | COPYBOOK 格納ディレクトリ |
 | `--db-md` | ✓ | DB定義書 .md パス |
 | `--output` | | 出力ディレクトリ（デフォルト: output） |
-| `--api-key` | | DeepSeek API Key |
+| `--api-key` | | DeepSeek API Key（未指定则读环境变量/配置文件） |
 | `--model` | | モデル名（デフォルト: deepseek-v4-flash） |
+| `--no-black-box` | | 跳过黑盒生成，仅跑白盒 cobol_testgen |
+| `--dry-run` | | 只打印要执行的命令，不实际执行 |
+
+### 运行时注意要点
+
+1. **执行顺序**：`run.py` 先跑步骤1黑盒生成，再跑步骤2白盒+黑盒比对。`cobol_testgen` 的 `--black-box` 只**读取**已生成的黑盒 JSON，不会自行生成数据；因此必须先生成黑盒数据。
+2. **API Key**：步骤1 需要有效的 DeepSeek API Key，优先级为 命令行 `--api-key` > 环境变量 `DEEPSEEK_API_KEY` > `black-box-data-create/config.json`。Key 缺失/无效会返回 `401 Authorization Required`，**与模型版本无关**。Key 以 `sk-` 开头，程序会自动加 `Bearer` 前缀（不要手写 `Bearer`）。
+3. **失败即停**：步骤1 失败（如 401、网络错误、JSON 解析失败）会立即返回非 0 退出码，不再执行步骤2。请先解决 Key/网络问题再重跑。
+4. **黑盒目录**：黑盒 JSON 输出到 `output/{程序ID}/black_box/g{N}/{程序ID}_g{N}.json`；步骤2 以 `--black-box output/{程序ID}` 读取，程序会自动在其中查找 `black_box/g*/`。
+5. **覆盖率隔离**：黑盒运行**不参与 gcov 覆盖率统计**，`coverage/` 与报告中的覆盖率数字只反映白盒。
+6. **目录隔离**：黑盒产物只写在 `output/{程序ID}/black_box/{组}/...`，不会覆盖白盒的 `cobol/main`、`run_skip`、`coverage`。
+7. **JDK 可选**：未发现对应 `JavaSrc/*Main.java` 时，Java 比对自动跳过，仅执行 COBOL 并生成报告。
+8. **重复执行安全**：重复运行会覆盖同名输出；黑盒各组使用独立工作目录，组间数据不会串扰。
+9. **cmd 与 PowerShell 差异**：cmd 用 `^` 续行、PowerShell 用 `` ` ``；在 cmd 中误用反引号会被当作参数导致 `unrecognized arguments`。
 
 ### 输出目录结构
 
 ```
 output/
 └── ZAN04MAT/
-    ├── main/                    # 白盒输出
-    │   ├── json/                # テストデータJSON
-    │   ├── input/               # 入力ファイル
-    │   └── gcov/                # カバレッジデータ
-    ├── g1/                      # 黑盒グループ1
-    │   └── ZAN04MAT_g1.json
-    ├── g2/                      # 黑盒グループ2
-    │   └── ZAN04MAT_g2.json
-    └── g3/                      # 黑盒グループ3
-        └── ZAN04MAT_g3.json
+    ├── cobol/main/              # 白盒输出（json / input / output）
+    ├── cobol/run_skip/          # Skip 数据集（主 FD 空文件）
+    ├── java/main/output/        # 白盒 Java 出力
+    ├── black_box/g1/            # 黑盒组1
+    │   ├── ZAN04MAT_g1.json     # 黑盒原始数据
+    │   ├── cobol/               # 黑盒 COBOL 入力/出力
+    │   └── java/output/         # 黑盒 Java 出力
+    ├── black_box/g2/            # 黑盒组2（同上）
+    ├── coverage/                # 覆盖率 HTML（仅白盒）
+    └── ZAN04MAT_测试报告.md      # 白盒组 + 黑盒组合并报告
 ```
 
 ## 架构