18 KiB
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.