Как применять codex-1c в разработке 1С

Часть 1. От небольшой задачи до проверенного результата

Продолжение статьи: //infostart.ru/1c/articles/2811830/

Бухгалтер попросила программиста сделать кнопку: пусть показывает, какие поля документа ещё не заполнены. Кнопка появилась быстро. Но стоило очистить поле без записи документа, как обнаружилась ошибка: проверка читала старое значение из базы.

Это учебный случай. Он объясняет, с чего стоит начинать работу с ИИ: показать, что делает человек, и договориться, какой результат он должен увидеть. Для самой разработки можно использовать codex-1c.

Что берёт на себя технология

codex-1c объединяет правила, навыки и скрипты для разработки в Codex. Агент изучает исходники конфигурации, предлагает решение, меняет BSL и XML, выполняет проверки и готовит результат. Разработчик задаёт нужное поведение, разрешает операции с базой и принимает работу.

Выбор формата зависит от задачи: CFE — расширение конфигурации, EPF — внешняя обработка, ERF — внешний отчёт. Задачи хранятся отдельно от технологии, каждая со своей историей в Git. Поэтому можно увидеть изменения и продолжить работу, не полагаясь на память чата.

Как дать первое задание

В подготовленном окружении откройте каталог codex-1c и вызовите $start-1c. Укажите задачу, вид объекта и id тестовой базы. Например:

$start-1c
Нужна задача CFE для базы <id_тестовой_базы>.
Добавь в форму <Документ> команду «Проверить заполнение».
Проверяй <поле А> и <поле Б> по текущим значениям формы,
в том числе до записи документа. Покажи все пропуски.
Документ не изменяй, не записывай и не проводи.
Сначала изучи исходники и предложи решение и приёмку.

Имена в угловых скобках нужно заменить своими. Для начала необходимы Codex, PowerShell 7, Git, платформа 1С, настроенный профиль и подходящая выгрузка конфигурации. Подробный порядок настройки и выполнения — во второй части.

Как довести задачу до результата

Сначала посмотрите решение. Какие объекты меняются? Откуда берутся данные? Что именно проверяется? Постановку, решение и приёмку сохраняют в PROJECT.md. Это помогает вернуться к договорённости, если работа пошла иначе.

Затем агент вносит изменения. Проверьте diff: для небольшой кнопки не должны без причины появляться посторонние объекты и обработчики. После этого выполняются проверки метаданных, кодировки и, при необходимости, анализ BSL. Замечания нужно разобрать, а не ограничиться сообщением о завершении анализатора.

Перед операцией с базой просмотрите её параметры через -WhatIf. Агент должен назвать точный id базы и режим. Разрешение на выполнение даётся отдельно от описания задачи. После установки или отката расширения нужен новый клиентский сеанс.

Наконец, проверьте работу так, как её делает пользователь. Для нашей кнопки мало нажать её в сохранённом документе. Нужно очистить поле без записи, создать новый документ, исправить пропуск и повторить проверку. Команда должна учитывать изменения формы и ничего не записывать сама.

За счёт чего работа становится проще

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

Практический выигрыш дают три привычки:

• Брать небольшую законченную задачу и сразу задавать наблюдаемый результат.

• Проверять решение до правки кода, пока ошибку ещё легко исправить.

• Завершать работу приёмкой, а не появлением файла в каталоге сборки.

Для первого задания достаточно одного агента. Несколько исполнителей полезны, когда есть независимые части работы; подключать их только ради маленькой кнопки незачем.

В итоге у разработчика должны остаться исходники, готовый файл CFE, EPF или ERF, результаты проверок и понятная запись о том, что принято. Экономию времени можно оценить на своих задачах. Само присутствие ИИ ещё ничего не доказывает.

Режимы, команды, файлы результата и документированный прогон EPF разобраны в части 2. Материал подготовлен по локальному codex-1c.

Рабочий процесс codex-1c

Часть 2. Режимы выполнения и артефакты каждого этапа

Эта часть — практическая карта технологии. Она показывает, что выполняется на каждом шаге, какой режим нужен и где искать результат. В конце приведён документированный цикл EPF на тестовой базе irtest, сверенный с сохранившимися протоколами. При подготовке статьи новые обращения к ИБ не выполнялись.

Основа описания — рабочее дерево codex-1c на 3 ноября 2026 года: HEAD 3f7051c и локальные изменения поверх него, включая исправление передачи /C. Поэтому один Git SHA здесь не описывает весь проверенный код. Общий принцип применения разобран в части 1.

Сначала различим режимы

В codex-1c слово «режим» относится к разным настройкам. Сценарий, доступ к базе, разрешение на выполнение и критерий завершения не заменяют друг друга.

ReadOnly не означает отсутствие файловых изменений: сборка EPF читает ИБ, но создаёт артефакт на диске. Write означает потенциальную запись; даже EPF с запросом ВЫБРАТЬ 1 запускается в этом режиме.

-WhatIf не обращается к ИБ, но некоторые команды создают локальный каталог протокола. Если переданы оба флага, предварительный просмотр имеет приоритет. В автоматическом исполнении нужен -Execute. Без флагов поведение зависит от команды: мастер и создание задачи дают просмотр, а общий механизм допуска может запросить интерактивное подтверждение либо отказать при отсутствии ввода. Для ясного workflow всегда задавайте нужный флаг явно.

Все семь сценариев мастера

Вход из чата — $start-1c; из CLI — scripts/start-scenario.ps1. HTA-анкета docs/master-anketa.hta формирует JSON v2 и копирует запрос для чата. Сама она его не отправляет и не разрешает исполнение.

Для run и web обязателен -ArtifactPath: мастер не выбирает «последний файл». Эти сценарии предназначены для EPF, не для запуска ERF как обработки. deploy предназначен только для CFE. Просмотр continue внутренне использует подготовку сценария build; это не разрешение на сборку или поставку.

Общий маршрут: постановка → решение → BSL/XML → проверки → сборка или поставка → функциональная приёмка → итог. Для расширения после поставки или отката обязательно начать новый клиентский сеанс.

Схема ветки CFE. У EPF/ERF вместо поставки расширения выполняется сборка внешнего объекта; запуск EPF — отдельный шаг.

По умолчанию работает один агент. $orchestra разрешает распределить независимые пакеты между onec-scout, onec-implement, onec-check, tech-implement. Каждому задают разрешённые файлы и результат. Модель и reasoning наследуются; обращения к ИБ и поставка остаются у главного агента.

Постановка и исходники

Окружение берётся из .v8-project.json, локальные секреты — из .v8-project.local.json или предусмотренных переменных среды. projectPath определяет каталог задач, configSrc — выгрузку родителя. Дополнительный профиль передают через -ProfilePath; у поддерживающих его скриптов есть также -ProfileMerge.

Для новой задачи сначала указывают имя, вид объекта, базу и постановку. Команды ниже выполняются в PowerShell 7 из корня технологии; id и пути нужно заменить своими.

Set-Location 'E:\1C\codex-1c'
$BaseId = '<id_тестовой_базы>'
pwsh -NoProfile -File scripts/new-project.ps1 `
  -Name ПроверкаЗаполнения -Kind cfe -Base $BaseId `
  -Assignment 'Проверять текущие значения полей формы' -WhatIf

После проверки параметров повторяют вызов с -Execute вместо -WhatIf. Для CFE нужна выгрузка родителя с Configuration.xml. Создание не устанавливает расширение в ИБ.

Ревизия технологии проверяется по .onec-task.json; другой HEAD вызывает отказ. Изменения незакоммиченного рабочего дерева этой проверкой не описываются. Пути вне задачи и reparse points отвергаются. Актуальность configSrc относительно живой ИБ нужно выяснить отдельно.

Решение записывают до изменения BSL/XML. После правок проверяют метаданные и формы, кодировку и при необходимости BSL:

$TaskPath = 'E:\1C\proj\ПроверкаЗаполнения'
pwsh -NoProfile -File scripts/check-encoding.ps1 `
  -Path "$TaskPath\src"
pwsh -NoProfile -File scripts/bsl-analyze.ps1 `
  -Path "$TaskPath\src" -Reporter json,junit -Execute

BSL LS запускается локально либо с -Docker. Доступны форматы console, json, sarif, generic, junit, tslint, code-quality; отчёты по умолчанию находятся в out/bsl/<runId>/. Код процесса 0 не означает отсутствия диагностик. Проверка технологии verify.ps1 работает без ИБ и сети; интеграционный контур запускают отдельно и явно с -Execute.

Сборка и поставка

Ветка CFE использует cfe-deploy.ps1. Перед реальным обращением к базе называются её точный id и режим Write. Сначала выполняется просмотр:

pwsh -NoProfile -File scripts/cfe-deploy.ps1 `
  -TaskPath $TaskPath -WhatIf

После авторизации именно этой операции — выполнение. -AllowCreate нужен, когда разрешено создать отсутствующее расширение:

pwsh -NoProfile -File scripts/cfe-deploy.ps1 `
  -TaskPath $TaskPath -Execute -AllowCreate

Этапы транзакции: prepare → inspect → snapshot-working и snapshot-applied для существующего расширения → load → update → settings → check → build → publish. Сначала фиксируется копия исходников; затем состояние расширения и необходимые снимки. При отказе обязательного снимка изменение не начинается. Готовый CFE публикуется только после успешного завершения предусмотренных проверок.

Параметр -SafeMode у поставки принимает три значения:

• Preserve — по умолчанию: сохранить прежнюю настройку; для нового расширения взять текущее состояние после создания.

• Enabled — включить безопасный режим расширения.

• Disabled — отключить его. Это не переключатель режима доступа ReadOnly/Write.

При сбое после изменения существующего расширения восстанавливаются применённое и рабочее состояния и настройки. Для нового расширения предусмотрено удаление созданного объекта с проверкой отсутствия. Это восстановление расширения, а не резервная копия всех данных ИБ.

Ветка EPF/ERF использует build-external.ps1; режим обращения к ИБ — ReadOnly. $TaskPath здесь должен указывать на задачу соответствующего вида:

pwsh -NoProfile -File scripts/build-external.ps1 `
  -TaskPath $TaskPath -WhatIf
# После проверки параметров и разрешения на операцию:
pwsh -NoProfile -File scripts/build-external.ps1 `
  -TaskPath $TaskPath -Execute

Результат обеих веток находится в задаче: build/<kind>/<имя>_<runId>.<kind>. В result.json записываются абсолютный путь и SHA-256. Предыдущие артефакты сохраняются; новый публикуется атомарно. Сборка EPF/ERF не означает, что внешняя обработка или отчёт уже прошли функциональную проверку.

Запуск EPF и завершение

run-epf.ps1 запускает клиент, run-epf-ws.ps1 — тонкий клиент через /WS выбранной публикации. Название сценария web не означает автоматизацию браузера. Для COM-проверки есть run-1c-check.ps1. Все эти проверки потенциально меняют данные и требуют режима Write.

$EpfPath = '<абсолютный путь EPF из result.json>'
pwsh -NoProfile -File scripts/run-epf.ps1 `
  -Base $BaseId -Path $EpfPath -CompletionMode AtomicReport -WhatIf
# После авторизации запуска в выбранной базе:
pwsh -NoProfile -File scripts/run-epf.ps1 `
  -Base $BaseId -Path $EpfPath -CompletionMode AtomicReport -Execute

Exit — режим по умолчанию: требуется успешное завершение процесса с кодом 0. AtomicReport дополнительно требует отчёт с совпадающим runId, schemaVersion=2, status="success" и строкой summary. Само появление отчёта не завершает ещё работающий клиент.

Обработка получает через /C JSON с schemaVersion, runId, reportPath, parameters. Она должна записать временный файл рядом с reportPath, закрыть его и атомарно переименовать. Прямая запись окончательного файла не принимается. Минимальная структура отчёта:

{"schemaVersion":2,"runId":"<runId из /C>",
 "status":"success","summary":"Проверка выполнена"}

У обёрток -ParametersFile содержит пользовательские параметры обработки. У invoke-onec.ps1 одноимённый аргумент содержит параметры самой операции. Это разные уровни. Все пути операций задаются абсолютными.

Designer, Enterprise, веб-подключение и COM проходят через общий gate, mutex базы на Windows-хосте и Windows job object. При таймауте завершается группа процессов. Для автоматического запуска нужен явный -Execute.

Где искать артефакты процесса

Исходники и итоговые бинарные файлы принадлежат задаче. Протоколы стандартных операций ядра находятся в технологии: out/<операция>/<runId>/. Для CFE это out/deploy/, для EPF/ERF — out/build/, для запусков — out/run-epf/ или out/run-web/. Не каждый файл появляется при каждом статусе.

В result.json поле artifact может быть пустым: например, у запуска EPF нет нового бинарного файла. Путь к уже собранной обработке и отчёт о её выполнении нельзя путать с результатом новой сборки. Создание каркаса, continue и простая проверка кодировки не гарантируют отдельный result.json: не все скрипты используют протокол запуска ядра.

Git задачи хранит изменения исходников и документов. Секреты, служебный out/ и артефакты build/ исключаются из Git. Итог приёмки записывают в PROJECT.md: что изменено, где результат, что проверено и какие ограничения остались. Отступления — в docs/otstuplenija.md; переносимый опыт — только если получен проверенный урок.

Каталог операций и граница доступа

Общий вход — scripts/invoke-onec.ps1 -Base ... -Operation ... -Mode .... Режим по умолчанию — ReadOnly; ядро отклоняет операцию записи без Write. Ниже весь каталог операций текущей версии; в скобках отмечены необязательные параметры.

Поставку расширения выполняют целиком через cfe-deploy.ps1, не заменяют набором отдельных load/update. Запись основной конфигурации требует отдельной постановки и -Execute -AllowMainConfig -ConfirmMainConfig <точный id>. Перечень выше описывает интерфейс, а не разрешает каждую операцию.

Пример подготовки инспекции базы:

pwsh -NoProfile -File scripts/invoke-onec.ps1 `
  -Base $BaseId -Operation inspect -Mode ReadOnly -WhatIf

У invoke-onec.ps1 параметры операции можно передать JSON-файлом через -ParametersFile, а из PowerShell — hashtable через -Parameters. Произвольной строки платформенных аргументов в публичном интерфейсе нет.

Для практической приёмки проверяют поведение пользователя, включая новый документ, несохранённые изменения и повторный запуск команды. Успешная сборка, код процесса 0 и зелёный статус анализатора отвечают каждый на свой вопрос. Они не заменяют такой проверки.

Документированный цикл на irtest

1 ноября 2026 года выполнен цикл задачи EPF_Cycle_irtest_20261101_024f7c: создание, сборка, запуск, отчёт и завершение клиента. Окружение — Windows x64, 1С 8.3.27.2342, БухгалтерияПредприятияКОРП 3.0.206.19. Обработка выполняла ВЫБРАТЬ 1, читала имя и версию конфигурации и возвращала параметр в отчёте.

Создание выполнялось публичным new-project.ps1, сборка — build-external.ps1 в ReadOnly, запуск — run-epf.ps1 в Write с AtomicReport. Перед исполнением делались preview. Согласно описанию цикла, прикладные данные этим кодом не изменялись; это не основание понижать режим доступа запуска.

При подготовке этой части прочитаны существующие result.json сборки 4c9cba96051b46ac85bd7acda5b26691, запуска e77334077c594f3b92188fa5e3bf4548 и отказа 8f80594394734a59b5007b3414e4baed. Проверены наличие собранного EPF, соответствие его SHA-256 и поля успешного completion.json. Новая сборка или запуск в ИБ не выполнялись.

Этот пример показывает весь путь доказательства: исходники задачи → опубликованный EPF → отдельный запуск → отчёт обработки → завершение клиента → итог ядра. Файл после сборки был пригоден для запуска, но проблема проявилась в передаче параметров. Её обнаружил именно полный цикл.

Источники и границы

Пути относительно E:\1C\codex-1c: README.md, docs/contract.md, docs/razrabotchik.md, docs/interfaces-v2.md, docs/orchestra.md, docs/epf-cycle-irtest.md; публичные скрипты scripts/; модули scripts/core/Policy.psm1, Delivery.psm1, Processes.psm1, Protocol.psm1.

Протоколы реального примера находятся в локальном out/ и не входят в Git. Для публикации достаточно приведённого описания и обезличенной сводки проверка/real-workflow-evidence.json; служебные журналы и сведения доступа переносить в статью не нужно. Испытание EPF подтверждает описанный сценарий на указанном окружении, но не является доказательством проверки всех операций каталога или аварийного восстановления CFE.