| name | refine-regression |
| description | 整体跑一遍真实测试用例（refine_real，真 LLM），并对比前后产物——content_list.json、refine_report.json、full.md——输出回归报告。当用户想"整体跑一下测试用例并对比前后数据"、验证清洗效果有没有回归时使用。 |
| model | opus |
refine 回归测试：整跑 + 前后对比
把 test_data/mineru/<stem>（MinerU 原始产物）整体过一遍 refine（真 LLM），输出到
test_data/refined/<stem>，并做两层对比：
- 输入 vs 本次输出（mineru → refined）：这次清洗到底改了什么。
- 上次输出 vs 本次输出（refined_prev → refined）：代码改动带来的回归/改进。
test_data/ 不进 git，"上次"只能靠文件系统快照（test_data/refined_prev/）。
步骤
1. 前置检查
.env 里要有 QWEN_APIKEY（refine_real 通过 dotenvy 加载；split_table / 视觉层都要用）。
缺了就停下来告诉用户，不要空跑。test_data/mineru/ 必须非空；为空提示先跑 just mineru-fetch。
2. 快速门禁（mock 测试）
先跑 just test（全程 mock，不打网络）。红了就停：先修单测，别烧真 LLM 的钱。
3. 快照上一次结果
rm -rf test_data/refined_prev
[ -d test_data/refined ] && cp -R test_data/refined test_data/refined_prev
没有 test_data/refined/（首跑）就跳过，后面只做"输入 vs 输出"对比。
4. 整跑
just refine-real 2>&1 | tee /tmp/refine_real.log
- 真 LLM，每个文档可能要几分钟——用
run_in_background 跑，期间 tail 日志看进度。
- 用户只想跑某一个文档时：
just refine-real <stem>（refine_real 只会重写该文档的输出目录，
其余文档保留上次结果，对比时也只看这个 stem）。
- 可选环境变量（用户明确要求时才加）：
REFINE_MAX_ITERATIONS=N、
REFINE_FIX_CONFUSION=1（OCR 混淆层）、REFINE_REWRITE_GARBLED=1（乱码表重转写层）。
- 日志本身就含每个文档的输入/输出疑点、耗时、ops、删除片段、混淆/重转写明细——这是
报告的重要素材，别丢。
5. 汇总对比
python3 .claude/skills/refine-regression/summarize.py [stem]
逐文档打印：items 数量（输入/本次/上次）、refine_report 关键指标及上次对照
（iterations / opCounts / dismissed / violations / failOpen / removedSpans / tokens）、
full.md 与 content_list.json 的 diff 量级。
只对量级非零的"上次→本次"差异深入看 diff，full.md 很大，别整篇倒进上下文：
git diff --no-index test_data/refined_prev/<stem>/full.md test_data/refined/<stem>/full.md
逐 hunk 判断是改进（修掉了之前没修的）还是回归（之前修好的又坏了）。
content_list.json 的 diff 同理，必要时配合 refine_report.json 里的 removedSpans /
confusionFixes / tableRewrites 解释每处变化的来源。
注意：MinerU 原版 full.md 与其 content_list 本就有少量出入；refined 的 full.md 是从清洗后
items 确定性重渲染的，对比"输入→输出"时以 content_list 为准，full.md 的格式性差异
（如渲染风格）不算回归。
6. 报告
输出一份 markdown 总结，按文档分节：
- 总览表：每个文档的 items 变化、耗时、token 消耗、violations / failOpen（这两项相比
上次不该上升，升了就是红灯）。
- 上次→本次有差异的文档：逐条列出 full.md / content_list 的实质变化，标注「改进」「回归」
「中性（非确定性抖动）」。真 LLM 输出有随机性，孤立的小抖动要点出来但别误报为回归。
- 输入→输出：本次清洗做了什么（ops 分布、删除片段、各层落地/拒绝数）。
最后给结论：本次代码状态相比上次快照是否安全。
