### Анализ репозитория Shellwright Shellwright — это открытый инструмент, разработанный на TypeScript и JavaScript (с использованием Node.js), который представляет собой сервер на основе протокола MCP (Model-Context-Protocol). Его основная цель — предоставить AI-агентам (таким как те, что интегрированы в Claude Code, Cursor, VS Code или другие LLM-driven инструменты) возможность управлять терминалом, выполнять команды, захватывать скриншоты и записывать анимированные GIF-файлы. По сути, это аналог Playwright, но для командной строки: он позволяет AI "играть" с терминалом, как с браузером, автоматизируя задачи в shell-окружении. Проект лицензирован под MIT, что делает его бесплатным для личного и коммерческого использования. Репозиторий содержит исходный код, примеры использования, документацию и демо-скрипты (например, на Python для тестирования). Основные файлы: `dist/index.js` после сборки, темы для рендеринга (one-dark, dracula и т.д.), а также инструменты для логирования и тестирования. #### Как это работает Shellwright запускается как сервер (либо через stdio, либо HTTP), который экспонирует набор инструментов (tools) в формате MCP. Эти инструменты позволяют AI-агенту взаимодействовать с псевдотерминалами (PTY — pseudo-terminals) в реальном времени. Вот пошаговый механизм: 1. **Запуск сервера**: - Команда: `npx @dwmkerr/shellwright` (для быстрого старта) или локальная сборка через `npm run build`. - Сервер может работать в HTTP-режиме (`--http`), слушая на порту (по умолчанию 7498), или в stdio-режиме для локальных интеграций. - Конфигурация через флаги или переменные окружения: размер терминала (cols/rows), тема цветов, шрифт, временная директория для файлов и т.д. 2. **Создание сессии PTY**: - AI вызывает инструмент `shell_start` с параметрами (например, командой "bash -i" для запуска интерактивной оболочки). - Сервер спавнит PTY с указанными размерами (по умолчанию 120x40), запускает команду и возвращает `shell_session_id` для дальнейшей работы. - Можно запускать несколько сессий параллельно. 3. **Отправка ввода и чтение вывода**: - `shell_send`: Отправляет keystrokes (символы, включая Enter) в терминал с опциональной задержкой (для симуляции ввода). - `shell_read`: Читает текущий буфер терминала (текст с ANSI-кодами или очищенный). Это позволяет AI видеть вывод команд в реальном времени. 4. **Захват медиа**: - `shell_screenshot`: Захватывает скриншот терминала в формате PNG (основной), SVG, ANSI или TXT. Буфер преобразуется в SVG с применением темы (например, one-dark), затем в PNG с помощью библиотеки вроде sharp. - `shell_record_start/stop`: Запускает/останавливает запись GIF (с FPS, по умолчанию 10). Кадры — это PNG-снимки, дубликаты удаляются для оптимизации размера. Файлы хранятся во временной директории (`/tmp/shellwright` по умолчанию). 5. **Экспорт и очистка**: - Сервер возвращает `download_url` для файлов (например, ` http://localhost:7498/download/...`), которые можно скачать через curl или браузер. - `shell_stop`: Завершает сессию, удаляет временные файлы. 6. **Интеграция с AI**: - Сервер регистрируется в AI-клиенте (например, в Claude: `claude mcp add ...` или в настройках VS Code/Cursor). - AI-агент (LLM) использует ReAct-подход: анализирует задачу, вызывает инструменты последовательно (например, start → send → screenshot → stop). - Логирование: Опционально пишет JSONL-файл с вызовами для отладки. Технически: Использует `child_process` Node.js для PTY, рендерит ANSI в изображения через CSS-темы. Нет зависимости от внешних сервисов, всё локально. Подходит для задач вроде автоматизации скриптов, тестирования CLI, создания туториалов с GIF или отладки (AI может запустить команду, увидеть ошибку на "скриншоте" и скорректировать). #### Примеры использования - **Простой скриншот**: Пользователь говорит AI: "Запусти htop и покажи скриншот". AI вызывает `shell_start("htop")`, затем `shell_screenshot` — возвращает URL PNG. - **Запись GIF**: "Открой Vim, напиши текст и запиши GIF". AI: start bash → send "vim" → send keystrokes → record_start → действия → record_stop. - **Автоматизация**: В демо-скрипте: `python demo/demo.py -- "Run ls and screenshot"` — сервер запускает HTTP, AI выполняет и возвращает файл. ### Сравнение с обычным запросом к Gemini CLI Gemini CLI — это официальный open-source инструмент от Google (устанавливается через `npm install -g @google/gemini-cli`), который предоставляет прямой доступ к моделям Gemini AI (включая Gemini 3 Pro) прямо из терминала. Он использует ReAct-цикл (reason-and-act: модель размышляет, затем действует через инструменты) и поддерживает встроенные инструменты (чтение/запись файлов, выполнение команд, поиск и т.д.), а также внешние MCP-сервера. Это универсальный AI-агент для кодирования, отладки, генерации контента и автоматизации, но с фокусом на текстовой взаимодействии. #### Обычный запрос к Gemini CLI - **Как работает**: Вы вводите команду вроде `gemini "Напиши shell-скрипт для листинга файлов"` или `gemini "Отладь этот код"`. Модель анализирует запрос, может использовать встроенные инструменты (например, `read_file` для чтения кода, `execute_command` для запуска простых команд), и возвращает текстовый ответ (скрипт, объяснение, исправления). Всё происходит в одном цикле: prompt → reasoning → action (если нужно) → response. - **Преимущества**: Простота, скорость, нет нужды в дополнительных серверах. Подходит для генерации кода, объяснений, исследований (может искать в вебе через инструменты). Бесплатный доступ с лимитами, или через API-ключ для продвинутых моделей. - **Ограничения**: Взаимодействие преимущественно текстовое. Если нужно запустить команду и увидеть визуальный вывод (скриншот терминала, GIF), Gemini CLI не захватывает это нативно — он может выполнить `ls` и показать текст, но не рендерит "как в терминале". Для сложных интерактивных задач (типа редактирования в Vim с визуальной отладкой) модель полагается на симуляцию, а не реальное выполнение с захватом. #### Сравнение с Shellwright | Аспект | Shellwright | Обычный запрос к Gemini CLI | |--------|-------------|-----------------------------| | **Фокус** | Специализирован на терминальной автоматизации: реальное выполнение команд в PTY, захват визуалов (скриншоты, GIF). Интегрируется как MCP-сервер в AI-агенты. | Универсальный AI-запрос: генерация текста/кода, простые действия через встроенные инструменты. Не фокусируется на визуальном терминале. | | **Взаимодействие** | Агентное и интерактивное: AI может итеративно отправлять команды, читать буфер, корректировать на основе вывода/скриншотов. Идеально для тестирования, туториалов, отладки CLI. | Одношаговое или простое цикличное: Запрос → Ответ. Для сложного — использует ReAct, но без глубокого контроля над терминалом (текст только). | | **Визуалы** | Да: Скриншоты (PNG/SVG), GIF-записи с темами и оптимизацией. | Нет: Только текст. Для визуалов нужно вручную запускать внешние инструменты. | | **Интеграция** | Как сервер для AI (включая Gemini CLI! — можно добавить Shellwright как MCP в Gemini). Требует запуска сервера. | Самостоятельный CLI, но может использовать внешние MCP (например, Shellwright для расширения). | | **Сложность установки** | Нужно npx или сборка + регистрация в AI-клиенте. | Простая: npm install, затем `gemini `. | | **Применение** | Для задач, где нужен "живой" терминал (автоматизация скриптов с верификацией, запись демо). Более мощный для agentic AI. | Для быстрых запросов (генерация скрипта, объяснение). Менее подходит для визуальной/интерактивной отладки. | | **Пример** | AI: "Запусти ls, скриншот" → Реальный PTY, PNG-файл. | `gemini "Запусти ls и покажи"` → Текст вывода ls (если в контексте), но без скриншота. | **Вывод**: Shellwright — это расширение для AI-агентов, делающее их "руками" в терминале, с визуальным фидбеком. Обычный запрос к Gemini CLI — это "мозги" без рук: быстро генерирует идеи/код, но не выполняет/визуализирует в реальном терминале. Если интегрировать Shellwright в Gemini CLI как MCP-сервер, вы получите комбо: Gemini размышляет и использует Shellwright для действий. Для простых задач Gemini CLI хватит, но для продвинутой автоматизации Shellwright добавляет глубину.