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:

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)

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_.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__.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 · 报告生成

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 · 输出格式

{
  "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

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

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

python3 scripts/grade_essay.py \
  --essay essay.txt \
  --rubric my_rubric.json \
  --output essay_feedback.md

Example 4: Photo of handwritten homework

python3 scripts/run_pipeline.py \
  --input photo.jpg \
  --answer-key key.json \
  --ocr --subject chinese --grade 5

🧪 Testing · 测试

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_.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 作业批改 自动评分