hangshuo652/cobol-java-v3
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
5a968b4e3765a875966bcfd8a5dd8f766f1ad857
cobol-java-v3/docs/detailed-design/04-hina-classification.md
T

12 KiB
Raw Blame History

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-N001A003, MT-N001N006 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

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: 合并策略数据到测试记录
Reference in New Issue View Git Blame Copy Permalink