ИИ‑агенты > Pastukhov Agent > Документация > Сборка и развёртывание

Сборка и развёртывание

Что такое сборки?

«Сборка» в Pastukhov Agent — это автоматическая проверка, которая контролирует действия ИИ. Несмотря на название, сборке не нужно ничего «собирать» или создавать готовые файлы — достаточно выполнить команду и сообщить об ошибках и предупреждениях в понятном виде, который распознаёт парсер сборок.

Думайте о сборках как о контрольных точках качества. Каждая — отдельная автоматическая проверка, которая запускается, когда меняются связанные с ней файлы. Компилятор, находящий синтаксические ошибки, — это сборка. Линтер, отмечающий неиспользуемые переменные (линтер — «проверка стиля кода»), — это сборка. Тесты, падающие на утверждении, — это сборка. Сканер безопасности, находящий уязвимости, — тоже сборка. Все они устроены одинаково: команда, создающая структурированный вывод ошибок.

Сборки настраиваются в файле .pastukhov/build.yml в корне проекта: для каждой задаются команда, какие файлы отслеживать и правила разбора в .pastukhov/build.parser. Когда агент меняет проект, Pastukhov Agent замечает изменения и сам запускает подходящие сборки — ничего нажимать не нужно.

Настоящая сила — в Автоисправлении. Когда оно включено, ошибки и предупреждения сборок автоматически отправляются агенту как сообщения чата. Модель видит точный вывод, понимает, что пошло не так, и исправляет — правки снова запускают сборки, и так создаётся обратная связь. Чем больше сборок настроено, тем больше автоматических проверок проходит модель и тем лучше результат.

Конфигурация сборок

Сборки определяются в файле .pastukhov/build.yml: каждая — это именованная задача с командой, шаблонами файлов для отслеживания и дополнительными настройками. Вручную файл создавать не обязательно — используйте кнопку Исправить build.yml с помощью ИИ (значок sparkle) в заголовке панели сборок, чтобы поручить настройку агенту.

build:
  task-name:
    path: "src/"              # Рабочая директория для команды
    command: "npm run check"  # Команда оболочки для выполнения
    delay: 3                 # Секунды ожидания перед запуском (по умолчанию: 3)
    timeout: 60              # Максимальное время выполнения в секундах (по умолчанию: 60)
    watch: "*.ts *.js"      # Шаблоны файлов или имена сборок (разделённые пробелом или запятой), или `chat` для отслеживания текущего завершения чата
    commandOutput: ""         # Путь к дополнительному файлу вывода (необязательно)
    ignore: []                # Regex-шаблоны для фильтрации из ошибок/предупреждений
    replacements:             # Поиск/замена в путях вывода
      - find: "/tmp/build"
        replace: "/project"
    stopStrings: []           # Строки, которые немедленно прерывают сборку
    startSound: ""            # Звук при запуске сборки (встроенный или пользовательский)
    endSound: ""              # Резервный звук при завершении сборки (используется, когда не задан специфичный звук результата)
    successSound: ""          # Звук при успешной сборке (переопределяет endSound)
    warningSound: ""          # Звук при завершении с предупреждениями (переопределяет endSound)
    errorSound: ""            # Звук при неудачной сборке (переопределяет endSound)
    soundVolume: 1.0          # Громкость 0-1 для звуков сборки

Что означает каждая настройка:

  • path — рабочая папка, где выполняется команда. По умолчанию — корень проекта
  • command — команда для выполнения; подойдёт любая, доступная в вашем окружении
  • delay — пауза (в секундах) после изменения файла перед запуском: если меняется сразу несколько файлов, сборка не запускается поминутно, а ждёт, пока изменения улягутся. По умолчанию — 3 секунды
  • timeout — максимальное время выполнения в секундах; если команда не уложилась, она прерывается. По умолчанию — 60 секунд
  • watch — какие файлы отслеживать: шаблоны имён (например, *.ts *.js) или имена других сборок (например, server-build,client-copy). При отслеживании другой сборки эта сборка запускается только после её успешного завершения
  • commandOutput — путь к дополнительному файлу вывода для разбора: некоторые инструменты пишут результат в файл, а не в консоль (например, JetBrains inspectcode создаёт XML) — укажите его, и парсер извлечёт ошибки оттуда
  • ignore — шаблоны поиска, которые отсеиваются из ошибок и предупреждений: удобно гасить заведомо ложные срабатывания и шум конкретных инструментов
  • replacements — пары «найти/заменить» для путей в выводе: нужно, когда сборка выполняется во временных папках (контейнеры, изолированные каталоги), чтобы места ошибок указывали на ваши реальные файлы
  • stopStrings — строки, при появлении которых сборка немедленно прерывается (например, "The operation was canceled")
  • startSound — звук при запуске сборки (встроенное имя вроде "complete" или ваш файл из .pastukhov/sounds/)
  • endSound — резервный звук при завершении сборки, если не заданы звуки результата
  • successSound — звук при успешной сборке (главнее endSound)
  • warningSound — звук при завершении с предупреждениями (главнее endSound)
  • errorSound — звук при неудачной сборке (главнее endSound)
  • soundVolume — громкость звуков сборки (0-1, по умолчанию 1.0)

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

build:
  compile:
    command: "dotnet build"
    watch: "*.cs"

  test:
    command: "dotnet test --no-build"
    watch: compile    # Запускается только после успешной компиляции

Система следит за файлами проекта и запускает сборки сама: файл из шаблона watch изменился — пошёл отсчёт delay; если за это время меняются ещё файлы, таймер сбрасывается. После отсчёта выполняется команда. Если файлы меняются во время самой сборки, запущенная сборка отменяется и стартует заново с учётом изменений.

Результаты сборок хранятся в .pastukhov/build/ — три файла на задачу: {task-name}.output.txt (полный вывод команды), {task-name}.errors.txt (распознанные ошибки) и {task-name}.warnings.txt (распознанные предупреждения).

Редактировать build.yml вручную не обязательно. Файл .pastukhov/README.md описывает полный формат — просто попросите агента добавить или изменить сборки, и он настроит всё правильно.

Файлы парсеров

Pastukhov Agent использует три файла парсеров, чтобы вытаскивать ошибки и предупреждения из текстового вывода. Все три имеют одинаковый формат и описывают сами себя встроенными комментариями — править их вручную обычно не нужно. Если вы добавляете собственную проверку с незнакомым форматом вывода или ваше приложение выдаёт ошибки, которые парсер не распознаёт, попросите агента обновить парсер.

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

Формат парсера

Каждый файл парсера состоит из блоков [ERROR] и [WARNING]. Внутри блока — шаблоны поиска по тексту (регулярные выражения), которые парсер по очереди пытается сопоставить с выводом команды:

  • Строки комментариев, начинающиеся с #, игнорируются — ими файлы парсеров поясняют, что за что отвечает
  • Однострочные шаблоны — выражение, которое должно целиком совпасть с одной строкой вывода. Затем парсер пробует следующий шаблон на следующей строке
  • Многострочные шаблоны — заключаются в {{...}} и захватывают сколько угодно идущих подряд строк: так снимается контекст после заголовка ошибки, стек-трейсы и прочий многострочный вывод

Вот пример, как шаблоны ловят ошибку TypeScript вместе с контекстом:

# Ошибки TypeScript
[ERROR]
.*\.ts.*              # Сопоставляет строку, содержащую путь к .ts файлу
Error.*               # Сопоставляет строку, начинающуюся с "Error"
{{^\s+}}              # Сопоставляет ноль или более строк, начинающихся с пробелов (контекст)
[/ERROR]

Парсер идёт по строкам вывода и в каждой позиции пробует шаблоны блоков [ERROR] по порядку. Когда все шаблоны блока совпали подряд, эти строки извлекаются как одна ошибка, и парсер двигается дальше. Блоки [WARNING] работают точно так же. Шаблоны, стоящие в файле раньше, имеют приоритет: как только найдено совпадение, другие блоки не пробуются.

Парсер автоматически перечитывает свои правила при изменении файла — правки действуют сразу, без перезапуска.

build.parser

Файл .pastukhov/build.parser извлекает ошибки и предупреждения из вывода команд сборки. Он уже содержит шаблоны для распространённых инструментов — C# (MsBuild, CSC), TypeScript, Svelte, Vite, Python (ruff) и ReSharper — и в него можно добавлять шаблоны для любых инструментов вашего проекта.

# Ошибки C# - формат MsBuild с путём к файлу и (строка,кол)->(строка,кол) CSxxxx:
[ERROR]
\[MsBuild\].*\(\d+,\d+\)-\>\(\d+,\d+\)\s+CS\d+\:.*
[/ERROR]

# Ошибки Python ruff (коды F/E) - с расположением файла и контекстом
[ERROR]
[A-Z]\d+\s+(\[\*\]\s+)?.*
\s*--\>.*
{{^\s+.*|\d+\s+\|.*}}
[/ERROR]

# Предупреждения C#
[WARNING]
\(\d+,\d+\): warning
[/WARNING]

deploy.parser

Файл .pastukhov/deploy.parser извлекает ошибки и предупреждения из работы вашего запущенного приложения — то, что происходит уже после сборки, на «боевом» этапе. Он распознаёт распространённые ошибки времени выполнения: необработанные исключения, стек-трейсы, сбои подключения к базе данных, коды ошибок HTTP и падения приложений на разных платформах:

# Необработанные исключения (полный стек-трейс)
[ERROR]
Unhandled exception\.
{{\S.*}}
[/ERROR]

# Уровень лога ошибок ASP.NET (Serilog/ILogger)
[ERROR]
^err\:.*
{{^\s+\S.*}}
[/ERROR]

# Внутренние ошибки сервера HTTP 500
[ERROR]
.*status code 500
[/ERROR]

# Ошибки отказа в подключении
[ERROR]
Connection refused
[/ERROR]

# Исключения SQL базы данных
[ERROR]
SqlException\:.*
{{^\s+\S.*}}
[/ERROR]

# Уровень лога предупреждений
[WARNING]
^warn\:.*
{{^\s+\S.*}}
[/WARNING]

output.parser

Файл .pastukhov/output.parser — универсальный парсер для вывода обычных скриптов: ошибки оболочки, стек-трейсы Python, исключения Node.js, сбои npm и прочие частые форматы ошибок. Он применяется, когда вывод не относится к сборкам или развёртываниям:

# Команда оболочки не найдена
[ERROR]
.*command not found
[/ERROR]

# Стек-трейсы Python
[ERROR]
^Traceback \(most recent call last\)\:
{{.*}}
[/ERROR]

# npm ERR!
[ERROR]
^npm ERR\!.*
[/ERROR]

# Предупреждения Python
[WARNING]
.*Warning\:.*
{{^\s+.*}}
[/WARNING]

Проверка конфигурации

Pastukhov Agent автоматически проверяет все файлы конфигурации .pastukhov/ при их сохранении. Проверка запускается как сборка, и результаты видны на панели сборок: ошибки красным, предупреждения жёлтым.

При каждом сохранении выполняется девять проверок — по одной на каждый файл конфигурации:

  • build.yml — синтаксис YAML, требует command или prompt, предупреждает о неизвестных свойствах
  • deploy.yml — синтаксис YAML, предупреждает о неизвестных свойствах
  • project.yml — синтаксис YAML, требует name, предупреждает о неизвестных свойствах
  • hooks.yml — синтаксис YAML, предупреждает о неизвестных типах событий и свойствах
  • mcp.yml — синтаксис YAML, предупреждает о неизвестных ключах верхнего уровня и свойствах серверов
  • skills.yml — синтаксис YAML, предупреждает о неизвестных свойствах и об отсутствии enabled
  • models.yml — синтаксис YAML, предупреждает о неизвестных свойствах (ожидает variables)
  • providers.yml — синтаксис YAML, предупреждает о неизвестных свойствах провайдеров и окружений
  • *.parser — парность блоков ([ERROR]/[/ERROR]), корректность регулярных выражений, шаблоны вне блоков

Сообщения об ошибках и предупреждениях ссылаются на нужный раздел .pastukhov/README.md, чтобы найти правильный формат:

Error: build.yml - 'lint': Missing required field 'command' or 'prompt' (see .pastukhov/README.md#buildyml)
Warning: deploy.yml - 'staging': Unknown property 'restart' (see .pastukhov/README.md#deployyml)
Warning: skills.yml - 'my-skill': Missing 'enabled' property (see .pastukhov/README.md#skillsyml)

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

Конфигурация развёртывания

Развёртывание — это запуск вашего приложения: на своём компьютере для проверки или на удалённом сервере для реальных пользователей. Настраивается в файле .pastukhov/deploy.yml. Pastukhov Agent поддерживает два способа: debug — для локальной разработки и docker — для развёртывания на удалённых серверах.

Развёртывание debug (локальное)

Способ debug запускает приложение прямо на вашей машине — самый частый вариант во время разработки:

deploy:
  my-app:
    method: "debug"            # Обязательно: должно быть "debug"
    os: "linux"                # "linux" или "windows" (по умолчанию: "linux")
    path: "./server"           # Путь к файлам приложения
    command: "dotnet run"      # Команда для запуска приложения
    delay: 3                   # Задержка перед запуском (по умолчанию: 3)
    timeout: 60                # Максимальное время выполнения (по умолчанию: 60)
    watch: "build-app"         # Имена сборок (разделённые пробелом или запятой), или `chat`
    shallowCopy: true          # Копировать только изменённые файлы (по умолчанию: true)
    url: "https://app.example.com/"  # Необязательный URL для кнопки ссылки
    startSound: ""            # Звук при запуске развёртывания (встроенный или пользовательский)
    endSound: ""              # Звук при завершении развёртывания (встроенный или пользовательский)
    soundVolume: 1.0          # Громкость 0-1 для звуков развёртывания
    environment:                # Переменные окружения для процесса
      - APP_KEY=your-key
      - APP_DB=/path/to/database

Ключевые настройки:

  • watch — список имён сборок (через пробел или запятую) или chat для запуска после завершения чата. Развёртывание запускается или перезапускается автоматически, когда все перечисленные сборки завершились успешно
  • shallowCopy — при включении копирует только изменённые файлы при каждом перезапуске: заметно быстрее полного копирования
  • url — необязательный адрес вашего приложения: в интерфейсе появляется кликабельная кнопка, открывающая приложение в новой вкладке
  • environment — переменные окружения, передаваемые запущенному процессу
  • startSound — звук при запуске развёртывания (встроенное имя вроде "complete" или ваш файл из .pastukhov/sounds/)
  • endSound — звук при завершении развёртывания
  • soundVolume — громкость звуков развёртывания (0-1, по умолчанию 1.0)

Развёртывание Docker (удалённое)

Способ docker отправляет ваше приложение на удалённый сервер как контейнер. Подходит для окружений staging (предварительная проверка) и production (рабочий вариант для пользователей):

deploy:
  my-docker:
    method: "docker"             # Обязательно: должно быть "docker"
    os: "linux"
    host: "server.com"          # Удалённый хост
    username: "deploy"           # Имя пользователя SSH
    sshKeyPath: "~/.ssh/key"    # Путь к ключу SSH
    sshPort: 22                  # Порт SSH (по умолчанию: 22)
    imageName: "app:latest"      # Имя образа Docker
    containerName: "myapp"       # Имя контейнера
    dockerfilePath: "./Dockerfile"
    buildContext: "."             # Контекст сборки (по умолчанию: ".")
    buildArgs:                    # Аргументы сборки Docker
      - NODE_ENV=production
    environmentVariables:         # Переменные окружения контейнера
      - PORT=3000
      - DATABASE_URL=postgresql://...
    portMappings:                 # Соответствия портов Хост:Контейнер
      "8080": "3000"
    volumeMappings:               # Соответствия томов Хост:Контейнер
      "/var/log/app": "/app/logs"
    networks:                     # Сети Docker
      - myapp-network
    pullLatestImage: true         # Загружать базовый образ перед сборкой (по умолчанию: true)
    removeExistingContainer: true # Удалять старый контейнер перед развёртыванием (по умолчанию: true)
    healthCheckPath: "/"          # Конечная точка проверки здоровья (по умолчанию: "/")
    healthCheckInterval: 30       # Интервал проверки здоровья в секундах (по умолчанию: 30)
    healthCheckRetries: 3         # Повторы проверки здоровья (по умолчанию: 3)
    localSourcePath: "."          # Локальный путь для развёртывания
    remoteWorkDir: "/tmp/deploy"  # Удалённая рабочая директория
    excludePaths:                 # Пути для исключения из rsync
      - ".git"
      - "node_modules"
      - ".pastukhov"

Вывод развёртывания сохраняется в .pastukhov/deploy/: {deploy-name}.log — для вывода времени выполнения, плюс отладочные логи на стороне клиента по адресу {domain}.log (автоматически обрезаются до 100 МБ).

Создавать и править deploy.yml вручную не обязательно. Файл .pastukhov/README.md полностью описывает оба способа — просто попросите агента настроить развёртывание, и он разберётся с деталями.

Управление сборками и развёртываниями

Панель состояния внизу экрана отвечает за контроль сборок и развёртываний в реальном времени. Она обновляется сама через живые соединения — перезагружать страницу не нужно.

Управление сборками

Вкладка Сборки показывает все настроенные сборки списком-аккордеоном: у каждой — имя, значок состояния и число ошибок/предупреждений.

  • Пересобрать — наведите курсор на завершённую сборку: появится кнопка пересборки для ручного запуска (отключена во время выполнения)
  • Просмотр вывода — нажмите на имя сборки: откроется полный вывод с тремя вкладками — Журнал (исходный вывод, последние 2000 строк), Ошибки (распознанные ошибки, красные), Предупреждения (жёлтые)
  • Переход к ошибкам — нажмите на счётчик ошибок или предупреждений, и диалог вывода сразу откроется на нужной вкладке
  • Копировать — копирует содержимое текущей вкладки в буфер обмена
  • Отправить в чат — отправляет ошибки или предупреждения агенту в виде сообщения в блоке кода build.log. Для предупреждений добавляется просьба «исправь предупреждения, не игнорируй их». Содержимое ограничено первыми 20 КБ

В заголовке панели сборок есть кнопка Исправить build.yml с помощью ИИ (значок sparkle) рядом с кнопкой редактирования: она добавляет во ввод чата запрос настроить автоматические сборки, используя .pastukhov/README.md как справочник.

В диалогах вывода сборок и в разделах ошибок/предупреждений панели сборок выделение текста открывает плавающую кнопку Исправить парсер: нажатие отправляет выделенный текст агенту с запросом обновить build.parser — вводить запрос вручную не нужно.

Сборки, прошедшие без проблем, сворачиваются сами. Сборки с ошибками или предупреждениями остаются раскрытыми — чтобы вы сразу их заметили.

Управление развёртываниями

Вкладка Развёртывания показывает каждое настроенное развёртывание с именем, состоянием и кнопками действий:

  • Запустить — запускает приложение; вывод времени выполнения транслируется в реальном времени
  • Остановить — корректно останавливает работающее приложение
  • Перезапустить — останавливает и сразу запускает заново (также срабатывает автоматически, когда завершились отслеживаемые сборки)
  • Открыть URL — если адрес задан в deploy.yml, кнопка открывает ваше приложение в новой вкладке браузера
  • Просмотр вывода — диалог с вкладками Журнал, Ошибки и Предупреждения, как у сборок. Вывод развёртывания разбирается в реальном времени парсером deploy.parser: ошибки выполнения — необработанные исключения, сбои подключения к базе, ошибки HTTP 500 — обнаруживаются и подкрашиваются. Выделение текста открывает кнопку Исправить парсер для обновления deploy.parser

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

Творческие сборки

«Сборка» — это просто название. Под ним может скрываться любая проверка, которая выдаёт структурированные ошибки. Вот несколько примеров за пределами традиционной компиляции:

Линтеры и форматтеры

Линтер — автономная проверка стиля и типовых ошибок в коде (неиспользуемые переменные, расхождения в оформлении):

build:
  eslint:
    path: "client/"
    command: "npx eslint src/ --format stylish"
    watch: "*.ts *.svelte"

  ruff:
    path: "src/"
    command: "ruff check ."
    watch: "*.py"

Проверка типов

Проверяет, что данные в коде используются правильно (не перепутаны типы, всё согласовано):

build:
  typecheck:
    path: "client/"
    command: "npx tsc --noEmit"
    watch: "*.ts"

Запуск тестов

Автоматически прогоняет написанные тесты и сообщает о падениях:

build:
  tests:
    path: "server/"
    command: "dotnet test --no-build"
    watch: compile

Сканеры безопасности

Проверяют зависимости проекта на известные уязвимости:

build:
  audit:
    path: "./"
    command: "npm audit"
    watch: "package.json"

Собственные проверки проекта

Можно написать свои скрипты проверки под правила вашего проекта: соглашения об именах, требуемые структуры файлов, соответствие API-контрактам, любые инварианты, которые проект должен соблюдать. Пока скрипт выводит ошибки в формате, понятном парсеру, — он работает как сборка. Если формат вывода не распознаётся, попросите агента добавить нужные шаблоны в build.parser.

Каждая добавленная сборка — дополнительная автоматическая обратная связь для агента через Автоисправление. Проект со сборками компилятора, линтера, проверки типов и тестов даёт модели четыре независимые проверки качества — каждая ловит свои категории проблем, которые другие могут пропустить.

Автоматическая пересборка и Автоисправление

Когда агент изменяет файлы проекта, Pastukhov Agent замечает изменения и сам запускает подходящие сборки. Никаких команд и кнопок — весь цикл проверки работает сам.

Автоматический рабочий процесс выглядит так:

  1. Агент изменяет файлы — модель вносит изменения в код проекта
  2. Запуск сборок — Pastukhov Agent замечает изменения и запускает соответствующие сборки после настроенной задержки
  3. Разбор вывода — парсер сборок извлекает ошибки и предупреждения из вывода каждой сборки
  4. Автоисправление проверяет результаты — если сборки дали ошибки, Автоисправление оборачивает их в блок кода markdown и отправляет агенту как сообщение чата. Для предупреждений добавляется «исправь предупреждения, не игнорируй их»
  5. Агент исправляет проблемы — модель видит вывод ошибок, понимает, что случилось, и вносит исправления
  6. Перезапуск сборок — исправления снова меняют файлы, и цикл запускается заново
  7. Успех — когда все сборки проходят без ошибок, цикл завершается, и приложение развёртывается повторно

Этот цикл работает полностью без вашего участия. Автоисправление включается, только когда нет активной сессии агента, проверяет повторяющиеся ошибки в последних 10 сообщениях (чтобы не зациклиться) и уважает лимит параллельности. Наблюдать за процессом можно на панели сборок и в истории чата — или просто заглянуть позже и увидеть результат.

Узнайте больше о конфигурации и ограничениях Автоисправления

← Файлы

Git →