Код и хуки

· 4 мин чтения · admin

Код и хуки

Hermes Agent предоставляет два механизма автоматизации: выполнение кода (execute_code) и событийные хуки (event hooks). Вместе они позволяют программно управлять рабочими процессами и вмешиваться в жизненный цикл агента.

Выполнение кода: execute_code

Инструмент execute_code запускает Python-скрипт в изолированном окружении с доступом ко всем инструментам Hermes через RPC. Это позволяет объединять множество шагов в одну программу вместо последовательных вызовов.

Python RPC

Внутри скрипта доступен модуль hermes_tools с RPC-прокси: terminal(), read_file(), web_search() и другие. Вызовы сериализуются в JSON, передаются через Unix-сокет и возвращают результат — поведение идентично обычным вызовам инструментов.

Режимы и ограничения

  • project — скрипт в рабочей директории сессии с активным venv
  • strict — изолированная временная директория с фиксированным интерпретатором

Лимиты: таймаут 300 секунд, stdout до 50 КБ, до 50 вызовов инструментов. Переменные окружения с KEY, TOKEN, SECRET и PASSWORD в имени автоматически вырезаются.

Событийные хуки

Хуки запускают код (Python-плагины или shell-скрипты) в ключевых точках жизненного цикла агента для логирования, аудита и блокировки опасных операций.

Жизненный цикл

  • on_session_start / on_session_end — начало и конец сессии
  • pre_llm_call / post_llm_call — до и после вызова LLM
  • pre_tool_call / post_tool_call — до и после вызова инструмента
  • subagent_stop — завершение подагента
  • transform_tool_result — модификация результата

Типы хуков

Python-плагины в ~/.hermes/hooks/ выполняются в процессе Hermes с доступом к его структурам. Shell-хуки настраиваются в config.yaml: получают JSON через stdin и возвращают {} для разрешения или {"decision": "block"} для блокировки.

Безопасность

Первое срабатывание требует подтверждения пользователя. Решения сохраняются в shell-hooks-allowlist.json. Для CI доступны --accept-hooks и hooks_auto_accept: true. Python-плагины имеют приоритет над shell-хуками, первый блокирующий ответ прерывает цепочку.

Добавление инструмента

Добавление нового инструмента в Hermes затрагивает 3 файла:

1. Создать tools/your_tool.py

import json, os
from tools.registry import registry

def check_requirements() -> bool:
    return bool(os.getenv("EXAMPLE_API_KEY"))

def example_tool(param: str, task_id: str = None) -> str:
    return json.dumps({"success": True, "data": "..."})

registry.register(
    name="example_tool",
    toolset="example",
    schema={"name": "example_tool", "description": "...", "parameters": {...}},
    handler=lambda args, **kw: example_tool(
        param=args.get("param", ""), task_id=kw.get("task_id")),
    check_fn=check_requirements,
    requires_env=["EXAMPLE_API_KEY"],
)

2. Добавить в toolsets.py

Добавить toolset в список _HERMES_CORE_TOOLS.

Auto-discovery

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

Важные правила для инструментов

  • Все handlers должны возвращать JSON-строки — не словари, не объекты, а именно json.dumps(...)
  • Используйте get_hermes_home() из hermes_constants для всех путей. Никогда не хардкодьте ~/.hermes
  • check_fn — функция проверки доступности. Инструмент появляется в списке только когда check_fn() возвращает True
  • requires_env — список переменных окружения, необходимых для работы инструмента

Добавление slash-команды

Slash-команда добавляется в два шага:

  1. CommandDef в COMMAND_REGISTRY — файл hermes_cli/commands.py. Определение команды с именем, описанием и параметрами
  2. Handler в cli.py — функция process_command() обрабатывает вызов команды
  3. (Опционально) Gateway handler в gateway/run.py — для поддержки команды в мессенджерах

Все потребители (текст помощи, автодополнение, Telegram-меню, Slack-маппинг) автоматически берут данные из центрального реестра.

Commit Conventions

Формат коммитов в проекте:

type: concise subject line

Optional body.

Допустимые типы:

  • fix: — исправление бага
  • feat: — новая функциональность
  • refactor: — рефакторинг без изменения поведения
  • docs: — изменения документации
  • chore: — обслуживающие задачи (зависимости, CI, конфигурация)

Key Rules

Критические правила, которые нельзя нарушать:

  • Никогда не ломайте prompt caching — не меняйте контекст, инструменты или системный промпт в середине сессии. Изменения toolset применяются только после /reset
  • Чередование ролей сообщений — никогда не должно быть двух сообщений assistant или двух сообщений user подряд
  • get_hermes_home() — используйте для всех путей (profile-safe). Не хардкодьте ~/.hermes
  • Конфигурация — настройки в config.yaml, секреты в .env
  • Новые инструменты — обязаны иметь check_fn, чтобы появляться только при выполнении требований