Описание
bitrix-bizproc-skill — скилл отладки бизнес-процессов Битрикс24 для Claude Code: разбор bpt-шаблонов — чтение XML-структуры процесса, поиск битых ссылок — на удалённые активности и константы, проверка логики — какие ветки выполнения невозможны или зациклены. Для администраторов порталов, у которых процессы «сломались» и никто не помнит, как они устроены.
Что умеет:
— разбирать bpt-шаблоны;
— находить битые ссылки на активности;
— проверять константы процесса;
— искать невыполнимые ветки логики.
Полная документация ниже — автоматически из репозитория shydamn/bitrix-bizproc-skill (ветка main). Оригинальные материалы проекта распространяются на условиях его лицензии.
bitrix-bizproc
Скилл для Codex и Claude Code: чтение, проверка и правка шаблонов
бизнес-процессов коробочного Битрикс24. Работает с экспортами .bpt
и с живым порталом через модуль synapseaagency.bpagent.
Файл .bpt содержит PHP-массивы, сериализованные через serialize() и сжатые
zlib. Инструменты разбирают дерево, сохраняют диалект узлов и проверяют ссылки
на активити, переменные, константы и состояния. Проверка различает ошибки
в активных и выключенных ветках.
Установка
Установите каталог репозитория в каталог скиллов своего агента.
Точка входа — SKILL.md.
Для файлов .bpt нужна библиотека phpserialize:
python -m pip install phpserialize
HTTP-клиент bpagent.py использует только стандартную библиотеку Python.
Модуль для портала устанавливается отдельно и в этот репозиторий не входит.
Работа с файлами
python scripts/inspect_bpt.py info файл.bpt
python scripts/inspect_bpt.py tree файл.bpt --depth=3
python scripts/inspect_bpt.py find файл.bpt --type=IfElseActivity --title=маршрут
python scripts/inspect_bpt.py node файл.bpt --path=/0/1
python scripts/validate_bpt.py файл.bpt
Для правок используйте scripts/bpt.py: load() → изменение дерева → dump().
Сырые сериализованные строки редактировать нельзя: длины строк в PHP serialize
считаются в байтах. Подробности — в описании формата.
Работа через шлюз
На портале должен быть установлен synapseaagency.bpagent, а ключ должен
иметь права на нужные операции и шаблоны. В Bash подключение задаётся так:
export BPAGENT_URL='https://portal.example.com/bitrix/tools/synapseaagency.bpagent/gateway.php'
export BPAGENT_TOKEN='ваш-ключ'
python scripts/bpagent.py ping
python scripts/bpagent.py list --name=согласование
python scripts/bpagent.py find 2746 --type=IfElseActivity
python scripts/bpagent.py subtree 2746 --path=/0/1
| Команда | Назначение |
|---|---|
ping |
Версия модуля, права и область ключа |
list |
Поиск шаблонов по названию/типу документа, пагинация, включение роботов |
get ID |
JSON шаблона с hash; выбор разделов через --include |
find ID |
Поиск узлов по типу, имени, заголовку и содержимому |
subtree ID --path=... |
Чтение одной ветки |
validate ID |
Структурная проверка текущего шаблона |
users --query=... или --ids=... |
Поиск сотрудников |
create --file=... |
Создание шаблона из JSON |
put ID --file=... --comment=... |
Частичная запись разделов с проверкой hash |
versions ID |
Список снимков |
restore ID --version=... |
Откат со снимком текущего состояния и If-Match |
get по умолчанию не выводит дерево крупнее 150 узлов. Для точечной работы
используйте find и subtree; если для правки нужен весь файл, сохраните
результат get ID --force в файл. У get --force смысл только в снятии этого
ограничения размера вывода.
Для записи сохраните hash из get в редактируемом JSON:
python scripts/bpagent.py get 2746 > tpl.json
# Изменить нужные разделы tpl.json, сохранив hash.
python scripts/bpagent.py validate 2746
python scripts/bpagent.py put 2746 --file=tpl.json --comment='исправлен маршрут'
python scripts/bpagent.py validate 2746
Поля tree, variables, constants и parameters, отсутствующие в JSON, не меняются.
Для очистки variables/constants/parameters используйте {} или [], не null.
put передаёт запись через POST с X-HTTP-Method-Override: PUT, чтобы пройти
конфигурации портала, в которых WebDAV перехватывает обычный PUT.
Откат и совместимость с модулем 0.3.1
python scripts/bpagent.py versions 2746
python scripts/bpagent.py restore 2746 --version=17
Клиент сначала читает метаданные текущего шаблона без дерева и передаёт
полученный hash в If-Match. Если вы уже проверили конкретное состояние,
передайте его хэш явно: restore 2746 --version=17 --hash=<hash>.
В этом случае клиент не подменяет его новым. Нужен хэш текущего шаблона,
а не исторического снимка.
Модуль 0.3.1 возвращает 428 без If-Match и 409 при несовпадении хэша.
Клиент не повторяет откат автоматически. После 409 сначала проверьте чужие
изменения и решите, допустимо ли их отменять. Если хэш не получен, POST не отправляется.
Старые копии клиента, отправляющие restore без If-Match, нужно обновить.
put --force и restore --force отправляют JSON boolean force: true для
явного обхода структурных ошибок с записью в аудит. Флаг не обходит права,
If-Match и остальные проверки записи. Без него ошибка 422 не включает force
автоматически. Для create это поле задаётся в исходном JSON.
Маршруты, права и ограничения описаны в references/api.md.
Модуль также предоставляет HTTP-маршруты запуска и просмотра процессов;
отдельных CLI-команд для них в bpagent.py пока нет.
Проверки
Локальные тесты работают без портала и настоящего ключа. HTTP-клиент проверяется
через временный сервер на loopback, файловый валидатор — на синтетических
шаблонах и временных .bpt. Для полного набора нужен phpserialize:
python -m unittest discover -s tests -v
Они проверяют фактический If-Match, получение и явную передачу хэша,
конфликты без повторной записи, ошибки чтения/валидации, boolean force и
совместимость PUT с подменой метода.
Файловые проверки покрывают типы имён состояний, активность корня и вложенных
веток, чтение параметров через {=Variable:...} и приоритет точного имени
перед суффиксным модификатором. Неверное имя состояния теперь даёт находку,
а не исключение Python; выключенные находки не меняют код выхода на ошибочный.
Для сравнения с настоящим PHP-валидатором модуля 0.3.1 используются те же
34 сценария из tests/validator_cases.py. Пример для Bash с PHP 8.2+:
validation_dir="$(mktemp -d)"
python tests/validator_cases.py > "$validation_dir/cases.json"
php tests/module_validator.php /path/to/synapseaagency.bpagent "$validation_dir/cases.json" > "$validation_dir/module-results.json"
BPAGENT_MODULE_VALIDATION_JSON="$validation_dir/module-results.json" python -m unittest discover -s tests -v
Адаптер читает только классы Codec и Validator и версию модуля, не подключается
к порталу или БД. Перед сравнением создавайте новый отчёт PHP. Без указанного
JSON пропускается только тест сравнения с модулем. Сравниваются коды находок,
пути и наличие активной ошибки; различия форматов отчётов нормализуются:
ERROR с active: false файлового валидатора соответствует предупреждению PHP.
Это проверка перечисленных сценариев, а не полная эквивалентность валидаторов.
Для проверки на тестовой коробке есть scripts/smoke_write.py:
python scripts/smoke_write.py --document-type=DYNAMIC_1046
Нужны права templates:create, templates:read и templates:write и
область ключа, разрешающая создание шаблона указанного типа. Тест создаёт
свой шаблон, проверяет чтение, запись, конфликт и откат. После проверки
шаблон остаётся на портале для ручного удаления; --keep пропускает откат.
Исходная проверка файлового формата включала 31 шаблон с нескольких порталов:
5343 узла, 42 типа активити и оба типа корня. roundtrip_ok() сравнивает
распакованный слой PHP serialize: сжатые байты могут отличаться между сборками zlib.
Границы
Скилл не пишет напрямую в таблицы ядра и не изменяет уже запущенные экземпляры.
Проверка ссылок не доказывает исполнимость маршрута. Проверка If-Match и запись
модуля не атомарны относительно параллельного изменения в визуальном редакторе.
Установку, Bitrix ORM, запуск маршрута и демо-лицензию нужно проверять на
тестовой коробке; локальные тесты клиента этого не подтверждают.
Лицензия
MIT