grade-report

# Анализ успеваемости и отчёт Данные: $ARGUMENTS ## Принципы 1. **Учительский UX:** учитель не должен ничего пересохранять. Принимаем XLSX напрямую из электронного журнала (МЭШ, Дневник.ру, Сетевой Город, ЭлЖур), а также CSV/TSV/JSON. 2. **Анонимизация в LLM-промпте:** в общении с моделью используем псевдонимы `Ученик #1`, `Ученик #2`, ... — реальные ФИО приходят из инструмента только в `name_map` и **никогда** не отправляются в LLM-сообщения. Реальные имена попадают только в локальный файл-отчёт через `Write`. 3. **Двухслойный анализ:** статистика (числовая) + аналитика поверх (паттерны, динамика). Чётко разделяй: «слой 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: 1. **Прочитай файл напрямую** через `Read` (для XLSX используй `Read` с извлечением текста; для CSV — текстовое чтение). 2. **Нормализуй данные «по смыслу»:** в твоём контексте есть ФИО и последовательности отметок 2-5/Н/Б. Преобразуй в простой формат `ФИО,оценка1,оценка2,...` и запиши во временный файл `/tmp/grades_normalized_<класс>.csv` через `Write`. 3. **Повторно вызови** `grade_analytics` с этим временным файлом. 4. Учителю показывай результат как обычно — не упоминай 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. Технически: 1. собери текст отчёта с псевдонимами, 2. в самый последний шаг перед `Write` сделай замену `Ученик #N → name_map["Ученик #N"]` локально, 3. запиши файл `отчёт_успеваемость_<класс>.md`. Если учитель попросит DOCX — вызови встроенный `anthropic-skills:docx` с параметрами ГОСТ из [.claude/rules/document-formatting.md](../../.claude/rules/document-formatting.md). Если учитель явно сказал «работай с псевдонимами и в файле» (например, для отправки во внешнюю систему) — оставь псевдонимы. ### Шаг 6. Self-validation перед завершением Перед тем как сообщить учителю «готово», убедись, что в выходном MD-отчёте есть: - [x] Класс - [x] Предмет (явно или из metadata) - [x] Период (II четверть, или диапазон дат) - [x] Привязка к нормативной базе (ФГОС / ФОП / ФРП) - [x] Чётко обозначенный слой 1 vs слой 2 (что от плагина, что от ИИ) - [x] Рекомендации, не диагнозы - [x] Никаких ФИО реальных учеников **в твоих сообщениях**, только в файле ## Поддерживаемые форматы файлов - **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-го урока. Хороший плагин-ИИ должен этот паттерн увидеть.