KD 3.1 - правила обмена EnterpriseData через MCP-toolkit

Скилл описывает работу с живой ИБ "Конвертация данных, редакция 3.1" (КД 3.1) через MCP-toolkit HTTP API: исследование структуры правил, создание/правка правил, настройка формата и получение артефактов для расширения формата EnterpriseData - модуля менеджера обмена (общий модуль BSL) и XDTO-пакета расширения / версии формата (XSD).

Относится к сборке КД 3.1.6.14 (платформа 8.5.1.1302).

Модель данных: КД 3.1 близка к КД 2.0 + слой формата

В этой сборке КД 3.1 по структуре похожа на КД 2.0:

• Теневая модель метаданных: Релизы (версия загруженной структуры) -> Объекты (Владелец=Релизы) -> Свойства/Значения (Владелец=Объекты). Конфигурации - топ-контейнер, на который ссылаются Релизы (версии живут в Релизах).
• Правила в справочниках: ПравилаКонвертацииОбъектов (ПКО), ПравилаКонвертацииСвойств (ПКС, Владелец=ПКО - это справочник, не регистр), ПравилаКонвертацииПредопределенныхДанных (ПКПД), ПравилаОбработкиДанных (ПОД), ПравилаРегистрацииОбъектов (ПРО, Владелец=Регистрации). ПКО/ПОД/ПКПД - топ-уровневые (без Владельца), связь с конвертацией - через СоставыКонвертаций. ВАЖНО: у ПКО нет реквизита Наименование (идентификатор в Коде, искать НайтиПоКоду) и ПКО НЕ иерархичен (нет ЭтоГруппа); ПКС иерархичен. Паттерн заполнения - 2 ПКО на объект (<Объект>_Отправка + <Объект>_Получение), эталон в демо. См. bsl-templates.md.
• Дополнительно - слой формата EnterpriseData (цепочка справочников): ВерсииФормата (ПространствоИмен, признак расширения) -> ОбъектыФормата (Владелец=ВерсииФормата) -> СвойстваФормата -> ЗначенияФормата; типы - ТипыФормата.

Отличие результата от КД 2.0: КД 3.1 генерирует модуль менеджера обмена (BSL) для движка ОбменДаннымиXDTO плюс работает с XDTO-пакетом/версией формата, а не выгружает XML-правила для "Универсального обмена". Для КД 2.0 - скилл kd2-rules.

Архитектура работы

Claude (агент)  --Bash+curl (payload через jq/python в файл)-->  MCP-toolkit (КД 3.1, СЕРВЕРНЫЙ контекст)
   -> справочники Конвертации/ПКО/ПКС/ПКПД/ПОД + теневая модель + слой формата
   -> штатные обработки (ЗагрузкаСтруктурыКонфигурацииИзФайловXML, НастройкаПравилОбмена, ВыгрузкаМодуля)
   -> артефакты: CommonModule (менеджер обмена) + XDTOPackage/XSD расширения
   -> перенос в расширение конфигурации-приемника (например УНФ)

Эндпоинты toolkit (порт по умолчанию 6011):

• POST /api/execute_query - запросы к справочникам/состоянию.
• POST /api/execute_code - чтение метаданных, создание/правка элементов. Серверный, без Возврат - результат через Результат = ....
• GET /api/get_metadata?type=Configuration - метаданные.

Граница автоматизации

Через toolkit реально:

• Инспекция структуры и состояния (состав справочников, реквизиты, статус Конвертации, есть ли Релиз).
• Создание/правка правил как элементов справочников: Конвертация, ПКО, ПКС, ПКПД, ПОД, СоставыКонвертаций (со снятой защитой записи в форме toolkit). ПКО/ПОД/ПКПД - топ-уровневые, в конвертацию включаются записью СоставыКонвертаций.
• Точечная правка реквизитов и привязок.
• Загрузка структуры и генерация модуля - тоже программно: у форменных обработок есть headless-точки входа (ВыполнитьЗагрузкуМетаданных, ВыполнитьВыгрузкуМодулей), вызываемые через фоновое задание. См. methods.md.

Удобнее интерактивно (через формы обработок КД 3.1), но НЕ обязательно:

• Загрузка структуры конфигурации (ЗагрузкаСтруктурыКонфигурацииИзФайловXML) - заполняет Релиз + Объекты/Свойства. Без нее правила привязывать не к чему. Headless - methods.md п.1 (для большой конфигурации запускать через фон).
• Создание/расширение версии формата (ВыгрузкаСтруктурыФормата / редакторы формата).
• Генерация модуля менеджера (ВыгрузкаМодуля). Headless - methods.md п.2.

Перед массовой работой проверять, что Релизы загружены: ВЫБРАТЬ КОЛИЧЕСТВО(*) ИЗ Справочник.Релизы (0 -> структура не загружена).

Карта references

Документ	Что внутри	Когда читать
references/data-schema.md	проверенные справочники и реквизиты (Конвертации, ПКО, ПКС, ПКПД, ПОД, теневая модель, слой формата), фактические имена обработок	нужны точные имена объектов/реквизитов
references/bsl-templates.md	BSL для execute_code: инспекция, состояние конвертации, создание ПКО/ПКС, привязка версии формата	конкретная операция через toolkit
references/format-extension.md	расширение формата ED: версия формата с namespace, привязка к Конвертации, обработчики ПКО, генерация менеджера, перенос в расширение; workflow + контекст проекта	разработка расширения формата и перенос артефактов
references/methods.md	программный API обработок (headless): загрузка структуры ВыполнитьЗагрузкуМетаданных, генерация модуля ВыполнитьВыгрузкуМодулей, прием вызова форменной обработки в обход UI, file:line	нужно вызвать обработку КД программно через toolkit
references/troubleshooting.md	ограничения toolkit :6011 и КД 3.1 (кодировка, Количество(), тип коллекции метаданных, длины реквизитов, имена перечислений)	при ошибке execute_code/execute_query

Scripts

• scripts/kd31_query.sh "<запрос>" [out.json] - execute_query.
• scripts/kd31_exec.sh <файл.bsl> [out.json] - execute_code из BSL-файла.

Оба: payload через jq (fallback python) + curl --data-binary @файл, порт через KD31_PORT (по умолчанию 6011). Если указан out.json - ответ в файл (читать через Read: терминал портит кириллицу).

Демо-база КД 3.1 как эталон (НАСТОЯТЕЛЬНО)

Если доступна демо-база КД 3.1 (типовая поставка содержит готовую конвертацию, напр. "БП->УП" - сотни ПКО, тысячи ПКС) - использовать ее как ЭТАЛОН заполнения правил, а не угадывать. Демо идентична рабочей ИБ по структуре метаданных. Перед созданием своего ПКО/ПКС снять образец аналогичного правила из демо (Код, как заполнены ОбъектКонфигурации/ОбъектФормата, паттерн _Отправка/_Получение, как оформлены прямые vs алгоритмические ПКС, ссылочные через ПравилоКонвертацииСвойства). Порт демо задается при запуске ее toolkit (порт toolkit уточнять по своей конфигурации). Чтение демо - KD31_PORT=<порт> bash scripts/kd31_query.sh "...".

Базовая проверка готовности

curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:6011/api/get_metadata?type=Configuration"   # 200
bash scripts/kd31_query.sh "ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК К ИЗ Справочник.Конвертации"
bash scripts/kd31_query.sh "ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК К ИЗ Справочник.Релизы"
# Релизы=0 -> структура конфигурации не загружена; для расширения проверить ЕстьРасширения
bash scripts/kd31_query.sh "ВЫБРАТЬ Наименование, ЕстьРасширения ИЗ Справочник.Релизы ГДЕ НЕ ЭтоГруппа"

Связанные скиллы

• 1c-mcp-toolkit - HTTP API к живой ИБ 1С (этот скилл - надстройка).
• kd2-rules - аналог для КД 2.0 (та же идея, другой результат - XML-правила).
• composing-1c-queries - синтаксис запросов для execute_query.