docs: 完成缺口分析项3-7 - AGENTS.md、README完善、测试报告、示例数据、Agent架构图
This commit is contained in:
hangshuo652
@@ -24,7 +24,152 @@ LLM 代理模块（`agents/`）是 COBOL 迁移验证平台 V3 的智能分析
|
||||
| `design_data.py` | 式样书驱动测试数据生成器 | `llm.py`, `design_data_input_parser` |
|
||||
| `design_data_input_parser.py` | 式样书 .md 解析器 | 标准库 `re`, `dataclasses` |
|
||||
|
||||
## 3. Agent1 解析代理（Agent1Parser）
|
||||
## 3. Agent 架构模型（感知-规划-行动-记忆）
|
||||
|
||||
本节描述 LLM 代理模块的核心架构模型，采用经典的**感知-规划-行动-记忆**（Perception-Planning-Action-Memory）循环。
|
||||
|
||||
### 3.1 架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Agent 架构模型 (感知-规划-行动-记忆) │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 感知层 (Perception) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ COBOL源码 │ │ COPYBOOK │ │ 设计书.md │ │ 比对结果 │ │ │
|
||||
│ │ │ 输入 │ │ 结构 │ │ 业务规则 │ │ 差异项 │ │ │
|
||||
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ └────────────────┼────────────────┼────────────────┘ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌───────────────────────┐ │ │
|
||||
│ │ │ read.py / DesignData │ │ │
|
||||
│ │ │ InputParser │ │ │
|
||||
│ │ └───────────┬───────────┘ │ │
|
||||
│ └──────────────────────────┼───────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 规划层 (Planning) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ 字段树构建 │ │ 路径枚举 │ │ 约束生成 │ │ 测试策略 │ │ │
|
||||
│ │ │ FieldTree │ │ BranchTree │ │ Constraints │ │ TestSuite │ │ │
|
||||
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ └────────────────┼────────────────┼────────────────┘ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌───────────────────────┐ │ │
|
||||
│ │ │ core.py / design.py │ │ │
|
||||
│ │ │ enum_paths │ │ │
|
||||
│ │ └───────────┬───────────┘ │ │
|
||||
│ └──────────────────────────┼───────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 行动层 (Action) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ LLM调用 │ │ 规则引擎 │ │ 数据生成 │ │ JSON输出 │ │ │
|
||||
│ │ │ DeepSeek │ │ Fallback │ │ Records │ │ output.py │ │ │
|
||||
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ └────────────────┼────────────────┼────────────────┘ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌───────────────────────┐ │ │
|
||||
│ │ │ agents/llm.py │ │ │
|
||||
│ │ │ LLMClient.call() │ │ │
|
||||
│ │ └───────────┬───────────┘ │ │
|
||||
│ └──────────────────────────┼───────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 记忆层 (Memory) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ pi_map │ │ assignments │ │ 决策点缓存 │ │ LLM缓存 │ │ │
|
||||
│ │ │ 字段映射 │ │ 赋值链 │ │ DecisionPts │ │ .cache/llm │ │ │
|
||||
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ └────────────────┼────────────────┼────────────────┘ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌───────────────────────┐ │ │
|
||||
│ │ │ models.py / config │ │ │
|
||||
│ │ │ 共享数据模型 │ │ │
|
||||
│ │ └───────────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 循环反馈 (Feedback Loop) │ │
|
||||
│ │ │ │
|
||||
│ │ 覆盖率分析 → 未覆盖分支 → 补充测试数据 → 重新执行 → 更新记忆 │ │
|
||||
│ │ (coverage.py) (DecisionPoints) (design.py) (runners/) (pi_map) │ │
|
||||
│ └──────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.2 四层职责
|
||||
|
||||
| 层级 | 职责 | 核心组件 | 数据模型 |
|
||||
|------|------|----------|----------|
|
||||
| **感知层** | 解析输入，提取结构信息 | `read.py`, `DesignDataInputParser` | COBOL源码, FieldTree |
|
||||
| **规划层** | 构建分支树，枚举路径，生成约束 | `core.py`, `design.py`, `cond.py` | BranchTree, Constraints |
|
||||
| **行动层** | 执行LLM调用，生成测试数据 | `agents/llm.py`, `output.py` | TestSuite, JSON |
|
||||
| **记忆层** | 缓存中间结果，共享状态 | `models.py`, `config/` | pi_map, assignments |
|
||||
|
||||
### 3.3 循环反馈机制
|
||||
|
||||
Agent 架构采用**闭环反馈**设计：
|
||||
|
||||
1. **感知 → 规划**: 解析结果驱动分支树构建
|
||||
2. **规划 → 行动**: 路径约束指导测试数据生成
|
||||
3. **行动 → 记忆**: 生成结果更新缓存和状态
|
||||
4. **记忆 → 感知**: 覆盖率分析触发新一轮感知
|
||||
|
||||
### 3.4 LLM 在架构中的位置
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Agent 架构 │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 规划层 行动层 │
|
||||
│ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 路径枚举 │ │ LLM调用 │ │
|
||||
│ │ (规则引擎) │──────│ (DeepSeek) │ │
|
||||
│ └─────────────┘ └─────────────┘ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────┐ │ │
|
||||
│ └────│ 记忆层 │───┘ │
|
||||
│ │ (缓存+状态) │ │
|
||||
│ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
LLM 作为**行动层**的核心组件，负责：
|
||||
- **Agent1**: COPYBOOK → FieldTree 解析
|
||||
- **Agent2**: FieldTree → TestSuite 测试数据设计
|
||||
- **Agent3**: FieldResult → 诊断建议文本
|
||||
- **DesignDataGenerator**: 式样书 → 机能测试数据
|
||||
|
||||
当 LLM 调用失败时，系统自动**降级到规则引擎**（fallback），确保流水线不中断。
|
||||
|
||||
### 3.5 记忆层详解
|
||||
|
||||
记忆层是 Agent 架构的**状态中心**，存储：
|
||||
|
||||
| 记忆类型 | 说明 | 位置 |
|
||||
|----------|------|------|
|
||||
| **短期记忆** | 单次执行的中间结果 | pi_map, assignments |
|
||||
| **长期记忆** | 跨执行的缓存数据 | .cache/llm/ |
|
||||
| **共享记忆** | 模块间传递的数据 | models.py |
|
||||
|
||||
---
|
||||
|
||||
## 4. Agent1 解析代理（Agent1Parser）
|
||||
|
||||
### 3.1 职责
|
||||
|
||||
@@ -63,7 +208,7 @@ class Agent1Parser:
|
||||
- LLM 返回非法 JSON 时，`parse` 捕获异常，返回一个 `FieldTree(copybook_name="parse_error")` 空树
|
||||
- 使用 bare `except` 捕获所有解析异常，保证流水线不中断
|
||||
|
||||
## 4. Agent2 数据生成代理（Agent2Data）
|
||||
## 5. Agent2 数据生成代理（Agent2Data）
|
||||
|
||||
### 4.1 职责
|
||||
|
||||
@@ -102,7 +247,7 @@ class Agent2Data:
|
||||
- LLM 调用失败或返回非法 JSON 时，生成一条兜底用例 `TestCase(id="TC-FALLBACK", fields={"BR-AMT": 0})`
|
||||
- 使用 bare `except` 捕获反序列化异常
|
||||
|
||||
## 5. Agent3 诊断代理（Agent3Diagnostic）
|
||||
## 6. Agent3 诊断代理（Agent3Diagnostic）
|
||||
|
||||
### 5.1 职责
|
||||
|
||||
@@ -135,7 +280,7 @@ class Agent3Diagnostic:
|
||||
- 依赖 `LLMClient.call()` 的重试机制
|
||||
- 返回原始 LLM 响应字符串，调用方负责解析
|
||||
|
||||
## 6. 式样书驱动测试数据生成器（DesignDataGenerator）
|
||||
## 7. 式样书驱动测试数据生成器（DesignDataGenerator）
|
||||
|
||||
### 6.1 职责
|
||||
|
||||
@@ -207,7 +352,7 @@ class DesignDataGenerator:
|
||||
|
||||
支持按指定键字段去重，`additional_records` 优先保留。
|
||||
|
||||
## 7. LLM 接口封装（LLMClient）
|
||||
## 8. LLM 接口封装（LLMClient）
|
||||
|
||||
### 7.1 职责
|
||||
|
||||
@@ -258,7 +403,7 @@ Header: Authorization: Bearer {key}
|
||||
|
||||
响应解析路径：`response["choices"][0]["message"]["content"]`
|
||||
|
||||
## 8. 接口定义
|
||||
## 9. 接口定义
|
||||
|
||||
### 8.1 模块公开 API
|
||||
|
||||
@@ -291,7 +436,7 @@ Agent3Diagnostic.analyze(field_result) → str (JSON)
|
||||
| `SparkConfig` | `data.test_case` | Spark 生成配置 |
|
||||
| `FieldResult` | `data.diff_result` | 字段比对结果 |
|
||||
|
||||
## 9. 错误处理
|
||||
## 10. 错误处理
|
||||
|
||||
### 9.1 错误策略
|
||||
|
||||
|
||||
Reference in New Issue
Block a user