grade-report

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-отчёте есть:

Класс
Предмет (явно или из metadata)
Период (II четверть, или диапазон дат)
Привязка к нормативной базе (ФГОС / ФОП / ФРП)
Чётко обозначенный слой 1 vs слой 2 (что от плагина, что от ИИ)
Рекомендации, не диагнозы
Никаких ФИО реальных учеников в твоих сообщениях, только в файле

Поддерживаемые форматы файлов

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-го урока. Хороший плагин-ИИ должен этот паттерн увидеть.