Урок 8. Передаём SDD-процесс bsl-flow

Результат: ты проводишь новую доработку расширения через bsl-flow и видишь, какие этапы он ведёт после ручного SDD из прошлого урока.

В прошлом уроке ты сам следил за порядком спецификации, ревью, реализации и проверки. Теперь коллега просит: «Сделай выгрузку нескольких заказов в XML. Если один не выгрузился, остальные должны уйти». В этой фразе нет ответа на важные вопросы. Что значит «ушли» — файлы на диске или HTTP-отправка? Что делать при повторе? Как назвать файлы? Можно ли оставить часть результата после ошибки? Начинать с генерации кода рано.

Для упражнения остаёмся в учебном расширении урока 4. Здесь «выгрузка» означает локальные файлы, без сети. Новая команда получает список выбранных учебных заказов. Один файл — один заказ, содержимое по формату урока 4. Имя файла строится из стабильного идентификатора заказа. Существующий файл не перезаписывается. Ошибка одного заказа не останавливает остальные; итог показывает число созданных, пропущенных и ошибочных файлов. Пустой выбор не создаёт файлов. Эти правила выбраны для упражнения; для рабочей задачи их надо согласовать с владельцем процесса.

Что здесь добавляет bsl-flow

Ручной SDD уже показал пользу спецификации: правила повтора попали в код после проверки, а не по догадке агента. Здесь больше вариантов поведения и этапов, за актуальностью которых пришлось бы следить самому: выбор заказов, имена файлов, повтор, частичная ошибка и проверка результата.

BSL Flow даёт 1С-проекту навыки для исследования, спецификации, ревью, реализации и проверки. Начиная с 0.9, он поставляется двумя пакетами:

Пакет	Для чего нужен
Core	Работа с отдельными навыками, OpenSpec, статические проверки и независимое ревью одним рецензентом. Порядок шагов выбираете ты и текущий агент — это режим assisted
Managed	Дополнение к Core: контроллер ведёт задачу через этапы, сохраняет состояние, проверяет результаты и поддерживает консилиум рецензентов

Для разовой спецификации или исправления часто достаточно Core. Для длинной задачи с сохранением состояния и проверками на каждом этапе выбирай Managed. В этом уроке используем Managed через навык 1c-task.

Core рассчитан на Windows, Linux и macOS; Managed работает только на Windows. Установка и подготовка проекта оставляют его в Core. Управляемая задача начинается лишь по твоему явному запросу. Ни один пакет сам по себе не подключает базу и не разрешает загрузку изменений.

1. Установи Core и Managed на Windows

Порядок ниже сверён с документацией 0.9.0-dev.1 — предварительной версии BSL Flow. Перед установкой прочитай актуальную инструкцию. Версии Core и Managed должны совпадать точно, включая суффикс предварительной версии.

Для работы по этому уроку нужны PowerShell 7, Git, Node.js, OpenSpec и Codex CLI. Для Managed используй машинную установку PowerShell 7 в C:\Program Files\PowerShell\7\pwsh.exe. Проверь команды в новом терминале PowerShell 7:

pwsh --version
git --version
node --version
openspec --version
codex --version

Если OpenSpec отсутствует, установи версию из INSTALL.md. Для указанной редакции проверенная версия — @fission-ai/openspec@1.11.0. Сам установщик Core не требует API-ключа, CLI модельного провайдера или .NET SDK. Codex CLI нужен для работы выбранного в уроке исполнителя, а настройка ревью проверяется отдельно.

Склонируй репозиторий в отдельную папку вне проекта УНФ. Если клон уже есть, используй его. Команды для нового клона:

git clone https://github.com/fokusov/bsl-flow.git C:\AI-Course-Work\bsl-flow
Set-Location C:\AI-Course-Work\bsl-flow
Get-Content .\INSTALL.md -TotalCount 100
pwsh -NoProfile -File scripts/Install-BSLFlowCore.ps1 -Host codex -WhatIf

Просмотри план: установщик обновляет навыки, схему OpenSpec и управляемый блок инструкций агента, сохраняя резервные копии. Если выбран правильный хост и каталоги, установи Core:

pwsh -NoProfile -File scripts/Install-BSLFlowCore.ps1 -Host codex

Затем из той же версии поставки просмотри план Managed и выполни установку:

pwsh -NoProfile -File scripts/Install-BSLFlowManaged.ps1 -WhatIf
pwsh -NoProfile -File scripts/Install-BSLFlowManaged.ps1

Прежний Install-BSLFlow.ps1 сохранён как установка полного комплекта. Это альтернативный путь: выполнять его дополнительно после двух установщиков не нужно.

Если BSL Flow уже установлен

Для версии 0.9 проверь записи установки и наличие навыков:

Get-Content "$env:USERPROFILE\.bsl-flow\installed-core.json"
Get-Content "$env:USERPROFILE\.bsl-flow\installed-managed.json"
openspec schema validate bsl-flow
Test-Path "$env:USERPROFILE\.agents\skills\1c-init-project\SKILL.md"
Test-Path "$env:USERPROFILE\.agents\skills\1c-task\SKILL.md"

Версии в двух записях должны совпасть, схема — пройти проверку, обе команды Test-Path — вернуть True. После установки перезапусти Codex. Если нужная версия уже установлена, повторять установку не требуется.

При переходе с 0.8 установи Core, затем Managed той же версии по руководству миграции. Core сохраняет старые файлы Managed, поэтому наличие 1c-task после обновления ещё не подтверждает совместимость контроллера.

Проверка файлов подтверждает установку, но не готовность исполнителя, рецензента или базы. Настрой провайдеров по INSTALL.md; секреты храни вне учебного Git-проекта и не вставляй в чат. YAxUnit и Vanessa не нужны для самой установки, но понадобятся, если выбранные проверки используют их.

2. Подготовь учебный проект

Вернись в Codex, открой проект с разрешёнными исходниками учебной УНФ и расширения. Создай отдельную задачу «Подготовить bsl-flow». Попроси проверить точный корень Git-проекта, существующие AGENTS.md, bsl-flow.yaml, .bsl-flow/project.yaml и openspec/config.yaml. Если проект ещё не инициализирован и конфликтов нет, агент применяет установленный 1c-init-project к этому корню, затем показывает созданные файлы и результат проверки схемы. Для нового пустого каталога сначала нужно явно подтвердить, что он и есть корень 1С-проекта; обычную папку с курсом или папку с базами инициализировать нельзя.

После подготовки в проекте должны быть схема bsl-flow, конфигурация и правила проекта. Проверь git status --short: контроллер Managed начинает работу из чистого Git-проекта. Если изменения прошлых уроков ещё не приняты, сначала заверши их проверку и сделай локальный коммит; публиковать его для урока не нужно. Это пока не доказывает, что контроллер сможет выполнить ревью или тесты. Если установка навыка, bootstrap или обязательный провайдер не готовы, остановись на этом шаге и сверяй сообщение ошибки с INSTALL.md и контрактом 1c-task.

3. Найди границы изменения

Начни новую задачу Codex «Пакетная XML-выгрузка» в том же проекте. Она не наследует переписку об установке, зато видит подготовленные файлы проекта. Сначала попроси агента исследовать существующую выгрузку:

Исследуй наше учебное расширение из урока 4. Найди команду выгрузки
одного заказа, её входы и побочные эффекты, форму списка заказов
и подходящую точку для команды пакетной выгрузки. Ничего не меняй.
Покажи реальные объекты и файлы, а также вопросы, без ответов
на которые нельзя формулировать задачу для bsl-flow.

Сверь ссылки на объекты с исходниками. Вопросы об идентичности файла, повторе и частичной ошибке должны появиться до кода. Если агент их пропустил, укажи на эти три ситуации явно.

4. Передай задачу в bsl-flow

Теперь у агента есть факты и правила. Отправь ему запрос как на управляемую задачу 1c-task, без самостоятельного перескакивания между этапами:

Создай задачу BSL Flow Managed через 1c-task для учебного расширения.
Цель: пакетная локальная XML-выгрузка выбранных заказов через новую
команду, используя формат выгрузки одного заказа из урока 4.
Один заказ — один файл по стабильному идентификатору. Существующий
файл не перезаписывать; при ошибке одного заказа продолжать остальные.
Пустой выбор не создаёт файлов. Итог: создано / пропущено / ошибки
с указанием конкретных заказов. Сеть и типовую конфигурацию не менять.
Сначала подготовь спецификацию с наблюдаемыми критериями и проверь её
по маршруту проекта. Покажи мне вопрос, если правило осталось неясным.
Только после готовой спецификации запускай предусмотренные этапы
реализации и проверки. Не загружай расширение в базу.

Продолжай эту же задачу Codex: исследование и запуск Managed служат одному результату. После регистрации контроллер вернёт идентификатор задачи bsl-flow, а Run проведёт её через нужные этапы. Если он остановится и попросит ответ, уточни правило в той же задаче; не регистрируй вторую задачу bsl-flow ради повтора. На шаге спецификации ищи не длинный документ, а ответы на конкретные вопросы: какой заказ попадёт в выбор, что считается повтором, что происходит с уже созданными файлами после ошибки, где виден итог.

5. Сверь результат с четырьмя сценариями

Подготовь в учебной базе три вымышленных заказа. Для первого заранее создай файл с ожидаемым именем: он должен быть пропущен. Для второго попроси агента предусмотреть контролируемую ошибку файловой записи в тесте без изменения рабочих правил. Третий должен выгрузиться после этой ошибки: так проверяется продолжение обработки. Ожидаемый итог согласуй со спецификацией: один созданный файл, один пропуск, одна ошибка. Отдельно проверь пустой выбор и повтор. Если воспроизвести ошибку записи в твоём контуре нельзя, не объявляй этот сценарий пройденным.

До запуска в 1С прочитай итог контроллера: какие исходники менялись, что прошло статическую проверку, какие тесты действительно запускались и что осталось без runtime-доказательства. Сборка .cfe, загрузка в учебную базу и проверка команды — отдельные шаги. Установленный bsl-flow может подтвердить только поддерживаемый им нативный контур; успешный source-only прогон не означает, что эта команда уже работает в твоей УНФ.

SDD здесь полезен тем, что неприятные варианты поведения получают ответ до кода. Самый важный результат урока — совпадение реализованной команды и наблюдаемых сценариев с согласованной спецификацией. Если нужный тестовый контур пока недоступен, не выдавай исходники за проверенную пакетную выгрузку.