g3 - AI-агент для программирования

g3 — это AI-агент для программирования, предназначенный для помощи в выполнении задач путём написания кода и выполнения команд. Написанный на Rust, он предоставляет гибкую архитектуру для взаимодействия с различными провайдерами больших языковых моделей (LLM), предлагая мощные возможности генерации кода и автоматизации задач.

Обзор архитектуры

g3 следует модульной архитектуре, организованной как рабочее пространство Rust с несколькими крейтами, каждый из которых отвечает за определённую функциональность:

Основные компоненты

g3-core

Сердце системы агента, содержащее: - Движок агента: Основная логика оркестрации для обработки бесед, выполнения инструментов и управления задачами - Управление контекстным окном: Интеллектуальное отслеживание использования токенов с прореживанием контекста (50-80%) и автоматической компактификацией при заполнении на 80% - Система инструментов: Встроенные инструменты для операций с файлами, команд оболочки, управления компьютером, управления задачами TODO и структурированного вывода - Парсер потоковых ответов: Парсинг ответов LLM в реальном времени с обнаружением вызовов инструментов и их выполнением - Выполнение задач: Поддержка одноразового и итеративного выполнения задач с автоматической логикой повторных попыток

g3-providers

Абстракционный слой для провайдеров LLM: - Интерфейс провайдера: Общий API на основе трейтов для различных бэкендов LLM - Поддержка нескольких провайдеров: - Anthropic (модели Claude) - Databricks (модели DBRX и другие) - Локальные/встраиваемые модели через llama.cpp с ускорением Metal на macOS - Аутентификация OAuth: Встроенная поддержка потока OAuth для безопасной аутентификации провайдеров - Реестр провайдеров: Динамическое управление и выбор провайдеров

g3-config

Система управления конфигурацией: - Конфигурация на основе переменных окружения - Учётные данные и настройки провайдеров - Выбор модели и параметры - Параметры конфигурации времени выполнения

g3-execution

Фреймворк выполнения задач: - Планирование и декомпозиция задач - Стратегии выполнения (последовательная, параллельная) - Обработка ошибок и механизмы повторных попыток - Отслеживание прогресса и отчётность

g3-computer-control

Возможности управления компьютером: - Автоматизация мыши и клавиатуры - Инспекция и взаимодействие с элементами интерфейса - Захват скриншотов и управление окнами - Извлечение текста с помощью OCR через Tesseract

g3-cli

Интерфейс командной строки: - Интерактивный терминальный интерфейс - Отправка и мониторинг задач - Команды управления конфигурацией - Управление сессиями

Обработка ошибок и устойчивость

g3 включает надёжную обработку ошибок с автоматической логикой повторных попыток: - Обнаружение восстановимых ошибок: Автоматически определяет восстановимые ошибки (ограничения по частоте запросов, сетевые проблемы, ошибки сервера, тайм-ауты) - Экспоненциальный откат с джиттером: Реализует интеллектуальные задержки между повторными попытками, чтобы избежать перегрузки сервисов - Детальное логирование ошибок: Захватывает исчерпывающий контекст ошибок, включая трассировки стека, данные запросов/ответов и информацию о сессии - Сохранение ошибок: Сохраняет подробные логи ошибок в .g3/errors/ для постмортем-анализа - Плавная деградация: Невосстановимые ошибки логируются с полным контекстом перед завершением работы

Обнаружение дубликатов вызовов инструментов

g3 включает интеллектуальное обнаружение дубликатов для предотвращения случайного двойного вызова одного и того же инструмента LLM подряд: - Предотвращение последовательных дубликатов: Блокируются только непосредственно следующие друг за другом идентичные вызовы инструментов - Разрешены вызовы с разделением текстом: Если между вызовами инструментов есть какой-либо текст, они не считаются дубликатами - Повторное использование в рамках сессии: Инструменты могут вызываться несколько раз в течение сессии — предотвращаются только подряд идущие дубликаты

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

Тайминговый футер

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

Ключевые особенности

Интеллектуальное управление контекстом

• Автоматический мониторинг контекстного окна с отслеживанием на основе процентов
• Умная автоматическая компактификация при приближении к лимитам токенов
• Прореживание контекста при достижении порогов 50%, 60%, 70%, 80% — автоматически заменяет большие результаты работы инструментов на ссылки на файлы
• Сохранение истории бесед через резюме
• Динамическое распределение токенов для разных провайдеров (от 4k до 200k+ токенов)

Интерактивные команды управления

Интерактивный CLI g3 включает команды управления для ручного управления контекстом:

• /compact: Вручную запустить уплотнение истории беседы
• /thinnify: Вручную запустить прореживание контекста для замены больших результатов работы инструментов на ссылки на файлы
• /skinnify: Вручную запустить полное прореживание контекста (как /thinnify, но обрабатывает всё окно контекста, а не только первую треть)
• /readme: Перезагрузить README.md и AGENTS.md с диска без перезапуска
• /stats: Показать детальную статистику контекста и производительности
• /help: Отобразить все доступные управляющие команды

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

Экосистема инструментов

• Операции с файлами: Чтение, запись и редактирование файлов с точностью до строк
• Интеграция с оболочкой: Выполнение системных команд с захватом вывода
• Генерация кода: Структурированная генерация кода с учётом синтаксиса
• Управление задачами TODO: Чтение и запись списков задач в формате markdown с чекбоксами
• Управление компьютером (Экспериментально): Автоматизация настольных приложений
  • Управление мышью и клавиатурой
  • Инспекция элементов интерфейса
  • Захват скриншотов и управление окнами
  • Список и идентификация окон
• Поиск по коду: Встроенный tree-sitter для синтаксически-осознанного поиска по коду (Rust, Python, JavaScript, TypeScript, Go, Java, C, C++) — см. руководство по поиску кода
• Финальный вывод: Форматированное представление результатов

Навыки агентов

g3 поддерживает спецификацию Agent Skills — открытый формат для переносимых пакетов навыков, расширяющих возможности агента.

Расположение навыков (в порядке приоритета, более поздние переопределяют более ранние): 1. Встроенные навыки (скомпилированы в бинарный файл) 2. Глобальные: ~/.g3/skills/ 3. Дополнительные пути из конфигурации 4. Рабочая область: .g3/skills/ 5. Репозиторий: skills/ (наивысший приоритет, сохраняется в git)

Формат SKILL.md:

---
name: pdf-processing          # Required: 1-64 chars, lowercase + hyphens
description: Extract text...  # Required: 1-1024 chars, when to use
license: Apache-2.0           # Optional
compatibility: Requires git   # Optional: environment requirements
---

# PDF Processing

Detailed instructions for the agent...

Конфигурация (в g3.toml):

[skills]
enabled = true                    # Default: true
extra_paths = ["/path/to/skills"] # Additional skill directories

При запуске g3 сканирует каталоги с навыками и добавляет их краткое описание в системный промпт. Когда агенту нужен навык, он считывает полный SKILL.md с помощью инструмента read_file.

Каждый навык добавляет ~50–100 токенов в контекст (название + описание + путь). Навыки могут включать: - scripts/ — Исполняемый код (Python, Bash и др.) - references/ — Дополнительная документация - assets/ — Шаблоны, файлы данных

Встроенные навыки: Основные навыки, такие как research, встроены в бинарный файл, что гарантирует их работу в любом месте без внешних файлов. Встроенные скрипты автоматически извлекаются в .g3/bin/ при первом использовании.

Встроенный навык исследования: Выполняйте асинхронное веб-исследование через background_process("research", ".g3/bin/g3-research 'ваш запрос'"). Результаты сохраняются в .g3/research/<id>/report.md.

Подробности см. в руководстве по навыкам.

Гибкость провайдеров

• Поддержка нескольких провайдеров LLM через унифицированный интерфейс
• Горячая замена провайдеров без изменения кода
• Оптимизации и поддержка функций, специфичных для провайдеров
• Поддержка локальных моделей для автономной работы

Встроенные модели (локальные LLM)

g3 поддерживает локальные модели через llama.cpp с ускорением Metal на macOS. Ниже приведено сравнение производительности для агентных задач (многоэтапные рабочие процессы с вызовом инструментов):

Тестовый сценарий: Переупаковка комиксов — извлечение архивов CBR/CBZ, пересортировка файлов с сохранением порядка страниц и выпусков, переупаковка в единый архив. Требует правильной последовательности действий, обработки файлов и отсутствия состояния гонки.

Облачные модели (базовый уровень)

Локальные модели

Ключевые выводы: - Плотные модели (Qwen3-32B, Qwen3-14B) корректно обрабатывают агентные циклы - MoE-модели (Qwen3-30B-A3B) быстрые, но не знают, когда прекращать вызов инструментов - Metal GPU хорошо работает с плотными моделями на Apple Silicon - Даже лучшие локальные модели (32B) значительно отстают от Claude Opus 4.5 в сложных задачах - Локальные модели лучше всего подходят для более простых агентных задач или когда требуется офлайн-режим/конфиденциальность

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

[providers.embedded.qwen3-big]
model_path = "~/.g3/models/Qwen_Qwen3-32B-Q4_K_M.gguf"
model_type = "qwen"
context_length = 40960
gpu_layers = 99  # Full GPU offload on Apple Silicon

Автоматизация задач

• Однократное выполнение задач для быстрых операций
• Итеративный режим задач для сложных многоэтапных рабочих процессов
• Автоматическое восстановление после ошибок и логика повторных попыток
• Отслеживание прогресса и обработка промежуточных результатов

Язык и технологический стек

• Язык: Rust (издание 2021 года)
• Асинхронная среда выполнения: Tokio для параллельных операций
• HTTP-клиент: Reqwest для взаимодействия с API
• Сериализация: Serde для работы с JSON
• Фреймворк CLI: Clap для парсинга командной строки
• Логирование: Tracing для структурированного логирования (логи уровня INFO конвертируются в DEBUG для более чистого вывода в CLI)
• Локальные модели: llama.cpp с поддержкой ускорения Metal

Варианты использования

g3 предназначен для: - Автоматической генерации и рефакторинга кода - Манипуляции с файлами и создания структуры проекта - Задач системного администрирования - Обработки и трансформации данных - Интеграции и тестирования API - Генерации документации - Сложных многоэтапных рабочих процессов - Параллельной разработки модульных архитектур - Автоматизации и тестирования настольных приложений

Начало работы

Режим по умолчанию: Накопительный автономный

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

# Simply run g3 in any directory
g3

# You'll be prompted to describe what you want to build
# Each input you provide:
# 1. Gets added to accumulated requirements
# 2. Automatically triggers autonomous mode (coach-player loop)
# 3. Implements your requirements iteratively

# Example session:
requirement> create a simple web server in Python with Flask
# ... autonomous mode runs and implements it ...
requirement> add a /health endpoint that returns JSON
# ... autonomous mode runs again with both requirements ...

Другие режимы

# Single-shot mode (one task, then exit)
g3 "implement a function to calculate fibonacci numbers"

# Traditional autonomous mode (reads requirements.md)
g3 --autonomous

# Traditional chat mode (simple interactive chat without autonomous runs)
g3 --chat

Режим планирования

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

# Start planning mode for a codebase
g3 --planning --codepath ~/my-project --workspace ~/g3_workspace

# Without git operations (for repos not yet initialized)
g3 --planning --codepath ~/my-project --no-git --workspace ~/g3_workspace

Рабочий процесс режима планирования: 1. Уточнение требований: Напишите требования в <codepath>/g3-plan/new_requirements.md, затем позвольте LLM предложить улучшения 2. Реализация: После утверждения требований они переименовываются в current_requirements.md, и цикл «тренер/игрок» реализует их 3. Завершение: После реализации файлы архивируются с временными метками (например, completed_requirements_2025-01-15_10-30-00.md) 4. Коммит в git: Подготовленные файлы коммитятся с сообщением, сгенерированным LLM 5. Повторение: Возврат к шагу 1 для следующей итерации

Все артефакты планирования хранятся в <codepath>/g3-plan/: - planner_history.txt — Журнал аудита всех действий по планированию - new_requirements.md / current_requirements.md — Активные требования - todo.g3.md — Список дел для реализации - completed_*.md — Архивированные требования и списки дел

Смотрите раздел конфигурации для настройки различных провайдеров для роли планировщика.

# Build the project
cargo build --release

# Run from the build directory
./target/release/g3

# Or copy both files to somewhere in your PATH (macOS only needs both files)
cp target/release/g3 ~/.local/bin/
cp target/release/libVisionBridge.dylib ~/.local/bin/  # macOS only

# Execute a task
g3 "implement a function to calculate fibonacci numbers"

Конфигурация

G3 использует файл конфигурации в формате TOML. Файл конфигурации автоматически создаётся в ~/.config/g3/config.toml при первом запуске с разумными значениями по умолчанию.

Конфигурация повторных попыток

g3 включает настраиваемую логику повторных попыток для обработки восстановимых ошибок (тайм-аутов, ограничений по количеству запросов, сетевых проблем, ошибок сервера):

[agent]
max_context_length = 8192
enable_streaming = true
timeout_seconds = 60

# Retry configuration for recoverable errors
max_retry_attempts = 3              # Default mode retry attempts
autonomous_max_retry_attempts = 6   # Autonomous mode retry attempts

Поведение при повторных попытках: - Режим по умолчанию (max_retry_attempts): Используется для интерактивного чата и однократных задач. По умолчанию: 3 попытки. - Автономный режим (autonomous_max_retry_attempts): Используется для длительных автономных задач. По умолчанию: 6 попыток. - Повторные попытки используют экспоненциальную задержку с джиттером, чтобы не перегружать сервисы - Автономный режим распределяет повторные попытки на ~10 минут для обработки длительных сбоев - Повторяются только восстановимые ошибки (тайм-ауты, ограничения по количеству запросов, ошибки 5xx, сетевые проблемы) - Невосстановимые ошибки (ошибки аутентификации, неверные запросы) завершаются немедленно

Пример: Чтобы повысить устойчивость к тайм-аутам в автономном режиме, установите autonomous_max_retry_attempts = 10 в вашем конфиге.

Смотрите config.example.toml для полного примера конфигурации.

Автоматизация браузера с помощью WebDriver

g3 включает поддержку WebDriver для задач автоматизации браузера. По умолчанию используется Chrome в безголовом режиме, с Safari в качестве альтернативы.

Однократная настройка (только для macOS):

Если вы хотите использовать Safari вместо Chrome в безголовом режиме, необходимо включить удалённую автоматизацию Safari. Выполните это один раз:

# Option 1: Use the provided script
./scripts/enable-safari-automation.sh

# Option 2: Enable manually
safaridriver --enable  # Requires password

# Option 3: Enable via Safari UI
# Safari → Preferences → Advanced → Show Develop menu
# Then: Develop → Allow Remote Automation

Использование:

# Use Safari (opens a visible browser window)
g3 --safari

# Use Chrome in headless mode (default, no visible window, runs in background)
g3

Параметры настройки Chrome:

Вариант 1: Использовать Chrome для тестирования (рекомендуется) — гарантирует совместимость версий:

./scripts/setup-chrome-for-testing.sh

Затем добавьте в ваш ~/.config/g3/config.toml:

[webdriver]
chrome_binary = "/Users/yourname/.chrome-for-testing/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"

Вариант 2: Использовать системный Chrome — требует совпадения версии ChromeDriver: - macOS: brew install chromedriver - Linux: apt install chromium-chromedriver - Или скачайте с: https://chromedriver.chromium.org/downloads

Примечание: Если вы видите ошибки типа «Версия ChromeDriver не соответствует версии Chrome», используйте Вариант 1 (Chrome для тестирования), который включает совместимые версии.

Управление компьютером (Экспериментальная функция)

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

Доступные инструменты: mouse_click, type_text, find_element, take_screenshot, list_windows

Настройка: Включите в конфигурации с помощью computer_control.enabled = true и предоставьте разрешения для специальных возможностей ОС: - macOS: Системные настройки → Защита и безопасность → Специальные возможности - Linux: Убедитесь в доступе к X11 или Wayland - Windows: Запустите от имени администратора (только при первом запуске)

Журналы сессий

G3 автоматически сохраняет журналы сессий для каждого взаимодействия в директории .g3/sessions/. Эти журналы содержат: - Полную историю переписки - Статистику использования токенов - Временные метки и статус сессии

Директория .g3/ создаётся автоматически при первом использовании и исключается из системы контроля версий.

Режим агента

Режим агента запускает специализированных ИИ-агентов с настраиваемыми промптами для конкретных задач. У каждого агента есть своя «личность» и область специализации.

Встроенные агенты

g3 поставляется с несколькими встроенными агентами, готовыми к работе «из коробки»:

Использование

# List all available agents
g3 --list-agents

# Run an agent on the current project
g3 --agent carmack

# Run an agent with a specific task
g3 --agent hopper "add tests for the parser module"

Пользовательские агенты

Создавайте пользовательских агентов, добавляя markdown-файлы в agents/<имя>.md в вашей рабочей области. Агенты из рабочей области переопределяют встроенных агентов с тем же именем, позволяя настраивать их под каждый проект.

Studio — менеджер рабочих областей для нескольких агентов

Studio — это сопутствующий инструмент для управления несколькими сессиями агентов g3 с использованием git worktree. Каждая сессия работает в изолированной рабочей области с собственной веткой, позволяя нескольким агентам работать с одним и тем же кодом без конфликтов.

Использование

# Build studio alongside g3
cargo build --release

# Run an agent session (creates worktree, runs g3, tails output)
studio run --agent carmack "fix the memory leak in cache.rs"

# Run a one-shot session without a specific agent
studio run "add unit tests for the parser module"

# List all sessions
studio list

# Check session status (shows summary when complete)
studio status <session-id>

# Accept a session: merge changes to main and cleanup
studio accept <session-id>

# Discard a session: delete without merging
studio discard <session-id>

Как это работает

1. Изоляция: Каждая сессия создаёт git worktree в .worktrees/sessions/<агент>/<идентификатор-сессии>/
2. Ветвление: Сессии работают в ветках с именами sessions/<агент>/<идентификатор-сессии>
3. Отслеживание: Метаданные сессий хранятся в .worktrees/.sessions/
4. Рабочий процесс: Запуск → Проверка → Принятие (слияние) или Отмена (удаление)

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

Карта документации

Подробная документация доступна в директории docs/:

Для ИИ-агентов, работающих с этим кодом, см. AGENTS.md.

Дополнительные ресурсы: - DESIGN.md — исходный документ с обоснованием дизайна

• config.example.toml — Полный пример конфигурации
• config.coach-player.example.toml — Пример конфигурации для нескольких ролей

Лицензия

Лицензия MIT