5. 覆盖率收敛与进度管理工作流
本工作流负责分析 VCS 覆盖率报告、识别代码与功能覆盖率缺口、按人工裁决补建覆盖模型或补充测试条目、维护验证进度 JSON 数据文件、绘制趋势折线图，并在一轮验证收尾时产出正式验证报告。
覆盖率与进度数据流
Skill 详解
1. uvm-coverage-closure：覆盖率收敛分析
功能说明：分析 VCS 覆盖率报告（如
urgReport），识别功能覆盖率与代码覆盖率（Line, Cond, Toggle, Branch, FSM）的空洞与缺口，输出轮次缺口分析报告，并在报告中生成两张人工裁决表：裁决表 填写内容 裁决后的去向 疑似 Dead Code 豁免/需补激励需补激励者生成[coverage-driven]testplan 条目覆盖模型补建裁决 补建/暂不补建补建者写入补建清单并委派uvm-env-coverage-add第二张表回答的是「该建的覆盖模型建了没有」——与「已有模型缺哪些 bin」是两件事。功能覆盖率 100% 也可能整块功能没有采样点，那样的百分比不能读作「功能验证完成度」。填「暂不补建」的类别会在下一轮报告中预填原裁决并再次列出，不会从视野中消失。
本 skill 不写覆盖模型代码、不跑仿真，仅产出报告与 testplan 条目。
用法：
/uvm-coverage-closure <WORK_DIR> <TESTPLAN_MD> <RTL_DIR> [--spec <spec.md>] [--extra-points <file>]
1b. uvm-env-coverage-add：覆盖模型增量补建
- 功能说明：读取上一步的「覆盖模型补建清单」与
testplan.md的覆盖率目标字段，向已有环境增量补建 covergroup。只修改{ip}_coverage.sv一个文件，其余环境文件一律不碰；写完以COV=1编译验证并修到通过（最多 3 轮，修不好则从备份还原）。 - 与
uvm-env-impl的区别：uvm-env-impl是从零建环境，会连同 driver / monitor / scoreboard 一并重写；成熟环境上增量补建必须用本 skill。 - 不做的事：不编译之外的动作——不跑仿真、不 merge 覆盖率。
- 用法：
/uvm-env-coverage-add <WORK_DIR> <TESTPLAN_MD> <RTL_DIR> [--from-report <报告路径>] [--categories "A,B"] [--spec <path>] [--max-groups N]
补建后必须全量重跑
covergroup 是仿真时采样的：simv.vdb 存覆盖率结构，各 tc_*.vdb 只存命中数据。修改 covergroup 定义改变了结构，必须重新编译并重跑全部 TC，只跑增量无效。补建后功能覆盖率会因分母变大而显著下降，属正常现象。
2. uvm-progress-tracker：验证进度 JSON 维护
- 功能说明：维护验证进度 JSON 数据文件：
init模式：生成新进度文件并填入当前时间作为时间起点；append模式：追加一个阶段数据，记录start_time（本阶段开始）、finish_time（本阶段结束）与duration（本阶段自身耗时，分钟）。传--rpt-dir时还会先make merge再从 URG 报告读回覆盖率各项指标。
- 用法：
/uvm-progress-tracker [<NAME>] [<COVERAGE>] [--file <PATH>] [--start-time <ts>] [--rpt-dir <PATH>]
duration 不是累计值
早期文件用的是 time_min，含义是「从流程起点到该阶段结束」的累计分钟——9 分钟的文档审核和 52 小时的仿真在文件里长得一样，得靠人手工做差才知道各自多久。现在每个阶段直接记自己的 duration。两种格式并存时，按整份文件判一次：任一阶段带 duration 就整份按「每阶段时长」读，否则 time_min 保持累计语义——逐阶段猜会让时间轴倒退。
3. uvm-progress-chart：验证进度折线图生成
- 功能说明：根据 JSON 格式的阶段进度数据，生成"验证进度（时间 vs 覆盖率）"折线图，全量绘制并输出
.drawio图表文件与.png图片。 - 用法：
/uvm-progress-chart <INPUT_JSON> <OUTPUT_DIR> [<BASENAME>]
4. uvm-report-gen：正式验证报告生成
- 功能说明：一轮验证收尾时，把分散在各处的事实汇总成一份可对外交付的 Word 报告。先跑
collect_facts.py从覆盖率报告、回归状态、DUT 缺陷记录、testplan、RTL、SVA、仿真日志采集可核实的数字，再按大纲撰写 Markdown，最后渲染成带样式的.docx，截图位置留成占位框。 - 为什么不手拼
python-docx：数据源分散，且每处都有口径陷阱——DUT 口径 vs 报告首页全局口径、断言源码条数 vs bind 实例数、regression_status.md记录即时判断且不回填。漏一个就是一个错数字送到读者面前。 - 两条硬规则：
- 不静默解决冲突——两个来源对不上时两个都写进「数据核对说明」，注明采用哪个、为什么；
- 不覆盖已贴过截图的报告——检测到目标 docx 内嵌图片时拒绝写入（占位框一旦换成真截图，重新生成会把人工编辑一并冲掉），确需覆盖用
--force。
- 缺陷只认
dut_defect_ledger.md，不从回归状态推断。 - 用法：
/uvm-report-gen <WORK_DIR> <OUTPUT_DOCX> [--rpt-dir <rpt>] [--testplan <md>] [--ledger <md>] [--spec <md>] [--rtl-dir <dir>] [--kb <md>] [--progress <json>] [--outline <md>]
4b. uvm-report-gen-qmd：多格式验证报告（Quarto）
和上一个的关系：采集与撰写完全相同——同一份
collect_facts.py、同一份大纲，由check-script-copies.mjs保证两边不漂移。只在渲染层分叉。uvm-report-genuvm-report-gen-qmd渲染 python-docx自己画Quarto（底层 Pandoc） 输出 只有 .docx.docx+.html（+.pdf）目录 / 页码 手写静态目录，无页码 YAML 一行，自动生成 表 / 图编号 无 自动，可 @tbl-x/@fig-x交叉引用截图 占位框，生成后人工贴进 docx 引用工程里的图片文件，渲染时装配 依赖 python-docx（pip wheel）Quarto 二进制（约 150MB，按平台） 怎么选：只交付 docx、或目标机器装不了 Quarto → 用
uvm-report-gen。要多格式 → 用本 skill。中间产物
.qmd落盘可见，渲染是单独一条quarto render命令——这样装不了 Quarto 的场合还能退回别的渲染器，不用拆管道。用法：
/uvm-report-gen-qmd <WORK_DIR> <OUTPUT_DIR> [--formats docx,html] [--assets-dir <dir>] [--reference-docx <docx>] [--rpt-dir <rpt>] [--testplan <md>] [--ledger <md>] …
Word 的目录是「域」，不是文字
Quarto 写进 docx 的目录是一条 TOC 域指令加一个空结果，要等 Word 更新域才填上。skill 的 finalize_docx.py 会写入 <w:updateFields w:val="true"/>，让 Word / WPS 打开时提示更新。
但 soffice --headless --convert-to pdf 不求值这个域（已实测）——直接拿 docx 转出来的 PDF，目录页是空的，而它看上去是完整的。要 PDF 请先用 Word/WPS 打开并更新域再另存，或让 Quarto 直接出 PDF（那条路的目录是真实正文，但需要中文可用的 LaTeX/typst 引擎）。