Reorganize docs: README as hub + per-group guides

Split monolithic README into: - README.md — concise hub with quick start and group links - docs/epf-guide.md — EPF skills guide (content from old README) - docs/mxl-guide.md — MXL skills guide (new scenarios and examples) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-11 00:14:56 +03:00 · 2026-02-08 21:36:44 +03:00
parent 56b1458545
commit 3819a5f7af
3 changed files with 267 additions and 150 deletions
@@ -0,0 +1,128 @@
+# Внешние обработки (EPF)
+
+Навыки группы `/epf-*` позволяют создавать, модифицировать и собирать внешние обработки 1С:Предприятия 8.3 (`.epf`) из XML-исходников, не запоминая детали формата.
+
+## Навыки
+
+| Навык | Параметры | Описание |
+|-------|-----------|----------|
+| `/epf-init` | `<Name> [Synonym]` | Создать новую обработку (корневой XML + модуль объекта) |
+| `/epf-add-form` | `<ProcessorName> <FormName> [Synonym]` | Добавить управляемую форму |
+| `/epf-add-template` | `<ProcessorName> <TemplateName> <TemplateType>` | Добавить макет (HTML, Text, SpreadsheetDocument, BinaryData) |
+| `/epf-add-help` | `<ProcessorName>` | Добавить встроенную справку (Help.xml + HTML) |
+| `/epf-remove-form` | `<ProcessorName> <FormName>` | Удалить форму |
+| `/epf-remove-template` | `<ProcessorName> <TemplateName>` | Удалить макет |
+| `/epf-build` | `<ProcessorName>` | Собрать EPF из XML (через 1cv8.exe) |
+| `/epf-dump` | `<EpfFile>` | Разобрать EPF в XML (через 1cv8.exe) |
+| `/epf-bsp-init` | `<ProcessorName> <Вид>` | Добавить регистрацию БСП (СведенияОВнешнейОбработке) |
+| `/epf-bsp-add-command` | `<ProcessorName> <Идентификатор>` | Добавить команду в дополнительную обработку БСП |
+
+Навыки удаления (`epf-remove-*`) не вызываются Claude автоматически — только по явной команде пользователя.
+
+## Сценарии использования
+
+Не обязательно запоминать команды и параметры. Просто опишите задачу своими словами — Claude сам подберёт нужные навыки.
+
+### Обработка с формой
+
+Типичная обработка для манипуляций с данными — форма для пользователя, модуль объекта для логики.
+
+```
+> Создай обработку ЗагрузкаПрайса с формой
+```
+
+Claude выполнит `/epf-init` и `/epf-add-form` с правильными параметрами.
+
+### Внешняя печатная форма
+
+Обработка с макетом табличного документа, подключаемая через механизм дополнительных обработок БСП к конкретному документу.
+
+```
+> Создай внешнюю печатную форму для документа Реализация. Макет — табличный документ.
+```
+
+Claude создаст обработку, добавит макет SpreadsheetDocument, вызовет `/epf-bsp-init` с видом ПечатнаяФорма и назначением, сгенерирует `СведенияОВнешнейОбработке()` и процедуру `Печать()`.
+
+### Доработка существующей обработки
+
+```
+> Добавь справку с описанием как пользоваться обработкой
+```
+
+Claude вызовет `/epf-add-help` и предложит отредактировать HTML.
+
+```
+> Добавь ещё одну команду печати — накладная
+```
+
+Claude вызовет `/epf-bsp-add-command`, добавит команду в `СведенияОВнешнейОбработке()` и блок обработки в процедуру `Печать()`.
+
+```
+> Собери
+```
+
+Claude вызовет `/epf-build`.
+
+### Примеры слеш-команд
+
+Слеш-команды работают для случаев, когда хочется точного контроля:
+
+```
+> /epf-init МояОбработка "Моя обработка"
+> /epf-add-form МояОбработка Форма
+> /epf-add-template МояОбработка Макет HTML
+> /epf-add-help МояОбработка
+> /epf-build МояОбработка
+```
+
+## Структура каталогов
+
+После `/epf-init` создаётся структура:
+
+```
+src/
+├── МояОбработка.xml                          # Корневой файл метаданных
+└── МояОбработка/
+    └── Ext/
+        └── ObjectModule.bsl                  # Модуль объекта
+```
+
+После `/epf-add-form` и `/epf-add-template`:
+
+```
+src/
+├── МояОбработка.xml
+└── МояОбработка/
+    ├── Ext/
+    │   └── ObjectModule.bsl
+    ├── Forms/
+    │   ├── Форма.xml                         # Метаданные формы
+    │   └── Форма/
+    │       └── Ext/
+    │           ├── Form.xml                  # Описание формы
+    │           └── Form/
+    │               └── Module.bsl            # Модуль формы
+    └── Templates/
+        ├── Макет.xml                         # Метаданные макета
+        └── Макет/
+            └── Ext/
+                └── Template.html             # Содержимое макета
+```
+
+Первая добавленная форма автоматически становится основной (DefaultForm). Флаг `--main` нужен только для переназначения основной формы на другую.
+
+## Технические детали
+
+- Все XML-файлы создаются в **UTF-8 с BOM** (как в реальных выгрузках 1С)
+- PowerShell-скрипты используют `System.Xml.XmlDocument` для модификации корневого XML
+- UUID генерируются через `[guid]::NewGuid()`
+- ClassId обработки фиксирован: `c3831ec8-d8d5-4f93-8a22-f9bfae07327f`
+- Порядок элементов в `ChildObjects`: TabularSections → Forms → Templates
+- Первая форма автоматически назначается основной (DefaultForm)
+- Навыки БСП (`epf-bsp-*`) не используют скрипты — Claude модифицирует код напрямую через Read/Edit
+
+## Спецификации
+
+- [XML-формат выгрузки обработок](1c-xml-format-spec.md) — структура XML-файлов, namespace, элементы форм
+- [Встроенная справка](1c-help-spec.md) — Help.xml, HTML-страницы, кнопка справки на форме
+- [Сборка и разборка EPF](build-spec.md) — команды `1cv8.exe`, параметры, коды возврата
@@ -0,0 +1,96 @@
+# Табличный документ (MXL)
+
+Навыки группы `/mxl-*` позволяют анализировать, создавать и модифицировать макеты табличных документов 1С — основной формат печатных форм в конфигурациях 1С:Предприятия.
+
+## Навыки
+
+| Навык | Параметры | Описание |
+|-------|-----------|----------|
+| `/mxl-info` | `<TemplatePath>` или `<ProcessorName> <TemplateName>` | Анализ структуры: области, параметры, наборы колонок |
+| `/mxl-validate` | `<TemplatePath>` или `<ProcessorName> <TemplateName>` | Валидация: индексы, ссылки, границы |
+| `/mxl-compile` | `<JsonPath> <OutputPath>` | Компиляция макета из JSON-определения в Template.xml |
+| `/mxl-decompile` | `<TemplatePath> [OutputPath]` | Декомпиляция Template.xml в JSON-определение |
+
+## Сценарии использования
+
+### Создание макета печатной формы с нуля
+
+Вы описываете макет словами или через JSON DSL, Claude компилирует его в Template.xml.
+
+```
+> Создай макет накладной М-11: шапка с реквизитами организации и склада,
+> таблица с колонками (номер, наименование, единица, количество, цена, сумма),
+> итоговая строка, подписи.
+```
+
+Claude напишет JSON-определение с областями, параметрами и стилями, вызовет `/mxl-compile` для генерации XML, затем `/mxl-validate` и `/mxl-info` для проверки.
+
+Рабочий цикл:
+1. Claude пишет JSON-определение макета
+2. `/mxl-compile` → Template.xml
+3. `/mxl-validate` → проверка корректности
+4. `/mxl-info` → верификация структуры (области, параметры)
+
+### Анализ существующего макета
+
+Быстрый обзор структуры макета без чтения тысяч строк XML.
+
+```
+> Покажи структуру макета ПФ_MXL_М11
+```
+
+Claude вызовет `/mxl-info` и выведет области, параметры и наборы колонок. С флагом `-WithText` покажет ещё и текстовое содержимое ячеек (заголовки колонок, надписи).
+
+### Модификация существующего макета
+
+Декомпиляция в JSON, правка, компиляция обратно.
+
+```
+> Добавь в макет М-11 колонку "Примечание"
+```
+
+Claude вызовет `/mxl-decompile` для получения JSON, добавит колонку в определение, вызовет `/mxl-compile` и `/mxl-validate`.
+
+Рабочий цикл:
+1. `/mxl-decompile` → JSON из существующего Template.xml
+2. Claude модифицирует JSON (добавляет области, меняет стили, параметры)
+3. `/mxl-compile` → обновлённый Template.xml
+4. `/mxl-validate` → проверка
+
+> **Ограничения:** Этот сценарий подразумевает полную перегенерацию макета, а не точечную правку XML. Поэтому diff может показать больше изменений, чем фактическая доработка. Кроме того, DSL пока поддерживает не все конструкции табличного документа — для сложных макетов с рисунками, штрихкодами или нестандартным форматированием часть информации может быть потеряна при round-trip.
+
+### Валидация макета
+
+Проверка структурной корректности после любых изменений.
+
+```
+> Проверь макет ПФ_MXL_М11
+```
+
+Claude вызовет `/mxl-validate`, который проверит индексы палитр, ссылки на наборы колонок, границы областей и другие структурные зависимости.
+
+### Примеры слеш-команд
+
+```
+> /mxl-info src/МояОбработка/Templates/ПФ_MXL_Накладная/Ext/Template.xml
+> /mxl-info МояОбработка ПФ_MXL_Накладная
+> /mxl-validate МояОбработка ПФ_MXL_Накладная
+> /mxl-compile макет.json src/МояОбработка/Templates/ПФ_MXL_Накладная/Ext/Template.xml
+> /mxl-decompile src/МояОбработка/Templates/ПФ_MXL_Накладная/Ext/Template.xml макет.json
+```
+
+## Связь с EPF-навыками
+
+Макет табличного документа — часть обработки. Типичный сценарий создания печатной формы:
+
+1. `/epf-init` — создать обработку
+2. `/epf-add-template` — добавить макет SpreadsheetDocument (с именем `ПФ_MXL_...`)
+3. `/mxl-compile` — заполнить макет содержимым из JSON-определения
+4. `/epf-bsp-init` — добавить регистрацию БСП с видом ПечатнаяФорма
+5. `/epf-bsp-add-command` — добавить команду печати
+6. `/epf-build` — собрать EPF
+
+## Спецификации
+
+- [Табличный документ (MXL)](1c-spreadsheet-spec.md) — XML-формат SpreadsheetDocument, совместимость версий
+- [MXL DSL](mxl-dsl-spec.md) — JSON-формат описания макета для `/mxl-compile` и `/mxl-decompile`