Проектирование CLI для AI-агентов: JSON, коды выхода и ожидание

CLI для AI-агента — это не просто инструмент командной строки для человека, которым случайно можно вызвать из модели. Это операционный протокол. Агенту нужны детерминированные входные данные, структурированные результаты, осмысленные коды выхода, стабильные категории ошибок и возможность ждать, пока асинхронная инфраструктура не достигнет конечного состояния.

Без такого контракта агент вынужден выводить успешность операции из фраз вроде «развёртывание запущено». Это опасно, поскольку принятый запрос впоследствии может завершиться ошибкой на этапе сборки, проверки работоспособности, запуска контейнера или переключения трафика.

Почему опасно считать развёртывание успешным на основании предположений?

Большинство операций с инфраструктурой выполняются асинхронно. API может принять развёртывание и вернуть ID за миллисекунды, тогда как сама сборка займёт несколько минут. Если агент сообщает об успехе в момент принятия запроса, все последующие действия основываются на ложной предпосылке.

Разница выглядит так:

Событие	Что оно доказывает	Чего оно не доказывает
Запрос принят	Платформа поняла запрос	Код успешно собран
Сборка завершена	Создан образ или артефакт	Приложение запустилось
Проверка работоспособности пройдена	Новый экземпляр отвечает требуемым образом	Бизнес-сценарии работают
Трафик переключён	Релиз стал активным	Он останется работоспособным
Наблюдение за доступностью	Сервис остаётся доступным	Все функции работают корректно

Человек может заметить эту разницу на панели мониторинга. Агенту, работающему через текстовый интерфейс, она должна быть явно закодирована в интерфейсе.

Контракт команд Dockup разделяет постановку в очередь и завершение операции. Команда deploy без --wait возвращается сразу с waited:false, а deploy с --wait блокируется до успешного завершения, ошибки или тайм-аута:

dockup deploy production/api --wait --json

Тайм-аут по умолчанию составляет 900 секунд. Команда завершается с кодом 0 только после успешного конечного состояния. Если результатом становится неуспех, она завершается с ненулевым кодом и кодом ошибки deploy_failed или deploy_timeout.

Что структурированный JSON CLI даёт AI-агенту?

Структурированный JSON заменяет интерпретацию прозы именованными полями. Агент может напрямую найти status, deploymentId, target или code, не полагаясь на знаки препинания, цвет, ширину столбцов или формулировки.

Успешный результат можно обработать как данные:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Ошибка использует ту же транспортную структуру:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

Важное правило проектирования: JSON записывается в stdout, а предупреждения, которые не должны нарушать разбор данных, — в stderr. При использовании follow-режима логи передаются в формате NDJSON — один JSON-объект на строку. Это позволяет вызывающей стороне обрабатывать поток постепенно, не дожидаясь формирования одного огромного массива.

Dockup поддерживает --json во всех основных командах. При наличии 135 команд требовать от агента запоминать флаги было бы ненадёжно. Справочник CLI и устанавливаемый skill содержат согласованные с версией инструкции по командам, которым должен следовать агент.

Важно не то, насколько умно реализовано обнаружение возможностей. Важно, что агент получает актуальные структурированные инструкции по работе и не придумывает флаг на основе старого промпта.

Как реальные коды выхода управляют автоматизацией развёртывания?

Код выхода операционной системы — самый переносимый сигнал успешного выполнения, доступный shell-скриптам, CI-раннерам и coding-агентам. Код 0 означает, что команда достигла определённого для неё результата. Ненулевой код означает, что вызывающая сторона должна перейти к восстановлению, эскалации или завершению работы.

Этот фрагмент shell намеренно прост:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Он не ищет слово «success» в stdout. Он не предполагает, что HTTP-ответ 202 означает готовность production. Он делегирует определение успеха CLI и передаёт ошибку родительскому процессу.

Реальные коды выхода не менее важны для одноразовых команд внутри контейнера. Команда Dockup PRO exec возвращает stdout, stderr и фактический код выхода команды:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Благодаря этому агент может отличить завершившуюся миграцию от команды, которая лишь запустилась. Это фундаментальный принцип защитных механизмов production для AI-агентов.

Как ожидание конечного состояния заменяет ненадёжный polling?

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

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

Dockup предоставляет два полезных шаблона:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

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

Следование за логами работает по тому же принципу:

dockup logs production/api --build -f --json

Поток завершается, когда сборка достигает успешного состояния или состояния ошибки. Финальный объект NDJSON содержит done:true, а при неудачной сборке команда завершается с ненулевым кодом. Вызывающей стороне не нужно реализовывать дополнительный polling.

Для проверки доступности приложения после развёртывания команда Dockup uptime возвращает проверки с интервалом в минуту, среднее время ответа и p95:

dockup uptime production/api --hours 24 --json

Ожидание и мониторинг — разные понятия. --wait отвечает на вопрос, достигло ли это развёртывание конечного результата; uptime показывает, как работающий сервис вёл себя с течением времени.

Какие коды ошибок должен понимать агент?

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

Код ошибки	Значение	Безопасная реакция агента
not_logged_in	Нет действительного токена	Остановиться и запросить аутентификацию
not_linked	Для push нет целевого объекта .dockup	Определить или передать target
no_target	Не удалось идентифицировать сервис	Выполнить services --json
needs_confirm	Для деструктивного действия нет подтверждения	Запросить человека
deploy_trigger_failed	Не удалось запустить развёртывание	Сообщить об ошибке API
deploy_failed	Сборка или развёртывание завершились ошибкой	Прочитать логи сборки
deploy_timeout	Операция всё ещё выполняется после истечения времени ожидания	Сообщить о неопределённости или осознанно увеличить тайм-аут

Сообщение об ошибке по-прежнему содержит полезный контекст, но именно код определяет первую ветку обработки. Благодаря этому автоматизация не зависит от более точных формулировок или локализации.

Подтверждение также является частью протокола. Деструктивная команда не должна молча выполняться только потому, что вызывающая сторона работает в неинтерактивном режиме. Dockup отказывает в таких операциях без --yes и возвращает needs_confirm. Для автономного агента это вопрос, требующий ответа, а не препятствие, которое нужно обойти.

Подробнее модель безопасности рассматривается в разделе лучшие практики безопасности.

Каков минимальный контракт production-ready CLI?

Production-ready CLI для AI-агента должен соответствовать небольшому, но строгому контракту:

1. Каждая операция чтения и записи имеет машиночитаемый вывод.
2. Ошибка приводит к ненулевому коду выхода процесса.
3. Асинхронные изменения позволяют ждать документированного конечного состояния.
4. Команды чтения никогда не возвращают значения секретов.
5. Для деструктивных действий требуется явное подтверждение.
6. Ошибки имеют стабильные коды, подходящие для ветвления.
7. Пакет CLI и инструкции для агента остаются согласованными по версии.
8. Изменения фиксируются в audit trail.

Skill Dockup превращает эти правила в поведение по умолчанию для Claude Code и Codex. Он инструктирует агента использовать JSON, выполнять аутентификацию через DOCKUP_TOKEN, определять точные target, развёртывать с --wait, защищать учётные данные и останавливаться при needs_confirm.

Сравните эту модель с более широкими концепциями в материале agent skills и MCP. Skill предоставляет рабочие знания, а CLI остаётся исполняемым интерфейсом, чей код выхода и вывод определяют достоверное состояние.

Матрица тестирования команды, предназначенной для агента

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

Тест	Ожидаемое поведение
Действительный запрос	JSON-результат и код выхода 0
Недействительный токен	Стабильный код ошибки аутентификации и ненулевой код выхода
Неизвестный target	Стабильный код ошибки target и отсутствие изменений
Долгое развёртывание	Ожидание конечного состояния или тайм-аута
Неудачное развёртывание	Ненулевой код выхода и диагностируемый ID развёртывания
Отсутствует подтверждение деструктивного действия	needs_confirm, удаление не выполнено
Чтение секрета	Метаданные ключа видны, значение скрыто
Предупреждение при выводе JSON	Предупреждение в stderr, корректный JSON в stdout

Эта матрица ценнее, чем отполированный индикатор выполнения. Человеческое форматирование можно добавить поверх интерфейса, но детерминированный машинный контракт невозможно восстановить задним числом.

В документации Dockup CLI показаны конкретные команды, реализующие эту модель, а в материале разработка с использованием AI объясняется более масштабный переход от ручного использования инструментов к управляемым агентами рабочим процессам.

Считайте наблюдаемость частью контракта команды

Изменяющая инфраструктуру команда, предназначенная для агента, должна возвращать идентификаторы, которые делают последующее расследование возможным. Ответ на развёртывание должен содержать target и ID развёртывания; созданная база данных — стабильный slug; snapshot тома — его ID. Без этих ссылок агент может описать событие, но не сможет надёжно проверить его, повторить операцию или отменить её.

Audit trail завершает контракт. Структурированный вывод описывает один вызов, а записи аудита связывают несколько вызовов во времени. Вместе они позволяют операторам ответить, работал ли агент с нужным ресурсом и относилась ли последующая команда восстановления к тому же событию в production.

Интерфейс должен оставаться простым

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

Финальная проверка интерфейса

CLI для AI-агента должен правдиво сообщать об ошибках.

Переведите рабочий процесс в production

Сначала протестируйте контракт из shell: проверьте разбор JSON, успешный код выхода, принудительную ошибку, тайм-аут и блокировку деструктивной операции, прежде чем предоставлять доступ к production.

npm install -g dockup-cli
dockup skill install

Первая команда устанавливает CLI. Вторая устанавливает соответствующий skill Dockup для Claude Code и Codex. Начните бесплатно на app.dockup.ai.

Часто задаваемые вопросы

Что делает CLI подходящим для AI-агентов?

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

Почему JSON лучше вывода CLI, отформатированного для человека?

JSON предоставляет стабильные имена и типы полей. Агенту не нужно выводить смысл из цветов, таблиц, знаков препинания или меняющихся формулировок.

Почему принятый запрос на развёртывание не означает успех?

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

Каков тайм-аут ожидания развёртывания Dockup по умолчанию?

Тайм-аут по умолчанию для dockup deploy --wait составляет 900 секунд. Его можно изменить с помощью документированного параметра --timeout.

Как агент должен реагировать на needs_confirm?

Он должен остановиться и запросить явное подтверждение. Этот код означает, что запрошенное действие является деструктивным и намеренно не было выполнено.