小学作业批改与错因诊断

用途

把一份作业照片变成三样东西：逐题批改（建立信任）→ 根因诊断（核心价值）→ 今晚一个动作（可执行）。

批改不是诊断的对立面，而是诊断的入场券。诊断的支点是卷面即行为化石——涂改密度、空白分布、字迹衰减、划改样式，在通用 OCR 里是噪声，在这里是主信号。

产物红线（硬约束，优先于任何默认习惯）

本技能的产物只有四种，且全部由 scripts/ 下的脚本生成：

禁止事项（违反即等于用错了技能）：

• ❌ 禁止生成 .docx / .doc / .pdf 报告，禁止 import python-docx，禁止写"生成 Word 报告"这类话术
• ❌ 禁止推荐讲解视频、教辅链接、网课资源——本技能不做资源推荐
• ❌ 禁止只用 Markdown 表格交付批改结果而不出 HTML 日报——没有标注图和 HTML 文件，就等于本次没做完
• ❌ 禁止脱离脚本手写报告模板

自查：如果发现自己正在写 作业诊断_年级学科_日期.docx 这种文件名，或正在组织"Word 诊断报告"的段落，说明加载的不是本技能——立即停止，改用上面的脚本。

何时使用

• 用户发来小学作业照片（语文 / 数学 / 英语）
• 要求批改、检查作业、看错题
• 要求生成作业日报、错因分析、复习卷
• 询问孩子拖拉、粗心、磨蹭等问题并需定位类型

不适用：用户要"生成 Word/PDF 诊断报告"时——本技能不产出办公文档（见上方产物红线）。同名相近的作业诊断类技能以 Word 报告为产物，与本技能是两套不同实现，不要混用其脚本或文件名规范。

工作流

第 0 步：图片预检（收到照片先跑，30 秒省一次返工）

python scripts/check_image.py 照片1.jpg 照片2.png

坏图、过小、失焦、空白、EXIF 方向反了，在这里拦住并给家长一句可执行建议（"放稳停 1 秒再拍"）。退出码 1 = 有图不可用，不要硬判——用糊图判读是误判的主要来源。判据写死在脚本头注释里，阈值已用真实照片标定。

第 1 步：准备（能识别就不问）

• 先识别，后提问：从照片提取线索——页眉年级/学校、单元标题、题目内容与难度、教材角标——推断年级 + 学期（上/下），并在回复里声明结论请家长纠错（"按照片判断是四年级上册，如有误告诉我"）。识别不出的字段才问，禁止先问后干
• 按场景问最小集：
• 批改 / 日报 → 只需年级 + 学期，够了就开批
• 教材版本只在"按单元定位知识点、组复习卷"时才需要——判对错不依赖版本，禁止在批改场景问版本
• 档案存在时（错题档案/ 有内容）→ 读 笔迹识别备忘.md（混淆先验）和 归档索引.json（学期/教材/已有错题），跳过一切提问
• 云端模式（工作目录 /workspace）→ 沙箱临时，档案缺失是常态，不是"首次使用"：只问一句"有上次导出的档案吗（在资料库）"，没有就直接用照片识别开批，用 preflight.py --init 静默建档；本轮产物结束前必须落库，协议见 references/storage-and-mobile.md

第 2 步：判读（三级）

1. 整页读，标可疑处
2. 可疑处放大 2 倍复判——能自己纠正的必须自己纠正
3. 数学自校验：读出值与正确值位数相同、仅差个别位 → 先假定自己读错

详见 references/recognition-memory.md。禁止不放大就下结论，禁止把能自己解决的甩给家长。

第 3 步：批改与归类

• 逐空判定：对 / 错 / 待核对
• 错题归入六类根因（拖延、粗心、不会做也不说、完美主义、糊弄、同错反复）——依据是"卡在哪个时间点"，不是错误长相
• 本次无行为问题必须明确输出"本次未触发"——每份都能找出"病"的诊断系统两周就会被弃用

详见 references/causes-six-types.md。

第 4 步：出证据图（红笔标注）

坐标一律用原图像素，不要目测百分比。实测教训：网格只有 10% 一格，在缩略图上估百分比有 1.5–2% 系统偏差，靠多轮微调校正要烧掉十几次视觉读图；视觉模型在 1:1 局部图上直接报像素一次就准。

1. 粗裁：python scripts/crop_evidence.py --src 照片.jpg --px x1,y1,x2,y2，把这块局部图发给视觉模型，让它在局部图上直接报像素
2. 换算：原图坐标 = 局部裁剪起点 + 局部图内坐标（局部 1:1 不缩放时可直接相加）
3. 一次出全部产物：写 marks.json（px 框 = 最终红圈范围，脚本不再外扩）→ python scripts/mark_all.py marks.json → 同时得到每题证据图、整页标注图、3 张验收小图
4. 只看验收小图验收（宽 900px，读图便宜），不要反复看整页大图

标注语义：circle 红圈（指认错）/ dashed 橙虚线（待核对）/ check 红勾 / underline / text。

裁剪与画圈三条硬规则（细则见 references/evidence-standard.md）：

1. 裁剪以"题"为单位：题号 → 题干 → 孩子作答 → 判分痕迹，横向通栏。永远禁止只截错误答案的孤图（如只截 ( A ) 两个字符）——家长看不出是哪题，贴进日报毫无意义。题目超长时用两段式：整题图（可缩小）+ 特写图（错处所在完整句子，1:1）
2. 红圈 = 指认，不是确认：错误点唯一且一眼可见（整题图里就一个错处）→ 不圈，需要说明改法就用红字批注锚在错处（→ C、少 of）；错误点隐蔽（漏做空白、小涂改）或 ≥2 处 → 每处都圈；特写图上永不圈（圈画在整题图上定位）
3. 出图前三问，缺一重截：这是第几题？孩子写了什么？错在哪（或批注锚点在哪）？

每道错题必须配自己的图，不允许跨块复用。

显示等比（治"小图字体放大失真"）：mark_all.py / crop_evidence.py 裁图时自动把每张图的
crop_w / src_w（裁剪宽 ÷ 原照片全宽）写进同目录 scale.json；日报与汇总渲染时按这个比例显示——
截图占原卷多少，就显示多大，大图小图字体缩放倍率一致。找不到记录的旧图兜底：只缩小、不放大。
日报下限 18%、汇总缩略图下限 40%（data.json 的 img_min_pct / --img-min-pct 可调），防止小到看不清。

第 5 步：生成日报

写 data.json（结构见 references/archive-schema.md）→ python scripts/build_daily.py data.json。

输出 A4 打印 + 手机自适应的单文件 HTML，图片 base64 内嵌。日报只放家长要动手或动嘴的事：错了哪道 / 原题截图 / 为什么错 / 怎么说 / 待核对的（精确到位置）。其余沉档案。

同类复发（N≥2）用固定句式："这已经是第 N 次「模式名」：上次（日期）一句话 + 同一个练法"。模式名必须用 references/behavior-patterns.md 代码表里的固定名称（P1 算对但输出丢失 / P2 审题偏移 / …），禁止自造；N=1 不提，禁止"又是/总是"。扩展检查（如"AC 键不懂→检查其他键"）必须过该文件的三条门槛。

第 6 步：写档案

更新 错题档案-{学科}.json（新错题、dailyStats、pendingVerify）、归档索引.json、笔迹识别备忘.md（新增误判模式）。状态机 open → reviewing → closed，closeRule 写清"做什么算过关"。

写任何已存在的 JSON 前必须先 Read 再改——直接 Write 会把家长的历史档案整个覆盖掉，这条不可协商。

第 7 步：交付

• 展示日报文件
• 自然语言说三件事：本次判定结果、今晚唯一动作、需家长核对的项
• 询问家长裁决（⚠ 项），24 小时内回写档案

五条铁律

1. 批改必须准，且必须能自我纠错——错一道，家长就不信后面的诊断
2. 日报极简——只留"错了什么、为什么、怎么说"，没问题的项目一律不显示
3. 鉴别诊断要说出口——"这次不像粗心，因为两道错在同一步"。专业感来自排除法
4. 主动承认边界——看不清就说看不清，并写清"核对什么、两种结果分别意味着什么"
5. 处方只给一件事——一条、今晚、几分钟

脚本

依赖：Python 3 + Pillow（可选，缺了自动降级但体验下降）。已实测：Pillow 12.1.0 与 13.0.0 全流程通过（本地 13.0.0 / 云端沙箱 12.1.0）。

环境与存储

云端模式落库是默认动作，不需要家长发起或确认：任务结束自动执行三件事——日报 HTML + 错题档案 JSON + 笔迹识别备忘 MD 导出到资料库，命名带时分防重复条目；完成后在回复末尾报一行落库清单（条目名）。仅当上传失败时才请家长手动兜底（手机相册 + 截图）。上传链路（列空间 → 凭证 → PUT → 登记 → 回读校验）与扩展名选择，见 references/storage-and-mobile.md 第八、九节——照做，不要现编。

移动端只有"云端工作"模式的家长：技能需从市场安装，照片从相册选。详见同一份 reference。

参考文档

学期汇总与复习卷

# 学期汇总（给家长回看）：带原题截图、错因分布、复发模式
# 时间范围三种给法：全学期 / --since+--until / --days 30（最近 30 天）
python scripts/build_summary.py --root . --term 2026-2027_四年级上
python scripts/build_summary.py --root . --since 2026-10-01 --until 2026-10-31
python scripts/build_summary.py --root . --days 30 --subject 数学

# 复习卷（给孩子做）：筛 status != closed 的错题，按知识点分组（只用原题），也支持日期筛选
python scripts/build_review.py --auto --root . --term 2026-2027_四年级上 --subject 数学
python scripts/build_review.py --auto --root . --since 2026-11-01

# 想要变式题（30% 原题 / 40% 变式 / 20% 薄弱 / 10% 提升）：
# AI 读档案后按 plan.json 结构写卷（脚本 docstring 有完整示例），变式题 kind 标"变式"
python scripts/build_review.py plan.json

• 分工别搞反：汇总 = 带截图给家长看（build_summary）；复习卷 = 只出题给孩子做（build_review）。家长问"这段时间错了哪些"→ 汇总；"考前练一练"→ 复习卷
• 汇总里每题必须有图：evidenceImage 指向的图自动嵌入，同名 _marked.png 存在时优先用标注版；缺图会印占位并在终端告警，看到告警要补图，不能装没看见
• 复习卷自动分两页：题卷 + 答案与错因提醒页（家长用），A4 打印
• 掌握图谱：按 knowledgePoint 聚合 errors 与 dailyStats，source 为"另购练习册"的单列
• 组卷节奏：考前三天第一份，考前一天第二份（只含仍未通过的）
• 档案里 question 字段只写题干，不要把孩子的答案写进去——原题重做时孩子会看到