SSAUGenerator/docx/AGENTS.md

AGENTS.md — генератор DocxGenerator

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

Документ создан и для людей, и для ИИ-агентов: он описывает CLI, формат контента, схему конфига и порядок сборки .exe.

---

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

• Windows (собранный .exe под win-x64).
• Node.js только для сборки .exe из исходников. Конечному пользователю Node.js не нужен.
• Готовые PNG вставляются без внешних зависимостей. Для рендеринга PlantUML (.puml) нужны установленная Java (JRE 11+) и файл plantuml.jar (см. п. 4, plantuml).

2. Состав дистрибутива

DocxGenerator.exe              # исполняемый файл
config.yaml              # настройки (создаётся автоматически при первом запуске)
content/                 # Markdown-файлы документа и ресурсы
  *.md
  assets/
    images/              # PNG для рисунков (готовятся заранее) и исходники .puml
    title-page.docx      # титульный лист (по умолчанию content/assets/title-page.docx)
tools/
  plantuml.jar           # рендерер PlantUML (для файлов .puml)
report.docx              # результат сборки (путь задаётся document.output)

Все относительные пути в config.yaml считаются от каталога самого config.yaml. Сам config.yaml и папки ищутся рядом с DocxGenerator.exe.

В монорепозитории общий plantuml.jar лежит в корне, в tools/plantuml.jar, поэтому репозиторный config.yaml задаёт plantuml.jar: ../tools/plantuml.jar. Для автономного дистрибутива положите tools/plantuml.jar рядом с .exe (значение по умолчанию при --init — tools/plantuml.jar).

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

DocxGenerator [опции]

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

Поведение:

• Если config.yaml не найден, инструмент сам создаёт config.yaml, примеры content/*.md и assets/images/placeholder.png, печатает подсказку и завершается.
• --check не пишет DOCX, но сообщает обо всех ошибках (битые ссылки, выход [@n] за границы списка источников, отсутствующие картинки и т.п.).

Типичный цикл работы:

.\DocxGenerator.exe --init        # первый запуск: получить шаблон
# ... правим config.yaml и content/*.md ...
.\DocxGenerator.exe --check       # проверить
.\DocxGenerator.exe               # собрать report.docx

4. Схема config.yaml

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

document

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

Титульный лист. Берётся готовый DOCX по пути document.titlePage и склеивается перед документом; между титульником и основным текстом вставляется разрыв страницы. При --init создаётся пример content/assets/title-page.docx — замените его своим. Значение null отключает титульный лист.

paths

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

output

Путь и имя выходного .docx задаются ключом document.output (по умолчанию report.docx). Путь считается от каталога config.yaml и может быть переопределён флагом --output.

page

width, height (DXA, 1/20 pt), margins: {left,right,top,bottom} (twips). A4 и поля СТО заданы по умолчанию.

typography

Ключ	Смысл
font	гарнитура (по умолчанию Times New Roman)
sizeBody / sizeTable / sizeSmall	размеры в half-points (28 = 14 pt)
lineSpacing	множитель межстрочного интервала (1.5 = полуторный)
color	цвет текста (hex, без #)
useBold	разрешить полужирный (СТО: false)
allowEmphasis	разрешить курсив (СТО: false)

headings

Интервалы/выравнивание для struct, section, subsection, point (twips).

captions

figure, table, tableContinue — префиксы и тире подписей (Рисунок, Таблица, —).

lists

bulletChar, letterSuffix, numberSuffix, nestedLevelStep, forbiddenLetters.

numbering

figures, tables, formulas: global (сквозная по документу) или section (в пределах раздела, вид 1.1). Приложения всегда имеют префикс буквы (А.1).

formula

spacingBeforeAfter, whereTabPosition.

table

font, size, borderColor, borderSize, cellMargins: {top,bottom,left,right}, headerFill, cellFill.

figure

maxWidth (px; null — по ширине полосы), maxHeight (px).

plantuml

Генерация рисунков из исходников PlantUML (см. п. 5, «Рисунки»).

Ключ	Тип	Смысл
enabled	bool	включить рендеринг .puml; false — считать ошибкой при наличии .puml
java	string	исполняемый файл Java; 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	таймаут рендера одной диаграммы, мс

Ошибки рендера (нет jar, нет Java, синтаксическая ошибка) — фатальные: сборка прекращается с кодом выхода 1. Требуется установленная Java (JRE 11+) и файл plantuml.jar; для части типов диаграмм нужен Graphviz либо встроенный Smlayout.

pageNumber

align, format, startFrom.

toc

enabled (bool), title, depth (1..3). Оглавление вставляется записью sections: [{ type: toc }].

bibliography / citation / appendix

bibliography.title, citation: {bracketOpen,bracketClose,pagePrefix}, appendix: {labelPrefix, forbiddenLetters}.

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

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

sections:
  - { type: toc }                                        # поле оглавления
  - { file: content/01-introduction.md, type: structural, title: Введение }
  - { file: content/02-main.md,         type: numbered } # # = 1, ## = 1.1, ### = 1.1.1
  - { file: content/03-conclusion.md,   type: structural, title: Заключение }
  - { file: content/04-bibliography.md, type: bibliography }
  - { file: content/05-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 заголовок берётся из конфига, а заголовки внутри файла рендерятся как обычные заголовки без номера.

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

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

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

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

Таблицы

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

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

Рисунки

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

file — относительно config.paths.assets. Если файла нет — предупреждение, подпись всё равно выводится.

PlantUML. Если file оканчивается на .puml (.plantuml, .pu, .iuml), то файл считается исходником PlantUML: инструмент рендерит его в PNG через локальный plantuml.jar (см. plantuml в конфиге) и вставляет результат как обычный рисунок. Нумерация, ссылки @fig:id и примечания работают так же. Пример:

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

Ошибка рендера — фатальная (код выхода 1), --check тоже рендерит .puml.

Подписи по СТО. Подпись ставится под рисунком по центру: Рисунок N — Наименование (с прописной буквы, без точки в конце). Если на рисунке обозначены отдельные детали, пояснительные данные размещают над подписью и оформляют перечислением а), б), в) — именно так, как показано в примере выше. Если рисунок общий и пояснять нечего, указывают только подпись Рисунок N — Наименование, а тело директивы оставляют пустым:

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

В приложениях номер рисунка получает префикс буквы: Рисунок А.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. Проверка и ошибки

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

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

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

7. Сборка .exe из исходников

npm install
npm run build:exe      # -> DocxGenerator.exe в корне (target node24-win-x64)
npm run generate       # локальная сборка (node src/cli.js)
npm run check          # проверка конфига и ссылок

Упаковка выполняется через @yao-pkg/pkg. Чтобы уменьшить размер, можно добавить --compress Brotli в команду build:exe.

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

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

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

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