# 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: 合并策略数据到测试记录