Плагины

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

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

→ Build a Hermes Plugin — пошаговое руководство с полным рабочим примером.

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

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

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # manifest
├── __init__.py      # register() — wires schemas to handlers
├── schemas.py       # tool schemas (what the LLM sees)
└── tools.py         # tool handlers (what runs when called)

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

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

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

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

name: hello-world
version: "1.0"
description: A minimal example plugin

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

"""Minimal Hermes plugin — registers a tool and a hook."""

import json


def register(ctx):
    # --- Tool: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet",
                }
            },
            "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="Return a friendly greeting for the given name.",
    )

    # --- Hook: log every tool call ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

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

Локальные плагины проекта в ./.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(). Поместите каталог, и он заменит встроенный без каких-либо изменений в репозитории.

Плагины подключаются добровольно (с некоторыми исключениями)

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

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # optional deny-list — always wins if a name appears in both
    - noisy-plugin

Три способа изменить состояние:

hermes plugins                    # interactive toggle (space to check/uncheck)
hermes plugins enable <name>      # add to allow-list
hermes plugins disable <name>     # remove from allow-list + add to disabled

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

Что не контролирует список разрешений

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

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

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

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

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

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

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

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

Memory providers и Context engines — это provider-плагины — только один каждого типа может быть активен одновременно. Model providers также являются плагинами, но загружаются одновременно; пользователь выбирает один из них через --provider или config.yaml. Обычные плагины можно включать в любой комбинации.

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

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

Декларативные плагины NixOS

На NixOS плагины можно установить декларативно через опции модуля — без hermes plugins install. Подробности см. в Nix Setup guide.

services.hermes-agent = {
  # Directory plugin (source tree with plugin.yaml)
  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
  # Entry-point plugin (pip package)
  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
  # Enable in config
  settings.plugins.enabled = [ "my-plugin" ];
};

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

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

hermes plugins                               # unified interactive UI
hermes plugins list                          # table: enabled / disabled / not enabled
hermes plugins install user/repo             # install from Git, then prompt Enable? [y/N]
hermes plugins install user/repo --enable    # install AND enable (no prompt)
hermes plugins install user/repo --no-enable # install but leave disabled (no prompt)
hermes plugins update my-plugin              # pull latest
hermes plugins remove my-plugin              # uninstall
hermes plugins enable my-plugin              # add to allow-list
hermes plugins disable my-plugin             # remove from allow-list + add to disabled

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

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

Plugins
  ↑↓ navigate  SPACE toggle  ENTER configure/confirm  ESC done

  General Plugins
 → [✓] my-tool-plugin — Custom search tool
   [ ] webhook-notifier — Event hooks
   [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]

  Provider Plugins
     Memory Provider          ▸ honcho
     Context Engine           ▸ compressor

• Раздел General Plugins — флажки, переключение пробелом. Отмечено = в plugins.enabled, не отмечено = в plugins.disabled (явное отключение).

• Раздел Provider Plugins — показывает текущий выбор. Нажмите ENTER, чтобы войти в переключатель, где вы выбираете одного активного провайдера.

• Встроенные плагины отображаются в том же списке с пометкой [bundled].

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

memory:
  provider: "honcho"      # empty string = built-in only

context:
  engine: "compressor"    # default built-in compressor

Включено, отключено или не выбрано

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

По умолчанию для нового или встроенного плагина — not enabled. hermes plugins list показывает все три различных состояния, чтобы вы могли видеть, что было явно отключено, а что просто ожидает включения.

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

Внедрение сообщений

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

ctx.inject_message("New data arrived from the webhook", role="user")

Signature: ctx.inject_message(content: str, role: str = "user") -> bool

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

• Если агент бездействует (ожидает ввода пользователя), сообщение помещается в очередь как следующий ввод и начинает новый ход.

• Если агент в процессе хода (активно работает), сообщение прерывает текущую операцию — так же, как если бы пользователь ввёл новое сообщение и нажал Enter.

• Для ролей, отличных от "user", содержимое дополняется префиксом [role] (например, [system] ...).

• Возвращает True, если сообщение было успешно поставлено в очередь, и False, если нет доступной CLI-ссылки (например, в gateway-режиме).

Это позволяет таким плагинам, как пульты дистанционного управления, мосты обмена сообщениями или приёмники webhook, передавать сообщения в беседу из внешних источников.

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