ИИ-агенты: проверка после правки¶

Агент, который правит код 1С (Claude Code, Codex, Cursor, агентный фреймворк), обычно проверяет себя анализатором BSL после каждой правки и синтаксическим контролем Конфигуратора (/CheckModules) перед коммитом. Синтаксический контроль не ловит опечатку в поле запроса, лишний параметр в вызове экспортного метода, переименованный обработчик события формы, ошибку при открытии формы и метод платформы новее режима совместимости той же линейки — каждый случай доказан контрольным дефектом («ОТК и проверка Конфигуратором»). ОТК ловит их и отвечает в виде, удобном агенту: код выхода, строки «файл(строка,колонка)» и JSON с находками.

Цикл¶

агент правит код → otk gate … → код выхода → 0: дальше / 1: исправить находки / 2: сообщить человеку

Когда	Команда	Время
после каждой правки	`otk gate --base HEAD --worktree --static-only --quiet --problems`	секунды, без базы и лицензии 1С
перед коммитом или PR	`otk gate --base HEAD --worktree --quiet --problems`	минуты: пробы в своей копии ИБ
ветка целиком	`otk gate --base origin/master --quiet --problems`	то же по всем коммитам ветки
без git	`otk gate --dir <выгрузка> --base-dir <было> --quiet --problems`	как выше

--worktree проверяет незакоммиченные правки рабочего дерева, --static-only — только статику. Ключи и настройки — «Команды».

Что читать агенту¶

Код выхода — главное: 0 — можно двигаться дальше, 1 — найдены ошибки, 2 — сбой окружения (копия ИБ занята, платформа не запустилась) или ничего не проверено. При 2 править код бесполезно — это задача человека.

Строки --problems (с --quiet — только они и строка вердикта):

# ОТК: есть ошибки — не отправлять (код 1)
…\Catalogs\Номенклатура\Ext\ObjectModule.bsl(14,1): error common-method: Слишком много параметров: Ценообразование.ОкруглитьЦену принимает 1, передано 2 [Справочник.Номенклатура.ПередЗаписью; найдено: статика (common-method)]
…\Catalogs\Номенклатура\Forms\ФормаЭлемента\Ext\Form\Module.bsl(1,1): error handler: Обработчик из Form.xml не найден в модуле формы: ЦенаПриИзменении [Справочник.Номенклатура.Форма.ФормаЭлемента; найдено: статика (handler)]
…\CommonModules\Взаиморасчеты\Ext\Module.bsl(65,1): warning platform-api: Метод ЗаписатьЗначениеJSON доступен с 8.3.23 (режим совместимости 8.3.21): на платформе ниже 8.3.23 модуль не скомпилируется [ОбщийМодуль.Взаиморасчеты.КонтрагентВJSON; найдено: статика (platform-api)]
…\otk-1c-demo(1,1): warning not-checked/analyzers: проверка «новые замечания анализатора BSL» — не найдено: BSL LS (…) — теряется: замечания анализатора по правке
сводка: …\otk\otk-1c-demo-…\summary.md (HTML: …\summary.html)

Формат строки — <абсолютный путь>(<строка>,<колонка>): <error|warning> <правило>: <текст> [<объект.метод>; найдено: <проверки>]. Это вывод ветки defects демо-проекта, правки которой лежат в рабочем дереве незакоммиченными.

summary.json — рядом со summary.md (путь — в последней строке вывода), схема — src/otk_1c/schema/summary.schema.json:

{
  "schema": "otk.summary.v1", "version": "…",
  "code": 1,
  "verdict": "есть ошибки — не отправлять",
  "findings": [{
    "severity": "error", "step": "static", "rule": "common-method",
    "file": "src/cf/Catalogs/Номенклатура/Ext/ObjectModule.bsl", "line": 14, "column": 1,
    "message": "Слишком много параметров: Ценообразование.ОкруглитьЦену принимает 1, передано 2",
    "object": "Справочник.Номенклатура", "method": "ПередЗаписью",
    "place": "Справочник.Номенклатура.МодульОбъекта(14)",
    "text": "Цена = Ценообразование.ОкруглитьЦену(Цена, 2);",
    "sources": [{"step": "static", "rule": "common-method", "message": "…"}]
  }],
  "notChecked": [{"check": "analyzers", "what": "проверка «новые замечания анализатора BSL»",
                  "reason": "не найдено: BSL LS …", "reasonCode": "no-analyzer"}],
  "infra": []
}

text — строка кода, по которой сделана находка: агент находит место, даже если строки уже сдвинулись. Что значит каждое правило (rule) и как исправить — справочник находок (раздел — по правилу). notChecked — чего ОТК не проверил из-за окружения: это не «чисто», агенту стоит сказать об этом человеку. Тот же результат в SARIF — summary.sarif («Сводка и коды выхода»).

Итог в JSON: `--json`¶

Агенту, который разбирает вывод программой, удобнее один объект: otk gate … --json печатает в stdout только итог (схема src/otk_1c/schema/gate-result.schema.json, "schema": "otk.gate-result.v1"), журнал прогона уходит в stderr, код выхода тот же. Перед gate агент проверяет окружение: otk doctor --json (doctor-result.schema.json, otk.doctor-result.v1).

otk doctor --json → чинить по reasonCode (или сказать человеку) → otk gate --base HEAD --worktree --json

{
  "schema": "otk.gate-result.v1", "version": "…", "code": 2, "status": "infra",
  "verdict": "сбой инфраструктуры", "summaryPath": "…/otk/проект-…/summary.json",
  "findings": [],
  "notChecked": [{"status": "not-checked", "reasonCode": "no-yaxunit", "check": "smoke",
                  "what": "проверка «открытие изменённых форм»",
                  "message": "не найдено: YAxUnit (--yaxunit; environment.yaxunit) — теряется: ошибки при открытии форм",
                  "remediation": "укажите YAxUnit (.cfe): --yaxunit, environment.yaxunit"}],
  "infra": [{"status": "infra", "reasonCode": "ib-busy",
             "message": "база D:\\ib\\копия занята (заблокированы 1Cv8.cfl); …",
             "remediation": "закройте Конфигуратор и сеансы 1С:Предприятия с этой базой и повторите gate"}]
}

status итога: ok — можно отправлять, nothing — нечего проверять, errors — есть ошибки (код 1), infra — сбой инфраструктуры, not-checked — ничего не проверено (оба — код 2). findings, uncovered, notes — как в summary.json. Прогон оборвался до сводки (нет выгрузки, ошибка git или настройки) — тот же объект с кодом 2, runDir и summaryPath — null. С --json объект печатается всегда, в том числе при исключении в самой ОТК (reasonCode — internal, трассировка — в stderr).

doctor --json не дошёл до окружения (битый otk.toml, сбой ОТК) — код 2 и поле error с reasonCode. В doctor --json недоступная проверка (checks[].state = "unavailable") несёт reasonCodes и remediation недостающих зависимостей, fatal — режим on: gate завершится сбоем. environment[] без зависимости тоже несёт reasonCode, но важна она, только если её ждёт доступная иначе проверка. Занятость копии ИБ doctor не проверяет (не трогает блокировки) — её сообщает gate (ib-busy).

Коды причин¶

Список стабилен: новые коды добавляются, существующие не переименовываются. Нераспознанная причина — other; незнакомый агенту код (из новой версии ОТК) читайте как other и действуйте по remediation («Контракт»).

Код	Причина	Что делать агенту
`ib-busy`	копия ИБ занята (`.cfl`, сеанс 1С)	сказать человеку; повторить после закрытия сеансов
`ib-auth`	в ИБ есть пользователи, вход не задан	`--user`, `OTK_PASSWORD` — у человека
`ib-invalid`	каталог копии ИБ не пуст и не файловая ИБ; нет копии с основной конфигурацией	сказать человеку
`no-ib`	копия ИБ не задана	`--ib` своей копии или `--static-only` и сказать, что не проверено
`no-platform`	платформа 1С не найдена	`--platform` или `--static-only`
`no-ibcmd`	нет `ibcmd` при `environment.ibTool = ibcmd`	`ibTool = designer` или сказать человеку
`no-license`	нет лицензии 1С	`--static-only`, сказать человеку
`no-yaxunit`	YAxUnit не задан	`--yaxunit`, если путь известен
`no-com`	нет COM (не Windows, нет pywin32)	YAxUnit или `pip install "otk-1c[com]"`
`no-display`	Linux без Xvfb и `DISPLAY`	сказать человеку
`no-analyzer`	нет BSL LS и bsl-analyzer	сказать человеку (проверку не выключать)
`no-edtcli`	нет 1cedtcli для исходников EDT	`--edtcli` или сказать человеку
`no-help`	нет справки платформы	`--platform` на полную установку
`no-availability`	нет точной таблицы доступности методов (только doctor)	`otk availability build` — по согласию человека
`no-git`	нет git (только doctor)	`gate --dir`
`no-python`	Python ниже 3.11 (только doctor)	сказать человеку
`no-source`	нет файла конфигурации в каталоге выгрузки	`--dir` или `--source`
`no-parent`	у расширения нет выгрузки основной конфигурации	`--parent`, если путь известен
`no-plan`	нет плана `otk.json` (`report`, `static`)	сначала `collect` или `gate`
`timeout`	платформа не завершилась за тайм-аут	повторить один раз; снова — сказать человеку
`platform-failed`	Конфигуратор или ibcmd завершился ошибкой	сказать человеку; код не править
`restore-failed`	ОТК не вернула базу к виду до проверки (расширения — в сохранённых `.cfe`)	сразу сказать человеку; повторно не запускать
`edt-failed`	экспорт EDT завершился ошибкой	сказать человеку
`config-invalid`	ошибка настройки или ключей	исправить ключ из сообщения
`probe-failed`	исполнитель проб не запустился (COM, сеанс YAxUnit)	повторить; снова — `otk doctor --json`
`query-incomplete`	текст запроса собран из переменных частей	сказать, что запрос не проверен
`internal`	исключение в самой ОТК (не в проверяемом коде)	повторить; снова — сказать человеку, код не править
`other`	прочее	сказать человеку текст `message`

Правило для агента¶

Вставьте в инструкции агента проекта (AGENTS.md, CLAUDE.md и т. п.) и поправьте под себя:

## Проверка кода 1С (ОТК)
- После каждой правки модулей: `otk gate --base HEAD --worktree --static-only --quiet --problems`.
- Перед коммитом: `otk gate --base HEAD --worktree --quiet --problems`.
- Код 1 — исправь находки `error` и запусти снова; `warning` — оцени, исправь или объясни, почему оставил.
- Код 2 — не правь код: сообщи человеку строку вердикта.
- Строки `not-checked` — перечисли человеку, что не проверено.
- Не отключай проверки и не меняй otk.toml, чтобы получить код 0.

Агенту, которому нужны данные копии ИБ (проверить запрос на живых данных, посмотреть метаданные, журнал регистрации), — MCP-сервер otk mcp («Дополнительные инструменты»).