feat: V3系统评审问题修复

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末尾添加范式执行统计
2026-08-29 13:23:28 +08:00
parent c6fa6b1aeb
commit b94757d9df
69 changed files with 1941 additions and 221 deletions
@@ -0,0 +1,226 @@
+# 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*