| name | dap-bsl-code-debug-procedure |
| description | Интерактивная DAP-отладка одной BSL-процедуры |
| uses_capabilities | ["debug_bsl_code"] |
Отладка BSL-процедуры через DAP/MCP
Используй навык для точечной интерактивной отладки, когда статический анализ, ЖР, скриншоты и временное логирование не дают ответа о фактическом пути исполнения или значениях переменных.
Предусловия
Перед стартом должны быть известны:
- URL HTTP debug server 1С или локального SSH-туннеля;
- алиас инфобазы;
- путь к исходникам конфигурации;
- пути к расширениям, если точка находится в расширении;
- воспроизводимый сценарий, который вызывает нужную процедуру;
- безопасное окно для остановки исполнения.
Если MCP-сервер отладчика не настроен, используй инструкцию docs/info/mcp-bsl-debugger.md.
Базовый цикл
- Найти процедуру и строку остановки через
code-navigation или чтение модуля.
- Подключиться к debug server:
attach.
- Проверить targets:
get_targets.
- Загрузить или обновить метаданные:
reload_metadata.
- Поставить breakpoint на строку внутри нужной процедуры:
set_breakpoints.
- Только после успешной установки breakpoint запустить сценарий, который вызывает процедуру.
- Сразу переключиться на MCP-отладчик и опрашивать stop event:
wait_for_stop каждые 5 секунд.
- Для быстрого кода остановиться после 30 секунд без stop event и пересмотреть target/breakpoint/сценарий. Для тяжёлой операции до запуска явно определить ожидаемую длительность и контрольный предел ожидания.
- Посмотреть стек и переменные:
get_call_stack, если tool доступен, затем get_variables.
- При необходимости вычислить безопасные выражения:
evaluate.
- Выполнить один или несколько шагов:
step_in, step_out, continue.
- Снять breakpoint:
clear_breakpoints.
- Отключиться:
detach.
Как инициировать выполнение кода
Порядок всегда один: сначала breakpoint, потом запуск сценария, потом polling stop event в отладчике. Не запускай тест или клиентское действие до установки breakpoint, иначе нужный участок может пройти до подключения отладчика.
После запуска сценария агент не определяет остановку по “зависанию” клиента. Он сразу переходит к debugger MCP и вызывает wait_for_stop с интервалом 5 секунд:
- быстрый код: общий предел 30 секунд;
- тяжёлая операция: перед запуском оценить длительность, возможные блокировки и безопасный контрольный предел;
- если предел вышел без stop event: не ждать бесконечно, проверить target, строку breakpoint, загруженные метаданные, фактический сценарий вызова и контекст исполнения.
Клиентский контекст через Vanessa
Используй, когда отлаживаемый код выполняется в форме, команде, обработчике UI или другом клиентском контексте.
- Запустить Vanessa/test-клиент штатным способом проекта.
- Через
v8-session-manager получить список активных сессий и определить сеанс тест-агента: infobase_name, ib_session_number, session_id, пользователь, признак тестового клиента.
- В
get_targets отладчика выбрать target, соответствующий этому сеансу. Если соответствие неочевидно, сверить время запуска, пользователя и номер сеанса ИБ.
- Поставить breakpoint в клиентском модуле.
- Запустить Vanessa-сценарий или конкретный шаг, который вызывает нужный обработчик.
- Сразу перейти в отладчик и опрашивать
wait_for_stop каждые 5 секунд до stop event или контрольного таймаута.
- После
continue вернуться к Vanessa-прогону и дождаться его штатного завершения.
Клиентский контекст через MCP-управление клиентом
Используй, когда сценарий проще инициировать накликиванием, чем писать или запускать Vanessa.
- Запустить тестовый клиент 1С.
- Подключить его к
v8-session-manager.
- Найти его сессию через
session_list и сопоставить с target отладчика.
- Поставить breakpoint.
- Через UI-tools менеджера открыть форму, нажать команду, заполнить поле или выполнить другое действие, которое вызывает нужный клиентский код.
- После остановки управлять ходом выполнения через debugger MCP, а не через UI-tools.
Серверный контекст через YaxUnit
Используй, когда отлаживаемый код выполняется на сервере, в общем модуле серверного назначения, менеджере, объекте, проведении или серверной части формы.
- Подготовить минимальный YaxUnit-тест, который вызывает нужную экспортную серверную процедуру или ближайшую публичную точку входа.
- Если в проекте уже есть tool/раннер для вызова произвольного серверного метода, можно использовать его вместо нового теста.
- Поставить breakpoint до запуска теста.
- Запустить один конкретный тест, а не весь набор.
- Сразу перейти к
wait_for_stop; для быстрого серверного метода предел ожидания 30 секунд, для тяжёлого — заранее заданный контрольный предел.
- После
continue дождаться завершения теста и проверить его результат.
Серверный контекст через временный MCP tool расширения
Используй как крайний вариант, когда серверный метод нельзя удобно вызвать тестом, HTTP-запросом или существующим runner/tool.
- В расширении с
mcp_tools временно добавить узкий tool, который вызывает только нужную серверную точку входа с контролируемыми параметрами.
- Пометить временный метод как отладочный и не смешивать его с рабочим API расширения.
- Поставить breakpoint.
- Вызвать временный tool через MCP-витрину.
- После отладки удалить временный tool, его регистрацию, экспортные методы и тестовые данные.
- Проверить, что в исходниках не осталось мусорных методов, временных команд, debug-имен и лишних прав.
Другие серверные триггеры
Допустимы HTTP-сервис, регламентное задание, проведение документа или фоновое задание, если это безопасно и воспроизводимо. Для таких сценариев заранее зафиксируй, какой target должен остановиться, и не оставляй остановленный поток в транзакции.
Выбор точки остановки
Ставь breakpoint не “где-нибудь в процедуре”, а на строке, которая отвечает на текущий вопрос:
- вход в процедуру — проверить факт вызова и аргументы;
- строка перед
Если — проверить переменные, влияющие на ветвление;
- строка перед запросом — проверить параметры запроса;
- строка после запроса — проверить размер и ключевые поля результата;
- строка перед возвратом — проверить итоговое значение.
Если процедура не останавливается, проверь:
- вызывается ли именно этот модуль, а не модуль расширения/переопределения;
- совпадает ли строка после загрузки метаданных;
- есть ли target нужного типа;
- не выполняется ли код в другом сеансе или фоновом задании.
Работа с переменными
Смотри только значения, которые влияют на текущую гипотезу:
- параметры процедуры;
- переменные из условия текущей ветки;
- параметры запроса;
- результат запроса, но без полного дампа больших таблиц;
- ссылки и объекты только через ключевые реквизиты.
Не вычисляй выражения с побочными эффектами. evaluate допустим для чтения простых выражений, но не для записи, проведения, вызовов HTTP, изменения глобального состояния и запуска бизнес-операций.
Пошаговая отладка
Используй шаги экономно:
step_in — когда нужно зайти в вызываемую процедуру и увидеть её аргументы/ветку;
step_out — когда текущая процедура уже понятна и нужен результат возврата;
continue — когда нужно дойти до следующего breakpoint или отпустить поток;
pause — только если нужно остановить уже выполняющийся target и это безопасно для сеанса.
После каждого шага фиксируй наблюдение: где остановились, какие значения изменились, какая гипотеза подтвердилась или отпала.
Завершение
Перед финальным ответом или передачей задачи дальше обязательно:
clear_breakpoints по всем установленным точкам.
continue, если поток ещё остановлен и его безопасно отпустить.
detach.
- Если
detach не сработал, attach возвращает ibInDebug, ping-cycle завис или get_targets показывает активный debug-состояние после очистки — выполнить force_detach, затем повторно проверить get_targets.
- Если создавался временный YaxUnit-тест или MCP tool — удалить его или явно оставить только если это согласовано как полезный тестовый артефакт.
- Проверить, что сценарий не оставил заблокированную сессию, зависшее задание или отключённые регламентные задания.
- В отчёте указать: module, procedure, breakpoint lines, target, способ инициирования выполнения, ключевые значения, вывод.
Когда лучше не использовать
- Нет воспроизводимого сценария вызова процедуры.
- Сценарий работает в продуктивной базе или несёт риск остановить транзакцию пользователя.
- Нужно массово собрать трассу по многим веткам: дешевле
agent-debug с ЖР.
- Достаточно ответа из кода, ЖР, техжурнала или запроса к данным.
depends_on:
- framework/skills/tool-usage/code-analysis/code-navigation/SKILL.md
- framework/skills/tool-usage/diagnostics/event-log-analysis/SKILL.md
- framework/skills/tool-usage/v8-session-manager/SKILL.md
- framework/skills/tool-usage/v8-runner/SKILL.md