cobol-java-v3/docs/detailed-design/09-run-pipeline.md

全流程管道详细设计 (run.py + black-box-data-create)

版本: v1.0 | 日期: 2026-08-23 本文档描述 COBOL 迁移验证平台 V3 的全流程入口 run.py 和黑盒 LLM 数据生成模块 black-box-data-create/。

---

1. 模块概述

1.1 职责

全流程管道模块是 V3 系统的顶层入口，负责：

1. 一键执行 白盒 + 黑盒全流程测试数据生成
2. 黑盒 LLM 生成 基于详细设计书的 LLM 测试数据生成
3. 管道编排 两步顺序执行，任一步失败即停止

1.2 边界

在范围内	不在范围内
白盒 cobol_testgen 调用	COBOL 程序执行（由 runners/ 负责）
黑盒 black-box-data-create 调用	字段比对（由 comparator/ 负责）
参数解析和传递	LLM API 调用细节（由 black-box-data-create 内部处理）
错误传播和退出码	覆盖率分析（由 coverage.py 负责）

---

2. 文件清单

2.1 run.py（全流程入口）

文件	行数	职责
run.py	86	全流程入口：白盒 + 黑盒顺序执行

2.2 black-box-data-create/（黑盒 LLM 模块）

文件	行数	职责
main.py	67	CLI 入口，参数解析，调用 generate()
agent/__init__.py	57	模块入口，generate() 函数，管道编排
agent/models.py	~80	数据类定义：ProgramMeta, FileInfo, CopyField, KeyInfo, TableColumn, TableInfo
agent/input_parser.py	330	设计书 + COPYBOOK + DB定义解析
agent/markdown_utils.py	~100	Markdown 表格解析工具
agent/rule_loader.py	226	PGM模式 → 规则文件匹配
agent/prompt_builder.py	146	LLM 提示词组装
agent/api_client.py	132	DeepSeek API 调用 + 3次重试
agent/output_writer.py	59	JSON/SQL 文件输出
rules/pgm_pattern/	~30 files	PGM 模式规则文件（.md）
tests/	10 files	单元测试 + 集成测试

---

3. 全流程管道设计 (run.py)

3.1 架构图

run.py (全流程入口)
    │
    ├── Step 1: python -m cobol_testgen --gcov <source> <output>
    │     │
    │     ├── read.py: 预处理 + DATA DIVISION 解析
    │     ├── core.py / procedure_parser.py: 分支树构建
    │     ├── design.py / design_mcdc.py: 路径枚举 + 值生成
    │     ├── output.py: JSON 输出
    │     └── coverage.py: HTML 覆盖率报告
    │
    └── Step 2: black-box-data-create/main.py
          │
          ├── InputParser: 解析设计书 + COPYBOOK + DB定义
          ├── RuleLoader: PGM模式匹配 → 规则文件
          ├── PromptBuilder: 组装 LLM 提示词
          ├── APIClient: DeepSeek API 调用
          └── OutputWriter: JSON/SQL 输出

3.2 参数设计

def build_parser():
    p = argparse.ArgumentParser(
        description="COBOL 迁移验证平台：先跑白盒 cobol_testgen，再跑黑盒 LLM 数据生成")
    p.add_argument("--design", required=True, help="詳細設計書 .md のパス")
    p.add_argument("--source", required=True, help="COBOL ソース .cbl のパス")
    p.add_argument("--file-db-md", required=True, help="ファイル/DB 構造 .md のパス")
    p.add_argument("--cpy", required=True, help="COPYBOOK 格納ディレクトリ")
    p.add_argument("--db-md", required=True, help="DB 定義書 .md のパス")
    p.add_argument("--output", default="output", help="出力ディレクトリ")
    p.add_argument("--api-key", help="DeepSeek API Key（透传给黑盒）")
    p.add_argument("--model", help="API モデル名（透传给黑盒）")
    p.add_argument("--rules", help="ルール格納ディレクトリ（透传给黑盒）")
    p.add_argument("--max-tokens", type=int, help="API 生成トークン上限（透传给黑盒）")
    p.add_argument("--dry-run", action="store_true", help="只打印要执行的命令，不真正执行")
    return p

3.3 执行流程

def main():
    args = build_parser().parse_args()

    # Step 1: 白盒 cobol_testgen
    rc = _run(
        [sys.executable, "-m", "cobol_testgen", "--gcov", args.source, args.output],
        cwd=ROOT,
        label="步骤1: cobol_testgen 白盒数据生成",
        dry_run=args.dry_run,
    )
    if rc != 0:
        return rc

    # Step 2: 黑盒 black-box-data-create
    bb_cmd = [
        sys.executable, BLACKBOX_MAIN,
        "--design", args.design,
        "--source", args.source,
        "--file-db-md", args.file_db_md,
        "--cpy", args.cpy,
        "--db-md", args.db_md,
        "--output", args.output,
    ]
    for opt in ("--api-key", "--model", "--rules", "--max-tokens"):
        v = getattr(args, opt.lstrip("-").replace("-", "_"))
        if v is not None:
            bb_cmd.extend([opt, str(v)])

    return _run(
        bb_cmd,
        cwd=ROOT,
        label="步骤2: black-box-data-create LLM 数据生成",
        dry_run=args.dry_run,
    )

3.4 输出目录结构

output/
  └── {PROGRAM_ID}/
        ├── main/                    # Step 1 白盒输出
        │   ├── {PROGRAM_ID}.json    # 测试数据
        │   ├── input/               # 输入文件
        │   └── coverage/            # 覆盖率报告
        └── g{N}/                    # Step 2 黑盒输出（按组分目录）
            ├── {PROGRAM_ID}_g{N}.json
            └── {PROGRAM_ID}_g{N}.sql

---

4. 黑盒 LLM 模块详细设计 (black-box-data-create/)

4.1 架构图

black-box-data-create/
    │
    ├── main.py (CLI入口)
    │     │
    │     └── agent.generate() (管道入口)
    │
    └── agent/
          │
          ├── InputParser ──────────────────────────────────────┐
          │   解析设计书 + COPYBOOK + DB定义                     │
          │   输出: ProgramMeta                                  │
          │                                                     │
          ├── RuleLoader ──────────────────────────────────────┐│
          │   PGM模式 → 规则文件匹配                            ││
          │   输出: rules_text, group_descriptions              ││
          │                                                     ││
          ├── PromptBuilder ──────────────────────────────────┐││
          │   组装 LLM 提示词                                   │││
          │   输出: prompt (str)                                │││
          │                                                     │││
          ├── APIClient ─────────────────────────────────────┐│││
          │   DeepSeek API 调用 + 3次重试                      ││││
          │   输出: Dict[str, Any] (AI 生成结果)               ││││
          │                                                     ││││
          └── OutputWriter ─────────────────────────────────┐││││
              JSON/SQL 文件输出                               │││││
              输出: Dict[str, str] (文件路径映射)             │││││
                                                              │││││
                                                              ▼▼▼▼▼
                                                          generate()

4.2 核心数据流

设计书 .md + COBOL 源码 + COPY句定義書.md + DB定義書.md
    │
    ▼  InputParser.run()
ProgramMeta {
    program_id, program_name, system_name,
    pgm_type, pgm_pattern,
    files: list[FileInfo],
    keys: list[KeyInfo],
    modules: list[ModuleInfo],
    process_detail, output_records,
    input_type: "file" | "db" | "mixed",
    copy_fields: dict[str, list[CopyField]],
    db_tables: dict[str, TableInfo]
}
    │
    ▼  RuleLoader.load()
rules_text: str (规则文本)
group_descriptions: list[str] (组描述)
group_count: int (组数)
    │
    ▼  PromptBuilder.build()
prompt: str (完整 LLM 提示词)
    │
    ▼  APIClient.generate()
Dict[str, Any] (AI 生成结果，按组分)
    │
    ▼  OutputWriter.write()
Dict[str, str] (文件路径映射)

4.3 InputParser 详细设计

4.3.1 职责

解析日文详细设计书 Markdown 文档，提取程序元信息。

4.3.2 输入

参数	类型	说明
design_md_path	str	详细设计书路径
source_cbl_path	str	COBOL 源码路径
file_db_md_path	str	COPY句定義書路径
cpy_dir	str	COPYBOOK 目录
db_md_path	str	DB定義書路径

4.3.3 输出

ProgramMeta 数据类，包含程序的所有元信息。

4.3.4 解析流程

def run(self) -> ProgramMeta:
    self._design_text = self._read_file(self.design_md_path)
    self._source_text = self._read_file(self.source_cbl_path)

    meta = ProgramMeta(...)
    self._parse_basic_info(meta)        # 基本情報セクション
    self._parse_use_files(meta)         # 使用ファイル一覧
    self._parse_keys(meta)              # キー情報
    self._parse_modules(meta)           # モジュール情報
    self._parse_process_detail(meta)    # 処理詳細
    self._parse_output_records(meta)    # 出力レコード
    self._determine_input_type(meta)    # 入力タイプ判定
    self._parse_copybooks(meta)         # COPYBOOK解析
    self._parse_db_definition(meta)     # DB定義解析
    return meta

4.4 RuleLoader 详细设计

4.4.1 职责

根据程序的 PGM 模式匹配对应的规则文件。

4.4.2 PGM 模式映射

PGM_PATTERN_MAP = {
    'マッチング(1:1)': 'マッチング(1-1).md',
    'マッチング(1:N)': 'マッチング(1-N).md',
    'マッチング(N:1)': 'マッチング(N-1).md',
    'マッチング(M:N)': 'マッチング(M-N).md',
    'キーブレイク(集計)': 'キーブレイク(集計).md',
    'キーブレイク(非集計)': 'キーブレイク(非集計).md',
    '項目チェック': '項目チェック(重複含まず).md',
    '振り分け': '振り分け(IF).md',
    'GETPUT': 'レイアウト編集のみ(GETPUT).md',
    # ... 30+ 映射
}

4.4.3 匹配逻辑

1. 完全匹配：PGM_PATTERN_MAP 中查找 pgm_pattern
2. 部分匹配：规则文件名（去除 .md）是否包含在 pgm_pattern 中
3. 半角/全角括弧容错：（） vs ()

4.5 PromptBuilder 详细设计

4.5.1 职责

将 ProgramMeta 和规则文本组装成 LLM 提示词。

4.5.2 提示词结构

## プログラム基本情報
- システム名: ...
- プログラムID: ...
- PGMパターン: ...
- 入力タイプ: ...

## 処理詳細

{process_detail}

## 入力構造
### ファイル {identifier}
| 項目名 | PIC | バイト数 |
|--------|-----|----------|
| ...    | ... | ...      |

## ルール
{rules_text}

## 出力フォーマット
{output_format_instruction}

## 生成指示
{generation_instruction}

4.6 APIClient 详细设计

4.6.1 职责

调用 DeepSeek API 生成测试数据。

4.6.2 核心参数

参数	默认值	说明
model	deepseek-v4-flash	API 模型
base_url	https://api.deepseek.com/chat/completions	API 端点
max_retries	3	最大重试次数
timeout	120	超时时间（秒）
max_tokens	32768	最大生成 token 数

4.6.3 重试机制

• 指数退避：1s, 2s, 4s
• 截断处理：finish_reason=length 时追加压缩指示重试
• 错误传播：3次重试后抛出异常

4.6.4 系统提示词

你是COBOL程序的测试数据生成专家。
请严格按照提供的规则，生成符合格式要求的测试数据。
输出必须是可被json.loads()直接解析的JSON，不要包裹在```json```代码块中。
不要在JSON前后添加任何说明文字。

4.7 OutputWriter 详细设计

4.7.1 职责

将 AI 生成的数据写入文件系统。

4.7.2 输出格式

input_type	输出文件
file	{PROGRAM_ID}_{GROUP}.json
db	{PROGRAM_ID}_{GROUP}.sql
mixed	两者都生成

---

5. 接口设计

5.1 run.py 接口

# run.py

def build_parser() -> argparse.ArgumentParser:
    """构建命令行参数解析器"""
    pass

def main() -> int:
    """全流程入口，返回退出码"""
    pass

5.2 black-box-data-create 接口

# black-box-data-create/agent/__init__.py

def generate(
    design_md: str,        # 詳細設計書パス
    source_cbl: str,       # COBOL ソースパス
    file_db_md: str,       # COPY句定義書パス
    cpy_dir: str,          # COPYBOOKディレクトリ
    db_md: str,            # DB定義書パス
    output_dir: str,       # 出力ディレクトリ
    api_key: str,          # DeepSeek API Key
    api_model: str,        # モデル名 (default: deepseek-v4-flash)
    rules_dir: str,        # ルールディレクトリ
    max_tokens: int,       # トークン上限 (default: 32768)
) -> dict:
    """黑盒 LLM 测试数据生成主入口"""
    pass

---

6. 错误处理

6.1 错误分类

类别	示例	处理策略
文件不存在	设计书路径错误	返回退出码 1
API 调用失败	网络超时、认证失败	3次重试后抛出异常
JSON 解析失败	LLM 返回非法 JSON	抛出异常
程序类型为サブ	子程序不处理	ValueError
白盒步骤失败	cobol_testgen 错误	停止后续步骤

6.2 退出码

退出码	说明
0	成功
1	文件不存在或参数错误
2	白盒步骤失败
3	黑盒步骤失败

---

7. 测试策略

7.1 单元测试

• test_input_parser.py：设计书解析
• test_rule_loader.py：规则匹配
• test_prompt_builder.py：提示词组装
• test_api_client.py：API 调用（mock）
• test_output_writer.py：文件输出
• test_models.py：数据类定义
• test_markdown_utils.py：Markdown 解析

7.2 集成测试

• test_integration.py：端到端管道测试

---

8. 依赖关系

8.1 内部依赖

run.py
  └── black-box-data-create/main.py
        └── agent/__init__.py
              ├── agent/input_parser.py
              │     └── agent/models.py
              │     └── agent/markdown_utils.py
              ├── agent/rule_loader.py
              │     └── agent/models.py
              ├── agent/prompt_builder.py
              │     └── agent/models.py
              ├── agent/api_client.py
              │     └── requests
              └── agent/output_writer.py

8.2 外部依赖

依赖	用途
requests	HTTP 请求（DeepSeek API）
json	JSON 解析
argparse	命令行参数解析
os, sys	文件系统操作