Menu
v8-runner: базы, сборка, проверки, тесты, клиенты 1С
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
When writing or reviewing BSL, apply 1C standards
При написании или ревью BSL применять стандарты 1С
Orchestrator: routing work and agent phases
Оркестратор: маршрутизация работы и фаз агентов
BSL LSP navigation: definitions, refs, call graph
Rules for using RLM tools for project search and navigation in 1C/BSL
| name | v8-runner |
| description | v8-runner: базы, сборка, проверки, тесты, клиенты 1С |
| provides_capabilities | ["build_project","full_rebuild_project","init_infobase","config_init","syntax_check_designer_modules","syntax_check_designer_config","syntax_check_edt","run_yaxunit","run_vanessa","dump_config","load_artifact","make_artifacts","convert_sources","launch_designer","launch_thin_client","launch_mcp_client","run_session_manager","extensions_update"] |
Используй этот навык, чтобы управлять v8-runner как слоем автоматизации для локальных 1С-проектов разработки.
Держи этот файл как точку входа для решений. Загружай только тот reference-файл, который соответствует задаче:
references/command-selection.md — для выбора правильной последовательности команд.references/bootstrap.md — для генерации v8project.yaml из существующего репозитория: что определять самостоятельно, а что спрашивать у пользователя (дерево решений для format, builder, connection).references/config-and-backends.md — про v8project.yaml, source-set'ы, форматы, builder'ы и ограничения backend'ов.references/project-workflows.md — типовые сценарии build, syntax, dump, launch и синхронизации исходников для Designer- и EDT-проектов.references/file-and-artifact-workflows.md — про dump, convert, load, make/artifacts и поэтапную публикацию.references/testing.md — про YaXUnit, Vanessa Automation, синтаксические проверки и артефакты.references/troubleshooting.md — про сбои настройки, устаревшее состояние и диагностику окружения.references/auth-guard.md — hard-stop по license-паттернам, правило двух кандидатов, классификация ошибок auth/path, хранение credentials в v8project.local.yaml.Канонический путь к бинарнику — tools/external/v8-runner/v8-runner (в проекте это работает через tools/-симлинк на фреймворк). Установщик фреймворка тянет Latest-релиз из alkoleft/v8-runner-rust (upstream) при каждом запуске; ручная переустановка — python tools/install.py --install-external-tools. Если бинарник по этому пути отсутствует и в PATH тоже нет — попроси путь у пользователя или используй wrapper-скрипт из проекта.
WS-транспорт: используется форк SteelMorgan. Для WS-сопряжения с менеджером сессий используется форк
SteelMorgan/v8-runner-rustвместо upstreamalkoleft/v8-runner-rust, т.к. PR-ы с WS-поддержкой в upstream не принимаются. Установщик фреймворка ориентирован на релизы этого форка. Аналогичноwt-mcp-adapter(расширенияmcp_client,test_clientи др.) берётся из форкаSteelMorgan/wt-mcp-adapter.
v8project.yaml — имя конфига проекта по умолчанию. Соседний v8project.local.yaml загружается автоматически для машинно-локальных путей, учётных данных, инструментов, тестов и MCP-настроек. Не передавай --config v8project.yaml, если пользователь явно не просит нестандартную форму команды или активный путь к конфигу отличается от дефолтного; никогда не передавай v8project.local.yaml через --config.
Сгенерированные файлы v8project.yaml содержат modeline yaml-language-server, который указывает на версионированный JSON Schema для текущего релиза v8-runner. Для v8project.local.yaml используй соответствующий raw-URL docs/schemas/v8project.local.schema.json с GitHub-тега в настройках редактора, когда важна редактура с подсказками по схеме.
Используй JSON-вывод только когда другому инструменту, скрипту или итоговому ответу нужны структурированные результаты:
v8-runner --json-message build
Для прямой человеческой диагностики используй текстовый вывод.
Полезные глобальные флаги:
--config <CONFIG> — когда активный конфиг не ./v8project.yaml.--json-message — для машиночитаемых CLI-конвертов.--workdir <WORKDIR> — переопределяет workPath; имеет приоритет над v8project.local.yaml.--clean-before-execution — очистить логи перед выполнением.--log-level <error|warn|info|debug|trace> — для диагностики.--no-color — простой текстовый вывод.Интерактивные клиенты 1С и MCP/VA-сессии, которые должны оставаться доступными после возврата команды агенту, запускай как самостоятельные процессы с явным управлением жизненным циклом. Не используй sleep, tail -f, бесконечный shell-loop или похожую wrapper-команду как способ «удержать» клиент 1С живым: при завершении wrapper'а терминал/PTY или окружение агента может закрыть дочерний процесс 1С, а session-manager увидит это как обрыв WS без нормального закрытия.
Правильный порядок:
v8-runner launch ....nohup, setsid, service/job runner или эквивалент проекта), сохрани PID и лог запуска.session_list, появление нужных MCP-tools, окно 1С, файл-протокол или запись в ЖР.kill <PID> только для своего сохранённого PID.sleep допустим только как короткое ожидание между проверками готовности внутри скрипта/poll-loop. Он не должен быть владельцем жизненного цикла 1С-процесса.
v8project.yaml в корне 1С-проекта.v8-runner config init ..., подходящую под форму проекта.v8-runner init только когда нужно создать файловую ИБ или EDT-воркспейс.Полезные команды инициализации:
v8-runner config init
v8-runner config init --connection "File=build/ib"
v8-runner config init --format edt
v8-runner config init --builder IBCMD
v8-runner init
v8-runner build.--source-set <NAME>, вместо полной пересборки или материализации всего.v8-runner build --full-rebuild.format и builder, затем выбери syntax designer-modules, syntax designer-config или syntax edt.v8-runner test ...; тесты сначала собирают.v8-runner launch mcp va ..., чтобы запустить сеанс менеджера тестирования VA с MCP-инструментами. После старта проверяй готовность по session_list: нужен kind=vanessa_test_client и появление VA-tools, а не только первичная WS-регистрация.v8-runner extensions или extensions --name <SOURCE_SET>.git status, затем запусти подходящую команду v8-runner dump ....v8-runner convert; это только CLI и не использует ИБ..cf или .cfe нужно применить к ИБ: используй v8-runner load ....v8-runner make ... или алиас artifacts.v8-runner launch designer, launch thin, launch thick или launch ordinary.v8-runner launch mcp ....--mcp-transport, --manager-url, --client-uid, --corr-id, --mcp-log-level, --mcp-ws-timeout-ms) доступны на launch ... и test ... командах одинаково. Тонкий момент clap-структуры: на test флаги ставятся до подкоманды yaxunit/va (например v8-runner test --mcp-transport=ws yaxunit module <NAME>), а не после.WS-сопряжение с v8-session-manager — режим, в котором клиентский MCP-сервер 1С подключается к менеджеру по WebSocket вместо локального HTTP MCP. Управляется одним и тем же набором CLI-флагов (--mcp-transport, --manager-url, --client-uid, --corr-id, --mcp-log-level, --mcp-ws-timeout-ms) или tools.wt_mcp_adapter.* в v8project.yaml. Канон по транспорту/автоопределению, дефолтам и override каждого флага, формату /C и internal kind mapping — references/project-workflows.md (раздел «WS-режим к session-manager»); clap-нюансы и диагностика WS на test-командах — references/testing.md.
Один и тот же набор флагов работает для:
v8-runner launch designer | thin | thick | ordinary — флаги ставятся после launch.v8-runner launch mcp / launch mcp va — флаги ставятся после launch mcp [va].v8-runner test yaxunit all / test yaxunit module <NAME> — флаги ставятся на уровне test, ДО подкоманды yaxunit.v8-runner test va — флаги ставятся на уровне test, ДО подкоманды va.Пример (test): v8-runner test --mcp-transport=ws --mcp-log-level=debug yaxunit module mcp_МспПровайдер_Тесты. Если ставишь WS-флаги после yaxunit или module <NAME> — clap отвечает error: unexpected argument, потому что эти подкоманды свой собственный McpClientWsArgs не объявляют.
| Режим | Назначение | MCP/VA поведение |
|---|---|---|
launch designer | Открыть Конфигуратор. | Не запускает клиентские MCP-tools и не применяет enterprise additional keys. |
launch thin, launch thick, launch ordinary | Открыть обычный UI-клиент 1С. | При WS-сопряжении регистрирует базовый клиентский MCP-набор без kind; сам по себе не даёт VA-tools. |
launch mcp | Запустить wt-mcp-adapter внутри 1С без Vanessa. | kind=v8_runner_client для WS; локальный HTTP MCP при --mcp-transport=mcp или fallback из auto. |
launch mcp va | Запустить менеджер тестирования Vanessa для исследования, авторинга и клиентских MCP-tools VA. | kind=vanessa_test_client; runner добавляет /TESTMANAGER, /DisableUnsafeActionProtection, /Execute <vanessa-automation.epf>, runtime VAParams, отключает автозапуск/автозакрытие сценариев и не использует StartFeaturePlayer. |
test yaxunit ... | Выполнить YAxUnit тесты. | kind=yaxunit_runner в WS-режиме; это тестовый runner, а не интерактивная UI-сессия. |
test va | Выполнить Vanessa feature-сценарии. | kind=vanessa_test_client, но payload — StartFeaturePlayer;VAParams=...; это прогон сценариев, не режим исследования менеджера. |
Формат /C в WS-ветке (полный payload, различие launch mcp/mcp va vs launch thin/thick/ordinary, appending для test-команд) — канон в references/project-workflows.md, раздел «Что v8-runner подставляет в /C в WS-ветке».
Для workflow Vanessa Research/Scenario через наш v8-session-manager запускается не простой тонкий клиент, а сеанс менеджера тестирования с открытой обработкой Vanessa Automation:
v8-runner launch mcp va \
--mcp-transport ws \
--manager-url ws://127.0.0.1:4000/sessions \
--client-uid <uid> \
--corr-id <uid> \
--mcp-log-level debug \
--mcp-ws-timeout-ms 5000
Ожидаемая форма запуска 1С, которую должен собрать runner:
1cv8c ENTERPRISE
/TESTMANAGER
/DisableStartupDialogs
/DisableUnsafeActionProtection
/IBConnectionString <строка подключения из v8project.yaml>
/N <пользователь>
/P <пароль>
/Execute <путь>/vanessa-automation.epf
/C"mcpMode=ws;manager_url=ws://127.0.0.1:4000/sessions;client_uid=<uid>;kind=vanessa_test_client;corr_id=<uid>;mcp_log_level=debug;mcp_ws_timeout_ms=5000;VAParams=<runtime va-params.json>"
Обязательный смысл этой строки запуска: MCP-сессия должна жить на стороне процесса тест-менеджера с открытой внешней обработкой Vanessa Automation. Не запускай тестируемое приложение с формой MCPVA: MCPVA — внутренняя форма/модуль внешней обработки VA, и именно VA в процессе /TESTMANAGER должна выполнить MCPVA.ЗарегистрироватьИнструментыMCP().
/IBConnectionString в этой команде — база тест-менеджера. Для launch mcp va предпочитай отдельную пустую файловую ИБ: тест-менеджеру не нужны данные тестируемой конфигурации, ему нужна только среда для запуска VA EPF и публикации MCP-инструментов. Если manager-база отсутствует, workflow настройки должен создать/инициализировать её до запуска. Конкретные тестируемые ИБ выбираются позже через профили ДанныеКлиентовТестирования в VAParams, а не через базу тест-менеджера.
Критерий готовности VA MCP-сессии: в session_list появилась live-сессия kind=vanessa_test_client, и в её tools есть VA-инструменты (get_VanessaAutomation_state, connect_test_client, get_window_list_os, get_window_screenshot_os, get_form_analysis, manage_command_interface) или число tools стало больше базового набора client_mcp. Первичная регистрация с базовыми tools ещё не означает, что MCPVA.ЗарегистрироватьИнструментыMCP() уже отработал.
Сразу после v8-runner launch mcp va ответ session_list=[] или отсутствие VA-tools не является ошибкой: запуск тест-менеджера и регистрация инструментов штатно могут занимать 10-90 секунд. Обязательный readiness-loop:
session_list каждые 5-10 секунд.kind=vanessa_test_client, state=active, disconnected_secs_ago=null, inflight=0, и наличии нужных VA-tools для текущей задачи.VA MCP readiness blocker.После готовности WS-сессии тестируемое приложение в VA-контуре запускает сам тест-менеджер: перед вызовом проверь, что порт из выбранного профиля ДанныеКлиентовТестирования свободен. Затем вызови MCP-tool connect_test_client с аргументом profileName (имя профиля клиента тестирования, например Codex thin AgentAI). VA поднимет отдельный процесс /TESTCLIENT -TPort <auto> из профиля и подключит к нему ТестируемоеПриложение; после этого становятся доступны клиентские MCP-методы VA (get_form_analysis, manage_command_interface, manage_form_elements, screenshot/data tools и т.п.). Не запускай этот /TESTCLIENT вручную для VA-пути, если только не отлаживаешь сам механизм профилей.
После исследования, прогона ручных действий или ошибки обязательно вызови MCP-tool close_test_client. Передавай тот же profileName, если работал с конкретным профилем; без profileName tool закрывает текущий подключенный профиль. Это освобождает test-client процесс и не оставляет лишние 1С-сессии перед следующим запуском.
Скриншотные MCP-инструменты VA (get_window_list_os, get_window_screenshot_os) считай готовыми только после короткой smoke-проверки на текущем окружении: live-сессия должна оставаться активной, inflight=0, а PNG должен быть не пустым и не чёрным. Детальный порядок визуальной проверки и fallback-условия описаны в навыке va-visual-check.
Секцию tools.va / tests.va, пустую manager-базу в infobase.connection, профили TestClient в VAParams и preflight портов настраивай по references/config-and-backends.md (разделы «Vanessa Automation в v8project.yaml», «База тест-менеджера VA», «Профиль TestClient внутри VAParams» и «Preflight портов TestClient»). Точную командную цепочку запуска manager → connect_test_client → close см. в references/testing.md (раздел «Точная цепочка VA manager → TestClient»). Полный payload, JSON-форму вывода (--json-message), правила probe и поведение при недоступности менеджера — в references/project-workflows.md (раздел «WS-режим к session-manager»). Подъём самого менеджера в v8-runner не входит — см. навык v8-session-manager.
Если задача — пройти интерфейс 1С через клиентские MCP-tools (open_form, click, input, get_value, get_table_rows, test_client_start), этот контур допустим только для структурного управления, когда нужная функция принципиально отсутствует в VA MCP или когда он используется как часть VA/TestClient-сценария.
Рабочая цепочка:
tools/call session_list должен отвечать, даже если sessions=[]./TESTMANAGER:uid=$(cat /proc/sys/kernel/random/uuid)
setsid nohup v8-runner --no-color --log-level debug launch thin \
--mcp-transport ws \
--manager-url ws://127.0.0.1:4000/sessions \
--client-uid "$uid" \
--corr-id "ui-$uid" \
--mcp-log-level debug \
--mcp-ws-timeout-ms 5000 \
--raw-key /TESTMANAGER \
> "/tmp/ui-mcp-$uid.log" 2>&1 &
session_list live-сессии kind=1c-client, state=active, inflight=0, infobase_name=<нужная ИБ>. Базовая проверка перед UI-вызовами: infobase_info должен быстро вернуть ответ./TESTCLIENT -TPort <порт> и теми же параметрами подключения, пользователем и паролем, что в проектном запуске. Это предпочтительный путь: агент сам поднимает тестируемое приложение detached и сохраняет PID/лог, а test_client_start на следующем шаге используется как подключение управляющего /TESTMANAGER к уже слушающему порту. Если в проекте есть готовый launcher, он тоже должен передавать /N, /P, /UC и тот же connection string; иначе используй прямую форму платформы:setsid nohup /opt/1cv8/x86_64/<version>/1cv8c ENTERPRISE \
/DisableStartupDialogs \
/IBConnectionString 'Srvr="<server>";Ref="<infobase>";' \
/N <user> /P <password> /UC <unlock_code> \
/TESTCLIENT -TPort 1538 \
> /tmp/test-client-1538.log 2>&1 &
{"name":"test_client_start","arguments":{"session_id":"<1c-client session_id>","port":1538}}
Успешный критерий: {"ok": true, "data": {"connected": true}}.
session_id управляющей сессии: open_form → click/input/select → get_value/get_table_rows. Для элементов формы можно строить URI напрямую как control://<urlencoded form name>/<urlencoded element name>, если find нестабилен.Не делай так:
/TESTMANAGER: при первом test_client_start платформа может упасть с Тип не определен (ТестируемоеПриложение).test_client_start как на единственный способ запуска /TESTCLIENT, если он стартует клиента без /N и /P: такой процесс может остаться на входе в базу, а подключение вернёт Отсутствует подходящий клиент тестирования.tools/list доказательством готовности: proxied tools могут быть только из кеша session-manager. Готовность подтверждает live-сессия в session_list и успешный простой вызов (infobase_info).Если yaxunit_runner не регистрируется в
session_list, хотя WS-payload подставлен в/C— известный инцидент idle-handler race (DRIVE 2026-05-11) и его фикс (интервалМсп_ОтложенныйСтарт_Тик1→0.1вManagedApplicationModule.bsl): канон вreferences/testing.md(раздел «Диагностика WS-сопряжения test-фазы»).
Запуск внешней обработки в пакетном (headless) режиме с автоматическим выполнением её логики делается через v8-runner launch <thin|thick|ordinary> --execute "<путь к .epf>" (это 1cv8 ENTERPRISE /Execute<epf>). Ключевой нюанс, без которого приём не работает:
/Execute<epf> ОТКРЫВАЕТ ФОРМУ обработки (эмулирует «Открыть обработку»). Сам по себе он НЕ вызывает экспортный метод модуля объекта. Поэтому обработка без формы (только модуль объекта с экспортной процедурой) через /Execute не исполнит свою логику — точка входа никогда не будет вызвана.&НаКлиенте Процедура ПриОткрытии(Отказ), который распознаёт пакетный режим по параметру запуска, вызывает &НаСервере-метод (он и делает работу / дёргает экспортную процедуру модуля объекта), затем корректно завершает сеанс через ЗавершитьРаботуСистемы(Ложь).--c "<строка>" (это /C"<строка>") и читается в BSL через ПараметрЗапуска(). Используй sentinel-строку, чтобы форма отличала headless-запуск от интерактивного открытия и не авто-исполнялась при ручном открытии.--raw-key /DisableUnsafeActionProtection. Альтернатива — снять у пользователя флаг «Защита от опасных действий» или настроить профиль безопасности (но CLI-ключ предпочтительнее для разовых прогонов).// Модуль формы обработки
&НаКлиенте
Процедура ПриОткрытии(Отказ)
Если ПараметрЗапуска() = "ЗАПУСК_ПАКЕТНО" Тогда // sentinel из --c
Протокол = ВыполнитьОперациюНаСервере(); // серверная работа
// записать Протокол в известный файл для верификации снаружи
ЗавершитьРаботуСистемы(Ложь); // корректный выход без диалогов
КонецЕсли;
КонецПроцедуры
&НаСервере
Функция ВыполнитьОперациюНаСервере()
// разрешить все параметры СЕРВЕРНО (не из реквизитов формы — в headless их никто не заполнил),
// выполнить бизнес-логику, вернуть текст протокола
КонецФункции
v8-runner launch thin --execute "<абс. путь к .epf>" --c "ЗАПУСК_ПАКЕТНО" --raw-key /DisableUnsafeActionProtection
v8project.yaml — отдельный /S//F указывать не нужно.Альтернатива без
/Execute: из уже подключённой серверной сессии —ВнешниеОбработки.Создать(<путь>, Ложь)+ вызов её экспортного метода (или БСПДлительныеОперации.ВыполнитьПроцедуруМодуляОбъектаОбработки). Это требует канала «выполнить код на сервере» (менеджер сессий / тест-раннер), а/Execute— самодостаточен из командной строки.
references/auth-guard.md.1cv8, ibcmd или 1cedtcli; предпочитай командную поверхность v8-runner.dump проверь git status, если результат может перезаписать или смешаться с уже внесёнными правками исходников.workPath/temp/<runner-id>/runs/<run-id>/ для диагностики, не очищай их сразу.Когда сообщаешь о результатах, разделяй: