SSAUGenerator/docx/AGENTS.md

AGENTS.md — работа с документом DOCX

Генератор docx/ собирает отчёт в формате DOCX из обычных Markdown-файлов по фиксированному дизайну СТО 02068410-004-2018. Этот файл — инструкция агенту по созданию и правке конкретного документа. Поведение полностью задаётся config.yaml проекта, менять код генератора не нужно.

1. Требования

• Node.js 18+, зависимости ставятся командой npm install в папке docx/.
• Windows/macOS/Linux.
• Готовые PNG вставляются без внешних зависимостей. Для рендеринга PlantUML (.puml) нужны Java 11+ и файл plantuml.jar (см. plantuml в конфиге).

2. Раскладка проекта

Проект лежит в content/<проект>/docx/ рядом с config.yaml:

content/<проект>/
├── assets/               # общие ресурсы проекта (общие с pptx)
│   ├── title-page.docx   # титульный лист
│   └── images/           # PNG-рисунки и исходники .puml
└── docx/
    ├── config.yaml       # настройки документа
    ├── 01-introduction.md
    ├── 02-*.md
    └── 05-bibliography.md

Все относительные пути в config.yaml считаются от каталога самого config.yaml. Если ресурсы общие с презентацией, указывайте их через ../assets (например, paths.assets: ../assets, document.titlePage: ../assets/title-page.docx).

Отчёт собирается в папку проекта и называется по имени проекта: content/<проект>/<проект>.docx. Значение ключа document.output при такой раскладке — ../<проект>.docx.

Структуру проекта создавайте командой --init: она формирует config.yaml, примеры *.md и общий каталог content/<проект>/assets/ (титульный лист, изображения), который используется и генератором pptx.

Готовый пример со всеми возможностями — content/example/docx/.

3. Командная строка

Из корня репозитория:

node docx/src/cli.js [опции]

  --config <путь>   путь к config.yaml (по умолчанию config.yaml в текущем каталоге)
  --content <dir>   каталог проекта: config.yaml, *.md и assets/ (по умолчанию текущий)
  --output <путь>   переопределить путь выходного .docx
  --check           только проверить конфиг и ссылки, без записи файла
  --init            создать шаблон config.yaml/*.md/assets и выйти
  --verbose         подробный вывод
  --version         показать версию
  --help            справка

Типичный цикл:

node docx/src/cli.js --content content/<проект>/docx --init    # создать структуру проекта
node docx/src/cli.js --content content/<проект>/docx --check   # проверить
node docx/src/cli.js --content content/<проект>/docx           # собрать

После любого изменения исходников (config.yaml, *.md, ресурсов assets/) пересоберите документ, чтобы результат соответствовал исходникам.

Если config.yaml не найден, инструмент сам создаёт шаблон (config.yaml, примеры Markdown и общий assets/) и завершается.

4. Схема config.yaml

Любой ключ можно опустить — берётся значение по умолчанию (см. docx/src/config/defaults.js).

document

Ключ	Тип	Смысл
output	string	путь выходного .docx (относительно config.yaml)
titlePage	string/null	путь к готовому title-page.docx; null — без титульника
features.updateFields	bool	обновлять поля (в т.ч. оглавление) при открытии в Word

Титульный лист склеивается перед документом, между ним и текстом вставляется разрыв страницы. При --init создаётся пример assets/title-page.docx.

paths

Ключ	Смысл
assets	корень ресурсов; file=images/x.png в директивах ищется здесь

Структура и оформление

Раздел	Назначение
page	width, height (DXA), margins (twips)
typography	font, sizeBody/sizeTable/sizeSmall, lineSpacing, color, useBold, allowEmphasis, language
headings	интервалы/выравнивание struct, section, subsection, point
captions	префиксы и тире подписей figure, table, tableContinue
lists	bulletChar, letterSuffix, numberSuffix, nestedLevelStep, forbiddenLetters
numbering	figures, tables, formulas: global или section
formula	spacingBeforeAfter, whereTabPosition
table	font, size, borderColor, borderSize, cellMargins, headerFill, cellFill
figure	maxWidth (px, null — по ширине), maxHeight (px)
pageNumber	align, format, startFrom
toc	enabled, title, depth (1..3)
bibliography	title
citation	bracketOpen, bracketClose, pagePrefix
appendix	labelPrefix, forbiddenLetters

plantuml

Ключ	Тип	Смысл
enabled	bool	включить рендеринг .puml; false — считать ошибкой
java	string	auto — %JAVA_HOME%\bin\java, иначе java из PATH
jar	string	путь к plantuml.jar (относительно config.yaml)
format	string	только png
charset	string	кодировка исходника (по умолчанию UTF-8)
cache	bool	не перерисовывать неизменённый исходник
cacheDir	string	каталог кэша PNG (относительно config.yaml)
timeoutMs	int	таймаут рендера одной диаграммы, мс

Общий plantuml.jar репозитория лежит в tools/plantuml.jar; из проекта путь вида ../../../tools/plantuml.jar. Ошибки рендера (нет jar, нет Java, синтаксическая ошибка) — фатальные: сборка останавливается с кодом 1.

sections — структура документа

Упорядоченный список частей:

sections:
  - { type: toc }                                          # поле оглавления
  - { file: 01-introduction.md, type: structural, title: Введение }
  - { file: 02-main.md,         type: numbered }           # # = 1, ## = 1.1, ### = 1.1.1
  - { file: 04-conclusion.md,   type: structural, title: Заключение }
  - { file: 05-bibliography.md, type: bibliography }
  - { file: 06-appendix-a.md,   type: appendix, letter: А, title: Приложение }

type	Поведение
toc	вставляет оглавление (не требует file)
structural	ненумерованный раздел (Введение/Заключение): заголовок = title, ЗАГЛАВНЫМИ, по центру, с новой страницы
numbered	нумеруемый раздел; # = раздел, ##/### = подраздел/пункт
bibliography	список источников; нумеруется автоматически
appendix	приложение: заголовок «ПРИЛОЖЕНИЕ » + title, буквенный префикс у рисунков/таблиц

5. Формат контента

Заголовки

В файле type: numbered:

# НАЗВАНИЕ РАЗДЕЛА        -> 1 НАЗВАНИЕ РАЗДЕЛА (с новой страницы)
## Подраздел             -> 1.1 Подраздел
### Пункт                -> 1.1.1 Пункт

Номера подставляются автоматически (Word-numbering). В structural/appendix заголовок берётся из title, а заголовки внутри файла рендерятся без номера.

Абзацы и списки

Обычные абзацы и списки Markdown. Пример:

- первый пункт;
- второй пункт:
  1. вложенный пункт (выведется как «а) вложенный пункт»);
  2. ещё один.

Маркер вложенности выбирается автоматически: тире → а) → 1). Полужирный и курсив по умолчанию игнорируются (СТО).

Таблицы

• Обычная GFM-таблица без директивы — таблица без подписи и номера.
• С подписью и автономером — директива ::: table:

::: table "Название таблицы" id=params note="примечание"
| Параметр | Значение |
|---|---|
| A | 1 |
| B | 2 |
:::

Рисунки

::: figure "Название рисунка" id=arch file=images/arch.png
а) первый поясняемый элемент;
б) второй поясняемый элемент.
:::

file — относительно paths.assets. Если файла нет — предупреждение, подпись всё равно выводится. Подпись ставится под рисунком по центру: Рисунок N — Наименование. Если пояснять нечего, тело директивы оставляют пустым:

::: figure "Общая схема системы" id=common file=images/common.png
:::

PlantUML. Если file оканчивается на .puml (.plantuml, .pu, .iuml), файл рендерится в PNG через plantuml.jar и вставляется как обычный рисунок:

::: figure "Диаграмма последовательности" id=seq file=images/seq.puml
а) запрос клиента;
б) ответ сервера.
:::

Ошибка рендера фатальна, --check тоже рендерит .puml.

В приложениях номер рисунка получает префикс буквы: Рисунок А.1 — Наименование.

Формулы

::: formula id=line
y = a*x + b
:::

::: where
y — результат;
x — аргумент;
a — коэффициент.
:::

Поддерживается простой синтаксис: ^ (степень), _ (индекс), / (дробь). Номер формулы ставится автоматически справа.

Примечания и термины

::: note
Текст примечания.
:::

::: notes
- первое примечание;
- второе примечание.
:::

::: definitions
Термин — определение;
Ещё термин — определение.
:::

Разрыв страницы

::: pagebreak
:::

Тематический разрыв --- также трактуется как разрыв страницы.

Ссылки на источники

[@1] — ссылка на 1-й источник, [@1, с. 96] — с номером страницы. Список источников — Markdown-список в файле type: bibliography; порядок строк = номера. Ссылка вне диапазона — ошибка в --check.

Перекрёстные ссылки

@fig:id, @tbl:id, @eq:id подставляют актуальный номер рисунка/таблицы/ формулы (например 2, 1.1, А.1). id задаётся в директиве.

Блоки кода

Fenced-блоки ``` игнорируются с предупреждением (функция листингов удалена).

6. Проверка и ошибки

--check проверяет:

• корректность config.yaml (типы, существование файлов, буквы приложений);
• наличие всех sections[].file;
• существование меток в @fig/@tbl/@eq;
• диапазон ссылок [@n];
• рендеринг всех ::: figure ... file=*.puml.

Ошибки печатаются списком и возвращают код выхода 1. Предупреждения (например, отсутствующий PNG) не останавливают сборку; ошибки PlantUML — фатальные.

7. Подготовка диаграмм

Готовые PNG кладутся в общий каталог ресурсов (content/<проект>/assets/images/). Исходники PlantUML (.puml) кладутся туда же и указываются в ::: figure ... file=images/<имя>.puml. Диаграммы других форматов (Mermaid, draw.io) готовятся внешними средствами и вставляются как PNG.

8. Замечания по дизайну

• Дизайн фиксирован под СТО 02068410-004-2018; меняются только параметры из config.yaml.
• Полужирный и курсив по умолчанию отключены (typography.useBold, allowEmphasis).
• Оглавление — поле Word; при открытии нажмите «Обновить поле» либо включите document.features.updateFields.