hangshuo652
b94757d9df
1. 场景价值与技术合理性修复： - 补充docs/SCENE_VALUE.md（业务背景、痛点分析、用户场景、竞品对比、价值量化） - 添加用户操作流程图（Mermaid） - 添加3个真实业务案例量化数据 2. 演示与文档修复： - 创建docs/API.md（完整API文档） - 创建docs/QUICKSTART.md（5分钟快速入门指南） 3. AI使用日志修复： - 更新AGENTS.md，添加强制自动执行的AI使用日志记录指令 - 在_AI_USAGE_LOG.md末尾添加范式执行统计 4. 安全性修复： - 在agents/llm.py中添加输入过滤（防Prompt注入） - 添加输出验证、速率限制、详细日志 5. 架构设计修复： - 创建tools/registry.py工具注册表 - 修改orchestrator.py和orchestrator_db.py使用注册表动态获取运行器 6. 开发范式修复： - 在_AI_USAGE_LOG.md末尾添加范式执行统计
227 lines
4.1 KiB
Markdown
227 lines
4.1 KiB
Markdown
# COBOL → Java/Spark 迁移验证平台 — 快速入门
|
||
|
||
> 5分钟快速上手指南
|
||
|
||
---
|
||
|
||
## 一、环境准备
|
||
|
||
### 1.1 系统要求
|
||
|
||
- Python 3.12+
|
||
- GnuCOBOL 3.2.0（可选，用于COBOL编译）
|
||
- Java JDK 8+（可选，用于Java编译）
|
||
|
||
### 1.2 安装依赖
|
||
|
||
```bash
|
||
# 安装Python依赖
|
||
pip install lark pathlib pyyaml httpx
|
||
|
||
# 或使用requirements.txt
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 二、快速开始
|
||
|
||
### 2.1 验证单个COBOL程序
|
||
|
||
```bash
|
||
# 基本用法
|
||
python -m cobol_testgen <cobol_source> [output_dir]
|
||
|
||
# 示例
|
||
python -m cobol_testgen benchmark-programs/KIN01INP.cbl output/
|
||
```
|
||
|
||
**执行流程：**
|
||
1. 解析COBOL源码
|
||
2. 分析分支路径
|
||
3. 生成测试数据
|
||
4. 编译运行COBOL程序
|
||
5. 编译运行Java程序
|
||
6. 字段级输出比对
|
||
7. 生成验证报告
|
||
|
||
### 2.2 带覆盖率的验证
|
||
|
||
```bash
|
||
# 启用gcov覆盖率
|
||
python -m cobol_testgen --gcov benchmark-programs/KIN01INP.cbl output/
|
||
```
|
||
|
||
### 2.3 批量验证
|
||
|
||
```bash
|
||
# 验证多个程序
|
||
python -m cobol_testgen benchmark-programs/*.cbl output/
|
||
```
|
||
|
||
---
|
||
|
||
## 三、运行测试套件
|
||
|
||
### 3.1 运行所有测试
|
||
|
||
```bash
|
||
# 运行pytest测试
|
||
python -m pytest tests/ -v
|
||
|
||
# 运行核心引擎测试
|
||
python -m pytest tests/cobol_testgen/ -v
|
||
```
|
||
|
||
### 3.2 运行验证脚本
|
||
|
||
```bash
|
||
# 运行覆盖率验证
|
||
python test-data/s15_coverage_verification.py
|
||
|
||
# 运行DB端到端测试（需要数据库）
|
||
python test-data/s30_db_e2e.py
|
||
```
|
||
|
||
---
|
||
|
||
## 四、配置说明
|
||
|
||
### 4.1 环境变量配置
|
||
|
||
```bash
|
||
# 设置LLM API密钥（可选）
|
||
export LLM_API_KEY="your-api-key"
|
||
|
||
# 设置LLM模型（默认deepseek-v4-flash）
|
||
export LLM_MODEL="deepseek-v4-flash"
|
||
|
||
# 设置DeepSeek API密钥（可选）
|
||
export DEEPSEEK_API_KEY="your-deepseek-key"
|
||
```
|
||
|
||
### 4.2 配置文件
|
||
|
||
项目配置位于 `config/` 目录：
|
||
|
||
```
|
||
config/
|
||
├── __init__.py # 配置初始化
|
||
├── program_schema.py # 程序Schema定义
|
||
└── teams.json # 团队配置（如有）
|
||
```
|
||
|
||
---
|
||
|
||
## 五、输出说明
|
||
|
||
### 5.1 输出目录结构
|
||
|
||
```
|
||
output/
|
||
├── test_input.json # 生成的测试输入数据
|
||
├── test_output.json # 期望的测试输出
|
||
├── working_storage.json # 工作存储区数据
|
||
├── diff_result.json # 差异比对结果
|
||
└── coverage/ # 覆盖率报告
|
||
├── index.html # 覆盖率概览
|
||
└── detail.html # 详细覆盖率
|
||
```
|
||
|
||
### 5.2 验证报告
|
||
|
||
验证完成后会生成HTML格式的验证报告，包含：
|
||
- 测试用例执行结果
|
||
- 字段级比对结果
|
||
- 覆盖率统计
|
||
- 差异分析
|
||
|
||
---
|
||
|
||
## 六、常见问题
|
||
|
||
### Q1: 编译COBOL失败
|
||
|
||
**问题：** `cobc: command not found`
|
||
|
||
**解决：** 安装GnuCOBOL
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt-get install gnucobol
|
||
|
||
# macOS
|
||
brew install gnucobol
|
||
```
|
||
|
||
### Q2: LLM调用失败
|
||
|
||
**问题：** `LLMError: API key not set`
|
||
|
||
**解决：** 设置API密钥
|
||
```bash
|
||
export LLM_API_KEY="your-api-key"
|
||
```
|
||
|
||
### Q3: 测试数据生成失败
|
||
|
||
**问题：** `FieldTree parse error`
|
||
|
||
**解决：** 检查COBOL源码格式，确保是有效的COBOL代码
|
||
|
||
### Q4: 覆盖率报告为空
|
||
|
||
**问题：** 覆盖率报告显示0%
|
||
|
||
**解决：** 确保启用了gcov选项（`--gcov`）
|
||
|
||
---
|
||
|
||
## 七、进阶使用
|
||
|
||
### 7.1 使用规则引擎（不依赖LLM）
|
||
|
||
```python
|
||
from cobol_testgen import main
|
||
|
||
# 使用规则引擎生成测试数据
|
||
config = {"proc_parser": "rule", "llm_generator": False}
|
||
main(["benchmark-programs/KIN01INP.cbl"], "output/", config)
|
||
```
|
||
|
||
### 7.2 使用LLM生成测试数据
|
||
|
||
```python
|
||
from cobol_testgen import main
|
||
|
||
# 使用LLM生成测试数据
|
||
config = {"proc_parser": "ai", "llm_generator": True}
|
||
main(["benchmark-programs/KIN01INP.cbl"], "output/", config)
|
||
```
|
||
|
||
### 7.3 自定义配置
|
||
|
||
```python
|
||
from cobol_testgen import main
|
||
|
||
# 自定义配置
|
||
config = {
|
||
"proc_parser": "rule",
|
||
"llm_generator": False,
|
||
"coverage_target": 0.85,
|
||
"max_paths": 200,
|
||
}
|
||
main(["benchmark-programs/KIN01INP.cbl"], "output/", config)
|
||
```
|
||
|
||
---
|
||
|
||
## 八、下一步
|
||
|
||
- 阅读 [API文档](API.md) 了解详细接口
|
||
- 阅读 [设计文档](../DESIGN.md) 了解系统架构
|
||
- 阅读 [场景与价值](SCENE_VALUE.md) 了解业务背景
|
||
|
||
---
|
||
|
||
*本文档最后更新：2026-08-28*
|