# EVALUATION — skill 质量评估框架（三层回归 + 验收规则）

> 目标：**保证每次优化后 skill 一定比优化前强**，用客观数据说话，避免拍脑袋。
> 核心机制：先记录基线 → 优化 → 三层回归测试 → 硬闸门+综合分对比 → 达标才发布，回归即回滚。

## 0. 三层回归总览

| 层 | 时机 | 内容 | 工具 | 判定 |
|---|---|---|---|---|
| **Tier 0 工具自检** | 每次改动后 | scaffold / 契约生成 / verify(合格+陷阱双工作区) / checks / 导出 / install | 手工+脚本 | 任一失败 → 禁止发布 |
| **Tier 1 迷你端到端** | 每次优化后 | 用 fixtures 数据跑完整流水线 | `auto-score.py` | 自动分 < 基线 → 禁止发布 |
| **Tier 2 往届盲测** | 重大优化 / 用户要求 | 真实往届题，题目+附件入隔离工作区，**获奖论文不提供** | `run-tier2.ps1` + `auto-score.py` + `blind-rubric.md` | 任一客观指标回归 → 禁止发布 |

## 1. 六个评估维度（加权总分 100，自动 90 + 人工 15 归一化）

| 维度 | 权重 | 客观指标（自动） |
|---|---|---|
| 正确性 | 40 | checks.py 错误数、verify.py 错误数、编造率 |
| 质量 | 35 | 章节完整度(10)、摘要数值密度(8)、摘要字数档位(3)、图表数(5)、表格数(2)、编号公式数(2)、参考文献(2)、模型检验章节(1)、灵敏度章节(1)、契约/PDF(3+2)；WARN 每警告扣 1 分（上限 4） |
| 流程 | 15 | 进度日志、数据契约、工作区目录齐备 |
| 效率 | 10 | 达到可提交论文的轮数（盲评量表换算，见 §1.1） |
| 触发 | 5 | skill 是否正确触发（盲评量表换算，见 §1.1） |

`auto-score.py` 自动计算前 90 分（正确性+质量+流程），效率/触发人工传入，
三者合计按 `×100/105` 归一化到 100 分制。细则：质量项中摘要数值 ≤15 处封顶、
图 ≤4 张封顶、表 ≥6 张满分、编号公式 ≥6 个满分、参考文献 ≥6 条满分、
摘要 700-1300 字满分（500-699/1301-1500 得一半）、版面合规分（format-check.py，
页边距/页码/图题注/三线表/首页摘要，满分 10）；`checks/verify/format-check` 警告数计入质量扣分。

### 1.1 盲评换算口径（blind-rubric.md ↔ 人工项）

- 盲评量表五维各 0-5 分，满分 25：模型可解释性 / 求解完整度 / 检验稳健性深度 / 写作质量 / 代码可复现性
- 换算规则：`efficiency = rubric_total × 10/25`，`trigger = rubric_total × 5/25`（按 2:1 映射到 15 分人工项）
- 评分纪律：同一评卷人、同一量表、不翻阅官方答案与获奖论文；硬闸门先跑，失败则量表仅作方法学参考
- **盲评客观化（v1.4.0）**：量表每维标注"证据来源"——求解完整度↔verify 溯源报告.md（未溯源率 ≤5% 优/≤15% 中）、写作质量↔checks 2.5 五要素逐项输出、代码可复现性↔verify 数据绑定/溯源率/图三方一致 + checks 附录双要件；评分前先跑工具锚定，主观项（模型可解释性/检验深度）须给出 1-2 句依据
- **格式硬伤一票否决（v1.3.0，v1.4.0 增补）**：摘要页超一页/页边距 <2.5cm/无页码/正文无 [x] 引用/附录无完整代码/图引用无插图/图表题注缺失或位置错误 → 写作质量维度上限 3 分，2 处及以上上限 2 分；**v1.4.0 增补**：论文含参赛者身份信息、支撑材料未打包或 >20MB 同样一票否决

### 1.2 版面格式检查（v1.4.0，format-check.py）

对导出 docx/PDF 做版面级硬检查，官方规范 HARD + 获奖论文惯例：
页边距 ≥2.5cm / 页脚 PAGE 页码域 / 首页为摘要专用页 / 每张图片后紧跟"图N"题注 /
三线表（无竖线） / 表题注在表上 / 题注字号 ≤ 正文 / 身份泄漏扫描（学校/队号/手机号/邮箱） /
PDF ≤20MB / **正文页数双阈值（>30 错、26-30 警、≤25 过，pypdf 定位附录/参考文献页计算，附录页数不计入）** /
PDF 第 1 页摘要版面校验（含"承诺书"即错误）。
`checks.py` 同步升级：摘要字数档位（<500 错、500-699 警、700-1300 过）、
**摘要五要素检查（2.5：归类/思想/算法/特点/结果逐问数值覆盖）**、
图片标签必须存在且编号连续、表题注须在表上方、"图N"引用须有对应插图、
正文 [x] 引用覆盖 ≥50% 文献、**附录双要件（文件列表 + 完整代码块）+ 豁免声明（"本论文没有用到程序"/"本论文没有支撑材料"）**、
**支撑材料须单个 zip/rar ≤20MB 且不含承诺书/编号页**、身份泄漏扫描。
`verify.py`：**全文数值溯源（摘要+正文全数值，含容差匹配）生成 4_论文/溯源报告.md**，
未溯源率 ≤5% 通过、≤15% 警告、>15% 错误。
`package.ps1`：打包后自校验（大小 / 承诺书编号页文件名黑名单 / 包内文本身份扫描）。

## 2. 验收规则（写入即生效）

1. **硬闸门**（一票否决）：
   - Tier 0 全部工具通过
   - checks.py 0 错误、verify.py 0 错误、format-check.py 0 错误（v1.3.0 起）
2. **比较规则**：候选版 `grand_total` ≥ 基线版；且任一客观指标（checks/verify 错误数、章节数、摘要数值）**不得回归**
3. **回滚规则**：任一硬闸门失败或客观指标回归 → 本次优化**禁止发布**，回滚该改动
4. **发布条件**：全部通过 + `grand_total ≥ 基线 + 0` 才 tag 发布；提升显著（≥5%）记入 CHANGELOG

## 3. 运行协议（每轮迭代）

```
1. 记录基线: evaluation/RESULTS.md 保存当前版本 auto-score.py 输出 + git commit
2. 做优化 → Tier 0 自检（必须全过）
3. Tier 1: 全新 fixture 工作区跑流水线 → auto-score.py 对比基线
4. (重大改动) Tier 2: run-tier2.ps1 -Year 2023 -Problem C → 跑全流程 → auto-score.py + blind-rubric
5. 对照验收规则 → 达标: commit + tag + CHANGELOG；不达标: 回滚
```

## 4. 基线记录（当前）

| 版本 | git | 硬闸门 | auto_score(90) | grand_total(100) | 备注 |
|---|---|---|---|---|---|
| v1.1.0 | 538a506 | PASS | —（评测体系当时未建） | — | 反幻觉体系首次验证通过 |
| v1.2.0 | 0931c6f | PASS | 85/85（旧制） | 98.0（旧制） | 自包含加固 + 评测自动化 |
| v1.2.2 | 9f6dac3 | PASS | 85/85（旧制） | 98.0（旧制） | Tier2×2 盲测通过 + run-tier2 修复 |
| v1.2.3 | aa5706d | PASS | 90/90 | 99.4 | 新评分制：质量 35 扩容 + WARN 扣分 + 盲评闭环 + 夹具强化（Tier1 97.6 / 2023C 99.4 / 2022C 100.0，详见 RESULTS.md） |
| v1.2.4 | 77cc127 | PASS | 90/90 | 99.4 | 2021C 第三类题型盲测通过（综合评价+LP优化） |
| v1.2.5 | 0477849 | PASS | 90/90 | 97.6 | 工具链收尾：契约多 sheet 支持 + 安装验证 + Tier1 无回归（89.5/90·97.6/100） |
| v1.3.0 | 61f99c4 | PASS | 90/90 | 97.1 | 格式硬检查体系：format-check.py 版面检查 + checks.py 摘要/引用/附录/题注升级 + md2docx 页码/三线表 + 盲评一票否决 + 负样本验证；2021C/2022C/2023C/Tier1 四工作区全部 0 错误 0 警告 0 版面错误（四区 auto 90/90·97.1/100） |

> 契约说明：`make-data-contract.py` 自 v1.2.5 起解析 xlsx 全部工作表（`sheets` 字段），并在文件条目顶层合并 stats/categories 保持向后兼容；类别列自动排除 供应商ID/转运ID 等标识列，避免分组数被 ID 基数污染。

> 旧制（auto 85 + 人工 15 = 100）与 v1.2.3 新制（auto 90 + 人工 15 归一化 100）分数不可直接比较；
> 历史旧制分数保留在 RESULTS.md 备注列，基线一律以新制重评后记录。

## 5. 反幻觉专项指标

- 编造率（陷阱1）= 编造数值题数 / 陷阱1 总题数，目标 **0%**
- verify 拦截率（陷阱3）= 成功拦截"疑似硬编码"题数 / 总题数，目标 **100%**
- 图表一致性通过率（陷阱2）= 通过 verify 图一致性检查题数 / 总题数，目标 **100%**
- 陷阱组一次性跑法：`run-benchmark.ps1` 生成 9 个工作区（含 3 陷阱），逐题执行后按此表统计