dsheard/cobol-o-matic
GitHub: dsheard/cobol-o-matic
一款利用 Claude Agent SDK 对 COBOL 遗留系统进行逆向工程的智能工具，自动提取结构化需求、业务规则和依赖关系图。
Stars: 2 | Forks: 0
# COBOL 逆向工程的智能体工作流
一款智能工具，可从任何 COBOL 应用程序中提取结构化需求、业务规则和依赖信息。它使用 [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) 生成专门的子智能体来分析 COBOL 源文件，并生成具有一致结构和机器可读前置数据的 markdown 制品。
专为**大型主机代码库**设计——它根据代码库大小自动选择最佳运行策略，支持灵活的源目录布局，并通过分块分析处理多达数千行的程序。
关于此工具背后的设计原理和架构，请参阅配套博客文章：[Feeding the SDLC factory: extracting requirements from legacy COBOL with agentic workflows](docs/feeding-the-factory.md)。有关真实 COBOL 应用程序的示例输出，请参阅 [`examples/cbsa-output/`](examples/cbsa-output/)。
## 工作原理
编排器会为包含 10 个以上程序的代码库自动选择**五阶段工作流**（最常见的现实场景）：
```
┌──────────────────────────────┐
│ Phase 1: Cross-cutting │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │Inventory │ │ Flow │ │
│ │ Worker │ │ Worker │ │
│ └────┬─────┘ └────┬─────┘ │
│ ┌────┴─────────────┴─────┐ │
│ │ Integration Worker │ │
│ └────────────┬───────────┘ │
│ Critic validates │
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ Phase 2: Per-program sweep │
│ │
│ For each program (or batch) │
│ ┌──────────┐ ┌──────────┐ │
│ │ Business │ │ Data │ │
│ │ Rules │ │ Worker │ │
│ │ Worker │ │ │ │
│ └────┬─────┘ └────┬─────┘ │
│ └──────┬───────┘ │
│ Critic validates │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Phase 3: Synthesis │
│ │
│ Requirements Deriver │
│ (capabilities, NFRs, │
│ modernization notes) │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Phase 4: Test Specs │
│ │
│ Test Specs Worker │
│ (behavioral, data │
│ contracts, equivalence │
│ matrix) │
│ Validator + Critic pass │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Phase 5: Implementation │
│ │
│ Implementation Plan Deriver │
│ (strategy evaluation, │
│ migration phases, │
│ risk assessment) │
└──────────────────────────────┘
```
对于小型代码库（1-10 个程序），所有 worker 将在单个会话中运行。
### Workers
| Worker | 分析内容 |
| ----------------------- | ------------------------------------------------------------------------ |
| **inventory** | 程序、copybook、JCL、BMS 映射、CSD 定义 |
| **data** | DATA DIVISION、copybook 结构、文件布局、DB 操作 |
| **business-rules** | PROCEDURE DIVISION 逻辑：条件、计算、错误处理 |
| **flow** | CALL 链、PERFORM 层次结构、JCL 序列、BMS 屏幕流 |
| **integration** | 文件 I/O、DB、MQ、CICS、CSD 映射、外部系统边界 |
| **test-specs** | 技术栈无关的行为测试、数据契约、可追溯性矩阵 |
| **implementation-plan** | 基于能力和依赖关系的策略评估与分阶段迁移计划 |
### Critic
在 worker 报告发现后，**critic subagent**（审查子智能体）会验证一致性：验证 CALL 目标是否存在于清单中，copybook 引用是否可解析，以及依赖前置数据是否双向一致。
### 需求推导器
将所有 worker 的输出综合为高级功能能力、非功能需求和现代化备注。
### 测试规范
从所有先前制品中推导出技术栈无关的测试规范。生成按能力分组的行为测试场景、数据契约测试（格式不变量、边界检查），以及将每个场景链接回业务规则和源段落的可追溯性矩阵。确定性验证器会自动修正覆盖率算术并检查能力完整性，随后由 LLM critic 进行语义一致性检查。
### 实施计划
根据实际代码库特征评估迁移策略（绞杀植物模式、重写、按抽象分支、并行运行、流水线替换），选择最合适的策略，并基于能力、依赖图和集成分析制定分阶段迁移计划。识别自然边界，根据依赖顺序和风险将能力排序为迁移阶段，并生成包含风险评估的具体路线图。
## 先决条件
- Python 3.10+
- Anthropic API 密钥或 AI Gateway 端点
```
pip install -r requirements.txt
```
## 环境变量
| 变量 | 必需 | 描述 |
| -------------------- | ---- | ----------------------------------------------- |
| `ANTHROPIC_API_KEY` | 是 | API 密钥（直连 Anthropic）或 JWT 令牌（AI Gateway）|
| `ANTHROPIC_BASE_URL` | 否 | AI Gateway 代理 URL。如果直连 Anthropic API 则省略 |
## 快速入门
```
# 1. 初始化工作区（或 clone 此 repo）
python analyse.py init
# 2. 编辑 config.yaml -- 将源路径指向您的 COBOL 文件
# （无需将文件复制到指定的子目录中）
# 3. 运行分析（自动选择最优策略）
export ANTHROPIC_API_KEY=sk-ant-...
python analyse.py run
```
该工具会扫描配置的源目录，计算程序数量，并自动运行最佳策略。对于像 CardDemo 这样包含 30 个以上程序的代码库，它将运行五阶段工作流，无需任何标志。
## 使用方法
### 默认模式（推荐）
直接运行，不带任何标志。编排器会评估代码库大小并自动选择最佳策略：
```
python analyse.py run
```
对于 1-10 个程序，它在单个会话中运行所有 worker。对于 11 个以上程序，它会自动选择五阶段工作流（跨切分、单程序扫描、综合、测试规范、实施计划）。
### 单程序模式
```
python analyse.py run --program ACCT0100
```
### Worker 选择
仅运行特定的 worker（适用于分阶段手动运行）：
```
# 仅 Cross-cutting
python analyse.py run --workers inventory,flow,integration --max-iterations 1
# 仅 Per-program depth
python analyse.py run --workers business-rules,data
# 仅 Synthesis
python analyse.py run --workers requirements --max-iterations 1
```
### 恢复运行
如果运行中途失败，可以恢复运行。已完成的程序将被跳过：
```
python analyse.py run --resume
```
### 预处理 (Staging)
在运行分析之前，将大型程序预先分块：
```
python analyse.py stage # stage all large programs
python analyse.py stage --program ACCT0100 # stage one program
python analyse.py stage --chunk-threshold 600
```
### 验证
根据确定性提取的事实验证输出制品：
```
python analyse.py validate
```
### 常用选项
```
python analyse.py run --dry-run # report without writing files
python analyse.py run --max-iterations 3 # limit iterations
python analyse.py run --batch-size 5 # parallel programs per window
python analyse.py run --verbose # debug logging
python analyse.py run --workspace /path # different workspace
```
## CLI 参考
### `run` -- 运行分析
| 标志 | 默认值 | 描述 |
| ------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `--program` | all | 分析单个程序（例如 `ACCT0100`） |
| `--workers` | all | 逗号分隔的 worker 列表 |
| `--batch-size` | `3` | 分阶段模式下每个并行窗口的程序数 |
| `--dry-run` | `false` | 报告发现结果但不写入文件 |
| `--max-iterations` | `5` | 每个分析循环的最大迭代次数 |
| `--n-stable` | `2` | 在连续 N 次迭代发现结果为 0 后停止 |
| `--resume` | `false` | 从状态文件恢复（跳过已完成的程序） |
| `--verbose` | `false` | 启用调试级别日志 |
| `--workspace` | 自动检测 | 工作区根目录的路径 |
### `stage` -- 将大型程序分块
| 标志 | 默认值 | 描述 |
| -------------------- | ------- | --------------------------------- |
| `--program` | all | 预处理单个程序 |
| `--chunk-threshold` | `2000` | 超过此行数的程序将被分块 |
| `--workspace` | auto | 工作区目录的路径 |
| `--verbose` | `false` | 启用调试日志 |
### `validate` -- 验证输出制品
| 标志 | 默认值 | 描述 |
| ------------- | ------ | -------------------- |
| `--workspace` | auto | 工作区目录的路径 |
| `--verbose` | `false`| 启用调试日志 |
## 运行策略
编排器根据程序数量自动选择，或者您可以显式覆盖：
| 程序数 | 自动策略 | 行为 |
| ------ | ---------- | ---------------------------------------------------------------------------- |
| 1-10 | `default` | 所有 worker 在单个会话中运行，2 次迭代 |
| 11-30 | `phased` | 跨切分 → 批量扫描（3 个/批）→ 综合 → 测试规范 → 实施计划 |
| 30+ | `phased` | 跨切分 → 单程序扫描 → 综合 → 测试规范 → 实施计划 |
### 为什么选择分阶段？
- **阶段 1**（跨切分）为 worker 提供完整的应用程序视图，以便进行调用图、集成映射和清单分析
- **阶段 2**（单程序）为每个程序提供针对性的关注，以提取业务规则和数据——大型程序不会在噪声中被遗漏
- **阶段 3**（综合）读取所有制品以推导需求和现代化备注
- **阶段 4**（测试规范）从所有先前输出推导技术栈无关的测试场景，然后在 critic 检查之前确定性验证覆盖率算术和跨制品一致性
- **阶段 5**（实施计划）根据代码库特征评估迁移策略，并基于能力、依赖图和所有先前阶段的风险分析制定分阶段迁移计划
## 配置
`config.yaml` 定义源路径（作为目录列表）、输出位置和分析设置：
```
application: CardDemo - Credit Card Management System
source:
programs:
- ./app/cbl
copybooks:
- ./app/cpy
- ./app/cpy-bms
jcl:
- ./app/jcl
- ./app/proc
bms:
- ./app/bms
csd:
- ./app/csd
sql: []
recursive: true
extensions:
programs: [.cbl, .cob, .CBL, .COB]
copybooks: [.cpy, .copy, .CPY, .COPY]
jcl: [.jcl, .JCL, .prc, .PRC]
bms: [.bms, .BMS]
csd: [.csd, .CSD]
sql: [.sql, .SQL]
output: ./output
settings:
model: claude-sonnet-4-6
max_iterations: 5
n_stable: 2
confidence_threshold: medium
strategy: auto
batch_size: 3
large_file_threshold: 400
```
### 源类型
| 类型 | 必需 | 扩展名 | 用途 |
| ----------- | ---- | -------------- | ------------------------------------------ |
| `programs` | 是 | `.cbl`, `.cob` | COBOL 程序源代码 |
| `copybooks` | 是 | `.cpy`, `.copy`| Copybook 包含文件 |
| `jcl` | 否 | `.jcl`, `.prc` | JCL 作业和过程 |
| `bms` | 否 | `.bms` | CICS BMS 屏幕定义 |
| `csd` | 否 | `.csd` | CICS 资源定义（事务到程序的映射） |
| `sql` | 否 | `.sql` | SQL/DDL 定义 |
### 灵活布局
该工具适用于任何目录结构。程序和 copybook 可以位于同一目录、不同目录或嵌套子目录中。扩展名过滤器用于区分文件类型。有关针对常见开源 COBOL 仓库的配置，请参阅 `examples/`。
## 示例配置
针对热门开源 COBOL 应用程序的预构建配置：
| 文件 | 应用程序 | 程序数 | 布局 |
| ------------------------------- | ---------------------- | ------ | ------------------------ |
| `examples/carddemo.yaml` | AWS CardDemo | 31 | 扁平，多目录，BMS+CSD |
| `examples/cbsa.yaml` | CICS Banking (CBSA) | 29 | 扁平，3 个 JCL 目录，BMS |
| `examples/benchmark-suite.yaml` | COBOL Legacy Benchmark | 42 | 按角色嵌套子目录 |
| `examples/genapp.yaml` | GenApp Insurance | 31 | 混合程序+copybook |
| `examples/cash-account.yaml` | Cash Account | 1 | 最小化，混合目录 |
| `examples/zbank.yaml` | zBANK | 7 | 仓库根目录，无 copybook |
## 示例输出
[`examples/cbsa-output/`](examples/cbsa-output/) 包含分析 [CICS Banking Sample Application (CBSA)](https://github.com/cicsdev/cics-banking-sample-application-cbsa) 的完整输出——这是一个包含 29 个程序的 CICS/DB2 在线银行应用程序。这展示了该工具产出的具体内容：
| 目录 | 内容 |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `business-rules/`| 29 个单程序业务规则提取，包含类型化依赖前置数据 |
| `inventory/` | 程序目录、copybook 目录、JCL 作业清单 |
| `data/` | 数据字典、文件布局、数据库操作 |
| `flows/` | 程序调用图（含 Mermaid 图）、批处理流、数据流 |
| `integration/` | 接口目录和 I/O 映射 |
| `requirements/` | 功能能力、非功能需求、现代化备注、实施计划 |
| `test-specs/` | 行为测试场景、数据契约测试、可追溯性矩阵 |
## 输出制品
| 制品 | 描述 | 依赖图角色 |
| ------------------------------------ | -------------------------------------- | ---------------- |
| `application.md` | 顶层概览 | 根节点 |
| `inventory/programs.md` | 程序目录 | 索引 |
| `inventory/copybooks.md` | 带有 `used_by` 的 copybook 目录 | 反向引用 |
| `data/data-dictionary.md` | 数据项参考 | -- |
| `data/file-layouts.md` | 带有 `read_by`/`written_by` 的文件描述 | 反向引用 |
| `business-rules/{prog}.md` | 单程序规则 | **主要图节点** |
| `flows/program-call-graph.md` | 带 Mermaid 图的调用拓扑 | 派生 |
| `integration/interfaces.md` | 带有 `used_by_programs` 的外部接触点 | 反向引用 |
| `requirements/capabilities.md` | 派生的功能能力 | 综合 |
| `requirements/modernization-notes.md`| 迁移观察 | 综合 |
| `test-specs/behavioral-tests.md` | 按能力分组的技术栈无关测试场景 | 源于上述所有内容 |
| `test-specs/data-contracts.md` | 数据格式不变量及边界检查 | 源于上述所有内容 |
| `test-specs/equivalence-matrix.md` | 可追溯性：测试 ↔ 规则 ↔ 源代码 | 源于上述所有内容 |
| `requirements/implementation-plan.md`| 策略评估与分阶段迁移计划 | 综合 |
###依赖图
单程序 `business-rules/{program}.md` 文件包含类型化的关系前置数据：
```
calls: [ACCT0200, DATE-UTIL]
called_by: [MAIN0100]
uses_copybooks: [ACCT-RECORD, COMMON-DATES]
reads: [ACCT-MASTER, TRANS-INPUT]
writes: [ACCT-REPORT, ERROR-LOG]
db_tables: [ACCOUNT, CUSTOMER]
```
这支持通过扫描输出目录中的前置数据进行影响分析、调用图遍历和数据血缘查询。
## 文件结构
```
analyse.py # Thin entry point
orchestrator/
├── __init__.py # Shared constants and utilities
├── cli.py # CLI argument parsing, command handlers, main()
├── config.py # Config loading, defaults, workspace scaffolding
├── agents.py # Agent construction, SDK interaction, critic
├── runner.py # Run strategies, phased execution, sweep
├── models.py # Discovery, ProgramFacts, ProgramManifest dataclasses
├── parser.py # Deterministic COBOL structural parser
├── stager.py # Chunk staging pipeline and output pre-population
├── state.py # State persistence and reporting
├── tracing.py # JSONL event logging and optional OTEL tracing
└── validator.py # Deterministic artifact validation
prompts/
├── __init__.py
├── _helpers.py # Shared prompt builder helpers
├── inventory.py # Inventory worker prompt
├── data.py # Data worker prompt
├── business_rules.py # Business rules worker prompt
├── flow.py # Flow worker prompt
├── integration.py # Integration worker prompt
├── requirements.py # Requirements deriver prompt
├── test_specs.py # Test specifications worker prompt
├── orchestrator.py # Orchestrator prompt and helpers
├── implementation.py # Implementation plan deriver prompt
└── critic.py # LLM critic prompt for corrective passes
templates/
├── application.md
├── program-inventory.md
├── copybook-inventory.md
├── data-dictionary.md
├── file-layouts.md
├── business-rules.md
├── program-call-graph.md
├── interfaces.md
├── capabilities.md
├── modernization-notes.md
├── behavioral-tests.md
├── data-contracts.md
├── equivalence-matrix.md
└── implementation-plan.md
examples/
├── carddemo.yaml # AWS CardDemo config
├── cbsa.yaml # CICS Banking config
├── cbsa-output/ # Full example output from CBSA analysis
├── benchmark-suite.yaml # COBOL Legacy Benchmark config
├── genapp.yaml # GenApp Insurance config
├── cash-account.yaml # Cash Account config
└── zbank.yaml # zBANK config
```
_Vibe coded with love._
标签：Anthropic, CIS基准, Claude, COBOL, CVE检测, DLL 劫持, IT遗产, Mainframe, Python SDK, 业务规则提取, 云资产清单, 代码分析, 代码理解, 依赖图, 凭证管理, 可配置连接, 大型机, 大语言模型, 文档生成, 程序分析, 系统重构, 软件现代化, 逆向工具, 逆向工程, 遗留系统迁移, 防御加固