back
loading skill details...
EN: Automated K-12 homework grading for Chinese, Math, English, Physics and Chemistry. Handles objective items (multiple-choice, fill-in-the-blank, true/fals...
---
name: edu-homework-grader
description: |
EN: Automated K-12 homework grading for Chinese, Math, English, Physics and Chemistry. Handles objective items (multiple-choice, fill-in-the-blank, true/false) with deterministic scoring, and subjective items (essays, short answers, math derivations) with rubric-based partial-credit evaluation. Produces per-student score sheet, common-error analysis, and personalized improvement suggestions. Use when user provides homework text/photos and asks "批改作业 / 改卷 / 评分 / grade homework".
中文：覆盖 K-12 语数英物化的自动作业批改。客观题（选择/填空/判断）按答案模板确定性评分；主观题（作文/简答/数学推导）按 rubric 给出部分分与文字反馈。输出每生成绩、共性错误分析、个性化提升建议。当用户提供作业内容并要求"批改/改卷/评分"时触发。
version: 1.0.0
metadata:
openclaw:
emoji: "📝"
homepage: https://github.com/openclaw-skills/edu-homework-grader
requires:
bins:
- python3
envVars:
- name: GRADER_CURRICULUM_REGION
required: false
description: Curriculum region hint, one of `RPEP|BNUEP|JSEP|HKDSE|US-CCSS`. Defaults to RPEP (人教版).
- name: GRADER_OCR_ENGINE
required: false
description: Override OCR engine for handwritten input. Defaults to bundled tesseract+layout post-processor.
---
# Edu Homework Grader · K-12 作业智能批改
> Rubric-driven, evidence-backed grading that explains *why* each point was lost, not just the score. Designed for teachers, tutors, and self-study learners.
>
> 不只是给分，更告诉学生**为什么扣分**。按 rubric 评分、按知识点归因、按个体出建议，给老师、家教与自学者使用。
---
## 🎯 When to Use · 何时使用
**Trigger keywords (中文):** 批改作业、改卷、判作业、评分、给分、作文批改、数学批改、英语批改、错题分析、知识点诊断
**Trigger keywords (EN):** grade homework, mark assignment, essay scoring, rubric grading, error analysis, concept gap detection
**Supported subjects & item types:**
| 学科 / Subject | 题型 / Item Types |
|---|---|
| 语文 Chinese | 选择/填空/默写/阅读理解/作文 |
| 数学 Math | 选择/填空/计算/解答题/几何证明 |
| 英语 English | 选择/完形/阅读/翻译/作文 |
| 物理 Physics | 选择/填空/实验/计算/推导 |
| 化学 Chemistry | 选择/填空/方程式/实验/计算 |
**Do NOT use when:**
- Input has no answer key and no rubric (the grader needs ground truth or scoring criteria)
- User asks the grader to do the homework instead of grading it
- Subjective grading without rubric for high-stakes exams (always require human teacher final review for graded transcripts)
---
## 📋 Grading Pipeline · 批改流程
### Step 1: Input parsing · 输入解析
Accepted inputs:
- Text (questions + student answers + answer key)
- Image (photo of handwritten or printed homework) — auto-routed through OCR
- PDF (multi-page exam papers)
- Excel/CSV (batch grading roster)
```bash
python3 scripts/parse_input.py --input <file-or-stdin> --format auto
```
### Step 2: Question type detection · 题型识别
`scripts/detect_item_types.py` classifies each item into one of:
- `MC` multiple-choice (single/multi-correct)
- `FIB` fill-in-the-blank
- `TF` true/false
- `SA` short-answer
- `ESSAY` extended essay
- `MATH_DERIV` math derivation/proof
- `CHEM_EQ` chemistry equation
- `LANG_TRANSLATE` translation
### Step 3: Scoring · 评分
Two paths:
**Objective items** (`MC`, `FIB`, `TF`, `CHEM_EQ`):
- Strict match against answer key
- For `FIB`: normalize whitespace, full/half-width chars, accept synonym set from `knowledge/synonym_<subject>.json`
- For `CHEM_EQ`: balance and stoichiometry check via `scripts/chem_eq_check.py`
**Subjective items** (`SA`, `ESSAY`, `MATH_DERIV`, `LANG_TRANSLATE`):
- Apply rubric from `templates/rubric_<subject>_<grade>.json`
- For `MATH_DERIV`: step-by-step credit using `scripts/math_step_grader.py` (each correct step gets partial credit, even if final answer is wrong)
- For `ESSAY`: 6-dimension scoring (内容/结构/语言/书写/创意/规范) with LLM-assisted evaluation grounded in rubric
- For `LANG_TRANSLATE`: BLEU + grammatical correctness + key-term coverage
### Step 4: Error analysis · 错因归因
`scripts/diagnose_errors.py` classifies each wrong answer into:
- 知识点缺失 (Concept gap) — links to specific curriculum standard code
- 概念混淆 (Concept confusion)
- 计算失误 (Calculation slip)
- 审题错误 (Misreading question)
- 表达不规范 (Notation/format violation)
- 应试技巧 (Test-taking strategy)
### Step 5: Report generation · 报告生成
```bash
python3 scripts/render_report.py --grading-result graded.json --format student|teacher|class
```
Three report flavors:
- **Student report** — per-question feedback, encouragement, study suggestions
- **Teacher report** — class-level statistics, common errors, knowledge-point heatmap
- **Class report** — for class management systems, includes CSV/Excel export
---
## 📤 Output Format · 输出格式
```json
{
"assignment": { "title": "...", "subject": "math", "grade": 8, "total_points": 100 },
"students": [
{
"student_id": "S001",
"name": "张三",
"score": 87,
"items": [
{
"item_id": "Q5",
"type": "MATH_DERIV",
"earned": 8,
"max": 10,
"feedback": "第二步因式分解正确，第三步符号错误导致后续计算偏差",
"error_class": "计算失误",
"knowledge_points": ["二次方程求根公式", "代数式化简"]
}
],
"improvement_plan": [
"重点复习：一元二次方程求根公式（人教版数学九年级上 第21章）",
"推荐练习：教材 P52 习题 21.2 第 3、5、7 题"
]
}
],
"class_stats": { "mean": 78.5, "median": 80, "stddev": 12.3, "knowledge_point_heatmap": {...} }
}
```
---
## ⚠️ Safety & Compliance · 安全合规
1. **Grader is an aid, not the final authority** — every report includes a "请教师终审" notice for graded transcripts.
2. **No student PII to external services** — all OCR and LLM processing happens through the assistant's configured providers per the user's setup; the skill itself never makes independent network calls.
3. **Bias mitigation** — essay rubrics are anchored to standard curriculum criteria; no personal-attribute features (gender, name, ethnicity) feed into scoring.
4. **Transparent rubrics** — all rubrics are stored as human-readable JSON in `templates/`, fully auditable and editable.
5. **Score appeal trail** — every score has a reasoning trace (`why_lost_points` field) supporting student appeals.
> 批改结果仅作教学辅助，正式成绩需教师终审；不向外部服务上传学生信息；评分依据公开 rubric；保留完整的扣分推理链以便申诉复核。
---
## 🚀 Usage Examples · 使用示例
### Example 1: Single student math homework
```bash
python3 scripts/run_pipeline.py \
--input homework_zhangsan.txt \
--answer-key key.json \
--subject math --grade 8 \
--output graded.json
python3 scripts/render_report.py --grading-result graded.json --format student
```
### Example 2: Batch grade an entire class
```bash
python3 scripts/batch_grade.py \
--roster class_8a.csv \
--homework-dir ./submissions/ \
--answer-key key.json \
--rubric rubric_math_g8.json \
--output class_report.xlsx
```
### Example 3: Essay scoring with custom rubric
```bash
python3 scripts/grade_essay.py \
--essay essay.txt \
--rubric my_rubric.json \
--output essay_feedback.md
```
### Example 4: Photo of handwritten homework
```bash
python3 scripts/run_pipeline.py \
--input photo.jpg \
--answer-key key.json \
--ocr --subject chinese --grade 5
```
---
## 🧪 Testing · 测试
```bash
cd tests && python3 -m pytest -v
```
Coverage includes:
- 5 subjects × 3 grade levels = 15 reference assignments
- Edge cases: blank answers, partial OCR garbage, ambiguous Chinese characters, half/full-width digits
- Rubric stability tests (same input → same score within ±2%)
---
## 📚 References · 参考资料
- 教育部《义务教育课程标准（2022 年版）》
- 人教版/北师大版/苏教版各年级教材章节代码表（`knowledge/curriculum_<region>.csv`）
- BLEU score for translation: Papineni et al., 2002
- Educational rubric design: Andrade, 2005
## 🏷️ Tags · 标签
`education` `K12` `homework-grading` `rubric` `essay-scoring` `error-analysis` `教育` `K12` `作业批改` `自动评分`
don't have the plugin yet? install it then click "run inline in claude" again.