Архитектура

Эта страница — карта внутреннего устройства Hermes Agent на верхнем уровне. Используйте его для ориентации в базе кода, а затем перейдите к документации по подсистемам для изучения деталей реализации.

Обзор системы

┌─────────────────────────────────────────────────────────────────────┐
│                        Точки входа                                 │
│                                                                      │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
│  Batch Runner    API Server                  Python Library          │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                          │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │ Сборщик      │  │ Разрешение   │  │ Диспетчери-  │               │
│  │ промпта      │  │ провайдера   │  │ зация        │               │
│  │ (prompt_     │  │ (runtime_    │  │ инструментов │               │
│  │  builder.py) │  │  provider.py)│  │ (model_      │               │
│  │              │  │              │  │  tools.py)   │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                 │                       │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
│  │ Сжатие и     │  │ 3 режима API │  │ Реестр       │               │
│  │ кэширование  │  │ chat_compl.  │  │ инструментов │               │
│  │              │  │ codex_resp.  │  │ (registry.py)│               │
│  │              │  │ anthropic    │  │ 70+          │               │
│  │              │  │              │  │ инструментов │               │
│  │              │  │              │  │ 28 наборов   │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ Хранилище сессий  │              │ Бэкенды инструментов  │
│ (SQLite + FTS5)   │              │ Терминал (7 бэкендов) │
│ hermes_state.py   │              │ Браузер (5 бэкендов)  │
│ gateway/session.py│              │ Веб (4 бэкенда)       │
└───────────────────┘              │ MCP (динамический)   │
                                   │ Файлы, Vision и др.  │
                                   └──────────────────────┘

Структура каталогов

hermes-agent/
├── run_agent.py              # AIAgent — основной цикл беседы (большой файл)
├── cli.py                    # HermesCLI — интерактивный терминальный интерфейс (большой файл)
├── model_tools.py            # Обнаружение инструментов, сбор схем, диспетчеризация
├── toolsets.py               # Группировки инструментов и пресеты для платформ
├── hermes_state.py           # База данных сессий/состояний SQLite с FTS5
├── hermes_constants.py       # HERMES_HOME, пути, зависящие от профиля
├── batch_runner.py           # Пакетная генерация траекторий
│
├── agent/                    # Внутреннее устройство агента
│   ├── prompt_builder.py     # Сборка системного промпта
│   ├── context_engine.py     # ContextEngine ABC (подключаемый)
│   ├── context_compressor.py # Стандартный движок — сжатие с потерями
│   ├── prompt_caching.py     # Кэширование промптов Anthropic
│   ├── auxiliary_client.py   # Вспомогательная LLM для побочных задач (vision, суммаризация)
│   ├── model_metadata.py     # Длины контекста моделей, оценка токенов
│   ├── models_dev.py         # Интеграция с реестром models.dev
│   ├── anthropic_adapter.py  # Преобразование формата Anthropic Messages API
│   ├── display.py            # KawaiiSpinner, форматирование предпросмотра инструментов
│   ├── skill_commands.py     # Слеш-команды навыков
│   ├── memory_manager.py    # Оркестрация менеджера памяти
│   ├── memory_provider.py   # ABC провайдера памяти
│   └── trajectory.py         # Вспомогательные функции сохранения траекторий
│
├── hermes_cli/               # Подкоманды CLI и настройка
│   ├── main.py               # Точка входа — все подкоманды `hermes` (большой файл)
│   ├── config.py             # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, миграция
│   ├── commands.py           # COMMAND_REGISTRY — центральное определение слеш-команд
│   ├── auth.py               # PROVIDER_REGISTRY, разрешение учётных данных
│   ├── runtime_provider.py   # Провайдер → api_mode + учётные данные
│   ├── models.py             # Каталог моделей, списки моделей провайдеров
│   ├── model_switch.py       # Логика команды /model (общая для CLI и gateway)
│   ├── setup.py              # Интерактивный мастер настройки (большой файл)
│   ├── skin_engine.py        # Движок тем CLI
│   ├── skills_config.py      # hermes skills — включение/отключение для каждой платформы
│   ├── skills_hub.py         # Слеш-команда /skills
│   ├── tools_config.py       # hermes tools — включение/отключение для каждой платформы
│   ├── plugins.py            # PluginManager — обнаружение, загрузка, хуки
│   ├── callbacks.py          # Терминальные колбэки (уточнение, sudo, разрешение)
│   └── gateway.py            # hermes gateway start/stop
│
├── tools/                    # Реализации инструментов (один файл на инструмент)
│   ├── registry.py           # Центральный реестр инструментов
│   ├── approval.py           # Обнаружение опасных команд
│   ├── terminal_tool.py      # Оркестрация терминала
│   ├── process_registry.py   # Управление фоновыми процессами
│   ├── file_tools.py         # read_file, write_file, patch, search_files
│   ├── web_tools.py          # web_search, web_extract
│   ├── browser_tool.py       # 10 инструментов автоматизации браузера
│   ├── code_execution_tool.py # execute_code sandbox
│   ├── delegate_tool.py      # Делегирование субагенту
│   ├── mcp_tool.py           # MCP-клиент (большой файл)
│   ├── credential_files.py   # Передача учётных данных через файлы
│   ├── env_passthrough.py    # Передача переменных окружения для песочниц
│   ├── ansi_strip.py         # Удаление ANSI-escape последовательностей
│   └── environments/         # Бэкенды терминала (local, docker, ssh, modal, daytona, singularity)
│
├── gateway/                  # Шлюз для платформ обмена сообщениями
│   ├── run.py                # GatewayRunner — диспетчеризация сообщений (большой файл)
│   ├── session.py            # SessionStore — сохранение бесед
│   ├── delivery.py           # Доставка исходящих сообщений
│   ├── pairing.py            # Авторизация спаривания DM
│   ├── hooks.py              # Обнаружение хуков и события жизненного цикла
│   ├── mirror.py             # Зеркалирование сообщений между сессиями
│   ├── status.py             # Блокировки токенов, отслеживание процессов в рамках профиля
│   ├── builtin_hooks/        # Точка расширения для всегда зарегистрированных хуков (не поставляются)
│   └── platforms/            # 20 адаптеров: telegram, discord, slack, whatsapp,
│                             #   signal, matrix, mattermost, email, sms,
│                             #   dingtalk, feishu, wecom, wecom_callback, weixin,
│                             #   bluebubbles, qqbot, homeassistant, webhook, api_server,
│                             #   yuanbao
│
├── acp_adapter/              # ACP-сервер (VS Code / Zed / JetBrains)
├── cron/                     # Планировщик (jobs.py, scheduler.py)
├── plugins/memory/           # Плагины провайдеров памяти
├── plugins/context_engine/   # Плагины движков контекста
├── environments/             # Среды обучения с подкреплением (Atropos)
├── skills/                   # Встроенные навыки (всегда доступны)
├── optional-skills/          # Официальные дополнительные навыки (устанавливаются явно)
├── website/                  # Сайт документации Docusaurus
└── tests/                    # Набор тестов Pytest (~3000+ тестов)

Поток данных

Сессия CLI

Ввод пользователя → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API-вызов (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → цикл
    → финальный ответ → отображение → сохранение в SessionDB

Шлюз сообщений

Событие платформы → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → авторизация пользователя
    → разрешение ключа сессии
    → создание AIAgent с историей сессии
    → AIAgent.run_conversation()
    → доставка ответа обратно через адаптер

Cron-задача

Тик планировщика → загрузка подлежащих выполнению задач из jobs.json
  → создание нового AIAgent (без истории)
  → внедрение прикреплённых навыков как контекст
  → выполнение промпта задачи
  → доставка ответа на целевую платформу
  → обновление состояния задачи и next_run

Основные подсистемы

Цикл агента

Синхронный движок оркестрации (AIAgent в run_agent.py). Обрабатывает выбор провайдера, построение промпта, выполнение инструментов, повторы, fallback, колбэки, сжатие и сохранение. Поддерживает три режима API для разных бэкендов провайдеров.

→ Внутреннее устройство цикла агента

Система промптов

Построение и поддержка промпта на протяжении жизненного цикла беседы:

prompt_builder.py — Собирает системный промпт из: личности (SOUL.md), памяти (MEMORY.md, USER.md), навыков, файлов контекста (AGENTS.md,.hermes.md), инструкций по использованию инструментов и моделеспецифичных указаний
prompt_caching.py — Применяет точки разрыва кэша Anthropic для префиксного кэширования
context_compressor.py — Суммаризирует средние витки беседы, когда контекст превышает пороги

→ Сборка промпта, Сжатие контекста и кэширование промптов

Разрешение провайдера

Общий разрешитель рантайма, используемый CLI, gateway, cron, ACP и вспомогательными вызовами. Сопоставляет кортежи (provider, model) с (api_mode, api_key, base_url). Обрабатывает 18+ провайдеров, OAuth-потоки, пулы учётных данных и разрешение алиасов.

→ Разрешение рантайма провайдера

Система инструментов

Центральный реестр инструментов (tools/registry.py) с 70+ зарегистрированными инструментами в ~28 наборах. Каждый файл инструмента саморегистрируется при импорте. Реестр управляет сбором схем, диспетчеризацией, проверкой доступности и обёрткой ошибок. Инструменты терминала поддерживают 7 бэкендов (локальный, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox).

→ Рантайм инструментов

Сохранение сессий

Хранилище сессий на основе SQLite с полнотекстовым поиском FTS5. Сессии имеют отслеживание родословной (родитель/потомок после сжатий), изоляцию по платформе и атомарные записи с обработкой конфликтов.

→ Хранилище сессий

Шлюз обмена сообщениями

Долго работающий процесс с 20 адаптерами платформ, единой маршрутизацией сессий, авторизацией пользователей (белые списки + спаривание DM), диспетчеризацией слеш-команд, системой хуков, тиками cron и фоновым обслуживанием.

→ Внутреннее устройство Gateway

Система плагинов

Три источника обнаружения: ~/.hermes/plugins/ (пользователь), .hermes/plugins/ (проект) и точки входа pip. Плагины регистрируют инструменты, хуки и команды CLI через контекстный API. Существует два специализированных типа плагинов: провайдеры памяти (plugins/memory/) и движки контекста (plugins/context_engine/). Оба являются единственным выбором — активным может быть только один из каждого типа в данный момент, настраивается через hermes plugins или config.yaml.

→ Руководство по плагинам, Плагин провайдера памяти

Cron

Задачи первого класса агента (не оболочки). Задачи хранятся в JSON, поддерживают несколько форматов расписания, могут прикреплять навыки и скрипты и доставляются на любую платформу.

→ Внутреннее устройство Cron

Интеграция ACP

Предоставляет Hermes как редакторский агент через stdio/JSON-RPC для VS Code, Zed и JetBrains.

→ Внутреннее устройство ACP

RL / Среды / Траектории

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

→ Среды, бенчмарки и генерация данных, Траектории и формат обучения

Принципы проектирования

Принцип	Что означает на практике
Стабильность промпта	Системный промпт не меняется в середине беседы. Нет мутаций, ломающих кэш, кроме явных действий пользователя (`/model`).
Наблюдаемое выполнение	Каждый вызов инструмента виден пользователю через колбэки. Обновления прогресса в CLI (спиннер) и gateway (сообщения чата).
Прерываемость	API-вызовы и выполнение инструментов могут быть отменены на лету пользовательским вводом или сигналами.
Ядро, независимое от платформы	Один класс AIAgent обслуживает CLI, gateway, ACP, батчевую обработку и API-сервер. Различия платформ находятся в точке входа, а не в агенте.
Слабая связанность	Дополнительные подсистемы (MCP, плагины, провайдеры памяти, среды RL) используют паттерны реестров и шлюзование через check_fn, а не жёсткие зависимости.
Изоляция профилей	Каждый профиль (`hermes -p <name>`) получает собственные HERMES_HOME, конфиг, память, сессии и PID gateway. Несколько профилей работают одновременно.

Цепочка зависимостей файлов

tools/registry.py  (нет зависимостей — импортируется всеми файлами инструментов)
       ↑
tools/*.py  (каждый вызывает registry.register() при импорте)
       ↑
model_tools.py  (импортирует tools/registry + запускает обнаружение инструментов)
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

Эта цепочка означает, что инструменты для регистрации происходят во время импорта, до создания любого экземпляра агента. Любой файл tools/*.py по вызову registry.register() на верхнем уровне обнаруживается автоматически — ручной список импортов не требуется.