教学学情诊断互动仪表盘

使命和核心约束

输入真实试卷 + 真实逐题分数，默认交付两份彼此独立的离线单文件HTML：

• 教师教学决策版：全班讲什么、哪些学生分层支持、什么必须查证；保留此前完整教师版功能。
• 学生个人成长版：学生切换、Content和Skill得分表现、优先问题、共享的失分题解题资源、最多三项今日行动。

教师只说“分析一下”“根据附件分析这次考试”“生成学情分析”且未指明视角时，必须同时生成两份HTML，不要默认只生成教师版，也不必额外问选择哪一版；明确“只生成教师版”或“只生成学生版/个人版”时才生成一份。若缺少必要试卷或逐题成绩，说明缺少的信息，不得伪造结果。优先级：数据真实准确 > 证据边界 > 教学行动 > UI精美。

• 允许AI提出知识/能力映射、可能错因和教学方案；所有分数、得分率、分层人数及失分统计必须由脚本确定性计算，不得AI心算或造数。
• 只知道题目得分，不知道实际错误作答时，禁止声称“学生都选了B”“多数学生漏写某步骤”“学生是粗心”“不会表达”。把解释写成假设并提供核验方式。
• 对综合题，仅有整题总分，不得为子题分摊分数；保留整题得分率、人均失分、群体差异，标识候选知识和需要抽卷核查的任务。个人版不能因该题不进入狭义Content/Skill掌握率就遗漏其重大失分。
• 学生分组反映此次相对位置，不作为稳定能力标签；“选择题高、非选择题低”不直接推断表达缺陷。
• 不从本次试卷推断未经提供的学校、年级或考试名称；不引用来源中没有的学生回答、标准答案、图示内容。
• 用户最少只需上传题目和成绩；评分标准/原题图片/学生答卷缺失时，应诚实标注待核，不阻碍可以可靠计算的部分。

0. 必须按需读取的资源

• references/data-contract.md：在构造题目JSON、导入数据以及输出教学建议前，读取字段规范与状态规则。
• references/teaching-diagnosis.md：在设计教师教学结论、分层方案和学生支持前读取；包含过去三版比较中发现的典型反例。
• references/student-learning.md：默认生成双报告或明确生成学生个人版时，必须读取；包含每题共用的学习资源、Content/Skill标签、证据条件、个人任务生成规则。
• references/qa-checklist.md：交付前逐项验证。
• examples/README.md：仅当需要了解运行方式或调试本技能时读取；其数据是虚构演示，不得混入真实用户报告。

使用本技能自带教师版 assets/dashboard.html 和学生版 assets/student_dashboard.html。不要把之前任何一次生物学 HTML 的题号、名单、教学活动硬编码到新报告里。两个模板均离线，无 CDN、远程字体或 API。学生版使用预编译内嵌的 Tailwind v4 CSS，不联网取样式。

统一设计系统（不可省略）：两版必须呈现为同一产品的教师和学生工作台，而不是两套视觉主题。共同采用背景 #f3f6fb、强调蓝 #276cce、主文字 #18324f、白色卡片及浅蓝边框 #e4ebf5；桌面端统一为左侧白底固定导航 + 顶部白底工具栏 + 中间内容区。移动端左侧菜单转为顶部横向可滚动菜单。教师版保留五个菜单，学生版为四个菜单：学习总览、问题诊断、错题突破、今日行动；个人版学生选择器置于顶部工具栏。禁止把学生版换回卡其/墨绿主色、深色通栏 hero、仅顶部横向导航或将四个模块堆成长页面。不得因学科变化而改变两版的整体设计语言，学科差异只调整题目内容。

1. 工作流程（必须执行）

步骤 A：读取并建立试题计分结构

1. 读取教师提供的试卷、评分标准和成绩表。对图片/PDF中的原题图、实验装置、坐标点，实际检查图像；无法还原则标记缺失。若源文件为PDF/DOCX/XLSX，使用当前环境适配的文档解析工具；无法读取时如实说明，不猜测。
2. 建立 questions.json：meta, items，按真实的独立计分单位建行。每个 item 填 id, max, type, response_kind, granularity, mapping_status, score_status, question_text, answer, scoring, topic, ability, topic_candidates, ability_candidates, flags, hypothesis, verify, activity, exit_task, teaching_mode。字段含义见数据契约。
3. 若有小问逐题分数： 按实际小问建行，例如 Q17(1)、Q17(2)；Q17只是父题，不另计分。若只有大题总分： 一条 Q17，标 composite_unresolved，关联候选知识，但不得为不同知识生成精确达成率。
4. 试题和答案有争议时，score_status: pending/disputed，并注明核查点。图形缺失且影响判断时，mapping_status: provisional/unmapped。只有独立计分、题意与归属已核、评分可靠的题目才能参与细分知识/能力得分率统计。
5. 若能够从原始试卷提取原图，优先保留并在数据合并后用 scripts/embed_question_image.py 内嵌真实图片；切勿凭文字描述重绘出一个“看起来像原题”的图。
6. 为每道题尽量选定一个主要 Content（topic）和 Skill（ability）标签，合并同义标签；次要标签仅说明不计分。若主任务确实无法定位，标记“综合任务（待定位）”及 mapping_status: unmapped；特别注意这不代表将整题总分归给一个狭义概念。详见 references/student-learning.md。

步骤 B：程序合并与成绩校验

在本 Skill 根目录执行：

python scripts/prepare_scores.py \
  --questions /path/to/questions.json \
  --scores /path/to/scores.xlsx \
  --out /path/to/dataset.json

• 支持 .xlsx、.csv 和 .json，适配宽表/长表。复杂题号列名用 --column-map /path/to/column-map.json；指定 Excel 工作表可加 --sheet "工作表名"。
• 默认从生成结果移除学生姓名，用学生编号。只有用户明确要求实名版且理解离线文件仍含姓名，才加 --include-names。不要将真实学生成绩示例打入Skill资产。
• 程序生成 dataset.json 和 dataset.audit.json。先读取审计文件；检查原始总分差异、异常分值、丢失列、重复学生与证据覆盖率。
• 数据冲突（如逐题合计≠报表总分）必须先核查，不得静默覆盖。如果确实无法修复，可以说明局限并按实际需要选择仅输出审计报告，不可伪称已完成准确诊断。
• CSV中文编码会自动尝试 UTF-8/GB18030；openpyxl 可用于 .xlsx，没有时请转CSV。

若只有总分而无逐题分，不能生成虚假的知识点分析。可输出真实的总分概况并提示还需要什么资料。

步骤 C：为有失分的题目一次性生成学生学习资源（需要学生版时执行）

读取 references/student-learning.md。在步骤B中读取成绩之后，找出至少一名学生有真实失分的每道题，并在该题目 items[].learning 下仅生成一套全班共享学习资源；不按学生重复生成AI分析。

• 必要资源：一句话core_concept、reasoning_key、50字内core_reminder、2–4条next_steps、variation.question、variation.answer、variation.explanation。选择题、多选题和计算题都要核对变式是否真能得到所给答案。
• 保留 learning.status: ready；原题图/答案/评分依据不足、无法安全生成正确练习时，写 learning.status: pending 以及明确原因，不填假答案。
• 不重复生成相同知识点的机械换皮题；用不同材料/情境真正考查同一核心知识与技能。不要使用教材中未提供的页码。
• AI学习资源不得从分数推断学生实际答错的选项/步骤；页面说明“这是题目级学习指导而非对该生真实作答的推断”。
• 不生成学生版时可以跳过 learning 准备，但默认双报告不能跳过。
• 完成后写回 dataset.json，并保持全卷 items/students 与教师版完全相同。

步骤 D：阅读审计后的真实统计，做教学决策（默认双版/教师版必做）

仅指定学生个人版时，不要求编造教师讲评课方案，可跳过 report 的教师教学决策编写；但前述题目解析、成绩校验与学生共用学习资源仍必须完成。

阅读 dataset.audit.json 的 summary：平均分、分数分布、逐题得分率、人均失分、低于60%人数、扣除当前题得分后重新分组得到的低/中/高三组表现、已确认的知识与能力覆盖。

在 dataset.json 中增补或更新 report（结构见 references/data-contract.md），必须做到：

• 首页四类决策卡：whole全班共同诊断、group分层补救、verify先核查、next下一节课，分别引用真实 item_ids。没有证据时明确写“暂无充分证据”，不凑数量。
• 教学优先级可解释：比较人均失分、受影响人数、不同群体、跨题证据、试题质量和课堂可补救性。说明某高失分题为何被暂缓（如图片/答案待核）。不用不可解释的人工权重或只排最低3题。
• 整题证据 vs 细分达成分开：所有题均呈现整题分数表现；知识点或能力百分比仅来自已确认的计分单元；未细分的综合题列作高价值待核任务，不能在看板上消失。
• 全班、分组、个别的决定真正不同：有显著群体差异时，不让已经掌握的群体再听同一套基础讲解；低分组并不一定是唯一补救对象。
• 小而具体的诊断任务：有争议原题可用不依赖缺失图片的独立短题验证知识，但必须标明“新诊断题，不是原题作答证据”。
• 40分钟或指定分钟的讲评课：lesson.steps 每步都写 minutes、教师问题、学生任务、观察证据、条件式 branches；总时长严格匹配；配分层练习与1–3道出口检测。
• 学生支持：聚焦有限重点对象，尽量给不同失分模式学生分别设计“先核查什么→若A怎样/若B怎样→怎样复测”，不要将“做题少/不努力/会认不会写”断言为事实。
• 题型反差：仅可称“选择题表现较好，某些非选择题得分较低”；未取得真实作答之前，不直接推荐统一的答题模板训练。
• 文案数值不硬编码：rationale 和 action 引用具体题号、结构和任务，不手写可能过期的百分比；页面由统计摘要自动补上关联题得分率和人均失分。

特别参考教学判定样例：references/teaching-diagnosis.md。

步骤 E：按请求模式生成教师版与学生版

默认生成两个HTML（教师未说明“仅某个版本”时）：

python scripts/render_reports.py --input /path/to/dataset.json --outdir /mnt/data

默认输出：

1. /mnt/data/学情诊断_教师教学决策.html
2. /mnt/data/学情诊断_学生个人成长.html

明确仅教师版：

python scripts/render_reports.py --input /path/to/dataset.json --outdir /mnt/data --mode teacher

明确仅学生版：

python scripts/render_reports.py --input /path/to/dataset.json --outdir /mnt/data --mode student

render_reports.py 只是便捷入口，使用同一份 dataset.json 依次运行 render_dashboard.py（教师）与 render_student_dashboard.py（学生），不会生成重复的AI题目分析；脚本均默认数据审计失败时拒绝正式输出。若用户明确指定单个HTML，不要顺手生成另一份。

教师版五个模块（延续已有模板）

1. 教学决策首页：班级指标、全班/分组/待核/讲评卡、成绩分布、知识细分证据覆盖。
2. 试题与知识：筛选、可点击SVG图表、逐题失分、题图/原题/答案抽屉、各组表现、可靠知识/能力统计、未映射综合题线索。
3. 学生支持：及格临界、题型反差、知识点定向、全部学生、个体主要失分与条件式辅导建议。
4. 课堂方案：时间线、教师提问、学生任务、课堂分支、分层练习与出口检测。
5. 核查校订：数据质量告警、教师修正题目标签/评分/假设状态、局部统计更新、导入/导出校订数据。

学生版四个模块（新增模板）

1. 我的学习表现：学生下拉切换、总分/得分率、内容与技能标签得分表现、证据覆盖、事实性的学习画像；标签默认精简但可点击查看全部；另展示未能可靠归属的高失分整题任务，不把它们伪算成知识点掌握率。
2. 主要问题诊断：采用双轨候选，结合已确认Content/Skill标签和高失分但未能细分的整题任务，展示最值得关注的1–3项；默认最多2项综合/待核任务，避免挤掉已确认的具体知识问题。单题标“样本较少”，不推断稳定能力缺陷。
3. Smart Error List：按实际失分价值排序，绝不因为“待核查”就把大失分题统一置后；同时以警示标签区分“先核查”与“可直接练习”。展开每道错题查看共用学习内容、2–4步解题策略、同类变式题；“查看答案”默认隐藏，只有 learning.status=ready 才允许展示。
4. 今日行动 To-Do：最多3个题号明确、可立刻执行的动作；学生切换后分数、图表、问题、错题和任务全部由 JavaScript 确定性更新。

个人版使用在本地编译后内嵌的Tailwind v4 CSS + 与教师版相同的蓝色设计系统；左侧菜单按四页切换，而非长页锚点滚动。顶部学生选择器切换后，当前页面的指标、重点问题、错题、任务同步更新；“今日行动”中的题号链接需先自动切到“错题突破”页面再定位并展开相应题目。完全离线，兼容电脑和手机，无需用户部署。

教师校订闭环：教师版修改题目知识归属、评分状态等字段后，浏览器只能即时重算有确定性依据的知识统计，原AI方案需要导出 JSON 再重生成。下次上传教师校订数据时，优先采用修正后的题目信息，再重做教师版 report 和学生版题目学习资源/相关标签结论；默认仍返回双报告，如明确只需一个则遵从。

步骤 F：运行 QA，再交付文件

读取 references/qa-checklist.md，重点执行回归防护专项：

• 运行 python scripts/smoke_test.py 测试内置虚构例子、默认双报告、单报告模式和离线渲染脚本；必须通过高失分综合题优先级、重点问题不消失、全部标签可展开、学生页面不泄露教师数据的回归断言。
• 学生版只序列化必要的公开字段：不得将教师侧的 report、审计详情、教师对学生的私密备注等内嵌其中（字段白名单由 render_student_dashboard.py 执行）；两份HTML共用同一源成绩与题目，但不是两个完全相同的JSON副本。
• 两份HTML分别进行真实浏览器检查（有自动化条件时用Playwright）：教师版五页/题目抽屉/校订导出；学生版学生切换/标签得分/主要问题/错题展开/变式答案隐藏与显示/今日任务勾选，核对手机端没有横向溢出。
• 检查单文件、零外部依赖和隐藏的个人数据；不能只看代码中写了“offline”。
• 有截图条件时检查1440×900和较窄屏幕的视觉效果；尽量使教师在首屏看到四个关键教学结论，不制造超长首页。
• 禁止硬编码示例中的Q3/Q4、S01等到真实报告。注意脚本输出中的审核提示，不应遮蔽严重问题。

2. 必须交付给教师什么

• 默认两个可双击打开的HTML，提供两个独立下载链接，文件名区分“教师教学决策”“学生个人成长”；不要生成一个网页内的混合双视角Tab来代替两份HTML。
• 若教师明确只要某一个版本，只交付那个版本的单HTML。
• 默认可以附带一份包含两个HTML的ZIP作为方便转发的可选包，但不能替代分别提供HTML。
• 用1–2句话说明最重要的教学发现及仍需核实的证据边界（若有）。
• 数据审计 JSON 可根据需要附上，便于复核；默认不交付含姓名的原始成绩。
• 不要未经用户请求额外上传至云端或共享学生资料。

3. 可选命令与运行示例

# 仅将从原始试卷实际提取的 PNG/JPG/WebP 题图内嵌进题目：
python scripts/embed_question_image.py \
  --dataset /path/to/dataset.json \
  --item Q12 --image /path/to/original_q12.png \
  --caption "原试卷第12题温度曲线"

# 用自带虚构例子检查运行环境：
python scripts/smoke_test.py

若源文件包含真实学生姓名、答卷图片或学号等信息，不要复制到示例目录、测试资产或Skill包里。学生个人HTML虽然可切换全班学生，但全部分数均内嵌在HTML中；默认匿名，交付需提示不要当公开网页传播。