dap-bsl-code-debug-procedure

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.

Базовый цикл

1. Найти процедуру и строку остановки через code-navigation или чтение модуля.
2. Подключиться к debug server: attach.
3. Проверить targets: get_targets.
4. Загрузить или обновить метаданные: reload_metadata.
5. Поставить breakpoint на строку внутри нужной процедуры: set_breakpoints.
6. Только после успешной установки breakpoint запустить сценарий, который вызывает процедуру.
7. Сразу переключиться на MCP-отладчик и опрашивать stop event: wait_for_stop каждые 5 секунд.
8. Для быстрого кода остановиться после 30 секунд без stop event и пересмотреть target/breakpoint/сценарий. Для тяжёлой операции до запуска явно определить ожидаемую длительность и контрольный предел ожидания.
9. Посмотреть стек и переменные: get_call_stack, если tool доступен, затем get_variables.
10. При необходимости вычислить безопасные выражения: evaluate.
11. Выполнить один или несколько шагов: step_in, step_out, continue.
12. Снять breakpoint: clear_breakpoints.
13. Отключиться: detach.

Как инициировать выполнение кода

Порядок всегда один: сначала breakpoint, потом запуск сценария, потом polling stop event в отладчике. Не запускай тест или клиентское действие до установки breakpoint, иначе нужный участок может пройти до подключения отладчика.

После запуска сценария агент не определяет остановку по “зависанию” клиента. Он сразу переходит к debugger MCP и вызывает wait_for_stop с интервалом 5 секунд:

• быстрый код: общий предел 30 секунд;
• тяжёлая операция: перед запуском оценить длительность, возможные блокировки и безопасный контрольный предел;
• если предел вышел без stop event: не ждать бесконечно, проверить target, строку breakpoint, загруженные метаданные, фактический сценарий вызова и контекст исполнения.

Клиентский контекст через Vanessa

Используй, когда отлаживаемый код выполняется в форме, команде, обработчике UI или другом клиентском контексте.

1. Запустить Vanessa/test-клиент штатным способом проекта.
2. Через v8-session-manager получить список активных сессий и определить сеанс тест-агента: infobase_name, ib_session_number, session_id, пользователь, признак тестового клиента.
3. В get_targets отладчика выбрать target, соответствующий этому сеансу. Если соответствие неочевидно, сверить время запуска, пользователя и номер сеанса ИБ.
4. Поставить breakpoint в клиентском модуле.
5. Запустить Vanessa-сценарий или конкретный шаг, который вызывает нужный обработчик.
6. Сразу перейти в отладчик и опрашивать wait_for_stop каждые 5 секунд до stop event или контрольного таймаута.
7. После continue вернуться к Vanessa-прогону и дождаться его штатного завершения.

Клиентский контекст через MCP-управление клиентом

Используй, когда сценарий проще инициировать накликиванием, чем писать или запускать Vanessa.

1. Запустить тестовый клиент 1С.
2. Подключить его к v8-session-manager.
3. Найти его сессию через session_list и сопоставить с target отладчика.
4. Поставить breakpoint.
5. Через UI-tools менеджера открыть форму, нажать команду, заполнить поле или выполнить другое действие, которое вызывает нужный клиентский код.
6. После остановки управлять ходом выполнения через debugger MCP, а не через UI-tools.

Серверный контекст через YaxUnit

Используй, когда отлаживаемый код выполняется на сервере, в общем модуле серверного назначения, менеджере, объекте, проведении или серверной части формы.

1. Подготовить минимальный YaxUnit-тест, который вызывает нужную экспортную серверную процедуру или ближайшую публичную точку входа.
2. Если в проекте уже есть tool/раннер для вызова произвольного серверного метода, можно использовать его вместо нового теста.
3. Поставить breakpoint до запуска теста.
4. Запустить один конкретный тест, а не весь набор.
5. Сразу перейти к wait_for_stop; для быстрого серверного метода предел ожидания 30 секунд, для тяжёлого — заранее заданный контрольный предел.
6. После continue дождаться завершения теста и проверить его результат.

Серверный контекст через временный MCP tool расширения

Используй как крайний вариант, когда серверный метод нельзя удобно вызвать тестом, HTTP-запросом или существующим runner/tool.

1. В расширении с mcp_tools временно добавить узкий tool, который вызывает только нужную серверную точку входа с контролируемыми параметрами.
2. Пометить временный метод как отладочный и не смешивать его с рабочим API расширения.
3. Поставить breakpoint.
4. Вызвать временный tool через MCP-витрину.
5. После отладки удалить временный tool, его регистрацию, экспортные методы и тестовые данные.
6. Проверить, что в исходниках не осталось мусорных методов, временных команд, debug-имен и лишних прав.

Другие серверные триггеры

Допустимы HTTP-сервис, регламентное задание, проведение документа или фоновое задание, если это безопасно и воспроизводимо. Для таких сценариев заранее зафиксируй, какой target должен остановиться, и не оставляй остановленный поток в транзакции.

Выбор точки остановки

Ставь breakpoint не “где-нибудь в процедуре”, а на строке, которая отвечает на текущий вопрос:

• вход в процедуру — проверить факт вызова и аргументы;
• строка перед Если — проверить переменные, влияющие на ветвление;
• строка перед запросом — проверить параметры запроса;
• строка после запроса — проверить размер и ключевые поля результата;
• строка перед возвратом — проверить итоговое значение.

Если процедура не останавливается, проверь:

• вызывается ли именно этот модуль, а не модуль расширения/переопределения;
• совпадает ли строка после загрузки метаданных;
• есть ли target нужного типа;
• не выполняется ли код в другом сеансе или фоновом задании.

Работа с переменными

Смотри только значения, которые влияют на текущую гипотезу:

• параметры процедуры;
• переменные из условия текущей ветки;
• параметры запроса;
• результат запроса, но без полного дампа больших таблиц;
• ссылки и объекты только через ключевые реквизиты.

Не вычисляй выражения с побочными эффектами. evaluate допустим для чтения простых выражений, но не для записи, проведения, вызовов HTTP, изменения глобального состояния и запуска бизнес-операций.

Пошаговая отладка

Используй шаги экономно:

• step_in — когда нужно зайти в вызываемую процедуру и увидеть её аргументы/ветку;
• step_out — когда текущая процедура уже понятна и нужен результат возврата;
• continue — когда нужно дойти до следующего breakpoint или отпустить поток;
• pause — только если нужно остановить уже выполняющийся target и это безопасно для сеанса.

После каждого шага фиксируй наблюдение: где остановились, какие значения изменились, какая гипотеза подтвердилась или отпала.

Завершение

Перед финальным ответом или передачей задачи дальше обязательно:

1. clear_breakpoints по всем установленным точкам.
2. continue, если поток ещё остановлен и его безопасно отпустить.
3. detach.
4. Если detach не сработал, attach возвращает ibInDebug, ping-cycle завис или get_targets показывает активный debug-состояние после очистки — выполнить force_detach, затем повторно проверить get_targets.
5. Если создавался временный YaxUnit-тест или MCP tool — удалить его или явно оставить только если это согласовано как полезный тестовый артефакт.
6. Проверить, что сценарий не оставил заблокированную сессию, зависшее задание или отключённые регламентные задания.
7. В отчёте указать: 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

---