ai-worker, часть 1: от задачи до проверенного слияния

ai-worker координирует планирование, реализацию и ревью кода в репозиториях Amitable. Задачи описывают нужный результат, комментарии фиксируют решения, а пул-реквесты содержат изменения. Контроллер на Python управляет процессом, а сессии моделей исследуют исходный код, реализуют изменения и проверяют их.

Статья описывает реализацию на 10 ноября 2026 года, коммит воркера 824c821. Среди последних изменений — три роли ботов, последовательное выполнение этапов в новых планах, выбор провайдеров по заданному порядку и веб-панель управления. Во второй части разбирается архитектура: изоляция, планировщик, подтверждение результатов и восстановление после сбоев.

Выбор точки входа и полномочий

Сейчас используются роли planner-bot, worker-bot и reviewer-bot, каждая с отдельной учётной записью Forgejo без прав администратора. Они разделяют планирование и координацию слияний, реализацию и независимое ревью. Имена служб, префиксы веток, маркеры владения и команды с ai-worker сохраняют совместимость.

Назначьте открытую задачу на planner-bot, если работе нужны план и разбиение на этапы. Опишите наблюдаемое поведение и ограничения. Например, для экспорта записей укажите, кто имеет право его запускать, какие записи включать и что должен содержать результат. Неясности станут вопросами на этапе планирования, до начала реализации.

Задачу, созданную пользователем с правом записи в репозиторий, можно назначить сразу на worker-bot. Это разрешает реализацию по задаче и требованиям человека без отдельного планирования и согласования плана. Воркер явно формулирует критерии приёмки; неоднозначные требования по-прежнему останавливают работу. Ссылка на ветку в Forgejo задаёт целевой контекст, иначе используется ветка по умолчанию.

Reviewer-bot может проверять отдельные PR без связанной задачи или плана. Если критерии не заданы, он ищет ошибки корректности, безопасности и регрессии по описанию PR, обсуждению и исходному коду, не придумывая новые требования. Одобрение ревью само по себе не даёт разрешения на слияние.

Опрос сервера, проверку полномочий, публикацию Git, чтение CI, обновление статуса и допустимые слияния выполняет обычный код. Для отображения задачи, которая простаивает или ждёт согласования, сессия модели не нужна.

Согласование конкретной версии плана

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

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

Человек с правами Write, Admin или Owner может согласовать план новым, неотредактированным комментарием:

@planner-bot approve-plan p-<revision>

Вместо шаблона подставьте версию, указанную под планом. Другой вариант — поставить 👍 на неотредактированное уведомление планировщика об ожидании согласования именно этой версии. Реакция на основной комментарий с планом не учитывается. Боты не могут дать согласование от имени человека; старые команды @ai-worker продолжают работать.

Согласование относится к конкретной версии и её требованиям. Открытые вопросы мешают выполнению, а изменение требований отменяет прежнее согласование. Изображения, приложенные пользователем с правом записи, могут входить в контекст планирования: добавление, изменение или удаление допустимого вложения меняет отпечаток требований и может вызвать повторное планирование.

Новые этапы выполняются по порядку

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

Каждый этап создаёт PR из управляемой ветки, например ai-worker/issue-N-m1, в интеграционную ветку задачи. Следующий этап начинается после подтверждения слияния текущего. Даже логически независимые этапы одного нового плана выполняются последовательно.

Рассмотрим условный план экспорта записей: m1 определяет общий контракт, m2 реализует экспорт с проверкой прав, а m3 добавляет интерфейс. Это пример, а не описание ранее выполненной задачи или результат измерения производительности.

Реализации разных родительских задач могут одновременно занимать доступные слоты. Планирование и ревью также могут идти параллельно с другой работой. Опубликованный PR, ожидающий ревью или CI, освобождает ресурсы реализации. Для исправлений уже опубликованного и проверенного PR предусмотрено ограниченное исключение из запрета на одновременную работу внутри одной родительской задачи. Исправления по ревью и CI имеют приоритет перед новой реализацией.

Контроллер поддерживает синхронизацию интеграционной ветки с веткой по умолчанию. Гостевая среда может разрешить конфликты относительно зафиксированного коммита основной ветки; результат обязан включать этот коммит до публикации. Исправления используют обычные коммиты и сохраняют накопленную работу, не заменяя её force push.

Реализация должна вернуть проверяемые подтверждения

Сессия реализации получает согласованную область текущего этапа, снимок исходного кода, прежние замечания и сохранённую работу. Она следует правилам репозитория и создаёт коммиты через его хуки. В Amitable общие проверки сборки, схемы и затронутых unit-тестов обычно выполняет pre-commit, а полную проверку покрытия — CI пул-реквеста. Нужные целевые e2e и явно согласованные измерения запускаются отдельно. Обходить хуки нельзя.

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

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

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

Провалы обязательных проверок и подходящие пробелы в отчёте запускают ограниченное восстановление: обычно до трёх попыток для неизменного снимка. Отсрочки из-за квоты не расходуют этот лимит. Вопросы и изменение области работ по-прежнему требуют участия человека или нового планирования.

Ревью и исправления — отдельные решения

Reviewer-bot начинает свежую сессию для полного diff зафиксированных коммитов и окружающего кода. Обычное ревью не устанавливает зависимости и не запускает тесты, линтер, проверку типов, сборку или e2e. Оно сообщает о конкретных ошибках корректности, безопасности и регрессиях с точными ссылками на исходный код. Подтверждением выполненных проверок остаются записи сессии реализации.

Замечания создают явное обязательство по исправлению. Worker-bot должен ответить на каждое из них коммитом с исправлением и проверкой регрессии, обоснованным по исходному коду возражением либо незавершённым результатом с объяснением блокировки. Прежние успешные тесты сами по себе замечание не закрывают. Неполные ответы или повторное «уже готово» без изменений получают корректирующую обратную связь в пределах лимита исправлений.

Возражение направляется на новое независимое ревью, даже если head и base не изменились. Worker-bot не может снять собственные замечания. Подходящие незавершённые ревью и блокировки реализации тоже могут перейти в ограниченное восстановление. После исчерпания попыток система сообщает о нерешённых пробелах и точной команде повтора; изменение области работ всё ещё требует решения человека.

Завершённое ревью публикует одобрение или запрос изменений. Черновые и WIP PR обычно пропускаются; для финального ревью ранее созданных параллельных функций есть отдельное исключение. Изменение снимка отменяет прежний допуск по ревью.

Условия доставки зависят от процесса

Для слияния этапа в интеграционную ветку нужны принятые подтверждения реализации, независимое ревью, отсутствие блокирующего запроса изменений и применимые проверки и правила сервера. Согласование плана разрешает такие промежуточные слияния без нового одобрения человека. После интеграции этапов контроллер поддерживает PR из интеграционной ветки в основную, сохраняя WIP, пока остаются незавершённые этапы.

У завершённого нового последовательного плана итоговый PR становится готовым и может слиться автоматически, когда интеграционная ветка синхронизирована, текущий head удовлетворяет настроенному CI, возможность слияния подтверждена и нет запроса изменений. Этот путь не требует отдельного финального одобрения человека, отдельного автоматического финального ревью или прежней задачи общей валидации. Подтверждения каждого этапа уже проверены до его интеграции.

Процесс	Разрешение на план	Условие финального слияния
Новый последовательный план	Человек согласовал версию	Актуальный применимый CI, возможность слияния, отсутствие запроса изменений, правила сервера
Прямая задача в основную ветку	Назначение задачи, созданной пользователем с правом записи	Формальное одобрение человеком текущего head, принятые ревью и проверки, применимый CI
Ранее созданная параллельная функция	Её согласованный граф	Независимое финальное ревью, общая валидация, одобрение человеком текущего head, применимый CI

Запуск настроенного CI привязан к текущему head. Новый head требует новых проверок; провал финального CI может запустить ограниченное исправление в интеграционной ветке и новый запуск CI. Если настроенный workflow отсутствует, доставка ждёт CI. Когда диспетчеризация не настроена, контроллер может принять отсутствие статусов, но не считает ожидающие или проваленные проверки успешными и не обходит правила сервера.

Запросы слияния не используют принуждение и содержат ожидаемый head. Доставка фиксируется только после подтверждения слияния сервером. Безрезультатная попытка слияния уступает место другой готовой работе. Здесь доставка означает попадание изменений в целевую ветку; развёртывание приложения выполняется отдельно.

Наблюдение и управление

Веб-панель дополняет терминальный интерфейс экранами Overview, Tasks, Logs и Settings. Overview показывает общий планировщик, активные слоты, фазу, провайдера и модель, сохранённые квоты, ресурсы хоста и гостей и ошибки. Tasks содержит историю этапов и результаты; Logs — ограниченную свежую выборку журнала; Settings — предварительный просмотр поддерживаемых изменений настроек.

В Settings также виден сохранённый статус доступа каждой роли к репозиторию. Check access проверяет права, а Repair access выдаёт недостающий неадминистративный доступ Write и проверяет его через учётные записи ботов. При добавлении репозиториев через Save эта операция выполняется для новых записей. Частичный сбой не отменяет сохранение настроек и отображается предупреждением. Открытие Settings не проверяет права, а удаление репозитория из настроек не отзывает существующий доступ.

Start now запрашивает немедленную проверку при наличии ресурсов. Pause scheduling не останавливает уже выполняемые задания. Stop selected slot требует подтверждения с указанием текущего задания и повторной проверки на сервере перед остановкой. Resume доступен только для корректно приостановленного, ранее включённого и проверенного планировщика; первичное включение и восстановление остаются операциями администратора вне веб-панели.

Обновление данных для чтения не обращается к провайдерам или Forgejo. Сохранённые квоты могут устаревать: звёздочка на снимке отмечает старое наблюдение, а не новое разрешение на выполнение. Неудачные наблюдения квоты не допускают запуск заданий. Изменения настроек действуют на последующие задания; активные сохраняют свою зафиксированную конфигурацию.

Изменения, остановка и очистка

Новые требования размещайте в родительской задаче и согласуйте свежую версию. Прежние области этапов сохраняют идентификаторы, изменённым нужны новые. Сохранённые коммиты можно явно перенести в заменяющую работу. Закройте устаревшие открытые PR до запуска их замены.

Используйте @planner-bot retry для задач планирования, @worker-bot retry для задач реализации и @reviewer-bot review или @reviewer-bot retry для PR. Закрытие родительской задачи или снятие назначения останавливает дальнейшую работу над функцией, публикацию и слияния, но не отменяет уже подтверждённые слияния.

После подтверждённой финальной доставки очистка удаляет локальных гостей, Git-бандлы, журналы, снимки экрана и старые попытки этой функции. SQLite сохраняет результаты, сведения о слиянии и запись об очистке; Forgejo — опубликованные обсуждения и подтверждения. Пока работа не закончена или остаётся неоднозначность, артефакты восстановления сохраняются.

О механизмах, обеспечивающих эти решения, читайте во второй части: архитектура и границы выполнения.