imsankz/mainframe-brain

[](https://www.apache.org/licenses/LICENSE-2.0) [](https://www.python.org/downloads/) [](https://github.com/imsankz/mainframe-brain/actions/workflows/ci.yml) [](#) [](#) # 大型机大脑 **一个针对遗留大型机应用程序的开源、模型无关的知识系统。** 如果你的团队拥有数百万行 COBOL 代码，而懂它的工程师正在退休，这就是介于 *parser* 和 *migration accelerator* 之间缺失的中间层：一个用于构建团队 **拥有**、**持久化** 且随着使用时间越长越 **增值** 的东西的工具 —— 没有 vendor lock-in，也无需为未更改的代码重复支付 token 成本。 ## 为什么会有这个项目 大多数针对大型机的“AI”工具只做以下两件事之一： - 将 COBOL **解析** 为 AST/XML 转储，然后就停止了。 - **推销迁移服务** —— vendor-locked（供应商锁定）、黑盒，针对“转换为 Java”进行优化，而不是“帮助工程师理解”。 两者都没有建立起团队拥有且持久化的理解。而 Mainframe Brain 做到了，它将 **免费层**（确定性结构提取 —— 零 LLM token）与 **昂贵层**（对未记录的业务逻辑进行有选择的 LLM 解读 —— 每段唯一逻辑永久仅执行一次）分离开来，并将结果写入一个可移植、可版本化的知识图谱中。 ## 它能做什么 1. **提取**（第 1 层，零 token）—— 解析 COBOL、JCL、CICS BMS、DB2 DDL、SQL PL 存储过程、DB2 触发器以及 VSAM/顺序文件。 2. **评估**（第 3 层，零 token）—— 针对上一次运行进行内容哈希差异比对，对几乎完全相同的段落进行去重，并根据确定性风险（圈复杂度 + GOTO 密度 + 外部调用 + 级联深度 + 触发链深度 + 解析置信度惩罚）进行排名。 3. **脱敏**（第 3.5 层，硬性闸门）—— 在任何内容到达模型之前，清除类似 SSN 格式的数字、卡号、IBAN、路由号码和嵌入式凭据。 4. **增强**（第 4 层，仅针对新增/变更的单元）—— 对未记录的 80% 的业务逻辑进行解读。缓存键是 *扩展后且脱敏后* 的内容哈希 —— 在未更改的代码上重新运行几乎不需要花费任何 token。 5. **查询**（第 6 层，零 token）—— 调用图、数据血缘、触发链和变更影响查询完全通过图遍历来回答。 ## 演示 完整的 JCL → 程序 → 子程序调用链，端到端，离线运行（无需 LLM 密钥 —— mock adapter 仅用于演示目的进行解读）： ``` pip3 install -e ".[dev]" --break-system-packages rm -f /tmp/mb.db mainframe-brain extract examples/cobol --out /tmp/mb.db mainframe-brain extract examples/db2 --out /tmp/mb.db mainframe-brain extract examples/jcl --out /tmp/mb.db mainframe-brain extract examples/cics_bms --out /tmp/mb.db # 哪个 job 运行哪个 program？（经典大型机问题） mainframe-brain query --store-path /tmp/mb.db "what runs INTCALC01" # → Program:default:INTCALC01 由以下调用： # --EXEC 来自--> JCLStep:default:STEP-CALC2 [JCLJob:default:PAYRUN] # 哪个 program CALL 哪个 subprogram？ mainframe-brain query --store-path /tmp/mb.db "what runs SUBPROG" # → Program:default:SUBPROG 由以下调用： # --CALL 来自--> Program:default:INTCALC01 # Impact analysis —— “如果我更改了这个，什么会中断” mainframe-brain query --store-path /tmp/mb.db "impact of ACCOUNTS" mainframe-brain query --store-path /tmp/mb.db "show triggers on TXNLOG" mainframe-brain query --store-path /tmp/mb.db "what touches ACCTFLDS" # 选择性 LLM enrichment —— 默认使用 mock adapter 用于离线演示 mainframe-brain enrich --store-path /tmp/mb.db --budget 20000 --adapter mock # → 已创建: 6, cache_hits: 0, tokens_used: 182 # Review 工作流 mainframe-brain verify --store-path /tmp/mb.db "BusinessRule:default:2000-CALC-INTEREST:987b31a8" mainframe-brain flag --store-path /tmp/mb.db --rule "BusinessRule:default:9000-ERROR:7b1c624e" --reason "needs SME review" mainframe-brain edit-rule --store-path /tmp/mb.db --rule "BusinessRule:default:0000-MAIN:e8b6f26b" --rule-text "Main driver schedule paragraph" ``` 如需真实的 LLM 增强，请设置 `ANTHROPIC_API_KEY`（或 `OPENAI_API_KEY`）并传入 `--adapter anthropic`（或 `--adapter openai`）。 ## 架构 ``` Legacy source repo │ ▼ Deterministic extractors (Layer 1 — zero LLM tokens) │ ▼ Knowledge graph (Layer 2 — structural facts) │ ▼ Change & risk triage (Layer 3 — decides what's worth spending tokens on) │ ▼ Redaction pass (Layer 3.5 — hard gate before any token is spent) │ ▼ Selective LLM enrichment (Layer 4 — only new/changed/high-value units) │ ▼ Persistent brain (Layer 5 — versioned, queryable, portable) │ ▼ Graph explorer + Change-impact + Chat/query layer (Layer 6 — interfaces) │ └──── future runs feed back into Layer 3, re-analyzing only diffs ``` 六个层次，严格排序，每一层都与下一层有着明确的窄契约。完整的设计和基本原理请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) —— 包括 9 个由审查驱动的缺口（VSAM、COPY REPLACING 扩展后哈希、脱敏闸门、IMS/CICS 控制流、部分解析报告、变更影响、外部边界、报告）是如何被整合进来的。版本化的图 schema 见 [`docs/SCHEMA.md`](docs/SCHEMA.md)；迁移历史见 [`docs/MIGRATIONS.md`](docs/MIGRATIONS.md)。 **核心特性：** 理解会不断累积。首次运行消耗的 token 与 *未解决* 的业务逻辑成正比。随后的每一次运行消耗的 token 仅与 *变更* 部分成正比。六个月后，在 40,000 行代码库中修改一行代码，只会将确切的某一个段落重新排队等待重新增强 —— 而且之前已验证的规则会被标记为过期，直到人类再次签字确认。 ## 安装 ``` pip install mainframe-brain # stable, when released # 或从 source（开发）： pip3 install -e ".[dev]" --break-system-packages ``` Python ≥ 3.10。由于 PEP 668 的限制，macOS 系统 Python 3.14 需要 `--break-system-packages` 标志。 ## 项目布局 ``` mainframe_brain/ ├── extractors/ # one folder per artifact type — community contributes here │ ├── cobol/ copybook/ vsam/ jcl/ cics_bms/ │ ├── db2_ddl/ sql_pl/ triggers/ (procedural-DB first-class) │ ├── report/ external_boundary/ (schema-ready stubs) │ └── ims_db/ ims_dc/ cics_control_flow/ (deferred) ├── graph/ # versioned schema + SQLite store (swappable backend) ├── triage/ # diff, dedup, risk scoring ├── redaction/ # L3.5 hard gate ├── enrichment/ # LLM-calling code — model-agnostic (mock/anthropic/openai adapters) ├── cli.py # L6 entry — thin orchestrator only └── skills/SKILL.md # Claude Code/Desktop/Cowork packaging ``` ## 定位对比 **对比 IBM Watsonx Code Assistant for Z：** 开源且模型无关 对比 平台锁定；拥有可移植的 Markdown/图资产 对比 供应商仪表板；使用 mock adapter 离线运行 对比 需要托管服务。 **对比迁移加速顾问：** 记录并保留对现有系统的理解 —— 不向你推销 Java 重写。这个图是一个可移植的产物，你可以将其提交到源代码旁边。 ## 状态 Pre-alpha（预发布阶段）。61 个测试（单元测试 + golden 测试）通过，ruff 检查无报错。 **第 1-2 阶段已交付：** COBOL + copybook + VSAM + DB2 DDL + SQL PL 存储过程 + 触发器 + JCL + CICS BMS 提取器，SQLite 图存储，评估，脱敏闸门，选择性 LLM 增强（mock + 真实 adapter），用于 extract/triage/enrich/query/explore/verify/flag/edit-rule 的 CLI。 **延期实现（schema 已就绪，特意不作为 MVP 的阻碍）：** IMS DB/DC、CICS XCTL/LINK 控制流、实时 DB2 目录摄取、D3 资源管理器。 ## 许可证 Apache 2.0 —— 在受监管行业的企业采用中，选择明确的专利授权而不是 MIT。不要让范围蔓延将这个工具变成一个声称拥有其尚未获得的监管权力的工具：这是一个文档和知识保存辅助工具，**不是**合规或审计工具。 ## 作者 Sankalp Singh —— 大型机现代化、AI 与 COBOL、针对即将退休工程师遗留资产的知识保存。

标签：COBOL, DLL 劫持, 代码理解, 大型机, 大语言模型, 逆向工具, 遗留系统