志远试卷精批（试卷批改与学情分析）

把学生手写试卷照片 → 独立重批（忽略卷面红笔批注）→ 结构化批改报告（错因归因 + 类似练习题）→ 直接导出 PDF 汇报文件 → 可选录入统计看板。

交付物（一次批改必须产出这三样）

导出格式选项（报告成品只有这三种形态，默认 PDF）：

用户没提格式时，只交 PDF，不要反问要不要 Word/HTML。

1. 批改报告 PDF（默认交付、最终形态）：批改报告_<试卷名>.pdf，存工作区根目录。
   做法：先按 @templates/report-template.html 生成 HTML（临时文件），再用本机 Chrome 无头模式打印成 PDF，命令见「4. 写批改报告并导出 PDF」。对话里不把 HTML 当成果交付，PDF 才是成品。
2. 三段总结（写在对话回复里，用户最关心，不可省略）：
   - ① 知识定位：这份卷子是哪个年级、哪个知识板块/课程阶段，考查主线是什么
   - ② 错题归因：每道错题属于哪个章节/知识点不熟练、错在哪里、正确解法是什么
   - ③ 类似练习题：按每个错误知识点出 2–4 道同型题（附答案与依据），并给词汇/公式等需背诵清单
3. 可编辑 Word 版本（仅当用户明确要求「保存 Word / 要能改 / 存桌面」时）：走 tencent-docx 的 S3 转换链路。

交付时必须调用 present_files 打开 PDF；用户另外要了 Word 就再调用一次。

标准流程

1. 读卷

• 用 Read 逐张读取照片；多张照片通常为同一份卷子的连续页，按顺序对应题号。
• 顺手判读：科目、试卷名称、满分、页数、是否有老师红笔批注。
• 若照片缺失（如作文页没拍），在报告中明确标注缺页，不猜内容。

2. 关键区域裁剪放大核对（精度模式）

何时必须做：字迹潦草、涂改多、批量多份、用户强调"仔细批"，或某个答案直接影响判分。
何时可跳过：字迹工整清晰的单份卷子 → 走快速模式，一次读图直批。

• 用托管 venv 的 Pillow 裁剪 + 放大（LANCZOS，2~2.6 倍）后重新 Read：
  /Users/wangfujun/.workbuddy/binaries/python/envs/default/bin/python
• 若该 venv 缺 Pillow，先装：/Users/wangfujun/.workbuddy/binaries/python/envs/default/bin/pip install pillow
• E1：Pillow / pip 都不可用时，macOS 用系统自带 sips 兜底：
  sips -c <高> <宽> --cropOffset <top> <left> in.jpg --out out.jpg && sips -z <H> <W> out.jpg
• 其他环境无 sips 时，改为整体放大读取，不强行裁剪。
• 临时脚本与裁剪图放工作区隐藏临时目录（如 .grading_tmp/），用完即删。
• 必核对区域：选择题答案括号、填空/首字母填空答案行、完形与阅读的答案区、任务型转换、情景对话选项、作文答题区。
• 区分笔迹：学生笔迹（黑/蓝）是判分依据；老师红笔批注（✓✗、圈划、分数）默认全部忽略，独立重批。
• 高频歧义点清单：
• 括号字母有改写痕迹（先写 A 后改 C）→ 放大看最后一笔
• 单词拼写漏字母（secretary / secretay）
• 连笔混淆（slowly / without、behind / beside）
• 数字与字母混淆（1 / l、0 / O）
• 有歧义且影响判分时：在报告与回复中写明「请老师核对 + 疑点在哪」，不擅自定论。

3. 独立重批

• 忽略卷面红笔批注、红笔总分、老师的圈划，从零判分。
• 计分口径见 references/report-structure.md（板块分、漏字母、未作答、作文的判定规则）。
• 语音题等依赖印刷细节（划线字母、下划线位置）的题目：照片看不清印刷细节时，按发音规则判定，同时注明依据与存疑点。

4. 写批改报告并导出 PDF（默认交付）

• 版式用 @templates/report-template.html（浅色、表格化、打印友好）；七段结构固定，缺项可省略但顺序不变。
• 每段的具体写法、话术模板、"先判断 X → 再选 Y"解题套路句式 → 读 @references/report-structure.md。
• 错因归因分类、类似练习题命制规则、各学科常见陷阱 → 读 @references/error-taxonomy.md。
• 先写 HTML 临时文件（放 .grading_tmp/批改报告_<试卷名>.html），再用本机 Chromium 内核浏览器无头模式打印成 PDF（已实测可用，无需额外安装依赖）。

第一步：按顺序探测浏览器，取第一个存在的（覆盖 macOS / Windows / Linux；Edge 与 Chrome 同为 Chromium 内核，参数完全一致）：

BROWSER=""
for c in \
  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" \
  "/Applications/Chromium.app/Contents/MacOS/Chromium" \
  "/c/Program Files/Google/Chrome/Application/chrome.exe" \
  "/c/Program Files (x86)/Google/Chrome/Application/chrome.exe" \
  "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" \
  "$LOCALAPPDATA/Google/Chrome/Application/chrome.exe" \
  "$LOCALAPPDATA/Microsoft/Edge/Application/msedge.exe" \
  "$PROGRAMFILES/Google/Chrome/Application/chrome.exe" \
  "$PROGRAMFILES(X86)/Microsoft/Edge/Application/msedge.exe" \
  "/usr/bin/google-chrome" "/usr/bin/chromium" "/usr/bin/chromium-browser" ; do
  [ -x "$c" ] && BROWSER="$c" && break
done
echo "BROWSER=$BROWSER"

Windows 上也可直接用 where chrome / where msedge 定位，把结果赋给 BROWSER。

第二步：打印 PDF（$BROWSER 非空才执行）：

"$BROWSER" --headless --disable-gpu --no-sandbox --disable-dev-shm-usage \
  --no-pdf-header-footer --print-to-pdf="批改报告_<试卷名>.pdf" "file://<HTML 绝对路径>"

• --headless 与 --headless=old 二选一：新版 Chrome 已移除 old 取值，报错就换另一个，不要反复重试同一个值。
• 360 / QQ / 搜狗等国产浏览器虽是 Chromium 内核，但不保证支持 --print-to-pdf，不纳入探测链。

• 探测结果为空（整台机器没有任何 Chromium）→ 直接走 HTML 兜底，不要空转。

• PDF 存工作区根目录，命名 批改报告_<试卷名>.pdf；确认文件已生成且非 0 字节后，present_files 打开预览。

• 版式提示：模板自带打印样式；表格跨页处表头可能断开，接受当前版式，不做额外分页调优。
• 临时 HTML 与 .grading_tmp/ 用完即删，只留 PDF。
• 兜底：探测不到任何 Chromium 内核浏览器、或打印失败时，交付 HTML 并说明原因（一句话：本机缺少 Chromium 内核浏览器，已改为 HTML 版），同时在回复里给出完整三段总结，不让用户空手。

5. 可选：导出 Word（仅用户要求时）

• 走 tencent-docx skill 的 S3 转换链路（html-to-docx 托管 venv），输出路径按用户指定，默认 ~/Desktop/试卷分析.docx。
• 转换成功后立即 present_files 打开预览。
• 注意：Word 是追加选项，PDF 仍是默认交付物。

6. 录入统计看板（可选，用户要求或说要累计错题时）

「志远教育·批改统计看板」https://grading-stats.app.workbuddy.host/ 收录每次批改的成绩与薄弱知识点。批改完给用户一行可直接按表单填写的字段：

学生姓名 / 班级 / 科目 / 试卷名称 / 日期 / 总分 / 得分 / 错题知识点（中文逗号分隔）/ 备注

• 错题知识点直接采用报告第四段的"薄弱知识点"原文，保证与看板的薄弱点排行口径一致。
• 作文未作答这类整体性问题也作为知识点标签写入（如「作文未作答」），便于看板统计。
• 若用户已在用看板，提醒：新增记录后图表自动重算，无需人工统计。

6.5 对接学情报告系统（结构化 JSON，可选）

当用户说「生成报告数据 / 对接学情报告系统 / 输出给家长端报告用 / 给 zhiyuan-report / 要结构化数据」时，除 PDF 外，在回复末尾额外输出一个 ```json 代码块，供系统直接消费。字段如下：

覆盖学段与学科（重要）：本技能面向 K12 全学段全学科——小学 / 初中 / 高中，语文、数学、英语、物理、化学、生物、地理、历史、政治、科学、信息技术等任意科目，不限于系统内置的 6 个科目。判定口径：
- subject 写卷面真实科目名（如「地理」「高一物理」「小学英语」）；系统按 subject 动态展示题型与知识点环形，不受预置科目限制。
- grade_level 写对应公立学校年级（如 二年级 / 七年级 / 高一），原样写入学生档案。
- sections / points 的名称直接取自卷面真实板块与知识点（听力 / 单选 / 完形 / 实验探究 / 材料分析…），系统原样展示，不强行套用「选择题/填空题/应用题」三档。
- 系统对未内置的科目会用中性骨架（选择题 / 填空题 / 解答题 + 核心概念 / 重点题型 / 综合应用）兜底空态，待粘贴本 JSON 后自动替换为真实数据。

数据流向（与系统对齐）：本 JSON 是「试卷」数据源 → 班主任在系统导入（或粘贴）→ 系统自动算六维雷达与得分结构、起草诊断五块 → 班主任提交校长审核 → 校长同意发布后家长端才可见。课堂表现 / 作业 / 学习态度 / 综合素养 / 面谈评估由任课老师、班主任、面谈官在系统里人工填，不在试卷 JSON 内。

硬性约束：

1. 不编造字段。课堂表现、作业完成、学习态度、综合素养、面谈评估这 5 项不在试卷批改范围内，一律填 null，由任课老师 / 班主任 / 面谈官在系统里人工填。
2. points[].v 掌握度：优先用「该知识点总题数 − 错题数」÷ 总题数 × 100；若只能识别错题、没有该知识点总题数，按错题数估算（错 1 题→70，错 2 题→55，错 ≥3 题→40），并在 summary 注明「掌握度为估算」。
3. sections 必须用卷面真实板块名（听力 / 单选 / 填空 / 完形 / 阅读 / 作文…），不要为了凑三档改成「选择题/填空题/应用题」；系统会按学科动态展示。
4. JSON 必须能被 JSON.parse 直接解析：不放注释、不留占位符、不用中文引号。
5. null 就是 null，不要用 ""、0 或「暂无」冒充。

示例：

{
  "student_name": "李明",
  "subject": "数学",
  "exam_title": "三年级上入学测评",
  "exam_date": "2026-10-18",
  "total_score": 100,
  "score": 86,
  "score_rate": 86,
  "textbook": "人教版三年级上",
  "grade_level": "三年级",
  "main_points": ["分数应用题", "图形几何", "统计图表"],
  "sections": [
    {"name": "选择题", "score": 18, "full": 20, "rate": 90, "weak": false},
    {"name": "填空题", "score": 24, "full": 30, "rate": 80, "weak": false},
    {"name": "应用题", "score": 22, "full": 30, "rate": 73, "weak": true}
  ],
  "difficulty_split": null,
  "points": [
    {"l": "数与代数", "v": 90, "weak": false},
    {"l": "图形几何", "v": 55, "weak": true},
    {"l": "应用题审题", "v": 60, "weak": true}
  ],
  "weak_points": ["图形几何", "应用题审题"],
  "summary": "本卷得分率 86%，基础计算扎实；失分集中在图形几何与应用题审题，属可短期突破板块。",
  "bullets": ["几何辅助线先讲模型再刷题", "应用题训练圈关键词再列式", "每周 2 次限时小测验收"]
}

6.6 诊断与规划起草（五大人工必写板块，可选）

学情诊断协同系统（zhiyuan-report）的报告经校长同意发布前，班主任必须填齐五项人工必写诊断（系统锁定必填，专家可起草但不代写、不锁定）。当用户说「起草诊断 / 帮我写优势待提升 / 生成诊断五块 / 阶段安排 / 家庭配合」时，在回复里额外输出如下 diagnosis JSON（可独立给出，也可与 6.5 的 paper JSON 合并到一个代码块）：

起草必须代入 subject 与 grade_level：学科决定家庭配合建议与板块话术（如小学重习惯养成、高中重专题突破），年级决定语言深度；不要套用示例里的「数学」口吻，要覆盖 K12 任意科目。

示例（与 6.5 同一学生）：

{
  "diagnosis": {
    "advantages": "本次数学测评得分率 86%，基础计算扎实；选择题表现最好（90%）。",
    "improvement": "失分集中在图形几何与应用题审题，其中图形几何掌握度仅 55%。",
    "conclusion": "数学基础较扎实，图形几何是下一步最值得突破的点，属稳步上升型。",
    "stage": "未来 4 周：第 1 周专攻图形几何；第 2 周应用题审题；第 3 周限时套卷；第 4 周验收。每周 2 次专项，每次 30 分钟。",
    "family": "每天 15 分钟口算 + 1 道应用题讲思路；周末用数学解决一个生活问题，让孩子当小老师。"
  }
}

硬性约束：

1. 这 5 块是人工必写锁，专家只起草、班主任定稿，输出时明确标注「需班主任核对后发布」。
2. 不编造：缺卷面明细时不写具体薄弱点，提示「请先粘贴试卷分析或精批 JSON」。
3. JSON 必须可被 JSON.parse 直接解析（无注释、无占位符、无中文引号）。
4. 与 6.5 的 paper 字段同源：薄弱点用报告第四段原文，保证口径一致。

7. 使用后复盘（自我修正，本机自动优化）

每次批改收尾时，执行一次轻量复盘，不额外增加用户操作：

1. 自问三件事：本次有没有出现「本技能没写到」的情况？有没有判分被用户纠正？有没有步骤冗余或卡顿（如读图失败、裁剪无效）？
2. 若有，在回复末尾加一段 🔧 技能改进建议（0–3 条），每条写清：现象 → 建议改成什么。无则省略该段，不写"无问题"凑数。
3. 用户表示采纳（"改吧/采纳/更新技能"）时，当场用 Edit 修改本技能文件，并按语义化版本号递增：
   - 补坑、改错字、补触发词 → 次版本 +1（1.1.0 → 1.2.0）
   - 流程/结构级调整 → 主版本 +1（1.x → 2.0.0）
4. 修改后必须重新打包校验（skill-creator 的 package_skill.py），保证技能包同步最新。
5. 隐私红线：改进建议里不得出现学生姓名、成绩、照片内容等个人信息，只描述流程与规则问题。

> 说明：这一步只优化本机这份技能。已发布到市场、别人安装的副本不会自动更新，需要发新版本后由使用者在【我的技能】里点更新。

批量模式（一整个班多份卷子）

1. 每份卷子独立走 1–6 步，报告按学生分文件命名：批改报告_<姓名>_<试卷名>.pdf。
2. 全部批完后额外出一张班级错题分布表（同版式，同样导出 PDF）：行=知识点，列=班级/学生，格=错误人次；末尾给"班级共性薄弱点 TOP3 + 讲评课建议"。
3. 回复里先给班级汇总，再给个体差异（谁需要单独辅导）。

输出风格（志远教育场景偏好）

• 表格化、信息密度高：能在表里说清的不用段落。
• 套路句式：讲解用"先判断什么 → 再选什么"，便于老师原样转述给学生。
• 可落地：讲评建议按优先级排，先解决分值最大/最紧急的问题。
• 合规：不承诺提分、不制造焦虑，只陈述本次卷面事实与可执行的改进动作。
• NCE 新概念体系：知识点按课文 Lesson 标注，并换算成公立学校年级水平。
• 未作答的整题（尤其作文）必须单独高亮，并给出"补交/补练"建议。

依赖与权限（上架审核要点）

• 读取：用户上传/指定的试卷照片；写入：工作区报告文件（PDF）、临时 HTML、用户指定的 Word 输出路径。
• 执行：在工作区临时目录里运行 Python 图片裁剪（Pillow，托管 venv）；调用本机 Chrome 无头模式把 HTML 打印成 PDF（本地渲染，无网络请求，无外部 API，无密钥）。
• 可选外部依赖：Word 导出依赖 WorkBuddy 内置技能 tencent-docx（其未安装时，不影响 PDF 交付，PDF 是默认交付物）。
• 数据出去向：仅在用户要求录入统计看板时，给出可填写的字段文本，不自动上传。
• 隐私：试卷照片与成绩属未成年人信息，不写入日志、不外传、不用于任何训练用途。

效率基线

省时要点：单份卷子优先快速模式；只在判分受影响的区域才裁剪核对，不做全页无差别放大。

常见坑（务必避开）

• ❌ 把老师红笔的 ✓/✗ 当依据 → 必须独立重批。
• ❌ 只看最终答案，不看解题过程 → 数学/物理类要检查步骤，算对但过程错也要指出。
• ❌ 凭常识答阅读题 → 自己批改时也要回原文定位，避免把"常识上对"的选项判对。
• ❌ 报告只罗列错题、不给解法 → 每个错点都必须有"错在哪里 + 正确解法 + 类似题"。
• ❌ 直接给结论不给依据 → 存疑处标注"请老师核对"，不擅自定论。
• ❌ 临时裁剪文件留在用户桌面不清理 → 用完即删。

```