Плагины

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

Если вы хотите создать пользовательский инструмент для себя, своей команды или одного проекта, обычно это правильный путь. Страница руководства разработчика Добавление инструментов созданы для встроенных основных инструментов Hermes, который находится в tools/ и toolsets.py.

→ Создайте плагин Hermes — пошаговое руководство с полной версией сборки.

Краткий обзор

Поместите каталог в ~/.hermes/plugins/ с plugin.yaml и кодом Python:

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # манифест
├── __init__.py      # register() — связывает схемы с обработчиками
├── schemas.py       # схемы инструментов (что видит LLM)
└── tools.py         # обработчики инструментов (что выполняется при вызове)

Запустите Гермес — ваши инструменты появятся рядом с блоками. Модель может немедленно изменить их.

Минимальный рабочий пример

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

~/.hermes/plugins/hello-world/plugin.yaml

name: hello-world
version: "1.0"
description: Пример минимального плагина

~/.hermes/plugins/hello-world/__init__.py

"""Минимальный плагин Hermes — регистрирует инструмент и хук."""

import json


def register(ctx):
    # --- Инструмент: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Возвращает дружеское приветствие для указанного имени.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Имя для приветствия",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
        description="Возвращает дружеское приветствие для указанного имени.",
    )

    # --- Хук: регистрировать каждый вызов инструмента ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] вызван инструмент: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

Поместите оба файла в ~/.hermes/plugins/hello-world/, перезапустите Hermes, и модель сможет немедленно вызывать hello_world. Хук выводит строку лога после каждого вызова инструмента.

Локальные плагины проекта в ./.hermes/plugins/ по умолчанию отключены. Включайте их только для доверенных репозиториев, установив HERMES_ENABLE_PROJECT_PLUGINS=true перед запуском Hermes.

Что могут делать плагины

Каждый API ctx.* ниже доступен внутри функции register(ctx) плагина.

Обнаружение плагинов

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

Подкатегории плагинов

Внутри каждого источника Hermes также распознаёт подкатегории каталогов, которые направляют плагины в специализированные системы обнаружения:

Пользовательские плагины в ~/.hermes/plugins/model-providers/<name>/ и ~/.hermes/plugins/memory/<name>/ переопределяют встроенные плагины с тем же именем — последний записавший побеждает в register_provider() / register_memory_provider(). Поместите каталог, и он заменит встроенный без каких-либо изменений в репозитории.

Плагины — opt-in (с несколькими исключениями)

Общие плагины и установленные пользователем бэкенды по умолчанию отключены — обнаружение находит их (поэтому они отображаются в hermes plugins и /plugins), но ничего с хуками или инструментами не загружается, пока вы не добавите имя плагина в plugins.enabled в ~/.hermes/config.yaml. Это предотвращает выполнение стороннего кода без вашего явного согласия.

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # необязательный список запрета — всегда побеждает, если имя появляется в обоих
    - noisy-plugin

Состояние три выхода изменить:

hermes plugins                    # интерактивное переключение (пробел для отметки/снятия)
hermes plugins enable <name>      # добавить в белый список
hermes plugins disable <name>     # удалить из белого списка + добавить в отключённые

После hermes plugins install owner/repo выводится запрос Включить 'name' сейчас? [y/N] — по умолчанию нет. Пропустите запрос для скриптовых установок с помощью --enable или --no-enable.

Что НЕ блокирует белый список

Несколько категорий плагинов обходят plugins.enabled — они являются частью встроенной поверхности Hermes и сломали бы базовую функциональность, если бы были отключены по умолчанию:

Кратко: встроенная инфраструктура «всегда работает» загружается автоматически; сторонние общие плагины — opt-in. Белый список plugins.enabled является шлюзом специально для произвольного кода, который пользователь помещает в ~/.hermes/plugins/.

Миграция для существующих пользователей

Когда вы обновляетесь до версии Hermes с opt-in плагинами (схема конфига v21+), любые пользовательские плагины, уже установленные в ~/.hermes/plugins/, которые не были в plugins.disabled, автоматически наследуются в plugins.enabled. Ваша существующая настройка продолжает работать. Встроенные автономные плагины НЕ наследуются — даже существующие пользователи должны явно включить их. (Встроенные плагины платформ/бэкендов никогда не нуждались в наследовании, потому что они никогда не были заблокированы.)

Доступные хуки

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

Типы плагинов

Hermes имеет четыре вида плагинов:

Провайдеры памяти и контекстные движки являются провайдерскими плагинами — только один каждого типа может быть активен одновременно. Провайдеры моделей также являются плагинами, но многие загружаются одновременно; пользователь выбирает один за раз через --provider или config.yaml. Общие плагины могут быть включены в любой комбинации.

Подключаемые интерфейсы — куда обращаться для каждого

Таблица выше показывает четыре категории плагинов, но внутри «Общих плагинов» PluginContext предоставляет несколько различных точек расширения — и Hermes также принимает расширения вне системы Python-плагинов (конфигурационные бэкенды, команды, подключённые через оболочку, внешние серверы и т.д.). Используйте эту таблицу, чтобы найти правильную документацию для того, что вы хотите создать:

На NixOS плагины могут быть установлены декларативно через опции модуля — без необходимости hermes plugins install. См. Руководство по установке Nix для получения полной информации.

services.hermes-agent = {
  # Плагин-каталог (дерево исходников с plugin.yaml)
  extraPlugins = [ (pkgs.fetchFromGitHub {... }) ];
  # Плагин entry-point (pip-пакет)
  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage {... }) ];
  # Включить в конфиге
  settings.plugins.enabled = [ "my-plugin" ];
};

Декларативные плагины связывают символические ссылки с префиксом nix-managed- — они сосуществуют с плагинами, установленными вручную, и автоматически удаляются при удалении из конфигурации Nix.

Управление плагинами

hermes plugins                               # единый интерактивный интерфейс
hermes plugins list                          # таблица: включено / отключено / не включено
hermes plugins install user/repo             # установить из Git, затем запрос Включить? [y/N]
hermes plugins install user/repo --enable    # установить И включить (без запроса)
hermes plugins install user/repo --no-enable # установить, но оставить отключённым (без запроса)
hermes plugins update my-plugin              # получить последнюю версию
hermes plugins remove my-plugin              # удалить
hermes plugins enable my-plugin              # добавить в белый список
hermes plugins disable my-plugin             # удалить из белого списка + добавить в отключённые

Интерактивный интерфейс

Запуск hermes плагинов без аргументов создаёт составной интерактивный экран:

Плагины
  ↑↓ навигация  ПРОБЕЛ переключить  ВВОД настроить/подтвердить  ESC готово

  Общие плагины
 → [✓] my-tool-plugin — Пользовательский инструмент поиска
   [ ] webhook-notifier — Событийные хуки
   [ ] disk-cleanup — Автоматическая очистка временных файлов [встроенный]

  Плагины провайдеров
     Провайдер памяти          ▸ honcho
     Контекстный движок        ▸ compressor

• Раздел встроенных плагинов — флажки, переключение пробела. Отмечено = в plugins.enabled, не отмечено = в plugins.disabled (явное выключение).
• Раздел плагинов провайдеров — показывает данный выбор. Нажмите ВВОД, чтобы перейти к радиокнопкам, где вы выбираете одного активного провайдера.
• Встроенные плагины приводятся в том же списке с тегом [встроенный].

Выбор плагинов провайдеров сохраняется в config.yaml:

memory:
  provider: "honcho"      # пустая строка = только встроенный

context:
  engine: "compressor"    # встроенный компрессор по умолчанию

Включено vs отключено vs ни то, ничего другого

Плагины находятся в одном из трёх состояний:

По умолчанию для нового установленного или встроенного плагина — «не включено». Список плагинов Гермеса показывает все три различных состояния, чтобы вы могли видеть, что было явно выключено, а что просто ожидает включения.

В запущенной сессии /plugins показаны какие плагины в данный момент загружены.

Вставка сообщений

Плагины могут отправлять сообщения в активный разговор с помощью ctx.inject_message():

ctx.inject_message("Новые данные поступили от вебхука", role="user")

Сигнатура: ctx.inject_message(content: str, role: str = "user") -> bool

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

• Если агент без стула (ожидает ввода пользователя), сообщение вставляется по очереди, как вводится ввод и начинается новый шаг.
• Если агент в середине шага (активно работает), сообщение прерывает текущую операцию — так же, как если бы пользователь ввёл новое сообщение и нажал Enter.
• Для ролей, отличных от "user", правилом предваряется [role] (например, [system]...).
• Возвращает True, если сообщение было успешно решено, в свою очередь, False, если нет доступных ссылок в CLI (например, в режиме шлюза).

Это позволяет подключать такие устройства, как пульт удаленного управления, мосты обмена сообщениями или приемники вебхуков, передавать сообщения в разговор из внешних источников.:::примечание inject_message доступен только в режиме CLI. В режиме шлюза нет ссылок на CLI, и метод возвращает False.