SSAUGenerator/AGENTS.md

AGENTS.md — управление проектом SSAU Generator

Репозиторий содержит два независимых генератора отчётных документов из Markdown. Этот файл описывает управление проектом в целом. Правила работы с конкретным документом — в docx/AGENTS.md и pptx/AGENTS.md.

Что использовать по запросу пользователя

• Просит сгенерировать документ (отчёт, DOCX, пояснительную записку, лабораторную работу) — используйте генератор в папке docx/.
• Просит сгенерировать презентацию (PPTX, слайды) — используйте генератор в папке pptx/.

Команды запускаются из корня репозитория; генератору указывается config.yaml нужного проекта. Содержимое документа задаётся Markdown-файлами и config.yaml проекта, а не кодом генератора.

Правила работы над проектом

• Уточните название проекта. Если пользователь не указал, над каким проектом ведётся работа, сначала спросите его. Проект — это папка content/<проект>/.
• Один проект за сессию. В рамках одной сессии работайте только над одним проектом.
• Создание — только через --init. Новый проект создавайте командами с флагом --init (см. ниже): они формируют правильную структуру и общий каталог ресурсов.
• Сначала план — потом работа. Прежде чем наполнять проект, составьте план и сохраните его в content/<проект>/PLAN.md (см. раздел «Планирование проекта»). Работу над содержимым начинайте только после согласования плана с пользователем.
• Имя результата = имя проекта. Документ и презентация собираются в папку проекта, а имя файла совпадает с именем проекта: content/<проект>/<проект>.docx и content/<проект>/<проект>.pptx. Соответствующий путь задаётся ключом output в config.yaml.
• Пересобирайте после правок. При любом изменении исходных файлов (config.yaml, *.md, ресурсов в assets/) заново запускайте сборку docx и/или pptx, чтобы результат соответствовал исходникам.

Структура репозитория

ssau-generator/
├── docx/            # генератор DOCX (только код)
├── pptx/            # генератор PPTX (только код)
├── tools/           # общий plantuml.jar
├── content/         # проекты (в git хранится только example)
│   └── example/
│       ├── assets/  # общие ресурсы проекта (для docx и pptx)
│       ├── docx/    # config.yaml + *.md
│       ├── pptx/    # config.yaml + slides/
│       └── PLAN.md  # согласованный план проекта
├── AGENTS.md        # этот файл
└── README.md

Проекты и каталог content

• Один проект = одна папка content/<проект>/.
• Внутри проекта при необходимости лежат папки docx/ и pptx/.
• Общие ресурсы проекта (титульный лист, задники, изображения, исходники .puml) размещаются в content/<проект>/assets/ и используются обоими генераторами. В docx/ и pptx/ внутри проекта хранятся только config.yaml и Markdown.
• Папки content/* добавлены в .gitignore; в репозитории хранится только content/example/. Рабочие проекты пользователя коммитить не нужно.

Планирование проекта

Перед наполнением проекта составьте план и сохраните его в content/<проект>/PLAN.md. План создаётся до работы над config.yaml и Markdown и согласуется с пользователем. В плане укажите:

• реквизиты — студент (ФИО), группа, дисциплина;
• тему работы и её цель;
• структуру — разделы и подразделы с названиями и пунктами (для документа — по sections, для презентации — список слайдов);
• краткое содержание каждого раздела/слайда;
• список источников — если согласован с пользователем;
• нюансы — особые требования пользователя (объём, оформление, сроки, ограничения и т.п.), если они указаны;
• прочие согласованные детали.

Пример готового плана — content/example/PLAN.md.

Создание нового проекта

Проект создаётся командами с флагом --init — они формируют структуру и общие ресурсы автоматически:

# только документ DOCX
node docx/src/cli.js --content content/<проект>/docx --init

# только презентация PPTX
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init

# оба генератора (каталог content/<проект>/assets/ создаётся первым вызовом
# и переиспользуется вторым)

После создания отредактируйте config.yaml и Markdown; общие ресурсы (титульный лист, задники, изображения, .puml) положите в content/<проект>/assets/.

Сборка

# Документ DOCX
node docx/src/cli.js --content content/<проект>/docx --check
node docx/src/cli.js --content content/<проект>/docx

# Презентация PPTX
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --check
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml

Результат: content/<проект>/<проект>.docx или content/<проект>/<проект>.pptx (имя и путь задаются ключом output в config.yaml). После правок исходников пересобирайте файлы.

Требования

• Node.js 18+, зависимости устанавливаются командой npm install в docx/ и pptx/.
• Java 11+ и файл tools/plantuml.jar — для рендеринга схем PlantUML (.puml).

Правила

• Для сборки документа не редактируйте код генераторов — меняйте config.yaml и Markdown проекта.
• Не коммитьте содержимое content/, кроме content/example/.
• Не храните ресурсы внутри docx/ и pptx/ — общие файлы живут в content/<проект>/assets/.