Coverage-hole Hunter: 从覆盖率空洞到 covIR、UVM case 和 run-local close-loop verdict
安装 · 快速开始 · Provider 配置 · 典型流程 · cov_hunter.yml 指南 · GitHub · 公众号
cov_hunter 是一个面向 VCS urg / Xcelium xrun IMC HTML 覆盖率报告的独立 Python CLI，负责把 coverage hole 解析为统一 covIR、做保守分类、生成 UVM case，并对单次回跑给出 run-local verdict。
本仓库是 cov_hunter 的独立项目仓库（位于 ~/Projects/cov_hunter/）。它以外部 CLI 形式服务于任意 UVM 验证工程，不依赖、也不被被验证工程反向依赖 —— 所有跨项目交互都通过 --project-root 指向的外部工程路径完成。
cd /home/robin/Projects/cov_hunter
python3.11 -m pip install -e .editable(-e)模式安装到用户级 site-packages,入口脚本落在 ~/.local/bin/cov-hunter,任意目录可用(确保 ~/.local/bin 在 $PATH)。改源码即生效,无需重装。
需要跑测试时再额外装 dev 依赖:
python3.11 -m pip install -e .[dev]
pytestcov-hunter configure
cov-hunter doctor
cov-hunter run --report-onlydoctor 用于检查已配置的 provider/role；--no-call 只做静态检查，不发起模型调用。
run --report-only 默认会串行执行 init -> parse -> classify -> review -> report，其中 init 会从 cov_hunter.yml 重新生成/刷新 .cov_hunter/profile.yml；产物写入新的.cov_hunter/runs/<timestamp>/ 目录，然后直接结束，不进入 case-gen 和 close-loop
cov-hunter configure 会写入全局配置 ~/.cov_hunter/config.yaml，为
classifier、case_writer、reviewer 三个 role 选择 provider、model 和 effort。
同时会生成 ~/.cov_hunter/env.sh，用于集中放置 Claude Code wrapper 所需的
shell 环境、PATH、函数定义和 API key；CLI 会把两个路径都打印到 terminal。选择
qwen / kimi / deepseek / glm 时，configure 会提示输入对应 API key；
如果 env.sh 里已经保存过，直接回车会沿用已有值。
内置 provider:
codex_official: 使用本机 Codex CLI 登录态，当前默认模型为gpt-5.5。可选模型为gpt-5.5、gpt-5.4、gpt-5.4-mini、gpt-5.3-codex、gpt-5.2；effort 支持low、medium、high、xhigh。claude_official: 使用本机 Claude CLI 登录态。qwen: 通过 Claude Code wrappercc-qwen调用，默认模型qwen3-max。kimi: 通过 Claude Code wrappercc-kimi调用，默认模型kimi-k2.6。deepseek: 通过 Claude Code wrappercc-ds调用，默认模型deepseek-v4-pro[1m]。glm: 通过 Claude Code wrappercc-glm调用，默认模型glm-4.7。
qwen、kimi、deepseek、glm 默认走本机 Claude Code CLI wrapper，因此
classifier、case_writer、reviewer 调用时会以目标 --project-root 作为
cwd，让 Claude Code 按其自身规则加载项目根目录的 CLAUDE.md。如果需要直接 HTTP
调用，仍可手写一个其他 provider 名称并设置 type: anthropic_compatible。
wrapper 运行前只会 source 与 config.yaml 同目录的 env.sh（默认
~/.cov_hunter/env.sh），不会依赖 ~/.bashrc。因此 cc-qwen、cc-kimi、
cc-ds、cc-glm 等函数和 token 都由 configure 写入该文件；该文件权限为
0600，不要复制到项目仓库。
cov-hunter doctor --no-call 会输出每个 role 解析后的 provider、model、CLI wrapper
或 endpoint、认证来源，并检查 wrapper 是否能在 source env.sh 后解析到；不发起网络请求。
去掉 --no-call 后会执行一次最小 provider 调用。
如需验证 Claude Code wrapper 冷启动是否加载目标工程的 CLAUDE.md，可在含
CLAUDE.md 的 --project-root 下运行 cov-hunter doctor --role case_writer --claude-md-probe；
doctor 会把真实 LLM 回复打印到 terminal 并写入 .cov_hunter/doctor/*_call_stdout.txt。
doctor 会自动补齐新版内置 provider，因此旧配置文件也可以直接检查指向
deepseek / glm 的 role。
参考 cov_hunter.yml 示例(逐字段说明见 docs/cov_hunter_yml_quickstart.md):
schema_version: 1
project:
hierarchy_root: uart_tb_top
rtl_roots: [rtl]
tb_roots: [tb, uart_agt_top]
coverage:
format: auto # auto | vcs_urg | xrun_imc
html_default: work/vcs_cov_report
dut_scopes:
- uart_tb_top.DUV1
- uart_tb_top.DUV2 2
tests:
list_file: test/sv_list
lib_file: test/uart_test_lib.sv
scan_from_list: true
feature_map:
parity: [parity_test]
case_generation:
test_class_template: cov_{hole_slug}_test
vseq_class_template: cov_{hole_slug}_v_seq
marker_begin: "// AI_GENERATED_FOR_COV BEGIN {hole_id}"
marker_end: "// AI_GENERATED_FOR_COV END {hole_id}"
mandatory_vseq_base_class: v_sequence
required_start: envh.vseqrh
classify:
severity_rules:
- name: assertions-first
severity: S1
match: { kind: assert }
- name: fsm-transitions
severity: S2
match: { kind: fsm_transition }
- name: conditions
severity: S3
match: { kind: cond }
- name: default-lines
severity: S4
match: { kind: line }
build:
build_dir: script
setup_cmd: source setup.sh
comp_cmd: make comp
run_cmd_template: make all SV_CASE={case_name} cov=1
isolated_cov_report_cmd_template: urg -full64 -dir {vdb_paths} -report {report_dir} -lca说明:
build.build_dir表示执行comp_cmd/run_cmd_template/isolated_cov_report_cmd_template前先切换到哪个目录；如果命令直接在工程根目录执行，就填.。classify.severity_rules只负责给reachablehole 赋S1-S4严重度，不负责决定reachable/deadcode/unr这类分类。classify会对rtl_roots与tb_roots做一次保守的结构扫描：当 input 在所有已发现实例中都被常量连接，或信号只有常量assign/声明初始化（包括常量传播链）时，相关 toggle/condition hole 会判为高置信unr。悬空及固定X/Zinput 只用于判定 toggle hole；遇到多驱动、过程赋值、force、未知/无法解析的连接等情况会放弃结论，避免误判。coverage.dut_scopes同时适用于 VCSurg和 XceliumxrunIMC 解析。每行可以写scope或scope depth：不写 depth 或写0表示当前 scope 及所有子层；1表示只保留当前层；2表示当前层加下一层；3/4/5/...以此类推。--dut-scope 'top.dut 2'可在parse/run时覆盖 profile 里的coverage.dut_scopes，可重复传入多次。
各字段的含义、必填/可选要求和填写方法,见 docs/cov_hunter_yml_quickstart.md。
cov-hunter configure
cov-hunter init --project-root /path/to/project
cov-hunter parse --cov-html /path/to/project/work/vcs_cov_report --project-root /path/to/project --output covir.json
cov-hunter parse --cov-html /path/to/project/work/cov_html --coverage-adapter xrun_imc --project-root /path/to/project --output covir.xrun.json
cov-hunter parse --cov-html /path/to/project/work/cov_html --coverage-adapter xrun_imc --dut-scope 'uart_tb_top.DUV1 2' --project-root /path/to/project --output covir.scoped.json
cov-hunter classify --input covir.json --project-root /path/to/project --profile /path/to/project/.cov_hunter/profile.yml --output covir.classified.json
cov-hunter review --input covir.classified.json --project-root /path/to/project --profile /path/to/project/.cov_hunter/profile.yml --output covir.reviewed.json
cov-hunter report --input covir.reviewed.json --output-md cov_hole_report.md --output-json cov_hole_report.json
cov-hunter run --project-root /path/to/project --report-only
cov-hunter case-gen --hole H0001
cov-hunter close-loop --hole H0001
cov-hunter run --project-root /path/to/project --yescov-hunter run --report-only 默认会串行执行 init -> parse -> classify -> review -> report，其中 init 会从 cov_hunter.yml 重新生成/刷新 .cov_hunter/profile.yml；产物写入新的 .cov_hunter/runs/<timestamp>/ 目录，然后直接结束，不进入 case-gen 和 close-loop。如果传 --skip-review，则退回到 init -> parse -> classify -> report。
完整 cov-hunter run 默认阶段是 init -> parse -> classify -> review -> report -> case-gen -> close-loop。--severity-floor 控制 review 阶段注释哪些严重度的 hole，默认 S3；--coverage-adapter 可覆盖 profile 里的 coverage.format。
cov-hunter case-gen --hole H0001 和 cov-hunter close-loop --hole H0001 现在支持只传 --hole。其余参数省略时默认采用：
--project-root: 当前工作目录--profile:<project-root>/.cov_hunter/profile.yml--config(case-genonly):~/.cov_hunter/config.yaml，如果该文件存在--input:<project-root>/.cov_hunter/runs/下最新 run 的covir.reviewed.json，若不存在则回退到covir.classified.json--run-dir: 从--input推断出的 run；如果--input也省略，则直接使用最新 run
也就是说，进入目标验证工程根目录后，通常可以直接执行：
cov-hunter case-gen --hole H0001
cov-hunter close-loop --hole H0001如果需要显式指定旧 run 或非默认输入，仍然可以写全参数：
cov-hunter case-gen --input /path/to/project/.cov_hunter/runs/2026-04-25T060331+0000/covir.reviewed.json --hole H0001 --project-root /path/to/project --profile /path/to/project/.cov_hunter/profile.yml --run-dir /path/to/project/.cov_hunter/runs/2026-04-25T060331+0000
cov-hunter close-loop --input /path/to/project/.cov_hunter/runs/2026-04-25T060331+0000/covir.reviewed.json --hole H0001 --project-root /path/to/project --profile /path/to/project/.cov_hunter/profile.yml --run-dir /path/to/project/.cov_hunter/runs/2026-04-25T060331+0000恢复已有 run 目录时，--resume 有两种写法：
cov-hunter run --report-only --resume
cov-hunter run --report-only --resume .cov_hunter/runs/2026-04-25T003656Z第一种会接续 .cov_hunter/runs/ 下最近一次 run，第二种会显式接续指定的 run 目录。
