作业审核 Skill

概述

智能批改学生作业和试卷，支持多张图片一次性拖入处理，自动输出：

• ✅ 带标注的试卷图片（✓/✗）
• 📊 HTML审核报告（总结页 + 各卷详情 + 详细解析 + 易错题库）

核心能力

1. 手写答案识别 - 精准辨认学生字迹
2. 自动判题评分 - 逐题对比，标记正误
3. 图片标注输出 - 在原卷上添加 ✓/✗ 标记
4. HTML报告生成 - 商务风格多页报告
5. 批量处理 - 支持文件夹或多张图片一次处理
6. 易错题库 - 针对性练习推荐

文件结构

homework-checker/
├── SKILL.md              # 本文件
├── scripts/
│   ├── batch_processor.py   # 多图批处理（并发加速）
│   ├── generate_report.py    # HTML报告生成器 v8.0
│   ├── annotate_math.py      # 数学试卷标注 + 报告
│   ├── annotate_geo.py       # 地理试卷标注 + 报告
│   ├── auto_check.py         # 自动查找图片
│   └── homework_checker.py   # 核心审核类
└── references/
    ├── 地理试卷标注说明.md
    └── README.md

使用流程

单张图片处理

from scripts.annotate_geo import annotate
annotated = annotate("地理试卷.png")

多张图片批量处理 ⭐ 新功能

支持三种输入方式：

方式1：拖拽多个文件

from scripts.batch_processor import BatchProcessor

processor = BatchProcessor(output_dir="./output")
results = processor.process_batch(
    ["试卷1.png", "试卷2.png", "试卷3.png"],
    subject='auto',      # 自动检测科目
    max_workers=4        # 并发数
)

方式2：拖拽整个文件夹

from scripts.batch_processor import process_folder

summary = process_folder(
    "./试卷文件夹/",
    subject='地理',      # 指定科目
    output_dir="./output"
)

方式3：快捷函数

from scripts.batch_processor import process_multiple_images
results = process_multiple_images(['img1.jpg', 'img2.jpg'], subject='数学')

生成合并报告

from scripts.generate_report import generate_html_report, generate_batch_report

# 方式A：传入列表（批量模式自动启用）
report_data_list = [
    {"subject": "地理", "score": 12, "total_score": 12, ...},
    {"subject": "数学", "score": 17, "total_score": 21, ...}
]
generate_html_report(report_data_list, "批量报告.html")

# 方式B：使用快捷函数
generate_batch_report(processor.results, "批量报告.html")

完整批量流程示例

import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'scripts'))

from batch_processor import BatchProcessor
from generate_report import generate_batch_report

# 1. 批量处理图片（并发加速）
processor = BatchProcessor(output_dir="./output")
results = processor.process_batch("./试卷文件夹/", subject='auto', max_workers=4)

# 2. 生成合并HTML报告
if results:
    summary = processor.get_summary()
    print(f"成功处理: {summary['success']}/{summary['total']}")

    # 构建报告数据
    report_items = []
    for r in results:
        if r['success']:
            report_items.append({
                "subject": r['subject'],
                "score": 12,       # 由AI识别填充
                "total_score": 12,
                "original_image": r['image'],
                "annotated_image": r['annotated'],
                "questions": []     # 由AI识别填充每道题
            })

    generate_batch_report(report_items, "./output/审核报告.html")

AI调用规范（通用环境）

当用户上传图片时，按以下步骤执行：

1. 保存图片到工作目录（支持用户拖入多张图片或文件夹）
2. 逐张仔细识别答案 - 逐题辨认手写笔迹，区分空白括号( )和学生写的字母
3. 构建审核数据 - 按格式组织每道题的信息：

```python

questions = [

{

'id': 4, # 题号

'title': '题目文字', # 题目简述

'answer': 'B', # 学生的答案（没写填"未作答"）

'correct': 'B', # 正确答案

'status': 'correct', # correct=正确, wrong=错误/未作答

'points': 4, # 分值

'analysis': '解析说明...' # 详细解析

},

# ... 更多题目

]

```

1. 调用报告生成器

```python

from scripts.generate_report import generate_html_report

generate_html_report(batch_data_list, "输出路径/审核报告.html")

```

1. 展示结果 - 用 preview_url 展示HTML，用 open_result_view 交付文件

⚠️ 关键规则

| 规则 | 说明 |

|------|------|

| 必须生成HTML | 无论什么环境，最终必须输出可点击查看的HTML报告 |

| 空括号=错误 | 学生没填的题标记为 status: 'wrong'，确保进入易错题库 |

| 仔细辨认字迹 | 必须逐题看图确认，不能凭印象判断 |

| 学科自动匹配 | subject字段包含"地理"/"数学"即可自动匹配对应巩固练习 |

输出文件

| 文件 | 说明 |

|------|------|

| *_已批注.png | 带有 ✓/✗ 标记的试卷图片 |

| *_审核报告.html | 完整审核报告（多页） |

HTML报告结构 v9.0

总结总览页（核心页面）

1. 📋 试卷信息头部卡片 — 科目、试卷数/题数、日期 + 大字得分 + 得分率 + 等级徽章
2. 📊 统计条 — 正确数 / 错误数 / 需完善 / 总题数 / 得分率 五维统计
3. 🎯 答题卡 — 按题型分组（选择/填空/判断等），网格卡片式展示每道题的答案和状态
4. 📷 试卷图片 — 原图与批注图并排对比
5. 📝 综合评价 — 优点 + 需改进（带颜色区分）
6. 💡 学习建议 — 带编号的建议列表

各卷详情页（批量模式独有）

• 每张试卷独立展示（含小答题卡 + 批注图 + 答题表）
• 可「返回总览」

详细解析页

• 所有题目逐一分析（含解析展开/收起）
• 答案对比高亮显示
• 可「返回总览」

易错题库页

• ⚠️ 错题汇总提示 + 具体错题回顾卡片（每道错题显示题目、你的答案、正确答案、解析）
• 📚 学科巩固练习题（自动匹配地理/数学等科目，含5道针对性练习）
• 点击展开查看答案和解析
• 可「返回总览」

性能优化

• 并发处理: ThreadPoolExecutor 多线程标注图片
• 列表拼接: 用list.join()替代字符串+=，提升10倍以上
• 懒加载: 图片使用 loading="lazy" 延迟加载
• 流式写入: HTML内容一次性写入磁盘
• 目标: 10张图片以内 30秒内完成全部处理

版本信息

• 版本：v9.4
• 更新日期：2026-04-09
• 更新内容：
• 🎯 易错题库升级：错题回顾卡片（具体题目+答案对比+解析）+ 巩固练习题
• 🔍 学科模糊匹配：subject字段自动识别"地理"/"数学"等关键词
• ⚠️ 空题处理规范：未作答题目统一标记为错误(wrong)，纳入易错题库
• 📦 跨平台兼容：支持在任何AI环境中使用，必须生成HTML报告
• 🎨 全新答题卡样式：按题型分组，网格卡片展示，一目了然
• 📊 保留完整得分模块：大字分数 + 得分率 + 等级徽章 + 五维统计条
• 🔙 所有子页面可返回总览：详情页/易错题库均有返回按钮
• ✨ 视觉升级：渐变背景、悬浮动效、更精致的圆角阴影