Архитектура

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

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

┌─────────────────────────────────────────────────────────────────────┐
│                        Entry Points                                  │
│                                                                      │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
│  Batch Runner    API Server                  Python Library          │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                          │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │ Prompt       │  │ Provider     │  │ Tool         │               │
│  │ Builder      │  │ Resolution   │  │ Dispatch     │               │
│  │ (prompt_     │  │ (runtime_    │  │ (model_      │               │
│  │  builder.py) │  │  provider.py)│  │  tools.py)   │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                 │                       │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
│  │ Compression  │  │ 3 API Modes  │  │ Tool Registry│               │
│  │ & Caching    │  │ chat_compl.  │  │ (registry.py)│               │
│  │              │  │ codex_resp.  │  │ 70+ tools    │               │
│  │              │  │ anthropic    │  │ 28 toolsets  │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ Session Storage   │              │ Tool Backends         │
│ (SQLite + FTS5)   │              │ Terminal (7 backends) │
│ hermes_state.py   │              │ Browser (5 backends)  │
│ gateway/session.py│              │ Web (4 backends)      │
└───────────────────┘              │ MCP (dynamic)         │
                                   │ File, Vision, etc.    │
                                   └──────────────────────┘

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

hermes-agent/
├── run_agent.py              # AIAgent — core conversation loop (large file)
├── cli.py                    # HermesCLI — interactive terminal UI (large file)
├── model_tools.py            # Tool discovery, schema collection, dispatch
├── toolsets.py               # Tool groupings and platform presets
├── hermes_state.py           # SQLite session/state database with FTS5
├── hermes_constants.py       # HERMES_HOME, profile-aware paths
├── batch_runner.py           # Batch trajectory generation
│
├── agent/                    # Agent internals
│   ├── prompt_builder.py     # System prompt assembly
│   ├── context_engine.py     # ContextEngine ABC (pluggable)
│   ├── context_compressor.py # Default engine — lossy summarization
│   ├── prompt_caching.py     # Anthropic prompt caching
│   ├── auxiliary_client.py   # Auxiliary LLM for side tasks (vision, summarization)
│   ├── model_metadata.py     # Model context lengths, token estimation
│   ├── models_dev.py         # models.dev registry integration
│   ├── anthropic_adapter.py  # Anthropic Messages API format conversion
│   ├── display.py            # KawaiiSpinner, tool preview formatting
│   ├── skill_commands.py     # Skill slash commands
│   ├── memory_manager.py    # Memory manager orchestration
│   ├── memory_provider.py   # Memory provider ABC
│   └── trajectory.py         # Trajectory saving helpers
│
├── hermes_cli/               # CLI subcommands and setup
│   ├── main.py               # Entry point — all `hermes` subcommands (large file)
│   ├── config.py             # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration
│   ├── commands.py           # COMMAND_REGISTRY — central slash command definitions
│   ├── auth.py               # PROVIDER_REGISTRY, credential resolution
│   ├── runtime_provider.py   # Provider → api_mode + credentials
│   ├── models.py             # Model catalog, provider model lists
│   ├── model_switch.py       # /model command logic (CLI + gateway shared)
│   ├── setup.py              # Interactive setup wizard (large file)
│   ├── skin_engine.py        # CLI theming engine
│   ├── skills_config.py      # hermes skills — enable/disable per platform
│   ├── skills_hub.py         # /skills slash command
│   ├── tools_config.py       # hermes tools — enable/disable per platform
│   ├── plugins.py            # PluginManager — discovery, loading, hooks
│   ├── callbacks.py          # Terminal callbacks (clarify, sudo, approval)
│   └── gateway.py            # hermes gateway start/stop
│
├── tools/                    # Tool implementations (one file per tool)
│   ├── registry.py           # Central tool registry
│   ├── approval.py           # Dangerous command detection
│   ├── terminal_tool.py      # Terminal orchestration
│   ├── process_registry.py   # Background process management
│   ├── file_tools.py         # read_file, write_file, patch, search_files
│   ├── web_tools.py          # web_search, web_extract
│   ├── browser_tool.py       # 10 browser automation tools
│   ├── code_execution_tool.py # execute_code sandbox
│   ├── delegate_tool.py      # Subagent delegation
│   ├── mcp_tool.py           # MCP client (large file)
│   ├── credential_files.py   # File-based credential passthrough
│   ├── env_passthrough.py    # Env var passthrough for sandboxes
│   ├── ansi_strip.py         # ANSI escape stripping
│   └── environments/         # Terminal backends (local, docker, ssh, modal, daytona, singularity)
│
├── gateway/                  # Messaging platform gateway
│   ├── run.py                # GatewayRunner — message dispatch (large file)
│   ├── session.py            # SessionStore — conversation persistence
│   ├── delivery.py           # Outbound message delivery
│   ├── pairing.py            # DM pairing authorization
│   ├── hooks.py              # Hook discovery and lifecycle events
│   ├── mirror.py             # Cross-session message mirroring
│   ├── status.py             # Token locks, profile-scoped process tracking
│   ├── builtin_hooks/        # Extension point for always-registered hooks (none shipped)
│   └── platforms/            # 20 adapters: 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 server (VS Code / Zed / JetBrains)
├── cron/                     # Scheduler (jobs.py, scheduler.py)
├── plugins/memory/           # Memory provider plugins
├── plugins/context_engine/   # Context engine plugins
├── environments/             # RL training environments (Atropos)
├── skills/                   # Bundled skills (always available)
├── optional-skills/          # Official optional skills (install explicitly)
├── website/                  # Docusaurus documentation site
└── tests/                    # Pytest suite (~3,000+ tests)

Поток данных

CLI-сессия

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

Сообщение шлюза

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Cron-задача

Scheduler tick → load due jobs from jobs.json
  → create fresh AIAgent (no history)
  → inject attached skills as context
  → run job prompt
  → deliver response to target platform
  → update job state and next_run

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

Цикл агента

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

→ Agent Loop Internals

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

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

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

→ Prompt Assembly, Context Compression & Prompt Caching

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

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

→ Provider Runtime Resolution

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

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

→ Tools Runtime

Персистентность сессий

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

→ Session Storage

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

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

→ Gateway Internals

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

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

→ Plugin Guide, Memory Provider Plugin

Cron

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

→ Cron Internals

Интеграция ACP

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

→ ACP Internals

RL / Окружения / Траектории

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

→ Environments, Benchmarks & Data Generation, Trajectories & Training Format

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

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

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

tools/registry.py  (no deps — imported by all tool files)
       ↑
tools/*.py  (each calls registry.register() at import time)
       ↑
model_tools.py  (imports tools/registry + triggers tool discovery)
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

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