学业质量 · 校内学情分析与三受众反馈引擎

把教师课堂记录、历次测验成绩与全班作答数据，转换成可校验、可追踪、且分别面向任课教师、学生本人、家长的反馈，并独立输出全班总体质量分析。

不可违反的规则

1. JSON 是唯一事实源：先补全并校验 session JSON，再生成 SVG/HTML；禁止手改 HTML。
2. 知识点 ID 只在 JSON 内部流转：四份报告、对话摘要均只显示知识点名称。
3. E01–E10 是封闭问题词表：错题和「答案正确但思路有瑕疵」的题都按 references/error-causes.md 归因。
4. 证据先于结论：逐题分析写原答案/过程与暴露的问题；学习表现只写可观察行为。
5. 无观测不打星：行为维度未观察到时 observed=false、score=null，显示「暂未观测」，禁止用三星占位。
6. 根因链必须可证：前置点本身有独立证据才允许 causal_chain；否则标为 independent_gaps 或 insufficient_evidence，禁止强行串链。
7. 雷达标注得分来源：每维必须声明 measured、observed 或 conservative；评分依据不写「样本不足/数据不足/保守估计」等说明句。
8. 外部输出不渲染数据说明：data_quality 只保存在 JSON，不出现在 HTML 或对话结果。
9. 班级统计必须由脚本算：class_overview 的均分、分布、及格率、共性错题、分层人数一律由 scripts/analyze_class.py 从原始成绩表计算；禁止目测估计、禁止编造人数或分数。无原始成绩表时该章节写「待录入成绩表」，不生成数字。
10. 成绩折线只画真实记录：折线数据只来自 score_history；少于 2 个成绩点时只显示「记录中」，不写上升/下降/波动结论。无观测填充值不得称为「进步/退步」。
11. 三受众信息边界（详见 references/audience-writing.md）：
    • 教师版可含 E/P 代码、根因链、置信度、全班统计、分层代号与完整教学预案。
    • 学生版与家长版一律不显示 E/P 代码、知识点 ID、根因诊断类型、置信度、教师内部预案、班级排名与其他学生对比。
    • 任何版本都不得出现人格化标签、「别人家孩子」或公开点名。
12. 学校语境：一律使用学校、班级、任课教师、班主任、单元测/月考、课时、教研组等校内表述；不出现「家教」「一对一/小班」「大学生家教」「补课」等校外辅导措辞。

资源路由

工作流

S0 收集原始记录

保留教师原话与成绩表原始数据。按输入类型分流：

# 三段以上自然语言课堂记录 → 逐题草稿
python scripts/parse_session_input.py 课堂记录.txt --kp assets/kp-glossary-sample.json -o draft.json

# 全班成绩表（+ 可选逐题对错表）→ 班级统计，不编造数据
python scripts/analyze_class.py --scores assets/class-scores-sample.csv \
  --items assets/class-items-sample.csv --exam 第三单元测验 -o class_overview.json

读取 questions_to_ask，一次最多追问 3 个可事实回答的问题。答不上来就记为未观测或不可判定，不猜。

S1 建立结构化 JSON

按 references/session-schema.md 补全 v3.0 数据。逐题使用四态：

• correct：答案与思路均可靠。
• incorrect：答案错误。
• correct_with_issue：答案正确，但思路、步骤、表达或猜测存在问题。
• unverifiable：没有卷面/口述过程，无法判断。

meta 必须写明学校、班级、年级、任课教师、学科、学期、课时与主题。同时填写课堂达成摘要、优势亮点、作业清单、学生自主行动、家长配合建议和三受众摘要。

S2 逐题归因与雷达

对 incorrect 和 correct_with_issue 填 issue_tag、evidence、micro_remedy。雷达每维填写：

• source=measured：来自题目/任务实测。
• source=observed：来自课堂行为观察推断。
• source=conservative：本次无直接观测，按中位锚点填充。

S3 根因判定

先判断类型再写链：

• causal_chain：前置知识点有独立错证，且能解释后续问题。
• independent_gaps：问题并列出现，没有可验证的因果依赖。
• insufficient_evidence：痕迹不足，暂不定位病根。
• no_error：可判定题全部正确且无明显思路瑕疵。

必须写 confidence_basis。只有 causal_chain 才允许非空 chain 和 prerequisite_verified=true。

S4 行为评价与下阶段教学计划

行为评价遵守「无观测不打星」。下阶段计划每个环节写基础目标、进阶目标、未过关预案；过关检验必须有简短变式题题干。计划总时长不得超过课时，复习补漏与前置铺垫合计不得超过课时 25%。

S5 成绩折线与分数分布

按 references/score-trend.md 整理 score_history（日期、考试标签、得分、满分、班级均分），生成：

python scripts/render_trend.py session.json --class-overview class_overview.json -o trend.svg
python scripts/render_radar.py session.json --baseline session-1.json --compare session-5.json -o radar.svg

trend.svg 含个人成绩折线、班级均分参考线与分数分布柱状图；点数不足或缺少分布数据时相应子图显示「记录中/待录入」。

S6 校验与四模式渲染

python scripts/validate_session.py session.json
python scripts/build_report.py session.json --mode all \
  --class-overview class_overview.json -o report.html

--mode all 一次生成四份：

• report-teacher.html 教师教研版：逐题问题代码、P0/P1/P2、根因置信度、图例、完整下阶段预案、成绩折线与全班总体情况（分布、共性错题、分层代号、教学调整）。
• report-student.html 学生版：第二人称，只讲「我做对了什么、哪里还能更好、接下来三件事」，附个人成绩折线，不含任何内部标签与他人对比。
• report-parent.html 家长精简版：课堂达成、优势、雷达来源、观察到的学习表现、作业与家庭配合动作，附个人成绩折线；隐藏 E/P 标签、根因内部字段、知识点 ID 和数据说明。
• report-class.html 班级质量分析版：纯全班视角，供教研组/年级组使用；不出现任何学生个人诊断与姓名。

也可用 --mode teacher|student|parent|class 只生成一份。三受众措辞与信息边界见 references/audience-writing.md。

边界分支

输出纪律

• 任何可见结果不显示 kp_id。
• 雷达 basis 不写「样本不足、数据不足、题量不足、支撑不足、保守估计」。
• 不生成「数据说明」段落，不复述 data_quality。
• 学生版、家长版不显示 E 代码、P 级别、根因诊断类型、置信度、班级排名与他人对比。
• 教师版必须附 P0/P1/P2 与 E01–E10 图例，并保留全班统计的来源说明。
• 家长摘要不超过 250 字，先写真实优势，再写一个主要关注点和一个当天可执行动作。
• 学生版导语不超过 200 字，用「你」称呼，先写真实做到的，再写三件按顺序可做的事。
• 班级质量分析版只出现统计与代号，不出现学生姓名、学号或个人诊断结论。

脚本

六个脚本只依赖 Python 标准库。

打包上传前确认包内只有两级结构（根目录/二级目录/文件）：scripts/__pycache__/ 是 Python 运行时自动生成的字节码缓存，属三级目录，上传前删除；也可在运行前设 PYTHONDONTWRITEBYTECODE=1 避免生成。