Шаблоны проектирования CLI для AI-агентов: Заблуждения и практические подходы

Уточнение протокола интерфейса командной строки

Самое большое заблуждение из Части 1 заключалось в том, что "CLI" означало предоставление LLM терминала Linux. CLI на самом деле является протоколом интерфейса: текстовые команды на вход → текстовые результаты на выход. Реализация может происходить двумя способами:

• Как бинарный файл или скрипт в PATH оболочки — становится инструментом CLI, который работает в реальной оболочке
• Как парсер команд внутри вашего кода — когда LLM выводит run(command="weather --city Tokyo"), вы разбираете строку и выполняете её непосредственно в коде вашего приложения без участия оболочки

Ключевой момент — заставить LLM чувствовать, будто она использует CLI. В системе автора большинство команд никогда не касаются ОС — это функции Go, вызываемые маршрутизатором команд. Только команды, которым действительно нужна реальная ОС (запуск скриптов, установка пакетов), отправляются в изолированную микро-ВМ. Агент не знает и не заботится о том, какой уровень обрабатывает его команду.

Принципы проектирования CLI, удобного для агентов

Две основные философии

Философия 1: Дизайн справки в стиле Unix

• tool --help → список команд верхнего уровня
• tool <command> --help → конкретные параметры и использование для этой подкоманды

Это позволяет агенту обнаруживать возможности по мере необходимости, не загружая всю документацию в контекст заранее.

Философия 2: Мышление подсказками

Каждый ответ — особенно ошибки — должен содержать руководство, которое сокращает ненужное исследование.

Плохой пример:

> cat photo.png [error] binary file

Хороший пример:

> cat photo.png [error] cat: обнаружен бинарный файл (image/png, 182KB). Используйте: see photo.png (просмотр изображения) Или: cat -b photo.png (кодировка base64)

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

Безопасный дизайн CLI

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

Dry-Run / Предварительный просмотр изменений — предотвращение ошибок

Для операций в пределах полномочий агента, но с трудно обратимыми последствиями. Цель — позволить агенту (или человеку) увидеть, что произойдёт, прежде чем подтвердить.

> dns update --zone example.com --record A --value 1.2.3.4 ⚠ DRY RUN: A запись для example.com: 5.6.7.8 → 1.2.3.4 Распространение: ~300с. Не мгновенно обратимо. Для выполнения: добавьте --confirm

Предварительный просмотр должен чётко показывать текущее состояние и то, во что оно изменится. Агент подтверждает с помощью --confirm.

Авторизация человеком — операции за пределами автономии агента

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

Подход 1: Блокирующее push-одобрение

> pay --amount 500 --to vendor --reason "office supplies for Q2" ⏳ Требуется одобрение. Уведомление отправлено на ваше устройство. Ожидание ответа... ✓ Одобрено. Платёж на $500 выполнен. [exit:0 | 7.2s]

Как проверка входа на устройстве Apple — CLI отправляет push-уведомление непосредственно на устройство человека с полным контекстом (сумма, получатель, причина). CLI блокируется до тех пор, пока человек не одобрит или отклонит, затем возвращает результат агенту.

Подход 2: Код подтверждения / 2FA

> transfer --from savings --to checking --amount 10000 ⚠ Эта операция требует проверки 2FA. Причина: перевод $10,000 между счетами. Код отправлен в ваш аутентификатор. Повторите с: --otp <code>