417 lines
12 KiB
Markdown
417 lines
12 KiB
Markdown
# HINA 程序分类模块 - 详细设计文档
|
|
|
|
> 模块路径: `hina/`
|
|
> 版本: V3 (2026技术大赛)
|
|
|
|
---
|
|
|
|
## 1. 模块概述
|
|
|
|
### 1.1 职责
|
|
|
|
`hina` 模块是 COBOL 迁移验证平台 V3 的程序分类与质量门禁系统，负责:
|
|
|
|
1. **程序分类** - 根据 COBOL 源码特征，将程序归类到预定义类型
|
|
2. **确信度评估** - 多因子计算分类结果的可信度
|
|
3. **质量门禁** - 测试数据生成前检查覆盖率和边界条件
|
|
4. **策略匹配** - 根据分类结果选择测试策略模板
|
|
5. **gcov 覆盖率收集** - 编译运行后采集动态代码覆盖率
|
|
6. **分层重试** - 处理编译/运行错误的自愈和重试机制
|
|
|
|
### 1.2 依赖关系
|
|
|
|
```
|
|
hina/
|
|
__init__.py <- 公开 API 入口
|
|
classifier.py <- L1 关键字规则匹配 + 结构性匹配检测
|
|
confidence.py <- 4 因子确信度计算
|
|
gate.py <- 质量门禁检查
|
|
gcov_collector.py <- gcov 覆盖率采集
|
|
hina_agent.py <- LLM 混淆组分类代理
|
|
retry.py <- 分层重试处理器
|
|
strategy.py <- 策略模板 + 必须项补充
|
|
pipeline/pipeline.py <- 完整分类管道
|
|
rule_engine/confusion_groups.py <- 8 个混淆对解析函数
|
|
rule_engine/contradiction.py <- 矛盾检测与解决
|
|
rule_engine/backtrack.py <- 多轮回溯判定
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 文件清单
|
|
|
|
| 文件 | 行数 | 职责 |
|
|
|------|------|------|
|
|
| `__init__.py` | 25 | 公开 API 入口，导出 classify_program |
|
|
| `classifier.py` | 304 | L1 关键字规则(14条)、注释剥离、KEY比较检测、结构性匹配检测 |
|
|
| `confidence.py` | 120 | 4 因子确信度计算 |
|
|
| `gate.py` | 106 | 质量门禁检查、双模式质量评分 |
|
|
| `gcov_collector.py` | 58 | gcov 覆盖率采集 |
|
|
| `hina_agent.py` | 283 | LLM 混淆组分类、规则兜底 |
|
|
| `retry.py` | 82 | 分层重试: 自愈修复 + 朴素重试 |
|
|
| `strategy.py` | 103 | 策略模板(5个类型) + 补充 |
|
|
| `pipeline/pipeline.py` | 698 | 完整分类管道: 3条路径 |
|
|
| `rule_engine/confusion_groups.py` | 287 | 8个混淆对解析函数 |
|
|
| `rule_engine/contradiction.py` | 163 | 矛盾检测与解决 |
|
|
| `rule_engine/backtrack.py` | 96 | 多轮回溯判定 |
|
|
|
|
---
|
|
|
|
## 3. 分类算法
|
|
|
|
### 3.1 分类管道总览
|
|
|
|
`classify_program()` 流程:
|
|
|
|
```
|
|
COBOL 源码
|
|
-> 并行: detect_keyword() + extract_structure()
|
|
-> 根据最高关键字确信度选择路径:
|
|
>= 90% -> 路径 A: keyword 直接输出
|
|
50-89% -> 路径 B: 规则引擎 + 确信度计算
|
|
< 50% -> 路径 C: LLM 辅助 + 规则验证
|
|
-> 匹配子类型区分（仅对匹配/键中断程序）
|
|
-> 输出最终 JSON
|
|
```
|
|
|
|
### 3.2 L1 关键字规则 (classifier.py)
|
|
|
|
定义在 `L1_RULES` 中，共 14 条规则，格式 `(分类名称, [关键字列表], 置信度阈值)`:
|
|
|
|
| 分类 | 关键字 | 置信度 |
|
|
|------|--------|--------|
|
|
| DB操作 | EXEC SQL | 0.95 |
|
|
| 子程序调用 | CALL, LINKAGE SECTION | 0.90 |
|
|
| IS INITIAL | IS INITIAL | 0.99 |
|
|
| SYSIN | ACCEPT ... FROM SYSIN | 0.90 |
|
|
| 编码转换 | ALPHABETIC, ASCII, EBCDIC | 0.85 |
|
|
| online | DFHCOMMAREA | 0.95 |
|
|
| SORT | SORT ... ON ... KEY | 0.95 |
|
|
| MERGE | MERGE ... ON ... KEY | 0.95 |
|
|
| 替代索引 | ALTERNATE RECORD KEY | 0.99 |
|
|
| 编辑输出 | WRITE ... AFTER/BEFORE | 0.80 |
|
|
| 文件编成 | ORGANIZATION IS | 0.99 |
|
|
| マッチング | WS-[*]KEY* 变量模式(3条) | 0.55-0.65 |
|
|
|
|
`re:` 前缀表示正则表达式匹配，无前缀表示字面量包含匹配。
|
|
|
|
### 3.3 结构性匹配检测
|
|
|
|
`_detect_matching_structure` 不依赖 KEY 变量名，通过 6 个信号判断匹配程序:
|
|
|
|
| 信号 | 检测内容 |
|
|
|------|---------|
|
|
| 1 | READ ... AT END |
|
|
| 1b | 2+ 个 READ 语句 |
|
|
| 2 | PERFORM UNTIL ... = 'Y'/'N' |
|
|
| 3 | ELSE ... READ (条件性读取) |
|
|
| 4 | IF A = B (跨文件字段比较) |
|
|
| 5 | 2+ 个 OPEN INPUT |
|
|
|
|
信号 >= 5: 0.55, = 4: 0.50, = 3: 0.40, < 3: 0.0
|
|
|
|
### 3.4 KEY 变量比较检测
|
|
|
|
`_matches_key_comparison` 确认 KEY 变量在比较上下文中实际使用:
|
|
- 模式 1: WS-KEY = / > / < (排除 Figurative Constant)
|
|
- 模式 2: 非 WS- 前缀 KEY
|
|
- 模式 3: READ INTO ... KEY
|
|
|
|
---
|
|
|
|
## 4. 确信度计算 (confidence.py)
|
|
|
|
### 4.1 4 因子公式
|
|
|
|
```
|
|
confidence = base x context_factor x consistency_factor x structure_factor
|
|
```
|
|
|
|
### 4.2 因子定义
|
|
|
|
**上下文因子:**
|
|
| match_count | 值 |
|
|
|-------------|-----|
|
|
| >= 3 | 1.0 |
|
|
| 2 | 0.95 |
|
|
| 1 | 0.90 |
|
|
| 0 | 0.50 |
|
|
| 共识奖励 | +0.15 (上限 1.0) |
|
|
|
|
**一致性因子:**
|
|
| 矛盾情况 | 值 |
|
|
|----------|-----|
|
|
| 无矛盾 | 1.0 |
|
|
| 全部已解决 | 0.90 |
|
|
| 未解决 < 3个 | 0.80 |
|
|
| 未解决 >= 3个 | 0.50 |
|
|
|
|
**结构一致性因子:**
|
|
| score | 值 |
|
|
|-------|-----|
|
|
| 5 | 1.0 |
|
|
| >= 3 | 0.7 |
|
|
| >= 1 | 0.5 |
|
|
| 0 | 0.3 |
|
|
|
|
### 4.3 判定结果
|
|
|
|
| 确信度范围 | 判定 | 需人工审核 |
|
|
|-----------|------|-----------|
|
|
| >= 0.90 | auto | 否 |
|
|
| 0.70-0.89 | review | 是 |
|
|
| 0.50-0.69 | manual | 是 |
|
|
| < 0.50 | impossible | 是 |
|
|
|
|
---
|
|
|
|
## 5. 规则引擎 (rule_engine/)
|
|
|
|
### 5.1 混淆组判定 (confusion_groups.py)
|
|
|
|
8 个混淆对解析函数:
|
|
|
|
| 混淆对 | 区分逻辑 | 置信度 |
|
|
|--------|---------|--------|
|
|
| matching_vs_keybreak | 三路IF+多文件->マッチング; WS-PREV-KEY+累加器->キーブレイク | 0.75-0.90 |
|
|
| dedup_vs_nodedup | WS-PREV-KEY存在->含重复; 不存在->不含重复 | 0.50-0.90 |
|
|
| validation_vs_keybreak | WS-ERR*字段->校验; WS-*CNT计数器->キーブレイク | 0.55-0.85 |
|
|
| csv_merge_vs_split | STRING+逗号->合并; INSPECT REPLACING+逗号->拆分 | 0.85 |
|
|
| simple_vs_two_stage | OPEN-CLOSE-再OPEN->二段階; 其他->単純 | 0.50-0.90 |
|
|
| pure_vs_mixed | has_switch+has_counter+IF>=3->混合 | 0.70 |
|
|
| division_50_25_100 | DIVIDE被除数常量匹配 | 0.95 |
|
|
| mn_output_mode | SELECT>=3+分支>=3->M:N | 0.55-0.65 |
|
|
|
|
### 5.2 特征注入 (pipeline.py)
|
|
|
|
从 COBOL 源码注入额外特征:
|
|
|
|
| 特征名 | 检测方式 | 用途 |
|
|
|--------|---------|------|
|
|
| has_key_var | 正则匹配KEY变量比较 | 防止计数器比较误触发 |
|
|
| has_structural_match | IF+跨文件字段比较+循环/读取 | 结构性匹配信号 |
|
|
| has_cross_file_cmp | IF A = B | 跨文件比较 |
|
|
| has_csv_merge | STRING ... ',' ... INTO | CSV合并信号 |
|
|
| has_csv_split | INSPECT ... REPLACING ... ',' | CSV拆分信号 |
|
|
|
|
### 5.3 矛盾检测与解决 (contradiction.py)
|
|
|
|
**矛盾对定义** (CONTRADICTION_PAIRS): 10 对可能冲突的分类类型。
|
|
|
|
**解决策略**:
|
|
1. 优先级比较 (TYPE_PRIORITY): マッチング(10) > キーブレイク(9) > 項目チェック(8) > ...
|
|
2. 优先级相同时，调用混淆对解析器重判定 (置信度 >= 0.80 则采纳)
|
|
3. 最终回退: 取 type_a
|
|
|
|
### 5.4 多轮回溯 (backtrack.py)
|
|
|
|
`BacktrackResolver` 封装多轮判定:
|
|
- 最大轮次: 3
|
|
- 超时: 30 秒
|
|
- 超时/超轮次: 标记 `backtrack_degraded = True`，降级返回
|
|
|
|
---
|
|
|
|
## 6. LLM 辅助分类 (hina_agent.py)
|
|
|
|
### 6.1 混淆组分类 Prompt
|
|
|
|
`CONFUSION_PROMPT` 包含 7 个混淆组定义:
|
|
1. simple_sequential - 极少决策点
|
|
2. condition_heavy - IF语句占比高
|
|
3. evaluate_driven - EVALUATE主导
|
|
4. data_file_centric - 文件操作密集
|
|
5. search_intensive - SEARCH ALL
|
|
6. call_based - CALL语句
|
|
7. mixed_complex - 多种复杂特征
|
|
|
|
### 6.2 规则兜底分类
|
|
|
|
LLM 失败时 `_fallback_classification` 基于结构特征优先级:
|
|
|
|
| 优先级 | 条件 | 分类 |
|
|
|--------|------|------|
|
|
| 1 | total_decisions == 0 | simple_sequential |
|
|
| 2 | has_search_all | search_intensive |
|
|
| 3 | has_call | call_based |
|
|
| 4 | evaluate > if 且 >= 2 | evaluate_driven |
|
|
| 5 | file_count >= 2 | data_file_centric |
|
|
| 6 | if >= 5 或 decisions >= 8 | condition_heavy/nested_if |
|
|
| 7 | if >= 2 | condition_heavy/simple_if |
|
|
|
|
复杂度升级: >= 3 个复杂度标志 -> mixed_complex
|
|
|
|
---
|
|
|
|
## 7. 匹配子类型区分
|
|
|
|
仅对 マッチング/キーブレイク/項目チェック 执行子类型区分。
|
|
|
|
### 7.1 分层策略
|
|
|
|
**第 1 层 - 静态规则:**
|
|
|
|
| 条件 | 子类型 |
|
|
|------|--------|
|
|
| 二段階 in category | 二段階 |
|
|
| file_count >= 3 + WS-SAVE-KEY | M:N->MxN |
|
|
| WS-PREV-KEY | 混合 |
|
|
| WS-MAST-KEY + WS-TRAN-KEY | 1:N |
|
|
| WS-KEY-M + WS-KEY-T | N:1 |
|
|
| WS-KEY-M + WS-KEY-N | M:N |
|
|
|
|
**第 2 层 - LLM 推理**: 多键变量+多文件时调用 LLM 判断子类型
|
|
|
|
**第 3 层 - 回退**: 多键+多文件->M:N; 对称键名->1:1
|
|
|
|
---
|
|
|
|
## 8. 策略模板 (strategy.py)
|
|
|
|
### 8.1 策略模板定义
|
|
|
|
| 分类 | 必须项 | 边界项 |
|
|
|------|--------|--------|
|
|
| マッチング | COM-N001~A003, MT-N001~N006 | MT-B001, MT-B002 |
|
|
| キーブレイク | COM-N001, A002, KB-N001~N005, A001 | KB-B001, KB-B002 |
|
|
| 条件分岐 | B-N001, N003, N006, N009 | - |
|
|
| 内部表検索 | T-N001, N002, A001, A002 | - |
|
|
| 項目チェック | VF-N001, N002, N004, A001 | - |
|
|
|
|
### 8.2 补充函数
|
|
|
|
- `supplement()`: 从模板追加全部必须项和边界项
|
|
- `supplement_only()`: 增量补充指定必须项
|
|
|
|
---
|
|
|
|
## 9. 质量门禁 (gate.py)
|
|
|
|
### 9.1 门禁检查
|
|
|
|
| 检查项 | 条件 | 输出 |
|
|
|--------|------|------|
|
|
| 决策点覆盖率 | branch_rate < 0.90 | decision_gaps |
|
|
| 段落覆盖率 | paragraph_rate < 1.0 | paragraph_gaps |
|
|
| 测试数据为空 | not complete_tests | no_data |
|
|
|
|
### 9.2 双模式质量评分
|
|
|
|
```
|
|
gcov 未启用: branch_rate*0.5 + paragraph_rate*0.5 + confidence*0.4
|
|
gcov 启用: static_cov*0.3 + gcov_cov*0.4 + confidence*0.3
|
|
```
|
|
|
|
---
|
|
|
|
## 10. gcov 覆盖率收集 (gcov_collector.py)
|
|
|
|
### 10.1 采集流程
|
|
|
|
1. 检查 .gcda 文件是否存在
|
|
2. 执行 gcov 命令 (30s 超时)
|
|
3. 查找 .gcov 输出文件
|
|
4. 解析行覆盖率
|
|
|
|
### 10.2 降级策略
|
|
|
|
所有 gcov 失败降级为仅静态分析。
|
|
|
|
---
|
|
|
|
## 11. 分层重试 (retry.py)
|
|
|
|
### 11.1 重试机制
|
|
|
|
`RetryHandler(max_heal=2, max_simple=3)`:
|
|
- PASS/QUALITY_WARN -> 返回结果
|
|
- BLOCKED/ERROR -> 自愈修复或朴素重试
|
|
- 总次数 >= 5 -> 标记 FATAL
|
|
|
|
### 11.2 自愈修复
|
|
|
|
| 错误 | 检测 | 修复 |
|
|
|------|------|------|
|
|
| compile_error | 日志含 "not found" | 设置 COB_LIBRARY_PATH |
|
|
| s0c7 | 日志含 "S0C7" | 记录警告 |
|
|
|
|
---
|
|
|
|
## 12. 接口定义
|
|
|
|
### 12.1 公开 API
|
|
|
|
```python
|
|
def classify_program(cobol_source: str, llm=None) -> dict:
|
|
"""返回: {category, confidence, needs_review, method, source,
|
|
judgment, matches, contradictions, v2_confidence, structure}"""
|
|
```
|
|
|
|
### 12.2 内部模块 API
|
|
|
|
- `classifier.detect_keyword(source)` -> list[tuple[str, float, str]]
|
|
- `confidence.compute_confidence_v2(keyword_result, structure_features, ...)` -> dict
|
|
- `gate.check(complete_tests, hina_result, coverage, ...)` -> dict
|
|
- `gate.compute_quality_score(static_coverage, gcov_coverage, confidence)` -> float
|
|
- `strategy.get_strategy(hina_type)` -> dict
|
|
- `strategy.supplement(base_tests, hina_result)` -> list[dict]
|
|
- `gcov_collector.collect_gcov(cobol_src, work_dir)` -> dict
|
|
- `RetryHandler(max_heal, max_simple).run(pipeline_fn)` -> VerificationRun
|
|
- `hina_agent.classify_with_llm(structure, llm)` -> dict
|
|
- `rule_engine.resolve_confusion_pair(features, pair_name)` -> dict
|
|
- `rule_engine.detect_contradictions(features)` -> list[dict]
|
|
- `rule_engine.resolve_contradiction(features, contradiction)` -> str
|
|
- `BacktrackResolver(structure_extractor).resolve(source, features)` -> dict
|
|
|
|
---
|
|
|
|
## 13. 错误处理
|
|
|
|
### 13.1 错误分类
|
|
|
|
| 类别 | 示例 | 处理 |
|
|
|------|------|------|
|
|
| L1解析错误 | 正则匹配失败 | 跳过该规则 |
|
|
| LLM调用失败 | API超时/网络错误 | 回退到规则引擎 |
|
|
| LLM响应解析 | 无效JSON | 返回unknown |
|
|
| gcov失败 | 命令未找到/超时 | 降级为静态分析 |
|
|
| 回溯超时 | > 30s | 标记降级返回 |
|
|
| 矛盾不可解 | 优先级相同 | 取type_a回退 |
|
|
| 空源码 | cobol_source为空 | 返回impossible |
|
|
|
|
### 13.2 日志策略
|
|
|
|
- `logger.info()`: 关键流程节点
|
|
- `logger.debug()`: 规则引擎特征、矛盾详情
|
|
- `logger.warning()`: LLM失败、回溯降级、gcov失败
|
|
|
|
---
|
|
|
|
## 14. 数据流总结
|
|
|
|
```
|
|
Input: cobol_source (str), llm (optional)
|
|
|
|
|
v
|
|
[Parallel] detect_keyword + extract_structure
|
|
|
|
|
v
|
|
Route by max keyword confidence:
|
|
>= 0.90 -> Path A: keyword direct
|
|
0.50-0.89 -> Path B: rule engine
|
|
< 0.50 -> Path C: LLM assisted / rule fallback
|
|
|
|
|
v
|
|
_resolve_matching_subtype (for matching/keybreak programs)
|
|
|
|
|
v
|
|
Output: {category, confidence, needs_review, method, source,
|
|
judgment, matches, contradictions, v2_confidence, structure}
|
|
```
|
|
|
|
下游集成:
|
|
1. orchestrator_db.py: 根据category选择测试策略
|
|
2. strategy.py: 获取必须项
|
|
3. gate.py: 用confidence计算质量评分
|
|
4. data_merger.py: 合并策略数据到测试记录
|