| name | grade-report |
| description | Use when analyzing class grades — анализ успеваемости класса, отчёт по успеваемости, средний балл, качество знаний, группа риска. Accepts XLSX/CSV from electronic journals (МЭШ, Дневник.ру, ЭлЖур, Сетевой Город) or simple `ФИО,5,4,3,...`. ФИО анонимизированы в LLM-промптах. |
| argument-hint | [путь к XLSX/CSV/JSON, или 'ввести вручную'] |
| allowed-tools | Read, Write, Skill, mcp__plugin_teacher-assistant_teacher__grade_analytics |
Анализ успеваемости и отчёт
Данные: $ARGUMENTS
Принципы
- Учительский UX: учитель не должен ничего пересохранять. Принимаем XLSX
напрямую из электронного журнала (МЭШ, Дневник.ру, Сетевой Город, ЭлЖур),
а также CSV/TSV/JSON.
- Анонимизация в LLM-промпте: в общении с моделью используем псевдонимы
Ученик #1, Ученик #2, ... — реальные ФИО приходят из инструмента
только в name_map и никогда не отправляются в LLM-сообщения. Реальные
имена попадают только в локальный файл-отчёт через Write.
- Двухслойный анализ: статистика (числовая) + аналитика поверх (паттерны,
динамика). Чётко разделяй: «слой 1 — что считает grade_analytics», «слой 2
— что увидел я как читатель данных».
Шаги
Шаг 1. Получить данные
- Если в
$ARGUMENTS путь к файлу — переходи к шагу 2.
- Если «ввести вручную» — предложи учителю упрощённый формат
ФИО,оценка1,оценка2,... и сохрани во временный CSV.
Шаг 2. Вызвать grade_analytics
mcp__plugin_teacher-assistant_teacher__grade_analytics(
data_path: "<file>",
metrics: ["average", "quality", "success_rate", "distribution",
"students_at_risk", "top_students", "attendance"],
anonymize: true // ← по умолчанию true; не отключай, если учитель явно не попросит
)
Если учитель явно спросит за конкретный период или по конкретному типу
работ, добавь параметры:
period: "q2" // или date_from / date_to для произвольного диапазона
work_type: ["КС", "КР"] // например, только классные сочинения и контрольные
Шаг 3. Fallback при total_students == 0
Если grade_analytics вернул пустой результат — это значит формат файла
непривычный (новая система или ручной XLSX). Не показывай ошибку учителю,
сделай тихий fallback:
- Прочитай файл напрямую через
Read (для XLSX используй Read с
извлечением текста; для CSV — текстовое чтение).
- Нормализуй данные «по смыслу»: в твоём контексте есть ФИО и
последовательности отметок 2-5/Н/Б. Преобразуй в простой формат
ФИО,оценка1,оценка2,... и запиши во временный файл
/tmp/grades_normalized_<класс>.csv через Write.
- Повторно вызови
grade_analytics с этим временным файлом.
- Учителю показывай результат как обычно — не упоминай fallback.
Шаг 4. Сформировать отчёт
Структура отчёта (см. подробный шаблон в templates/grade-report.md):
1. Общая статистика
- средний балл по классу,
- качество знаний (% на 4-5),
- успеваемость (% без 2),
- распределение отметок (5, 4, 3, 2),
- посещаемость (Н/Б) если есть.
2. Индивидуальный анализ — слой 1 (по статистике)
- ученики на 4-5 (
top_students) — рекомендация: олимпиады, проекты,
роль наставника;
- хорошисты, среднеуспевающие, на грани (между 3.0 и 3.5) — мониторинг;
- группа риска (
students_at_risk с reason: "low_average") —
индивидуальная работа, дифференциация;
- не-аттестованные (
reason: "not_attested") — выяснить причины,
организовать индивидуальную аттестацию.
3. Индивидуальный анализ — слой 2 (паттерны, поверх статистики)
То, что не видит базовая статистика, но видит читатель данных. Применяй
только если в данных есть даты (поле date у grades):
- синхронные изменения — несколько учеников показывают одинаковую
динамику (например, у 4 учеников после 7-го урока — провал). Сформулируй
педагогические гипотезы (общее событие, психологическая реакция на
формат работы, социальная динамика). Никогда не утверждай причину —
предлагай для проверки классным руководителем.
- прогресс отдельного ученика — оценки растут от начала к концу
периода. Это часто упускается за усреднением.
- провалы по типу работ — например, если средний по
work_type=КС
на 1 балл ниже общего, это сигнал по подготовке к сочинениям.
4. Рекомендации (содержательные приоритеты для учителя)
5. Сводная карточка для пятиминутной планёрки с завучем
6. Что делал плагин и где заканчивается его ответственность
Дай учителю явное разделение «слой 1 — числовая статистика плагина», «слой 2
— анализ ИИ поверх данных». И зафиксируй: «истинную причину аномалий
определит только живой разговор с детьми».
Шаг 5. Анонимизация в LLM ↔ ФИО в файле
Внутри ответов и обоснований используй псевдонимы из основного вывода
grade_analytics («Ученик #1»). При записи итогового MD-отчёта в файл
учителя — разреши себе использовать реальные ФИО из name_map,
потому что файл локальный, не отправляется в LLM. Технически:
- собери текст отчёта с псевдонимами,
- в самый последний шаг перед
Write сделай замену
Ученик #N → name_map["Ученик #N"] локально,
- запиши файл
отчёт_успеваемость_<класс>.md. Если учитель попросит
DOCX — вызови встроенный anthropic-skills:docx с параметрами ГОСТ
из .claude/rules/document-formatting.md.
Если учитель явно сказал «работай с псевдонимами и в файле» (например,
для отправки во внешнюю систему) — оставь псевдонимы.
Шаг 6. Self-validation перед завершением
Перед тем как сообщить учителю «готово», убедись, что в выходном MD-отчёте есть:
Поддерживаемые форматы файлов
- XLSX — основной путь. Прямой экспорт из ЭлЖур / МЭШ / Дневник.ру /
Сетевого Города. С шапкой и multi-line ячейками.
- CSV/TSV — авто-разделитель
, ; \t; авто-кодировка UTF-8 / UTF-8
BOM / Windows-1251.
- Простой CSV
ФИО,5,4,3,... — для быстрых вводов.
- JSON
[{student, grades}] — для интеграций.
Шаблоны отчётов
templates/grade-report.md — структура с примерами заполнения.
Эталонный кейс
/test-fixtures/grades/grades_8b_literature_q2_full.csv (8Б, литература,
II четверть 2025-2026): 25 учеников, 334 отметки, средний 3.22, в данных
заложен паттерн «синхронное снижение четвёрки» — учеников 8Б-13..16 после
7-го урока. Хороший плагин-ИИ должен этот паттерн увидеть.
