gost-report

name

gost-report

description

Generate Russian academic reports (.docx) formatted to GOST 7.32 — лабораторные, отчёты по практике, курсовые, ВКР, домашние задания для любого российского вуза (ИТМО, МГУ, СПбГУ, МФТИ, Бауманка, и т.д.). Use whenever the user asks for a report по ГОСТ, лабораторную, отчёт по практике, курсовой, ВКР, или любую Russian-language student paper needing proper title page, headings, page numbers, figure/table captions. Triggers even when only "лабораторная" or "отчёт" is mentioned — Russian-language context (ИТМО / МГУ / СПбГУ / университет / ГОСТ) is enough. ITMO is the default profile; other universities via UniversityProfile.

GOST report generator

⛔ Правило №1 — приоритет выше всего остального

Никогда не пиши длинное (—) или среднее (–) тире в тексте отчёта. Ни в одном тексте, который ты передаёшь в r.text(...), r.task(...), r.h1/h2/h3(...), r.numbered([...]), r.bullet([...]), в caption у r.figure/r.table, и в ячейках таблиц. Это правило важнее любых стилистических соображений — даже если ИИ-«хороший вкус» подсказывает, что тире здесь к месту, не ставь его.

Что писать вместо:

• В середине предложения между словами — запятая или точка с запятой. Было: «Москва — столица России». Пиши: «Москва, столица России» или переписывай: «Столица России — Москва» → «Столица России Москва» / «Москва является столицей» (но не используй штамп «является» — лучше: «Столица России Москва»).
• В диапазонах (1—5) — обычный дефис: 1-5.
• В прямой речи и тире пропуска подлежащего — переписывай предложение.

Библиотека дополнительно подстраховывается: любой текст, переданный в content-методы, проходит через автоматический санитайзер _sanitize_prose, который заменяет — / – на , и одиночные —/– на -. Не полагайся на санитайзер — он подчищает за тобой, но текст, написанный сразу без тире, читается естественнее. Санитайзер это страховка, а не разрешение лениться.

Исключения (тире там ставит сама библиотека, по ГОСТ — менять нельзя):

• Авто-подписи рисунков: Рисунок N — Описание.
• Авто-подписи таблиц: Таблица N — Описание.

Эти префиксы формирует код, твой caption в них уже очищен. Поэтому когда ты пишешь r.figure(path, "Схема сети"), в документ попадёт «Рисунок 3 — Схема сети» — это правильно, тире здесь стоит библиотека, не ты.

Writing style — обязательно соблюдать

Любой текст, который ты пишешь в отчёт (всё что идёт в r.text(...), r.task(...), и аргумент caption у r.figure/r.table), должен подчиняться этим правилам. Без исключений:

Пиши в естественной, человеческой, русскоязычной манере, избегая «ИИ-тона» — чрезмерно правильных, формальных и шаблонных конструкций.

Исключай длинные тире (—) и средние тире (–) — см. Правило №1 выше, оно категорично и важнее всего остального в этом разделе. Также исключай лишние кавычки (« »), канцеляризмы и корпоративный жаргон. Используй понятные, живые выражения и уместный разговорный жаргон, если он помогает донести смысл. Избегай повторяющихся фраз и чрезмерно сложных оборотов. Варьируй длину и ритм предложений, приближая текст к естественной речи человека.

Приоритет — смысловая ясность, индивидуальный стиль и практическая ценность в каждом предложении. Каждое предложение должно быть осознанным, как у настоящего человека.

Конкретные запрещённые обороты (типичные ИИ-маркеры — никогда не пиши так):

• «В ходе выполнения работы было...»
• «В результате проведённого исследования...»
• «Данный / вышеуказанный / нижеследующий ...»
• «Является / представляет собой / осуществляется ...»
• «Стоит отметить, что ...» / «Необходимо подчеркнуть, что ...»
• «Таким образом, можно сделать вывод о том, что ...»

Что писать вместо: короткие фразы по делу. Если задание — вывести список файлов, пиши «Команда ls -la показывает все файлы, включая скрытые.» Не «Для решения данной задачи была применена команда ls -la, в результате чего было получено отображение всех файлов».

Это правило НЕ распространяется на:

• Автоматические подписи рисунков и таблиц (Рисунок N — Описание) — их формирует библиотека по жёсткому шаблону ГОСТ.
• Канонические заголовки структурных элементов (Введение, Заключение, Список литературы).
• Прямые цитаты из источников — приводи как есть.

When to use

Любая русскоязычная академическая работа по ГОСТ: лабораторная, отчёт по практике, курсовая/курсовой проект, ВКР, домашнее задание/РГР. Не используй для презентаций, не-ГОСТ-документов, нерусских работ.

Quickstart

Запуск всегда через bootstrap. Скилл сам управляет своим venv в глобальном state-dir вне кода (ADR-008 — $GOST_REPORT_HOME или ${XDG_DATA_HOME:-~/.local/share}/agentpipe/gost-report/venv) — не запускай pip install глобально:

python3 <skill_dir>/scripts/ensure_env.py твой_скрипт.py

(<skill_dir> это папка где лежит SKILL.md. Bootstrap пробует uv → conda --prefix → python -m venv. Тёплые запуски ~30 мс, deps обновляются автоматически при апдейте скилла.)

Персональный конфиг (ФИО, группа, преподаватель)

Чтобы не дублировать в каждом build.py своё ФИО, группу и преподавателя, скилл читает дефолты из ~/.config/gost-report/config ($XDG_CONFIG_HOME/gost-report/config если задан). install.sh копирует шаблон при первой установке, существующий файл не перетирает.

Формат — обычный .env:

GOST_REPORT_STUDENT_NAME="Иванов И.И."
GOST_REPORT_STUDENT_GROUP="P3XXX"
GOST_REPORT_TEACHER_NAME="Сидоров С.С."
GOST_REPORT_TEACHER_DEGREE="к.т.н."
GOST_REPORT_TEACHER_POSITION="доцент"
GOST_REPORT_TEACHER_LABEL="Проверил"
GOST_REPORT_YEAR="2026"

Subject-уровневый конфиг (по предмету)

Для каждого курса/предмета свой преподаватель, своя кафедра. Чтобы не дублировать это в каждом build.py, рядом с проектом курса можно положить .gost-report.env — он применяется только к работам этого предмета:

учёба/
├── .git/
├── математика/
│   ├── .gost-report.env       ← препод по матану, степень, должность
│   └── .claude/gost-report/
│       └── build.py           ← все лабы по матану
├── физика/
│   ├── .gost-report.env       ← препод по физике
│   └── .claude/gost-report/
│       └── build.py

Скилл при запуске build.py идёт вверх по дереву от файла до project root (.git/Makefile/pyproject.toml/.claude — то же определение, что у paths()) и берёт первый найденный .gost-report.env. В отдельной репе по предмету — конфиг рядом с .git/. В монорепо — конфиг в папке конкретного предмета побеждает.

Формат тот же — KEY=VALUE. Обычно сюда кладут только специфичное для предмета:

GOST_REPORT_TEACHER_NAME="Сидоров С.С."
GOST_REPORT_TEACHER_DEGREE="к.т.н."
GOST_REPORT_TEACHER_POSITION="доцент"

Приоритет резолва (сверху вниз — первый непустой)

1. os.environ.GOST_REPORT_* — реальные переменные окружения (например, экспорт в .zshrc)
2. <курс>/.gost-report.env — subject-конфиг (поиск вверх от build.py)
3. ~/.config/gost-report/config — глобальный конфиг
4. Явный аргумент TitleConfig(student_name=..., ...) в build.py

То есть env побеждает build.py, если непустое. Пустое/отсутствующее значение в env-слое — оставляет слой пониже. Это удобно: ФИО/группа один раз в глобальном, преподаватель один раз в subject-конфиге курса, тема/номер — в build.py каждой работы.

Перезаписать путь глобального конфига можно через GOST_REPORT_CONFIG=/path/to/config.

Командная работа

Несколько участников — student_names (список):

r = Report(TitleConfig(
    work_type="Лабораторная работа",
    work_number="№3",
    topic="Командный проект",
    student_names=["Иванов И.И.", "Петров П.П.", "Сидоров С.С."],
    student_group="P3XXX",   # общая для всех; из env, если не задано тут
))

На титульной странице автоматически пишется «Выполнили: …» вместо «Выполнил», все имена выровнены под первое. То же через env: GOST_REPORT_STUDENT_NAMES="Иванов И.И., Петров П.П., Сидоров С.С." (CSV).

Если у участников разные группы — указывай это прямо в строке имени: "Иванов И.И. (P3XXX)". Кастомный label (например, «Выполнила» для женщины-одиночки) — через student_label="Выполнила" или GOST_REPORT_STUDENT_LABEL.

Project layout (рекомендуемая конвенция)

Скрипт-генератор кладётся в <project>/.claude/gost-report/build.py. Артефакты идут в <project>/docs/:

<project>/
├── .claude/
│   └── gost-report/build.py          # скрипт (инструмент, не артефакт)
├── docs/
│   ├── figures/*.png                 # картинки
│   ├── tables/*.tex                  # таблицы (если есть)
│   └── report.docx                   # сгенерированный отчёт
├── Makefile или .git/                # маркер project root
└── ...

Project root определяется автоматически (обход вверх до первого маркера: .git/ → Makefile → pyproject.toml → .claude/). Из этого выводятся:

• r.figure("name.png", ...) — резолвится от <project>/docs/figures/
• r.save() без аргумента — кладёт в <project>/docs/report.docx
• paths() — (root, docs, figures, tables, out, tex) если нужен явный доступ

Готовый скелет: references/templates/build.py.

Минимальный пример (ИТМО, дефолт):

from gost_report import Report, TitleConfig

# ФИО, группа, преподаватель и год — из ~/.config/gost-report/config (env-формат).
# install.sh кладёт туда шаблон при первой установке скилла. Если предпочитаешь
# хардкод — передай аргументы явно в TitleConfig(...).
r = Report(TitleConfig(
    work_type="Лабораторная работа",
    work_number="№1",
    topic="Основы работы в командной строке Unix",
))

r.toc()
r.h1("Введение")
r.text("Цель работы освоить базовые команды Unix.")
r.h1("Выполнение работы")
r.task("Задание 1. Вывести список файлов.")
r.code("ls -la")
r.text("Команда показывает все файлы, включая скрытые.")
f1 = r.formula(r"\sum_{i=1}^{n} i = \frac{n(n+1)}{2}")
r.text(f"Сумма по формуле ({f1}).")
r.h1("Заключение")
r.numbered(["Команда ls освоена.", "Опции -a и -l изучены."])
r.figure("schema.png", "Архитектура")  # относительный путь → <project>/docs/figures/

r.save()  # без аргумента → <project>/docs/report.docx; mkdir parents автоматический

API

Method	What it does
r.toc()	Поле Word TOC + флаг updateFields=true в settings.xml. Word/Pages при первом открытии файла спросит «Update fields?» — нажми «Yes», и оглавление с нумерацией обновится автоматически.
r.h1(text), r.h2(text), r.h3(text)	Заголовки. h1 авто-капс и с новой страницы (профиль).
r.text(text, bold=False, italic=False)	Абзац основного текста (justify, отступ 1.25 см).
r.task(text)	Жирный «Задание N. ...».
r.code(code)	Блок моноширинного кода (Courier New 11).
r.figure(image_path, caption, width_cm=None)	Картинка + «Рисунок N — caption». Ширина клампится по печатной области. Относительный путь → <project>/docs/figures/.
r.formula(latex, where=None) → int	LaTeX-формула как нативное Word-уравнение, авто-номер «(N)» справа. Возвращает номер для ссылок.
r.table(rows, caption, has_header=True)	Таблица + «Таблица N — caption».
r.numbered(items), r.bullet(items)	Списки. Каждый вызов стартует с 1 заново.
r.page_break()	Принудительный разрыв (редко нужен — h1 сам ставит).
r.save(path=None)	Сохранить .docx. Без аргумента → <project>/docs/report.docx. Относительный путь → от <project>/docs/. Возвращает абсолютный Path.
paths(start=None) → ProjectPaths	(root, docs, figures, tables, out, tex). По умолчанию резолвит от file caller'а.

TitleConfig — часто переопределяемые поля

Поле	Дефолт	Когда менять
teacher_label	"Проверил"	Женщина-преподаватель: "Проверила". ВКР/курсовая: "Руководитель" / "Руководительница".
work_number	""	Лабы с номерами: "№1", "№3".
variant	""	Лабы с вариантами: "3".
teacher_degree	""	"к.т.н.", "д.ф.-м.н.".
teacher_position	""	"доцент", "профессор", "ст. преподаватель".

Обязательные: work_type, topic, student_name, student_group, year. Полный список (включая city, ministry, university_*, faculty для override профиля) — в references/api.md.

Подробности — see references/

Загружай по необходимости (агент не должен держать это в контексте каждый раз):

• references/profiles.md — другие вузы: GOST_PROFILE, кастомный UniversityProfile, переопределение полей через TitleConfig.
• references/formulas.md — полный список поддерживаемых LaTeX-конструкций, edge cases, санитайзер vs LaTeX, отладка.
• references/patterns.md — структура для лаб, ВКР, курсовых, отчёта по практике, ДЗ.
• references/api.md — TitleConfig полный, поведенческие заметки (TOC поле, рестарт списков, нет кавычек у topic, картинки клампятся, санитайзер семантика).

Dependencies

Управляются автоматически через scripts/ensure_env.py. Список (см. scripts/requirements.txt):

• python-docx>=1.1.0
• latex2mathml>=3.77.0

При первом запуске bootstrap пишет gost_report.pth в site-packages venv'а — поэтому в твоём скрипте достаточно from gost_report import Report, TitleConfig. Никаких sys.path.insert(...) не нужно. Если IDE настроен на venv скилла — импорт тоже работает напрямую.

License

MIT — see LICENSE.