From 37f39a5022db89a69254779686aaf15b02522586 Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Fri, 17 Jul 2026 20:42:13 +0300 Subject: [PATCH] =?UTF-8?q?docs(mxl):=20=D0=B2=D0=BD=D0=B5=D1=81=D1=82?= =?UTF-8?q?=D0=B8=20DSL-=D1=81=D0=BF=D0=B5=D0=BA=D1=83=20=D0=B2=20=D0=BD?= =?UTF-8?q?=D0=B0=D0=B2=D1=8B=D0=BA,=20=D1=83=D0=B1=D1=80=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20=D1=81=D1=81=D1=8B=D0=BB=D0=BA=D1=83=20=D0=BD=D0=B0=20?= =?UTF-8?q?docs/=20(#40)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md навыков ссылались на docs/mxl-dsl-spec.md, которого нет в порт-ветках — агент искал документацию внутри папки навыка. - mxl-compile: спека внесена как reference/dsl-spec.md (self-contained), SKILL.md ссылается на неё относительно навыка + добавлен empty в правила - mxl-decompile: спеку не тянет (нужна только для авторинга JSON), убраны описания внутренностей скрипта — оставлено «как применять» Co-Authored-By: Claude Opus 4.8 --- .claude/skills/mxl-compile/SKILL.md | 11 +- .../skills/mxl-compile/reference/dsl-spec.md | 160 ++++++++++++++++++ .claude/skills/mxl-decompile/SKILL.md | 23 +-- 3 files changed, 171 insertions(+), 23 deletions(-) create mode 100644 .claude/skills/mxl-compile/reference/dsl-spec.md diff --git a/.claude/skills/mxl-compile/SKILL.md b/.claude/skills/mxl-compile/SKILL.md index e7de18f1..f35b8140 100644 --- a/.claude/skills/mxl-compile/SKILL.md +++ b/.claude/skills/mxl-compile/SKILL.md @@ -34,16 +34,16 @@ powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/mxl-compile.ps1" -J ## Рабочий процесс -1. Claude пишет JSON-определение (Write tool) → файл `.json` -2. Claude вызывает `/mxl-compile` для генерации Template.xml -3. Claude вызывает `/mxl-validate` для проверки корректности -4. Claude вызывает `/mxl-info` для верификации структуры +1. Написать JSON-определение (Write tool) → файл `.json` +2. Вызвать `/mxl-compile` для генерации Template.xml +3. Вызвать `/mxl-validate` для проверки корректности +4. Вызвать `/mxl-info` для верификации структуры **Если макет создаётся по изображению** (скриншот, скан печатной формы) — сначала вызвать `/img-grid` для наложения сетки, по ней определить границы колонок и пропорции, затем использовать `"Nx"` ширины + `"page"` для автоматического расчёта размеров. ## JSON-схема DSL -Полная спецификация формата: **`docs/mxl-dsl-spec.md`** (прочитать через Read tool перед написанием JSON). +Ниже — компактная структура и ключевые правила, достаточные для типового макета. Полные таблицы полей (все свойства шрифтов, стилей, ячеек), развёрнутый пример и ограничения формата — в **`reference/dsl-spec.md`**; нужны не всегда, читать по необходимости. Краткая структура: @@ -63,3 +63,4 @@ powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/mxl-compile.ps1" -J - `rowStyle` — автозаполнение пустот стилем (рамки по всей ширине) - Тип заполнения определяется автоматически: `param` → Parameter, `text` → Text, `template` → Template - `rowspan` — объединение строк вниз (rowStyle учитывает занятые ячейки) +- `empty` в строке — шорткат для N подряд пустых строк (`{ "empty": 3 }` = три `{}`) diff --git a/.claude/skills/mxl-compile/reference/dsl-spec.md b/.claude/skills/mxl-compile/reference/dsl-spec.md new file mode 100644 index 00000000..9320e10e --- /dev/null +++ b/.claude/skills/mxl-compile/reference/dsl-spec.md @@ -0,0 +1,160 @@ +# Спецификация MXL DSL — JSON-формат описания табличного документа + +Компактный JSON-формат для описания макетов табличных документов 1С (SpreadsheetDocument). Используется навыком `/mxl-compile` (JSON → XML). + +## Пример + +```json +{ + "columns": 10, + "defaultWidth": 30, + "columnWidths": { "1": 15, "2-8": 40, "9-10": 50 }, + + "fonts": { + "default": { "face": "Arial", "size": 10 }, + "bold": { "face": "Arial", "size": 10, "bold": true }, + "header": { "face": "Arial", "size": 14, "bold": true } + }, + + "styles": { + "default": {}, + "header": { "font": "header", "align": "center" }, + "label": { "font": "bold" }, + "bordered": { "border": "all" }, + "bordered-right": { "border": "all", "align": "right" }, + "total-right": { "font": "bold", "border": "top", "align": "right" } + }, + + "areas": [ + { + "name": "Заголовок", + "rows": [ + { "height": 20, "cells": [ + { "col": 1, "span": 10, "style": "header", "param": "ТекстЗаголовка" } + ]} + ] + }, + { + "name": "ШапкаТаблицы", + "rows": [ + { "rowStyle": "bordered", "cells": [ + { "col": 1, "text": "№" }, + { "col": 2, "span": 6, "text": "Наименование" }, + { "col": 9, "text": "Кол-во" }, + { "col": 10, "text": "Сумма" } + ]} + ] + }, + { + "name": "Строка", + "rows": [ + { "rowStyle": "bordered", "cells": [ + { "col": 1, "param": "НомерСтроки" }, + { "col": 2, "span": 6, "param": "Товар", "detail": "Номенклатура" }, + { "col": 9, "style": "bordered-right", "param": "Количество" }, + { "col": 10, "style": "bordered-right", "param": "Сумма" } + ]} + ] + }, + { + "name": "Итого", + "rows": [ + { "cells": [ + { "col": 8, "span": 2, "style": "total-right", "text": "Итого:" }, + { "col": 10, "style": "total-right", "param": "Всего" } + ]} + ] + } + ] +} +``` + +## Верхний уровень + +| Поле | Обяз. | По умолч. | Описание | +|------|:-----:|-----------|----------| +| `columns` | да | — | Количество колонок | +| `page` | нет | — | Формат страницы: `"A4-landscape"` (780), `"A4-portrait"` (540) или число. Автоматически вычисляет `defaultWidth` из суммы пропорций `"Nx"` | +| `defaultWidth` | нет | 10 | Ширина колонок по умолчанию. Игнорируется если задан `page` и все колонки используют `"Nx"` | +| `columnWidths` | нет | `{}` | Ширины колонок. Ключи 1-based: `"1"`, `"3-14"`, `"5,7,9"`. Значения: число (абсолют) или `"Nx"` (множитель от defaultWidth, напр. `"2x"`, `"0.5x"`) | +| `fonts` | нет | — | Именованные шрифты (если не задано, создаётся Arial 10) | +| `styles` | нет | `{}` | Именованные стили | +| `areas` | да | — | Массив именованных областей (порядок = порядок в документе) | + +## Шрифты (`fonts.`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `face` | `"Arial"` | Имя шрифта | +| `size` | `10` | Размер | +| `bold` | `false` | Жирный | +| `italic` | `false` | Курсив | +| `underline` | `false` | Подчёркнутый | +| `strikeout` | `false` | Зачёркнутый | + +Шрифт `"default"` используется когда стиль не указывает шрифт явно. Если не определён, создаётся автоматически (Arial 10). + +## Стили (`styles.`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `font` | `"default"` | Ссылка на имя шрифта | +| `align` | — | `left`, `center`, `right` | +| `valign` | — | `top`, `center` | +| `border` | — | Стороны рамки: `all`, `top`, `bottom`, `left`, `right`, `none`. Через запятую: `"top,bottom"` | +| `borderWidth` | `"thin"` | Толщина рамки: `thin` (1px) или `thick` (2px) | +| `wrap` | `false` | Перенос текста | +| `format` | — | Формат данных 1С: `"ЧЦ=15; ЧДЦ=2"`, `"ДФ=dd.MM.yyyy"` и т.д. | + +## Области (`areas[]`) + +| Поле | Обяз. | Описание | +|------|:-----:|----------| +| `name` | да | Имя области для `Макет.ПолучитьОбласть("Имя")` | +| `rows` | да | Массив строк | + +## Строки (`rows[]`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `height` | — | Высота строки (если не задана, используется авто) | +| `rowStyle` | — | Стиль для ВСЕХ колонок (заполняет пустоты рамками) | +| `cells` | `[]` | Массив ячеек | +| `empty` | — | Количество подряд идущих пустых строк (заменяет N отдельных `{}`) | + +Строка без `cells` и `rowStyle` → пустая строка. `{ "empty": 3 }` эквивалентно трём `{}`. + +## Ячейки (`cells[]`) + +| Поле | Обяз. | По умолч. | Описание | +|------|:-----:|-----------|----------| +| `col` | да | — | Позиция колонки (1-based) | +| `span` | нет | `1` | Объединение по горизонтали (количество колонок) | +| `rowspan` | нет | `1` | Объединение по вертикали (количество строк) | +| `style` | нет | rowStyle | Стиль ячейки (переопределяет rowStyle) | +| `param` | нет | — | Параметр заполнения | +| `detail` | нет | — | Параметр расшифровки (только с `param`) | +| `text` | нет | — | Статический текст | +| `template` | нет | — | Шаблонный текст с `[Параметр]` | + +### Тип заполнения + +Определяется автоматически по содержимому ячейки: +- `param` → fillType=Parameter +- `template` → fillType=Template +- `text` → fillType=Text +- ничего → без fillType (пустая ячейка или рамка) + +## `rowStyle` — автозаполнение + +Когда задан `rowStyle`, компилятор создаёт ячейки для ВСЕХ колонок строки. Позиции без явных ячеек заполняются пустыми ячейками с указанным стилем. Это обеспечивает сплошные рамки в табличных строках. + +Если в предыдущих строках той же области есть ячейки с `rowspan`, их колонки при автозаполнении пропускаются. + +## Ограничения + +Текущая версия не поддерживает: +- Множественные наборы колонок (`columnsID`) +- Области типа Columns / Rectangle +- Рисунки (штрихкоды, картинки) +- Фон ячеек diff --git a/.claude/skills/mxl-decompile/SKILL.md b/.claude/skills/mxl-decompile/SKILL.md index 946177e0..9faf7bc1 100644 --- a/.claude/skills/mxl-decompile/SKILL.md +++ b/.claude/skills/mxl-decompile/SKILL.md @@ -36,22 +36,9 @@ powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/mxl-decompile.ps1" Декомпиляция существующего макета для анализа или доработки: -1. Claude вызывает `/mxl-decompile` для получения JSON из Template.xml -2. Claude анализирует или модифицирует JSON (добавляет области, меняет стили) -3. Claude вызывает `/mxl-compile` для генерации нового Template.xml -4. Claude вызывает `/mxl-validate` для проверки +1. Вызвать `/mxl-decompile` для получения JSON из Template.xml +2. Проанализировать или изменить JSON (добавить области, поменять стили) +3. Вызвать `/mxl-compile` для генерации нового Template.xml +4. Вызвать `/mxl-validate` для проверки -## JSON-схема DSL - -Полная спецификация формата: **`docs/mxl-dsl-spec.md`** (прочитать через Read tool). - -## Генерация имён - -Скрипт автоматически генерирует осмысленные имена: - -- **Шрифты**: `default`, `bold`, `header`, `small`, `italic` — или описательные имена по свойствам -- **Стили**: `bordered`, `bordered-center`, `bold-right`, `border-top` и т.д. — по комбинации свойств - -## Детектирование `rowStyle` - -Если в строке есть пустые ячейки (без параметров/текста) и все они имеют одинаковый формат — этот формат распознаётся как `rowStyle`, а пустые ячейки исключаются из вывода. +Формат JSON на выходе — тот же DSL, что принимает `/mxl-compile`; его полное описание живёт в навыке `/mxl-compile`.