kd2-rules · git:20260529.6a42d35 · 2026-05-29 · sha256 a51496028585259f
kd2-rules git:20260529.6a42d35A
Immutable. This exact content is served forever at /api/v1/blob/a51496028585259f.
---
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` - проверка живости.
## Предварительные требования
1. Запущенная ИБ КД 2.0 в тонком/толстом клиенте с открытой обработкой
`MCP_Toolkit.epf` (см. скилл `1c-mcp-toolkit`). HTTP-сервер слушает
`localhost:6003` (или `:7003` по настройке).
2. В форме toolkit-а проверить и при необходимости снять защиту от записи:
снять флажки на ключевые слова `Записать`, `Удалить`,
`УстановитьПривилегированныйРежим`. Без этого работают только
`execute_query` и read-only вызовы.
3. Желательно тестовая копия ИБ КД, а не production - правила пишутся
напрямую в справочники.
## Быстрая проверка готовности
```sh
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. Найти конвертацию по имени
```bsl
Конв = Справочники.Конвертации.НайтиПоНаименованию("Имя_Конвертации");
Если Конв.Пустая() Тогда
ВызватьИсключение "Конвертация не найдена";
КонецЕсли;
Результат = XMLСтрока(Конв);
```
### 2. Список ПКО в конвертации
```sh
curl -sS -X POST "http://localhost:7003/api/execute_query" \
-H "Content-Type: application/json" \
-d '{
"query": "ВЫБРАТЬ ПКО.Наименование, ПКО.ТипИсточника, ПКО.ТипПриемника, ПКО.Порядок ИЗ Справочник.ПравилаКонвертацииОбъектов КАК ПКО ГДЕ ПКО.Владелец.Наименование = &Конв И НЕ ПКО.ЭтоГруппа УПОРЯДОЧИТЬ ПО ПКО.Порядок",
"params": {"Конв": "Имя_Конвертации"}
}'
```
### 3. Создать ПКО
```bsl
Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
ОбъИст = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Источник);
ОбъПр = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Приемник);
ПКО = Справочники.ПравилаКонвертацииОбъектов.СоздатьЭлемент();
ПКО.Владелец = Конв;
ПКО.Наименование = "Контрагенты";
ПКО.Источник = ОбъИст;
ПКО.Приемник = ОбъПр;
ПКО.ТипИсточника = "СправочникСсылка.Контрагенты";
ПКО.ТипПриемника = "СправочникСсылка.Контрагенты";
ПКО.Порядок = 100;
ПКО.Записать();
Результат = Новый Структура("ссылка", XMLСтрока(ПКО.Ссылка));
```
### 4. Создать ПКС внутри ПКО
```bsl
ПКО = Справочники.ПравилаКонвертацииОбъектов.НайтиПоНаименованию("Контрагенты", Истина, Конв);
СвИст = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Источник);
СвПр = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Приемник);
ПКС = Справочники.ПравилаКонвертацииСвойств.СоздатьЭлемент();
ПКС.Владелец = ПКО;
ПКС.Источник = СвИст;
ПКС.Приемник = СвПр;
ПКС.ИмяИсточника = "Наименование";
ПКС.ИмяПриемника = "Наименование";
ПКС.ТипИсточника = "Строка";
ПКС.ТипПриемника = "Строка";
ПКС.ВидИсточника = "Свойство";
ПКС.ВидПриемника = "Свойство";
ПКС.Наименование = "Наименование --> Наименование";
ПКС.Порядок = 100;
ПКС.Записать();
```
### 5. Выгрузить конвертацию в XML
```bsl
Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
Обр = Обработки.ВыгрузкаКонвертации.Создать();
Обр.КонвертацияДляВыгрузки = Конв;
Обр.ИмяФайлаПравил = "C:\Output\rules.xml";
Обр.СжиматьФайлПравил = Ложь;
Обр.ВыгружатьПравилаКорреспондента = Ложь;
Обр.ВыгружатьПравилаРегистрации = Ложь;
Обр.ВыполнитьВыгрузкуПравил();
Файл = Новый Файл(Обр.ИмяФайлаПравил);
Результат = Новый Структура("ok,path,size", Истина, Обр.ИмяФайлаПравил, Файл.Размер());
```
## Принципы работы
1. **Все справочники иерархические** «Папки и элементы». ПКО-группы (`ЭтоГруппа=true`)
используются для логической группировки правил внутри конвертации.
2. **Владелец = главная связь.** ПКО подчинен Конвертации, ПКС/ПКЗ подчинены ПКО,
Объекты подчинены Конфигурации, Свойства подчинены Объектам, Значения
подчинены Свойствам.
3. **Денормализованные дубликаты.** Поля типа `ИмяИсточника`/`ТипИсточника` в ПКО и
ПКС - строковые копии данных из связанной ссылки (для быстрого поиска без
join-ов). Заполняй их явно при создании.
4. **Поле `Код`** в Конвертациях и ПКО - это «внутренний идентификатор» (UUID-подобная
строка фиксированной длины 40 символов с trailing-пробелами). Используется в
итоговом XML как `<Ид>` и `<КодПравилаКонвертации>`.
5. **Имя файла в `ИмяФайлаПравил`** должно быть путём к существующему каталогу.
`КаталогВременныхФайлов()` - надёжный способ получить временную папку клиента.
## Ограничения
- Все ключевые методы КД работают через `execute_code` без явного
`execution_context` (toolkit живет в клиентском контексте 1С,
директива `#Если Клиент Тогда` не блокирует).
- В стандартной конфигурации toolkit-а заблокированы ключевые слова
`Записать`, `Удалить`, `УстановитьПривилегированныйРежим`. Для создания
правил - отключить защиту в форме toolkit-а.
- Возможны trailing-пробелы в строковых ссылочных полях (`Код` 40 символов
с пробелами). При сравнениях использовать `СокрЛП(...)`.
- Обработка `ВыгрузкаКонвертации` использует переменную модуля
`мФормаПрогрессора.Значение` - при программном запуске она остается
не инициализированной, но падения не происходит (проверено).
## Связанные скиллы
- `1c-mcp-toolkit` - HTTP API к живой ИБ 1С (этот скилл - надстройка
поверх него).
- `composing-1c-queries` - синтаксис языка запросов 1С для `execute_query`.