物理试卷综合分析报告生成
功能概述
本技能实现高中物理考试的全流程深度分析，生成六段式个性化综合分析报告：
- 考试全景扫描（板块得分统计表）
- 逐题答题与反思对照分析（每题深度根因分析+针对性建议）
- 知识模块整体诊断（模块得分率+薄弱环节）
- 反思深度分析（学生自我认知偏差纠正）
- 提分路径规划（三阶段目标拆解）
- 给学生的个人留言（温暖鼓励+行动建议）
触发条件
当用户同时提供以下文件时触发：
- 试卷 PDF：含完整试题内容
- 答案 PDF：含标准答案和评分标准
- 学生答题 Excel：含每题选项/得分（如"沈阳二中...成绩报告_学生小题明细表.xlsx"）
- 学生反思文件：学生考后总结（.docx 或 .pdf 格式）
典型用户表述：
- "帮我分析这次物理考试"
- "根据试卷和学生反思生成分析报告"
- "帮XX同学分析四月月考成绩"
输入文件说明
试卷 PDF
高二物理标准试卷，通常结构：1-7单选题（每题4分）、8-10多选题（每题6分）、11实验题（14分）、13-15计算题。
答案 PDF
参考答案，标准格式如 "1、D"、"8. AC"。
学生答题 Excel
通常由学校阅卷系统导出（如"成绩报告_学生小题明细表"），包含：序号、姓名、总分、各题选项/得分。
学生反思文件
学生考后提交的总结文字（.docx 或 .pdf），包含对错题原因的分析和自我评估。
核心工作流程
第一步：确认输入文件
确认用户提供的所有文件路径存在且可读。
- 微信临时目录中的文件可能失效，若无法读取则引导用户重新发送
- 确认需要为哪些学生生成报告
第二步：提取并预处理数据
运行数据提取脚本，获得结构化JSON：
python scripts/exam_analysis.py <成绩.xlsx> <试卷.pdf> <答案.pdf> \
--config <知识点配置.json> \
--multi-qs "8,9,10" \
--single-score 4 --multi-full 6 --multi-partial 3 \
--exclude-qs "11,12" \
--exam-name "高二4月月考" --class-name "高二16班" \
--extract-only --output-json <数据输出.json>
参数说明：
- --exclude-qs "11,12"：排除不需要分析的题号（如合并给分的题目）
- --extract-only：仅输出JSON数据，不生成报告
- --output-json：JSON输出路径
脚本会自动完成：
- 识别单选题/多选题/主观题列
- 从答案PDF中提取标准答案并批改客观题
- 计算每题正确率和班级统计
- 计算知识模块得分率
- 为学生排名
第三步：读取学生反思
对每位目标学生，读取其反思文件：
- .docx：使用 python-docx 提取文本
- .pdf：使用 PyMuPDF（fitz）提取文本
第四步：准备知识点配置
从试卷 PDF 中提取每道题的知识点信息，创建 JSON 配置文件（如无已有配置）：
{
"knowledge_map": {
"1": {"topic": "电磁学", "subtopic": "交变电流", "weight": 4, "exam_point": "交变电流的四值辨析与安培力方向判断", "common_mistakes": ["混淆瞬时值与有效值"]},
...
},
"topic_categories": {
"电磁学": [1, 8, 10],
"热学": [2, 13, 15],
"光学": [3, 9, 14],
"原子物理": [4, 5, 6],
"力学": [7],
"实验": [11]
},
"subjective_max": {"11": 14, "13": 10, "14": 12, "15": 18}
}
配置要点：
- exam_point：具体考查要点，用于错题分析中的【考查要点】
- common_mistakes：该考点的常见错误，用于【针对性建议】中的提醒
- weight：题目的满分值（用于加权计算模块得分率）
- 详细说明见 references/knowledge_map.md
第五步：AI 深度分析（核心步骤）
对每位学生，结合提取的数据和学生反思，进行深度分析。
5.1 逐题分析
对每道学生出错的题目，撰写以下内容：
诊断的撰写原则：
1. "粗心"不能作为唯一解释——追问：如果概念理解足够清晰，还会"粗心"吗？
2. 结合学生反思——利用反思中的线索找到真正问题
3. 具体化——不说"计算错误"，说"漏写了pS表示力这一步"
每题的输出格式（写入JSON给 build 脚本）：
{
"qnum": 1,
"topic": "电磁学",
"subtopic": "交变电流",
"score": 0, "max_score": 4,
"status": "零分", # "零分" / "部分得分" / "全对"
"student_answer": "C", "correct_answer": "D",
"exam_point": "交变电流的四值辨析与安培力方向判断",
"reflection": "学生反思原文（如有）",
"diagnosis": "一句话问题诊断",
"root_cause": "深层根因分析（200-400字）",
"suggestions": ["建议1", "建议2", "建议3"]
}
根因分析示例（不要简单归因）：
- ❌ 错误："审题粗心导致选错"
- ✓ 正确："学生归因为'审题问题'，但本题考查分子势能Ep-r图像的理解，正确答案C要求理解'分子势能的零点选取与引力做功的关系'。如果对图像有透彻理解，即使审题不细也能通过排除法找到正确答案。因此根因仍是：分子势能图像的核心物理含义理解不深。"
建议撰写原则：
- 必须具体可操作（不说"多做题"，说"做5道活塞+气体定律综合题"）
- 给出具体方法和步骤（如"三步法：Step1受力分析→Step2列平衡方程→Step3联立状态方程"）
- 有针对性（根据学生的错误类型定制）
5.2 知识模块诊断
对各知识模块：
- 按得分率从低到高排列
- 每个模块一段文字分析：涉及题号、考点、问题模式总结
- 给出模块级攻建议
5.3 反思深度分析
如有学生反思：
- 分析学生自我认知中的偏差（常见偏差示例在 references/report_template.md 中）
- 总结积极发现（学生的优点和亮点）
如无学生反思：
- 根据答题数据推测学习习惯和方法问题
- 改为"学习习惯与方法分析"章节
5.4 提分路径规划
三阶段规划，每阶段包含：标题、目标、具体行动项（4-5条）。
阶段模板：
- 第一阶段（急救期，1-2周）：解决"会但没做对"和"没时间做"的问题
- 第二阶段（补强期，2-4周）：攻克薄弱模块
- 第三阶段（巩固期，4-6周）：稳定输出、减少波动
提分目标要合理：根据学生当前水平和潜力设定。
5.5 个人留言
撰写给学生的个人留言，要求：
- 温暖亲切、老师范儿（使用"你"形成对话感）
- 先肯定优点和努力（必须提及具体亮点，不能泛泛夸奖）
- 指出核心问题（以鼓励方式，不说教）
- 给出简单可行的第一步行动建议
- 以鼓励性语句结尾
第六步：生成报告 DOCX
将AI分析结果组织为JSON，运行报告生成脚本：
python scripts/build_personalized_report.py <报告数据.json> --output <学生姓名_综合分析报告.docx>
JSON数据结构详见 scripts/build_personalized_report.py 末尾的 DATA_SCHEMA 注释。
脚本会按模板格式生成包含所有六段的DOCX文件，格式特点：
- 标题居中
- 表格蓝色表头（#4472C4）
- 题目标题红色加粗（#C00000）
- 建议项为列表格式
- 状态标记（✗/△/✓）
第七步：交付报告
将生成的DOCX报告保存到用户指定位置（通常是桌面指定文件夹），并行处理时使用 TaskCreate 跟踪进度。
脚本文件说明
scripts/exam_analysis.py
核心数据提取脚本，处理数据读取、答案批改、统计计算。主要模式：
- 普通模式：生成班级汇总报告或基础个人报告（--per-student）
- 提取模式：--extract-only 输出结构化JSON供后续AI分析使用
scripts/build_personalized_report.py
个性化综合报告生成器，接受结构化JSON数据，生成符合模板格式的六段式DOCX报告。
- 支持六段完整报告结构
- 每题独立样式（红色标题、标签加粗、列表建议）
- 自动处理表格格式（蓝底白字表头、居中）
scripts/generate_enhanced_reports.py
增强版深度分析个人报告生成器，整合深度题目分析数据库（deep_analysis.py），为每位学生生成包含以下内容的详尽报告：
- 知识模块全景诊断（个人vs班级对比、五级掌握等级）
- 逐题深度分析（解题思路 + 错因诊断 + 学习建议 + 反思引导问题）
- 错题分类总结（按错误类型归类：概念混淆/公式误用/推理链断裂等8类）
- 三阶段分步提分规划
- 个性化教师留言
用法：python generate_enhanced_reports.py <xlsx> <试卷pdf> <答案pdf> --config config.json --output-dir ./报告/
scripts/deep_analysis.py
深度分析数据库模块，包含每道题的物理概念解析、常见错误选项分析、解题思路详解和学习建议。供其他脚本导入使用。
references/knowledge_map.md
知识点映射配置的完整说明，包含模板和示例。
references/report_template.md
报告模板完整规范，详细描述：
- 六段报告结构
- 每段的内容要求和格式
- 表格样式规范
- 语言风格要求
- 撰写原则和示例
注意事项
- 排除题号：报告中排除的题号（如第12题）不在任何分析中出现
- 第11题：实验题，虽归为主观题但属于"实验"模块
- 多选题分析：要分类讨论漏选/选错/选错且漏选，给出不同建议
- 时间管理：如果学生因时间不够失分，第一阶段必须包含时间管理训练
- 反思利用：每道错题必须引用学生反思原文（如有），不能凭空猜测
- 根因不归因粗心：始终追问"如果概念足够清晰，还会错吗？"
- 建议具体化：所有建议必须有具体数量、步骤或方法
- 语言温暖：全文使用"你"，形成对话感；鼓励性语气
- 所有Python文件使用UTF-8编码，保存前确保中文内容正常
- 生成时报错先检查依赖：
python-docx,openpyxl,PyMuPDF（fitz）
