From 3819a5f7afc0cf7339bbddfc780efafdd00a6b60 Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Sun, 8 Feb 2026 21:36:44 +0300 Subject: [PATCH] Reorganize docs: README as hub + per-group guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 193 +++++++++++----------------------------------- docs/epf-guide.md | 128 ++++++++++++++++++++++++++++++ docs/mxl-guide.md | 96 +++++++++++++++++++++++ 3 files changed, 267 insertions(+), 150 deletions(-) create mode 100644 docs/epf-guide.md create mode 100644 docs/mxl-guide.md diff --git a/README.md b/README.md index f0496f8d..5d3dc842 100644 --- a/README.md +++ b/README.md @@ -1,173 +1,66 @@ -# 1C EPF Skills for Claude Code +# 1C Skills for Claude Code -Набор [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills) для работы с исходниками внешних обработок 1С:Предприятия 8.3. Позволяет создавать, модифицировать и собирать обработки (`.epf`) из XML-исходников, не запоминая детали формата. +Набор [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills) для работы с артефактами 1С:Предприятия 8.3. Позволяет создавать и модифицировать обработки, макеты печатных форм и другие объекты из XML-исходников, не запоминая детали формата. -## Навыки +## Быстрый старт -| Навык | Параметры | Описание | -|-------|-----------|----------| -| `/epf-init` | ` [Synonym]` | Создать новую обработку (корневой XML + модуль объекта) | -| `/epf-add-form` | ` [Synonym]` | Добавить управляемую форму | -| `/epf-add-template` | ` ` | Добавить макет (HTML, Text, SpreadsheetDocument, BinaryData) | -| `/epf-add-help` | `` | Добавить встроенную справку (Help.xml + HTML) | -| `/epf-remove-form` | ` ` | Удалить форму | -| `/epf-remove-template` | ` ` | Удалить макет | -| `/epf-build` | `` | Собрать EPF из XML (документация команды 1cv8.exe) | -| `/epf-dump` | `` | Разобрать EPF в XML (документация команды 1cv8.exe) | -| `/epf-bsp-init` | ` <Вид>` | Добавить регистрацию БСП (СведенияОВнешнейОбработке) | -| `/epf-bsp-add-command` | ` <Идентификатор>` | Добавить команду в обработку БСП | -| `/mxl-info` | `` | Анализ структуры табличного документа (области, параметры, колонки) | -| `/mxl-validate` | `` | Валидация табличного документа (индексы, ссылки, границы) | -| `/mxl-compile` | ` ` | Компиляция табличного документа из JSON-определения | -| `/mxl-decompile` | ` [OutputPath]` | Декомпиляция табличного документа в JSON-определение | - -Навыки удаления (`epf-remove-*`) не вызываются Claude автоматически — только по явной команде пользователя. - -## Как пользоваться - -Не обязательно запоминать команды и параметры. Просто опишите задачу своими словами — Claude сам подберёт нужные навыки. - -### Сценарий 1: обработка с формой - -Типичная обработка для манипуляций с данными — форма для пользователя, модуль объекта для логики. - -``` -> Создай обработку ЗагрузкаПрайса с формой -``` - -Claude выполнит `/epf-init` и `/epf-add-form` с правильными параметрами. - -### Сценарий 2: внешняя печатная форма БСП - -Обработка с макетом табличного документа, подключаемая через механизм дополнительных обработок БСП к конкретному документу. - -``` -> Создай внешнюю печатную форму для документа Реализация. Макет — табличный документ. -``` - -Claude создаст обработку, добавит макет SpreadsheetDocument, вызовет `/epf-bsp-init` с видом ПечатнаяФорма и назначением, сгенерирует `СведенияОВнешнейОбработке()` и процедуру `Печать()`. - -### Сценарий 3: доработка существующей обработки - -``` -> Добавь справку с описанием как пользоваться обработкой -``` - -Claude вызовет `/epf-add-help` и предложит отредактировать HTML. - -``` -> Добавь ещё одну команду печати — накладная -``` - -Claude вызовет `/epf-bsp-add-command`, добавит команду в `СведенияОВнешнейОбработке()` и блок обработки в процедуру `Печать()`. - -``` -> Собери -``` - -Claude вызовет `/epf-build`. - -Слеш-команды (например `/epf-init МояОбработка`) тоже работают — для тех случаев, когда хочется точного контроля. - -### Примеры слеш-команд - -``` -> /epf-init МояОбработка "Моя обработка" -> /epf-add-form МояОбработка Форма -> /epf-add-template МояОбработка Макет HTML -> /epf-add-help МояОбработка -> /epf-build МояОбработка -``` - -Первая добавленная форма автоматически становится основной (DefaultForm). Флаг `--main` нужен только для переназначения основной формы на другую. - -После `/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 # Содержимое макета -``` - -## Подключение к проекту - -Скопируйте каталог `.claude/skills/` в корень вашего проекта. Навыки будут доступны при запуске Claude Code из этого каталога. Каталог `docs/` копировать не нужно — все инструкции и шаблоны встроены в SKILL.md каждого навыка. +Скопируйте каталог `.claude/skills/` в корень вашего проекта. Навыки станут доступны при запуске Claude Code из этого каталога. ``` МойПроект/ ├── .claude/skills/ ← скопировать из этого репозитория -├── src/ ← исходники обработки (создаются навыками) +├── src/ ← исходники (создаются навыками) └── ... ``` +Не обязательно запоминать команды и параметры — просто опишите задачу своими словами, Claude сам подберёт нужные навыки. Слеш-команды (например `/epf-init МояОбработка`) тоже работают — для точного контроля. + +## Группы навыков + +| Группа | Навыки | Описание | Гайд | +|--------|--------|----------|------| +| Внешние обработки (EPF) | 10 навыков `/epf-*` | Создание, модификация, сборка обработок из XML-исходников | [Подробнее](docs/epf-guide.md) | +| Табличный документ (MXL) | 4 навыка `/mxl-*` | Анализ, создание, компиляция макетов печатных форм | [Подробнее](docs/mxl-guide.md) | + ## Требования - **Windows** с PowerShell 5.1+ (входит в Windows) - **1С:Предприятие 8.3** — для сборки/разборки EPF (навыки генерации XML работают без платформы) -## Структура репозитория - -``` -.claude/skills/ # Навыки Claude Code -├── epf-init/ # SKILL.md + scripts/init.ps1 -├── epf-add-form/ # SKILL.md + scripts/add-form.ps1 -├── epf-add-template/ # SKILL.md + scripts/add-template.ps1 -├── epf-remove-form/ # SKILL.md + scripts/remove-form.ps1 -├── epf-remove-template/ # SKILL.md + scripts/remove-template.ps1 -├── epf-build/ # SKILL.md (только документация) -├── epf-dump/ # SKILL.md (только документация) -├── epf-add-help/ # SKILL.md + scripts/add-help.ps1 -├── epf-bsp-init/ # SKILL.md (шаблоны кода, без скриптов) -├── epf-bsp-add-command/ # SKILL.md (шаблоны кода, без скриптов) -├── mxl-info/ # SKILL.md + scripts/mxl-info.ps1 -├── mxl-validate/ # SKILL.md + scripts/mxl-validate.ps1 -├── mxl-compile/ # SKILL.md + scripts/mxl-compile.ps1 -└── mxl-decompile/ # SKILL.md + scripts/mxl-decompile.ps1 -docs/ -├── 1c-xml-format-spec.md # Спецификация XML-формата выгрузки -├── 1c-help-spec.md # Спецификация встроенной справки -├── build-spec.md # Спецификация команд сборки/разборки -└── 1c-spreadsheet-spec.md # Спецификация табличного документа (MXL) -``` - ## Спецификации -- [XML-формат выгрузки обработок](docs/1c-xml-format-spec.md) — полное описание структуры XML-файлов, namespace'ов, элементов форм +- [XML-формат выгрузки обработок](docs/1c-xml-format-spec.md) — структура XML-файлов, namespace, элементы форм +- [Управляемая форма](docs/1c-form-spec.md) — Form.xml, элементы, команды, реквизиты - [Встроенная справка](docs/1c-help-spec.md) — Help.xml, HTML-страницы, кнопка справки на форме - [Сборка и разборка EPF](docs/build-spec.md) — команды `1cv8.exe`, параметры, коды возврата - [Табличный документ (MXL)](docs/1c-spreadsheet-spec.md) — XML-формат SpreadsheetDocument, совместимость версий - [MXL DSL](docs/mxl-dsl-spec.md) — JSON-формат описания макета для `/mxl-compile` и `/mxl-decompile` -## Технические детали +## Структура репозитория -- Все XML-файлы создаются в **UTF-8 с BOM** (как в реальных выгрузках 1С) -- PowerShell-скрипты используют `System.Xml.XmlDocument` для модификации корневого XML -- UUID генерируются через `[guid]::NewGuid()` -- ClassId обработки фиксирован: `c3831ec8-d8d5-4f93-8a22-f9bfae07327f` -- Порядок элементов в `ChildObjects`: TabularSections → Forms → Templates -- Первая форма автоматически назначается основной (DefaultForm) -- BSP-навыки (`epf-bsp-*`) не используют скрипты — Claude модифицирует код напрямую через Read/Edit +``` +.claude/skills/ # Навыки Claude Code +├── epf-init/ # Создание обработки +├── epf-add-form/ # Добавление формы +├── epf-add-template/ # Добавление макета +├── epf-add-help/ # Добавление справки +├── epf-remove-form/ # Удаление формы +├── epf-remove-template/ # Удаление макета +├── epf-build/ # Сборка EPF +├── epf-dump/ # Разборка EPF +├── epf-bsp-init/ # Регистрация БСП +├── epf-bsp-add-command/ # Команда БСП +├── mxl-info/ # Анализ макета +├── mxl-validate/ # Валидация макета +├── mxl-compile/ # Компиляция макета из JSON +└── mxl-decompile/ # Декомпиляция макета в JSON +docs/ +├── epf-guide.md # Гайд: внешние обработки +├── mxl-guide.md # Гайд: табличный документ +├── 1c-xml-format-spec.md # Спецификация XML-формата +├── 1c-form-spec.md # Спецификация управляемых форм +├── 1c-help-spec.md # Спецификация встроенной справки +├── build-spec.md # Спецификация сборки/разборки +├── 1c-spreadsheet-spec.md # Спецификация табличного документа +└── mxl-dsl-spec.md # Спецификация MXL DSL +``` diff --git a/docs/epf-guide.md b/docs/epf-guide.md new file mode 100644 index 00000000..2f6c91a8 --- /dev/null +++ b/docs/epf-guide.md @@ -0,0 +1,128 @@ +# Внешние обработки (EPF) + +Навыки группы `/epf-*` позволяют создавать, модифицировать и собирать внешние обработки 1С:Предприятия 8.3 (`.epf`) из XML-исходников, не запоминая детали формата. + +## Навыки + +| Навык | Параметры | Описание | +|-------|-----------|----------| +| `/epf-init` | ` [Synonym]` | Создать новую обработку (корневой XML + модуль объекта) | +| `/epf-add-form` | ` [Synonym]` | Добавить управляемую форму | +| `/epf-add-template` | ` ` | Добавить макет (HTML, Text, SpreadsheetDocument, BinaryData) | +| `/epf-add-help` | `` | Добавить встроенную справку (Help.xml + HTML) | +| `/epf-remove-form` | ` ` | Удалить форму | +| `/epf-remove-template` | ` ` | Удалить макет | +| `/epf-build` | `` | Собрать EPF из XML (через 1cv8.exe) | +| `/epf-dump` | `` | Разобрать EPF в XML (через 1cv8.exe) | +| `/epf-bsp-init` | ` <Вид>` | Добавить регистрацию БСП (СведенияОВнешнейОбработке) | +| `/epf-bsp-add-command` | ` <Идентификатор>` | Добавить команду в дополнительную обработку БСП | + +Навыки удаления (`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`, параметры, коды возврата diff --git a/docs/mxl-guide.md b/docs/mxl-guide.md new file mode 100644 index 00000000..3663916c --- /dev/null +++ b/docs/mxl-guide.md @@ -0,0 +1,96 @@ +# Табличный документ (MXL) + +Навыки группы `/mxl-*` позволяют анализировать, создавать и модифицировать макеты табличных документов 1С — основной формат печатных форм в конфигурациях 1С:Предприятия. + +## Навыки + +| Навык | Параметры | Описание | +|-------|-----------|----------| +| `/mxl-info` | `` или ` ` | Анализ структуры: области, параметры, наборы колонок | +| `/mxl-validate` | `` или ` ` | Валидация: индексы, ссылки, границы | +| `/mxl-compile` | ` ` | Компиляция макета из JSON-определения в Template.xml | +| `/mxl-decompile` | ` [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`