Exam Evaluator

从 .xlsx/.xls/.docx/.pdf 试卷/题库中提取试题，从五个维度（内容效度、结构效度、难度控制、区分度潜力、规范性）评估命题质量，生成交互式 HTML 可视化报告。Use when: (1) 用户要求评估试卷或题库质量，(2) 命题后需要质量检验，(3) 对比多份试卷的命题水平，(4) 生成试题分析报告，(5) 用户上传 Excel/Word/PDF 文件要求分析。触发词：评估试卷、评估题库、试题质量、试卷分析、题库分析、命题质量、命题检验、exam evaluation、question quality assessment、.xlsx、.docx、.pdf

试题质量评估

从试卷/题库中提取试题，结合客观量化指标（Python）和主观语义评价（Agent），从五个维度输出评估结果。

⛔ NEVER

• NEVER 跳过 Phase 4 确认模式直接评分
• NEVER 在没有解析质量标注的情况下生成报告
• NEVER 使用纯加权平均计算综合评分（必须用短板机制 min(加权平均, 最低分+2)）
• NEVER 将填空题答案唯一性交由 Python 判定（必须由 Agent 判断）
• NEVER 在低置信度题型未向用户确认的情况下继续
• NEVER 让判断题"正确"比例偏离 40%-60% 区间而不指出
• NEVER 忽略最长选项偏差 > 45% 的结构性问题
• NEVER 接受选择题答案分布标准差 > 7 而不指出失衡风险
• NEVER 在认知层级仅覆盖 ≤2 层时给出"良好"及以上评价

工作流程

Phase 1: 解析

运行本地脚本提取原始文本：

• .xlsx/.xls → scripts/parse_excel.py <file> temp/clean.json（结构化可靠，直出 clean.json）
• .docx → scripts/parse_docx.py <file> temp/raw.json
• .pdf → scripts/parse_pdf.py <file> temp/raw.json

注意：Word/PDF 脚本仅提取文本，结构化由 Phase 2 Agent 完成。

Phase 2: Agent 结构化

多卷识别（MANDATORY）：Agent 结构化前 MUST 先判断文档是否包含多套独立试卷。 识别信号：

• 出现多个独立标题（如不同学校/学期/科目名称）
• 题号重新从 1 开始
• 科目/班级/命题人信息发生变化
• 出现明显的分隔线或"第X页 共Y页"重置

不应判为多卷的情况（否定规则）：

• 题干内容中出现"第1题"字样（非题号标记）
• 同一试卷的附加页/续页（页码增加但科目、题型结构连续）
• 参考答案与试题正文被误判为独立试卷（检查是否只有答案无题干）
• 同一学校/学科不同题型分节（如"一、选择"→"二、填空"是单卷的正常分段）

输出规则：

• 多卷：分别输出 temp/clean_1.json、temp/clean_2.json...，每个文件包含一套完整试卷的 metadata 和 questions
• 单卷：输出 temp/clean.json

Excel 路径：跳过本 Phase，parse_excel.py 已输出 clean.json。

Word/PDF 路径：Agent 读取 temp/raw.json 中的 paragraphs 和 tables，转换为标准 clean JSON：

1. 识别题型（选择/判断/填空/简答/论述/案例分析/计算/应用等），附带 confidence（高/中/低）
2. 提取每题的 id、question_type、stem、options、answer、explanation、score、rubric、knowledge_point、cognitive_level、difficulty
3. 答案自动关联（可能在题干后，也可能在文末"答案与解析"部分）
4. 判断题答案标准化：A/正确/对/√/TRUE → "正确"，B/错误/错/×/FALSE → "错误"
5. 选择题选项提取为数组 ["A. 内容", "B. 内容", ...]
6. 知识点自动识别（MANDATORY）：即使原始试题无标注，MUST 根据题干+选项+解析自动识别 knowledge_point：
   • 选择题/判断题：从题干关键词 + 解析提取核心考点
   • 填空题：从答案反推考查知识点
   • 主观题：从评分标准提取能力要求对应的知识点
   • 无法归类时用"综合应用"
7. 低置信度题型标记"待确认"，无法识别的题跳过（不要编造）

内容质量验证（MANDATORY）：

1. Agent MUST 逐题验证答案与题干逻辑一致性：

   • 检查答案是否实际回应题干提问内容
   • 多选题：确认正确选项存在且选项内容合理（非空/非占位符）
   • 记录结果至 clean.json answer_verified 字段："verified" | "suspicious" | "unverifiable"

2. Agent MUST 检查题干语言文字质量：

   • 标记错别字、语法错误、歧义表述
   • 记录问题至 clean.json linguistic_issues 字段（字符串数组，无问题则为 []）

3. Agent MUST 检查内容对齐性：

   • 确认答案内容确实属于本题（而非错位粘贴到其他题目）
   • 确认选项主题与题干相关
   • 记录问题至 clean.json content_alignment 字段（字符串数组，无问题则为 []）

4. ⚠️ GUARDRAIL：Agent MUST NOT 自行判定答案为"错误"（verified_wrong），最高判定为 "suspicious"。最终验证由 Phase 7 完成。

新增字段说明：

字段	类型	必填	说明
answer_verified	string	✅	"verified" | "suspicious" | "unverifiable" — Agent 对答案正确性的判断
linguistic_issues	array	✅	语言文字问题列表，如 ["第3题题干存在歧义表述", "第5题出现错别字"]，无问题则为 []
content_alignment	array	✅	内容错位问题列表，如 ["第2题答案与题干主题不一致"]，无问题则为 []

输出格式：标准 clean JSON，包含 metadata（title/total_score/source_type）、parse_quality（high/medium/low）、questions 数组（每题含 id、question_type、stem、options、answer、explanation、score、knowledge_point、cognitive_level、difficulty、confidence、answer_verified、linguistic_issues、content_alignment）。

Phase 2+ 输出质量自动验证（Word/PDF 路径必须执行）

生成 clean.json 后，MUST 计算以下覆盖率指标：

指标	计算公式	合格阈值
答案覆盖率	有 answer 字段的题数 / 总题数	≥80%
题型识别率	question_type ≠ "未知" 的题数 / 总题数	≥80%
知识点覆盖率	knowledge_point ≠ "综合应用" 的题数 / 总题数	≥60%

验证结果分支：

• 任一指标 < 80%（答案/题型）或 < 60%（知识点） → ⚠️ 暂停后续流程，Do NOT 继续 Phase 3。 向用户展示验证结果（三项指标的具体数值），并明确询问：

  "当前 parse_quality 偏低（答案覆盖率 X%，题型识别率 Y%，知识点覆盖率 Z%）。是否启用 Agent 大模型深度识别进行二次解析？"

  • 选择"是"：Agent 重新逐题审阅 raw.json 中未识别/低置信度的段落，利用语义理解补充缺失字段
  • 选择"否"：按当前质量继续，parse_quality 标记为 "low"，报告中显示警告

• 全部达标 → 继续 Phase 3

⚠️ clean.json 字段名校验（Phase 3 前 MUST 确认）：compute_metrics.py 按固定字段名读取。确认 clean.json 中每题的字段名使用下划线命名（question_type、cognitive_level、knowledge_point），不得使用驼峰（questionType、cognitiveLevel）。任一字段名不匹配将导致 metrics.json 所有统计为 0 或"未知"。

Phase 3: 量化指标计算

单卷：

• scripts/compute_metrics.py temp/clean.json temp/metrics.json
• scripts/detect_duplicates.py temp/clean.json --output temp/duplicates.json

多卷：对每个 temp/clean_N.json 分别运行，输出 temp/metrics_N.json、temp/duplicates_N.json。

Phase 4: 确认模式（强制明确）

必须向用户确认（使用以下精确交互格式）：

AskUserQuestion（一次询问三个问题）：

问题1 - 评价模式：请选择评价模式

• "整体评价"（推荐，token 最少）：全卷综合评分，速度最快
• "抽样评价"：分层抽取 5-10 题逐题评价后推导全卷
• "逐题评价"（token 最多）：每题独立评分，输出最详细

问题2 - 权重预设：请选择评估权重标准

• "默认权重"（推荐）：内容25%, 结构20%, 难度20%, 区分度15%, 规范20%
• "升学考试"：侧重难度(30%)和区分度(25%)
• "日常测验"：侧重内容(30%)和规范性(25%)
• "竞赛选拔"：侧重区分度(30%)和难度(25%)

问题3 - 低置信度题型（如有 confidence=低的题）：以下题目识别置信度较低，是否确认？ [列出低置信度题目摘要]

用户未回复前 Do NOT 继续 Phase 5。

Phase 5: Agent 评价

评估前自问框架（评分前 MUST 思考）：

• 内容效度：这份试卷真的考查了它声称要考的内容吗？知识点与题型匹配是否恰当？
• 结构效度：如果我是学生，能否从选项长度/格式猜出答案？干扰项是否"似是而非"？
• 难度控制：真正理解的学生 vs 死记硬背的学生，得分差异会明显吗？
• 区分度潜力：每道题都有明确的区分意图吗？还是只是"送分题"？
• 规范性：题干表述有歧义吗？解析质量能帮助学生理解错误原因吗？
• 答案一致性：每道题的答案真的回答了那个问题吗？是否有答非所问？
• 语言文字质量：题干表述是否存在错别字、语病或标点问题？
• 内容错位：是否有答案不属于本题、选项内容与题干无关的情况？

MANDATORY - READ ENTIRE FILE: 评分前 MUST 完整读取 references/evaluation_criteria.md（51 行），严格按 10 分制细则评分。

条件加载：

• 用户要求分析认知层级分布 → 读取 references/bloom_taxonomy.md（18 行）
• 题型含简答/论述/案例分析等主观题 → 读取 references/question_types.md（19 行）
• 明确是职教/对口升学考试 → 读取 references/vocational_standards.md（17 行）
• 用户明确指定权重场景（如"按升学考试标准评估"）→ 读取 references/weights/ 下对应预设

Do NOT load：

• bloom_taxonomy.md — 只需整体评分或全是客观题（选择/判断/填空）
• question_types.md — 全是选择/判断/填空
• vocational_standards.md — 非职教考试
• weights 预设文件 — 用户未指定权重场景时使用默认权重

五维度：

维度	默认权重	评分要点
内容效度	25%	考点覆盖、考纲匹配、认知层级分布、答案与题干一致性、内容错位检测
结构效度	20%	答案分布、选项设计、干扰项质量
难度控制	20%	低中高比例、难度梯度
区分度潜力	15%	区分不同水平学生、干扰项有效性
规范性	20%	格式统一、题干清晰、解析质量、无重复、语言文字质量（错别字、语病、标点规范）

内容验证评分要点（Agent MUST 参考 clean.json 中的验证字段）：

• answer_verified: "suspicious" 的题目：内容效度自动扣 1 分/题
• linguistic_issues 非空：规范性扣分 0.5 分/题（最多扣 3 分）
• content_alignment 非空：内容效度扣分 1 分/题
• 跨题答案矛盾：发现后每题在内容效度中扣 1-2 分

评分规则：

• 每题/全卷 五个维度各评 1-10 分
• 综合评分 = min(加权平均, 最低维度得分 + 2) — 短板机制
• 列出优秀项、需改进项、具体建议（P0/P1/P2 优先级） 评价模式差异：
• 整体模式：全卷综合评分
• 抽样模式：分层抽取 5-10 题逐题评价，推导全卷
• 逐题模式：每题独立评分，输出详细明细

Phase 5 Output: evaluation.json Schema

MUST 严格按以下 Schema 输出，字段名必须完全匹配（generate_report.py 按固定字段名读取，命名不一致将导致报告全部显示默认值/空白）：

json

{
  "evaluation_mode": "overall",
  "overall_scores": {
    "内容效度": 7,
    "结构效度": 6,
    "难度控制": 8,
    "区分度潜力": 5,
    "规范性": 7
  },
  "dimension_details": {
    "内容效度": { "evidence": "考点覆盖了教材核心章节，但缺少xxx知识点..." },
    "结构效度": { "evidence": "选项分布基本均衡，但第5题最长选项偏差达40%..." },
    "难度控制": { "evidence": "低:中:高≈3:5:2，难度梯度合理..." },
    "区分度潜力": { "evidence": "多数题为记忆型，缺乏应用分析类题目..." },
    "规范性": { "evidence": "格式统一，但第3题题干存在歧义..." }
  },
  "weights": {
    "内容效度": 0.25,
    "结构效度": 0.20,
    "难度控制": 0.20,
    "区分度潜力": 0.15,
    "规范性": 0.20
  },
  "strengths": [
    "难度梯度设计合理，低中高比例为3:5:2",
    "选择题干扰项设计有效"
  ],
  "weaknesses": [
    "判断题答案严重偏向'正确'（占比75%），不符合命题规范",
    "缺少答案解析，规范性不足"
  ],
  "suggestions": [
    {
      "priority": "P0",
      "title": "调整判断题答案分布",
      "description": "将判断题正确/错误比例调整至接近1:1，避免答案一边倒"
    },
    {
      "priority": "P1",
      "title": "补充题目解析",
      "description": "为每道题添加详细解析，解释正确选项的原因和干扰项的排除理由"
    }
  ],
  "questions": [
    {
      "id": "1",
      "question_type": "选择题",
      "stem_summary": "下列关于xxx的说法正确的是",
      "scores": {
        "内容效度": 8,
        "结构效度": 7,
        "难度控制": 6,
        "区分度潜力": 5,
        "规范性": 8
      },
      "total_score": 6.7
    }
  ],
  "knowledge_points_summary": {
    "细胞结构": 3,
    "光合作用": 2,
    "遗传定律": 1
  }
}

字段说明：

字段	类型	必填	说明
evaluation_mode	string	✅	"overall" / "per_question" / "sampling"
overall_scores	object	✅	五个维度各评 1-10 分，键名必须用中文全称
dimension_details	object	✅	每维度含 evidence 字段，说明评分理由
weights	object	✅	五维度权重，值之和为 1.0
strengths	array	✅	优秀项列表，每项为字符串
weaknesses	array	✅	需改进项列表，每项为字符串
suggestions	array	✅	含 priority（P0/P1/P2）、title、description
questions	array	逐题/抽样模式	含 id, question_type, stem_summary（≤30字）, scores（五维度）, total_score
knowledge_points_summary	object	✅	{"知识点名称": 出现次数}，用于词云图

⚠️ 字段名拼写错误（如 overall_scores 写成 overallScores、scores 或 dimension_scores）将导致 generate_report.py 的 .get() 全部返回默认值，报告显示综合评分 0.0、图表空白。

Phase 5+ evaluation.json Schema 校验（MUST 执行）

写入 temp/evaluation.json 后，MUST 运行自动化校验脚本：

bash

python scripts/validate_evaluation.py temp/evaluation.json [--mode overall|per_question|sampling]

校验内容（脚本内置）：

• evaluation_mode 有效性、"区分度"简写检测
• overall_scores 五维度完整 + 值域 [1,10]
• weights 键名与 overall_scores 一致 + 值之和 = 1.0
• dimension_details 五维度含 evidence
• knowledge_points_summary 非空
• suggestions 子字段 (priority/title/description)
• 逐题模式：questions 数组每项含 id/scores/total_score

校验结果：

• 输出 ✅ 全部校验通过 → 继续 Phase 6
• 输出 ❌ 校验失败 — N 个错误 → Do NOT 继续 Phase 6。根据输出的具体失败项修正 evaluation.json 后重新运行脚本，直到通过。

Phase 6: 报告生成

单卷：

• scripts/generate_report.py --metrics temp/metrics.json --evaluation temp/evaluation.json --duplicates temp/duplicates.json --output output/report.html

多卷：

• 对每套试卷分别运行 generate_report.py，输出 output/report_1.html、output/report_2.html...
• 生成 output/index.html 汇总导航页，列出各卷名称、科目、题量和综合评分，提供链接跳转各卷详细报告。

输出要求（脚本不可用时 Agent 直接生成 HTML）：

1. Chart.js CDN（https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js）
2. 五维雷达图 + 题型分布饼图 + 难度分布图 + 认知层级环形图
3. 选择题答案分布柱状图（如有选择题）
4. 知识点分布词云图（从 knowledge_points_summary 生成，字体大小映射频次）
5. 五维度评分表（短板机制说明，"说明"列填充 evidence 字段）
6. 优秀项/需改进项/改进建议（P0/P1/P2 标签）
7. 每个图表下方解读文本（数据异常、合理之处、改进建议）

Phase 7: 质量验证

交付前 MUST 执行以下自动化 + 手动验证：

1. 自动化验证：

bash

# Schema 校验（如跳过 Phase 5+，此处补执行）
python scripts/validate_evaluation.py temp/evaluation.json [--mode overall|per_question|sampling]

# 报告文件存在性
test -f output/report.html && echo "✅ report.html 存在" || echo "❌ 缺失"

2.5. 内容验证检查：

读取 temp/metrics.json 的 format_validation 字段和 temp/clean.json 的验证字段，执行以下检查：

1. 格式问题联动检查：

   • 遍历 format_validation 中的每个 issue
   • 检查该 issue 是否在 evaluation.json 的 weaknesses 或 suggestions 中得到回应
   • 未被回应的格式问题 MUST 生成新增建议项：

     text

     suggestion: { "priority": "P1", "title": "修复格式问题", "description": "..." }
     

2. 可疑答案审查：

   • 读取 temp/clean.json，检查 questions 数组中 answer_verified 为 "suspicious" 的题目
   • 如有 suspicious 条目，在 Phase 7 输出中列出：

     text

     ⚠️ 发现 N 题答案标记为 suspicious，建议人工复核：
       - 第X题：题干摘要...
       - 第Y题：题干摘要...
     

   • 确认这些题目已在 evaluation 的 weaknesses 中得到回应（如"第X题答案存疑"）

3. 内容错位检查（如有 content_alignment 非空题目）：

   • 确认对应题目在 evaluation 的 weaknesses 中有对应项
   • 未被回应的错位问题 MUST 生成建议项

2. 手动验证：

• 五个维度均有评分（1-10），综合评分计算正确（短板机制）
• HTML 文件可打开，图表（雷达图/饼图/柱状图/词云）正常渲染
• 逐题表数据完整（逐题/抽样模式下 questions 列数与总题数一致）
• 中文显示正常，无乱码
• 无"0.0"综合评分、无空白图表区域

3. 验证失败处理：

• 自动化验证失败 → 回 Phase 5+ 修正后重新运行
• 手动验证失败 → 回 Phase 6 修正报告生成

错误处理（按优先级排序）

处理原则：先处理 P0 → 再处理 P1 → 最后处理 P2。P0 无法解决则停止后续流程。

P0 - 阻断级（必须解决才能继续）：

• clean.json 为空 → 检查原始文件是否加密/损坏/格式不匹配，告知用户
• questions 数组为空 → 题型格式无法识别，告知用户

P1 - 警告级（继续但标注）：

• 解析质量=低 → 报告标题区标注 "⚠️ 解析质量低，部分数据可能不准确"
• 某题型题量 < 3 → 该题型指标仅供参考，不纳入综合评分

P2 - 降级级（跳过并注明）：

• compute_metrics.py 报错 → 检查 clean.json 格式后重试，仍失败则跳过量化指标
• detect_duplicates.py 报错 → 跳过重复检测，报告中注明 "未执行重复检测"
• generate_report.py 报错 → Agent 直接生成 HTML（见 Phase 6 fallback）

多卷场景：

• 无法明确分卷 → 按单卷处理，报告中注明"文档可能包含多套试卷但未明确分隔"
• 某卷题量 < 5 → 该卷单独标注"题量过少，评估结果仅供参考"

常见问题

问题	排查步骤
Excel 读取失败	确认文件未加密，检查是否为 .xls 旧格式（需 openpyxl 或 xlrd）
Excel 含多个工作表	parse_excel.py 自动合并所有 sheet，若混入无关数据可在 Phase 2 过滤
Word 文档含图片题	图片中的题干/选项无法被 parse_docx.py 提取，Agent 结构化时标记"图片题-需人工确认"
认知层级仅 1-2 层	在建议中明确指出，降低内容效度评分
判断题答案一边倒	P0 级问题，必须在 weaknesses 中突出显示
无解析字段	规范性评分降至 3-4 分，建议补充解析

输出

• 主文件：output/report.html（交互式可视化报告）
• 可选：output/逐题明细.csv（从 HTML 导出按钮下载）

| 评价模式/权重不一致 | evaluation_mode 与 questions 数组内容不匹配（如 mode="overall" 但有 questions 数据） | | 权重键名不一致 | weights 的键与 overall_scores 的键不完全匹配 → 某维度权重被静默置0 |

权重预设文件

⚠️ 键名一致性约束：所有权重预设文件的键名 MUST 与 overall_scores 完全一致，使用五维度的中文全称：内容效度、结构效度、难度控制、区分度潜力、规范性。不得使用简写（如"区分度"）。键名不匹配将导致对应维度权重被静默置0。

• references/weights/升学考试.json — 难度30%, 区分度潜力25%, 内容20%, 结构15%, 规范10%
• references/weights/日常测验.json — 内容30%, 规范25%, 难度20%, 结构15%, 区分度潜力10%
• references/weights/竞赛选拔.json — 区分度潜力30%, 难度25%, 内容20%, 结构15%, 规范10%