mirror of
https://github.com/StepanovPlaton/SSAUGenerator.git
synced 2026-10-31 10:18:29 +04:00
first commit
This commit is contained in:
324
AGENTS.md
Normal file
324
AGENTS.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# AGENTS.md — генератор lab-gen
|
||||
|
||||
`lab-gen` — автономный инструмент, который собирает отчёт в формате **DOCX** из обычных
|
||||
**Markdown**-файлов по фиксированному дизайну СТО 02068410-004-2018. Поведение полностью
|
||||
задаётся файлом `config.yaml`.
|
||||
|
||||
Документ создан и для людей, и для ИИ-агентов: он описывает CLI, формат контента, схему
|
||||
конфига и порядок сборки `.exe`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Требования
|
||||
|
||||
- Windows (собранный `.exe` под `win-x64`).
|
||||
- Node.js **только для сборки** `.exe` из исходников. Конечному пользователю Node.js не нужен.
|
||||
- Никаких Java/Chrome/интернета: инструмент не рендерит диаграммы, а вставляет готовые PNG.
|
||||
|
||||
## 2. Состав дистрибутива
|
||||
|
||||
```
|
||||
lab-gen.exe # исполняемый файл
|
||||
config.yaml # настройки (создаётся автоматически при первом запуске)
|
||||
content/ # Markdown-файлы документа и ресурсы
|
||||
*.md
|
||||
assets/
|
||||
images/ # PNG для рисунков (готовятся заранее)
|
||||
title-page.docx # титульный лист (по умолчанию content/assets/title-page.docx)
|
||||
report.docx # результат сборки (путь задаётся document.output)
|
||||
```
|
||||
|
||||
Все относительные пути в `config.yaml` считаются **от каталога самого `config.yaml`**.
|
||||
Сам `config.yaml` и папки ищутся **рядом с `lab-gen.exe`**.
|
||||
|
||||
## 3. Командная строка
|
||||
|
||||
```
|
||||
lab-gen [опции]
|
||||
|
||||
--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]` за границы
|
||||
списка источников, отсутствующие картинки и т.п.).
|
||||
|
||||
Типичный цикл работы:
|
||||
|
||||
```powershell
|
||||
.\lab-gen.exe --init # первый запуск: получить шаблон
|
||||
# ... правим config.yaml и content/*.md ...
|
||||
.\lab-gen.exe --check # проверить
|
||||
.\lab-gen.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).
|
||||
|
||||
### 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 — структура документа
|
||||
Упорядоченный список частей:
|
||||
|
||||
```yaml
|
||||
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` | приложение: заголовок «ПРИЛОЖЕНИЕ <letter>» + `title`, нумерация рисунков/таблиц с префиксом буквы |
|
||||
|
||||
## 5. Формат контента
|
||||
|
||||
### Заголовки
|
||||
|
||||
В файле `type: numbered`:
|
||||
|
||||
```md
|
||||
# НАЗВАНИЕ РАЗДЕЛА -> 1 НАЗВАНИЕ РАЗДЕЛА (с новой страницы)
|
||||
## Подраздел -> 1.1 Подраздел
|
||||
### Пункт -> 1.1.1 Пункт
|
||||
```
|
||||
|
||||
Номера подставляются автоматически (Word-numbering). В `structural`/`appendix` заголовок
|
||||
берётся из конфига, а заголовки внутри файла рендерятся как обычные заголовки без номера.
|
||||
|
||||
### Абзацы, списки
|
||||
|
||||
Обычные абзацы и списки Markdown. Списки:
|
||||
|
||||
```md
|
||||
- первый пункт;
|
||||
- второй пункт:
|
||||
1. вложенный пункт (выведется как «а) вложенный пункт»);
|
||||
2. ещё один.
|
||||
```
|
||||
|
||||
Маркер вложенности выбирается автоматически: тире → `а)` → `1)`. Полужирный/курсив по
|
||||
умолчанию игнорируются (СТО).
|
||||
|
||||
### Таблицы
|
||||
|
||||
- Обычная GFM-таблица без директивы — таблица **без подписи и номера**.
|
||||
- С подписью и автономером — директива `::: table`:
|
||||
|
||||
```md
|
||||
::: table "Название таблицы" id=params note="примечание"
|
||||
| Параметр | Значение |
|
||||
|---|---|
|
||||
| A | 1 |
|
||||
| B | 2 |
|
||||
:::
|
||||
```
|
||||
|
||||
### Рисунки
|
||||
|
||||
```md
|
||||
::: figure "Название рисунка" id=arch file=images/arch.png
|
||||
а) первый поясняемый элемент;
|
||||
б) второй поясняемый элемент.
|
||||
:::
|
||||
```
|
||||
|
||||
`file` — относительно `config.paths.assets`. Если файла нет — предупреждение, подпись
|
||||
всё равно выводится.
|
||||
|
||||
**Подписи по СТО.** Подпись ставится **под** рисунком по центру: `Рисунок N — Наименование`
|
||||
(с прописной буквы, без точки в конце). Если на рисунке обозначены отдельные детали,
|
||||
пояснительные данные размещают **над подписью** и оформляют перечислением `а)`, `б)`, `в)` —
|
||||
именно так, как показано в примере выше. Если рисунок общий и пояснять нечего, указывают
|
||||
только подпись `Рисунок N — Наименование`, а тело директивы оставляют пустым:
|
||||
|
||||
```md
|
||||
::: figure "Общая схема системы" id=common file=images/common.png
|
||||
:::
|
||||
```
|
||||
|
||||
В приложениях номер рисунка получает префикс буквы: `Рисунок А.1 — Наименование`.
|
||||
|
||||
### Формулы
|
||||
|
||||
```md
|
||||
::: formula id=line
|
||||
y = a*x + b
|
||||
:::
|
||||
|
||||
::: where
|
||||
y — результат;
|
||||
x — аргумент;
|
||||
a — коэффициент.
|
||||
:::
|
||||
```
|
||||
|
||||
В формулах поддерживается простой синтаксис: `^` (степень), `_` (индекс), `/` (дробь).
|
||||
Номер формулы ставится автоматически справа.
|
||||
|
||||
### Примечания и термины
|
||||
|
||||
```md
|
||||
::: note
|
||||
Текст примечания.
|
||||
:::
|
||||
|
||||
::: notes
|
||||
- первое примечание;
|
||||
- второе примечание.
|
||||
:::
|
||||
|
||||
::: definitions
|
||||
Термин — определение;
|
||||
Ещё термин — определение.
|
||||
:::
|
||||
```
|
||||
|
||||
### Разрыв страницы
|
||||
|
||||
```md
|
||||
::: pagebreak
|
||||
:::
|
||||
```
|
||||
|
||||
Тематический разрыв `---` также трактуется как разрыв страницы.
|
||||
|
||||
### Ссылки на источники
|
||||
|
||||
`[@1]` — ссылка на 1-й источник, `[@1, с. 96]` — с номером страницы. Список источников —
|
||||
это Markdown-список в файле `type: bibliography`; порядок строк = номера источников.
|
||||
Ссылка вне диапазона — ошибка в `--check`.
|
||||
|
||||
### Перекрёстные ссылки
|
||||
|
||||
`@fig:id`, `@tbl:id`, `@eq:id` подставляют актуальный номер рисунка/таблицы/формулы
|
||||
(например `2`, `1.1`, `А.1`). `id` задаётся в директиве.
|
||||
|
||||
### Блоки кода
|
||||
|
||||
Функция листингов удалена: fenced-блоки ``` игнорируются с предупреждением.
|
||||
|
||||
## 6. Проверка и ошибки
|
||||
|
||||
`lab-gen --check` проверяет:
|
||||
|
||||
- корректность `config.yaml` (типы, существование файлов, допустимые буквы приложений);
|
||||
- наличие всех `sections[].file`;
|
||||
- существование меток в `@fig/@tbl/@eq`;
|
||||
- диапазон ссылок `[@n]`.
|
||||
|
||||
Ошибки печатаются списком и возвращают код выхода `1`. Предупреждения (например,
|
||||
отсутствующий PNG) не останавливают сборку.
|
||||
|
||||
## 7. Сборка `.exe` из исходников
|
||||
|
||||
```powershell
|
||||
npm install
|
||||
npm run build:exe # -> lab-gen.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, Mermaid, draw.io, редактор).
|
||||
|
||||
## 8. Замечания по дизайну
|
||||
|
||||
- Дизайн фиксирован под СТО 02068410-004-2018; меняются только параметры из `config.yaml`.
|
||||
- Полужирный и курсив по умолчанию отключены (`typography.useBold`, `allowEmphasis`).
|
||||
- Шрифт, размеры, интервалы, отступы и подписи настраиваются в конфиге.
|
||||
- Оглавление — поле Word; при открытии нажмите «Обновить поле», либо включено
|
||||
`document.features.updateFields`.
|
||||
Reference in New Issue
Block a user