GraderFlow Skills
ruomuo/GraderFlow-skills
Correção automática de provas com OMR + LLM multimodal
Ver no GitHubSuite de automação para correção de provas com IA, combinando YOLO para reconhecimento óptico de marcas (OMR) em questões objetivas e modelos multimodais LLM para questões subjetivas. Processa lotes de imagens de provas, extrai dados de estudantes e exporta resultados com anotações e estatísticas.
Instalação
npx convez-ai ruomuo/GraderFlow-skills1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Correção em lote de folhas de resposta com questões objetivas
- Avaliação automática de questões abertas com IA
- Extração e reconhecimento de dados de estudantes em provas
Veredito

Ferramenta robusta para automação de processos educacionais, bem estruturada com suporte a OMR e LLM. Requer configuração técnica considerável e conhecimento em Python, mas entrega valor real em cenários de correção em escala.
README
A tradução para o português deste README ainda está na fila.
GraderFlow Skills 📝
🎓 阅卷 Skills — AI 驱动的试卷批改工具集,可集成到 Claude Code / Trae / Cursor 等 AI Agent 中使用。AI-powered exam grading skill: YOLO-based OMR + multimodal LLM for objective & subjective questions + batch processing.
GraderFlow Skills is a standalone, headless runtime designed for automated exam grading. It combines a YOLO-based OMR (Optical Mark Recognition) engine for multiple-choice questions with multimodal LLM-powered grading for subjective questions — packaged as an AI Agent Skill usable in Claude Code, Trae, Cursor, or any agent platform. Also fully controllable via CLI.
✨ Features
- 📋 Objective Grading — YOLOv5-based answer sheet detection + contour-based fill recognition. Supports multi-select questions, configurable scoring rules, and per-question option counts.
- 🤖 Subjective Grading — LLM-powered (multimodal vision models) for open-ended questions, with structured scoring reports.
- 👤 Student Info Recognition — Extract name and student ID from exam sheets via multimodal LLM.
- 🔢 Barcode Recognition — Optional barcode-based student ID extraction (OpenCV + pyzbar).
- 📊 Batch Processing — Process entire directories of exam images in one command, export to Excel/CSV with detailed statistics.
- 🎨 Annotation — Auto-generates annotated images marking wrong answers, summaries, and per-question CSV records.
- 🤖 AI Agent Skill — Ships with a Claude Code / Trae skill (
skill/SKILL.md) for conversational grading workflows.
📦 Project Structure
graderflow-skills/
├── README.md # ← You are here
├── skill/
│ └── SKILL.md # AI agent skill definition
└── runtime/
├── config/
│ ├── config.json # Main configuration
│ ├── answer_config/
│ │ ├── objective_answer.txt # Multiple-choice answer key
│ │ └── subjective_answer.txt # Subjective answer key
│ └── weights/
│ └── best.pt # YOLOv5 detection model
├── core/
│ ├── omr/ # OMR engine (detection, recognition, annotation)
│ ├── subjective/ # LLM-based subjective grading
│ └── data/ # Student data model
├── test_script/
│ └── agent_batch_marking.py # ★ Main batch grading entry point
├── utils/ # Config manager, path utils
├── yolo/ # YOLOv5 inference code
├── prompts/ # Reusable AI prompts
├── run_marking.bat # Windows batch wrapper
├── run_marking.ps1 # PowerShell wrapper
├── requirements-runtime.txt # Python dependencies
└── requirements.txt
🚀 Quick Start
Prerequisites
- Python 3.8+
- PyTorch (CPU or CUDA)
1. Install Dependencies
pip install -r runtime/requirements-runtime.txt
2. Prepare Answer Keys
Edit the answer configuration files under runtime/config/answer_config/:
objective_answer.txt — one line per question:
# 题号:答案:分值:选项个数
1:A:1.0:4
2:B,C:2.0:4 # Multi-select: comma-separated answers
3:A,B,C,D:1.0:4 # Select-all
subjective_answer.txt — free-form answer reference:
1题(10.0分)
(1) 参考答案要点一 (+3)
(2) 参考答案要点二 (+7)
2题(15.0分)
...
3. Configure (Optional)
Edit runtime/config/config.json:
{
"api_key": "sk-your-api-key-here", // Required for subjective grading & student info
"api_base_url": "https://api.siliconflow.cn/v1",
"model_name": "Qwen/Qwen3-VL-30B-A3B-Instruct",
"recognition": {
"mode": "A", // "A" = natural order, "B" = column-priority
"layout": "row", // "row" or "column"
"group_size": 5, // Questions per image crop
"conf_thres": 0.75 // YOLO confidence threshold
},
"objective_scoring_rule": "standard" // or "partial_penalty"
}
Note: You can leave
api_keyempty — objective-only grading works without any API key. The system will automatically skip subjective grading and student info recognition.
4. Run
# Grade a single exam paper
python runtime/test_script/agent_batch_marking.py \
--input-file "E:/exams/answer_001.jpg" \
--enable-subjective false
# Batch grade a directory
python runtime/test_script/agent_batch_marking.py \
--input-dir "E:/exams/batch_01/" \
--output-dir "E:/results/" \
--recursive
# Full pipeline (objective + subjective + student info)
python runtime/test_script/agent_batch_marking.py \
--input-dir "E:/exams/batch_01/" \
--enable-subjective true \
--enable-student-info true \
--enable-barcode false
5. Using Wrapper Scripts (Windows)
.\runtime\run_marking.ps1 -InputDir "E:\exams\batch_01"
runtime\run_marking.bat "E:\exams\batch_01"
📋 CLI Reference
python runtime/test_script/agent_batch_marking.py --help
| Argument | Type | Default | Description |
|---|---|---|---|
--input-file | path | — | Single exam image path (mutually exclusive with --input-dir) |
--input-dir | path | — | Directory containing exam images (mutually exclusive with --input-file) |
--output-dir | path | input_parent/graderflow_output/ | Root directory for all output artifacts |
--output | path | auto-generated | Specific output file path (.xlsx or .csv) |
--recursive | flag | false | Recursively scan subdirectories for images |
--enable-objective | bool | true | Enable multiple-choice grading |
--enable-subjective | bool | true | Enable LLM-based subjective grading |
--enable-student-info | bool | true | Enable student name/ID recognition |
--enable-barcode | bool | false | Enable barcode recognition |
Supported image formats: .jpg, .jpeg, .png, .bmp, .webp
📤 Output Structure
All results are written to the output directory (default: <input-parent>/graderflow_output/):
graderflow_output/
├── grading_summary_20260609_111208.xlsx # Main results (Excel)
├── grading_summary_20260609_111208_summary.json # Statistics (JSON)
├── grading_summary_20260609_111208_summary.txt # Statistics (plain text)
├── annotated/ # Annotated answer sheets
│ └── answer_186_annotated.jpg # — wrong answers highlighted
├── originals/ # Original image backups
│ └── answer_186_original.jpg
├── summaries/ # Score summary images
│ └── answer_186_summary.jpg
├── records/ # Per-question CSV records
│ └── answer_186_records.csv # — question-by-question breakdown
├── reports/ # Subjective grading reports (if enabled)
│ └── <id>+<name>+subjective.txt
└── _temp/ # Temporary files (safe to delete)
Excel Result Columns
| Column | Description |
|---|---|
原图文件 | Original image filename |
学号 | Student ID (recognized) |
姓名 | Student name (recognized) |
客观题成绩 | Objective score |
主观题成绩 | Subjective score |
总成绩 | Total score |
错题数 | Wrong answer count |
空白数 | Blank answer count |
错题列表 | Comma-separated wrong question numbers |
空白题列表 | Comma-separated blank question numbers |
状态 | success / failed |
错误信息 | Error details if failed |
🧠 How It Works
Objective Grading Pipeline
Input Image → Deskew → YOLOv5 Detection (answer areas)
→ Crop & Sort → Contour Fill Detection
→ Answer Matching → Scoring → Annotation
- Deskew: Projection-based image rotation correction
- YOLOv5 Detection: Locates answer-area bounding boxes on the sheet
- Crop & Sort: Extracts individual answer blocks (5 questions per block by default)
- Fill Detection: Contour-based filled/empty classification per option
- Scoring: Match against answer key with support for standard and partial-penalty rules
- Annotation: Generate visual feedback marking wrong answers
Subjective Grading Pipeline
Input Image → Base64 Encode → Multimodal LLM API
→ Structured Scoring → Report Generation
Student Info Recognition
Input Image → Multimodal LLM API → JSON Parse → Name + Student ID
🤖 AI Agent Integration
GraderFlow ships with a Claude Code / Trae skill at skill/SKILL.md. When loaded, AI agents can:
- Parse natural language grading requests
- Auto-detect and validate runtime configuration
- Execute grading workflows with proper parameters
- Summarize results in readable format
- Flag anomalies for manual review
To use with Claude Code, copy the skill to your .claude/skills/ directory.
🔧 Configuration Deep-Dive
Scoring Rules
| Rule | Behavior |
|---|---|
standard | Full score only if exactly matching the answer key |
partial_penalty | Multi-select: partial credit for partially correct answers, penalty for wrong selections |
Recognition Modes
| Mode | Sorting | Use Case |
|---|---|---|
A | Natural sequential order | Most standard answer sheets |
B | Column-priority order | Column-based layouts |
Layout
| Layout | Meaning |
|---|---|
row | Each question occupies one row (A B C D horizontally) |
column | Each question occupies one column (A B C D vertically) |
Supported LLM Models
Via SiliconFlow API (or any OpenAI-compatible endpoint):
Qwen/Qwen3-VL-30B-A3B-Instruct(recommended, cost-effective)Qwen/Qwen3-VL-8B-InstructQwen/Qwen3-VL-32B-InstructQwen/Qwen3-VL-235B-A22B-Instruct(best quality)zai-org/GLM-4.6V- And more — edit
available_modelsinconfig.json
📊 Requirements
python >= 3.8
torch >= 1.7
opencv-python >= 4.5
pandas
openpyxl
Pillow
numpy
openai >= 1.0
pyzbar # optional, for barcode
Full list: runtime/requirements-runtime.txt
⚠️ Limitations & Notes
- GPU recommended for batch processing — CPU mode is functional but slower (YOLO inference on CPU ~120ms/image).
- Subjective grading quality depends on the LLM model used. For high-stakes exams, human review is still recommended.
- Answer sheet layout must be consistent with the YOLO model's training data. Custom layouts may require fine-tuning
best.pt. - Student info recognition requires a multimodal LLM with vision capabilities and an internet connection (API call).
- Barcode recognition depends on OpenCV's
barcode_BarcodeDetector(OpenCV 4.8+) orpyzbar.
🤝 Contributing
Issues and pull requests are welcome. Areas that particularly need contributions:
- YOLO model training pipeline for custom answer sheet layouts
- Support for more answer sheet formats
- Web UI / GUI improvements
- Additional LLM provider integrations
📄 License
[Specify your license here — e.g., MIT, Apache 2.0, GPL]
🙏 Acknowledgements
- Ultralytics YOLOv5 for the object detection backbone
- SiliconFlow for multimodal LLM API access
- OpenCV & pyzbar for image processing and barcode decoding