kd2-rules - SKILL.md Agent Skill

name: kd2-rules description: > Программная разработка правил обмена в «Конвертация данных 2.1» (КД 2.0) через MCP-toolkit к живой ИБ. Создание/чтение/изменение Конвертаций, ПКО, ПКС, ПКЗ, ПВД, ПОД в справочниках КД и выгрузка итогового XML штатными обработками КД (ВыгрузкаКонвертации, ВыгрузкаРегистрации, ЗагрузкаКонвертации, ЗагрузкаСтруктурыМетаданных). Содержит схему данных, шаблоны BSL для execute_code, схему итогового XML, типичные ошибки. Триггеры на русском: «работа с КД 2.0», «правила обмена в КД», «создать конвертацию», «настроить ПКО ПКС ПКЗ», «выгрузить правила обмена в XML», «конвертация данных 2.1», «загрузить метаданные конфигурации в КД», «автонастройка правил конвертации». Триггеры на английском: «1C data conversion rules», «KD 2.0», «create conversion rule», «PKO PKS PKZ», «export exchange rules XML».

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

Скилл описывает, как агент создает/изменяет правила обмена в живой ИБ «Конвертация данных 2.1» (КД 2.0) через MCP-toolkit HTTP API (порт по умолчанию 6003, в проектах часто 7003) и в финале выгружает XML штатными обработками КД.

Что такое КД 2.0

Конфигурация фирмы «1С», v2.1.8.2, обычные формы, режим совместимости 8.2.13. Программа для разработки правил обмена данными между парами конфигураций (например, БП КОРП -> УПП, УТ -> ERP).
Результат работы в КД - XML с правилами, который грузится в «Универсальный обмен данными в формате XML» в конфигурации-источнике.
Все правила хранятся в справочниках самой КД: Конвертации, ПравилаКонвертацииОбъектов, ПравилаКонвертацииСвойств, ПравилаКонвертацииЗначений, ПравилаВыгрузкиДанных, ПравилаОчисткиДанных, ПравилаРегистрацииОбъектов, плюс Конфигурации/Объекты/Свойства/Значения (теневая модель метаданных источника и приемника).

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

Claude (агент)
   ↕  MCP-протокол / прямые tool-вызовы
Скилл kd2-rules
   ↕  HTTP POST :6003/api/* (или :7003 если переопределен порт)
MCP-toolkit (обработка MCP_Toolkit.epf в живой ИБ)
   ↕  внутрипроцессно
ИБ КД 2.0
   ↕  через ВыгрузкаКонвертации.ВыполнитьВыгрузкуПравил()
Файл XML с правилами обмена

Низкоуровневый транспорт - MCP-toolkit (скилл 1c-mcp-toolkit). Главные эндпоинты, которые используются здесь:

POST /api/execute_query - читать справочники КД и их связи.
POST /api/execute_code - создавать/изменять элементы справочников, запускать экспортные методы обработок.
GET /api/health - проверка живости.

Предварительные требования

Запущенная ИБ КД 2.0 в тонком/толстом клиенте с открытой обработкой MCP_Toolkit.epf (см. скилл 1c-mcp-toolkit). HTTP-сервер слушает localhost:6003 (или :7003 по настройке).
В форме toolkit-а проверить и при необходимости снять защиту от записи: снять флажки на ключевые слова Записать, Удалить, УстановитьПривилегированныйРежим. Без этого работают только execute_query и read-only вызовы.
Желательно тестовая копия ИБ КД, а не production - правила пишутся напрямую в справочники.

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

curl http://localhost:7003/health
# Ожидание: {"status":"healthy", ...}

curl -sS -X POST "http://localhost:7003/api/execute_query" \
  -H "Content-Type: application/json" \
  -d '{"query":"ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК Кол ИЗ Справочник.Конвертации"}'

Карта references

Документ	Что внутри	Когда читать
`references/architecture.md`	объектная модель КД, иерархия Владелец, полные списки реквизитов всех ключевых справочников	проектирование новой операции, нужны типы и связи
`references/methods.md`	экспортные методы обработок выгрузки/загрузки + file:line + параметры (реквизиты обработки)	вызов конкретного метода через `execute_code`
`references/workflows.md`	end-to-end сценарии: подготовка ИБ, загрузка метаданных, создание правил, выгрузка XML, импорт XML, автонастройка	впервые делаешь полный цикл или сложный сценарий
`references/xml-schema.md`	схема итогового XML правил обмена + маппинг полей справочника на XML	надо понять, что КД ожидает увидеть в XML, или сверить результат с эталоном
`references/troubleshooting.md`	типичные ошибки и ограничения toolkit-а, особенности КД 2.0	при ошибке `execute_code`/`execute_query`

5 базовых операций (краткий справочник)

1. Найти конвертацию по имени

Конв = Справочники.Конвертации.НайтиПоНаименованию("Имя_Конвертации");
Если Конв.Пустая() Тогда
    ВызватьИсключение "Конвертация не найдена";
КонецЕсли;
Результат = XMLСтрока(Конв);

2. Список ПКО в конвертации

curl -sS -X POST "http://localhost:7003/api/execute_query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ВЫБРАТЬ ПКО.Наименование, ПКО.ТипИсточника, ПКО.ТипПриемника, ПКО.Порядок ИЗ Справочник.ПравилаКонвертацииОбъектов КАК ПКО ГДЕ ПКО.Владелец.Наименование = &Конв И НЕ ПКО.ЭтоГруппа УПОРЯДОЧИТЬ ПО ПКО.Порядок",
    "params": {"Конв": "Имя_Конвертации"}
  }'

3. Создать ПКО

Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
ОбъИст = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Источник);
ОбъПр  = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Приемник);

ПКО = Справочники.ПравилаКонвертацииОбъектов.СоздатьЭлемент();
ПКО.Владелец      = Конв;
ПКО.Наименование  = "Контрагенты";
ПКО.Источник      = ОбъИст;
ПКО.Приемник      = ОбъПр;
ПКО.ТипИсточника  = "СправочникСсылка.Контрагенты";
ПКО.ТипПриемника  = "СправочникСсылка.Контрагенты";
ПКО.Порядок       = 100;
ПКО.Записать();

Результат = Новый Структура("ссылка", XMLСтрока(ПКО.Ссылка));

4. Создать ПКС внутри ПКО

ПКО = Справочники.ПравилаКонвертацииОбъектов.НайтиПоНаименованию("Контрагенты", Истина, Конв);
СвИст = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Источник);
СвПр  = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Приемник);

ПКС = Справочники.ПравилаКонвертацииСвойств.СоздатьЭлемент();
ПКС.Владелец     = ПКО;
ПКС.Источник     = СвИст;
ПКС.Приемник     = СвПр;
ПКС.ИмяИсточника = "Наименование";
ПКС.ИмяПриемника = "Наименование";
ПКС.ТипИсточника = "Строка";
ПКС.ТипПриемника = "Строка";
ПКС.ВидИсточника = "Свойство";
ПКС.ВидПриемника = "Свойство";
ПКС.Наименование = "Наименование --> Наименование";
ПКС.Порядок      = 100;
ПКС.Записать();

5. Выгрузить конвертацию в XML

Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
Обр = Обработки.ВыгрузкаКонвертации.Создать();
Обр.КонвертацияДляВыгрузки         = Конв;
Обр.ИмяФайлаПравил                 = "C:\Output\rules.xml";
Обр.СжиматьФайлПравил              = Ложь;
Обр.ВыгружатьПравилаКорреспондента = Ложь;
Обр.ВыгружатьПравилаРегистрации    = Ложь;
Обр.ВыполнитьВыгрузкуПравил();

Файл = Новый Файл(Обр.ИмяФайлаПравил);
Результат = Новый Структура("ok,path,size", Истина, Обр.ИмяФайлаПравил, Файл.Размер());

Принципы работы

Все справочники иерархические «Папки и элементы». ПКО-группы (ЭтоГруппа=true) используются для логической группировки правил внутри конвертации.
Владелец = главная связь. ПКО подчинен Конвертации, ПКС/ПКЗ подчинены ПКО, Объекты подчинены Конфигурации, Свойства подчинены Объектам, Значения подчинены Свойствам.
Денормализованные дубликаты. Поля типа ИмяИсточника/ТипИсточника в ПКО и ПКС - строковые копии данных из связанной ссылки (для быстрого поиска без join-ов). Заполняй их явно при создании.
Поле Код в Конвертациях и ПКО - это «внутренний идентификатор» (UUID-подобная строка фиксированной длины 40 символов с trailing-пробелами). Используется в итоговом XML как <Ид> и <КодПравилаКонвертации>.
Имя файла в ИмяФайлаПравил должно быть путём к существующему каталогу. КаталогВременныхФайлов() - надёжный способ получить временную папку клиента.

Ограничения

Все ключевые методы КД работают через execute_code без явного execution_context (toolkit живет в клиентском контексте 1С, директива #Если Клиент Тогда не блокирует).
В стандартной конфигурации toolkit-а заблокированы ключевые слова Записать, Удалить, УстановитьПривилегированныйРежим. Для создания правил - отключить защиту в форме toolkit-а.
Возможны trailing-пробелы в строковых ссылочных полях (Код 40 символов с пробелами). При сравнениях использовать СокрЛП(...).
Обработка ВыгрузкаКонвертации использует переменную модуля мФормаПрогрессора.Значение - при программном запуске она остается не инициализированной, но падения не происходит (проверено).

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

1c-mcp-toolkit - HTTP API к живой ИБ 1С (этот скилл - надстройка поверх него).
composing-1c-queries - синтаксис языка запросов 1С для execute_query.