🏠 Главная › developer guide › contributing

Вклад в проект

Спасибо, что решили внести вклад в агента Гермеса! Это руководство приводит к уменьшению окружения разработчика, понимания кодовой базы и процесса слияния вашего PR.

Приоритеты вклада

Мы ценим вклад в следующем порядке:

  1. Исправление ошибок — краши, некорректное поведение, потеря данных.
  2. Кросс-платформенная совместимость — macOS, различные дистрибутивы Linux, WSL2.
  3. Безопасность крепления — внедрение команд, внедрение промптов, обход пути.
  4. Производительность и надежность — логика повторных операций, обработка ошибок, плавная деградация.
  5. Новые навыки — широко полезны (см. Создание навыков)
  6. Новые инструменты — требуются редко; большинство возможностей должны быть навыками
  7. Документация — исправления, уточнения, новые образцы.

Типичные способы внесения вклада

Настройка окружения разработчика

Предварительные требования

Требование Примечания
Гит С поддержкой --recurse-submodules и установленными расширениями git-lfs
Питон 3.11+ уф установить его, если отсутствует
УФ Быстрый менеджер пакета Python (установка)
Node.js 20+ Опционально — требуется для инструментов браузера и моста WhatsApp (соответствует «engine» в корневом «package.json»)

Клонирование и установка

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Создание venv с Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Установка со всеми дополнительными пакетами (обмен сообщениями, cron, меню CLI, инструменты разработчика)
uv pip install -e ".[all,dev]"
# tinker-atropos является git submodule — сначала требуется `git submodule update --init`
# если вы клонировали без `--recurse-submodules`
uv pip install -e "./tinker-atropos"

# Опционально: инструменты браузера
npm install

Настройка для разработки

mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# Добавьте как минимум ключ LLM-провайдера:
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

Запуск

# Символическая ссылка для глобального доступа
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# Проверка
hermes doctor
hermes chat -q "Hello"

Запуск тестов

pytest tests/ -v

Стиль кода

Кросс-платформенная совместимость

Hermes официально поддерживает Linux, macOS, WSL2 и нативную Windows (ранняя бета-версия — установка через PowerShell). Нативный Windows использует Git Bash (из Git for Windows) для управления контролем. Некоторые функции требуют примитивов ядра POSIX и ограничены: встроенная панель терминала PTY в приборной панели (вкладка /chat) доступна только в WSL2. Путь нативного Windows нового и быстрого развития — если вы активно разрабатываете под Windows, ожидайте появления недоделанных мест и исправляйте их.

При внесении кода помните следующие правила:

Ключевые шаблоны:

1. termios и fcntl доступны только в Unix

Всегда перехватывайте и ImportError, и NotImplementedError:

try:
    from simple_term_menu import TerminalMenu
    menu = TerminalMenu(options)
    idx = menu.show()
except (ImportError, NotImplementedError):
    # Запасной вариант: нумерованное меню
    for i, opt in enumerate(options):
        print(f"  {i+1}. {opt}")
    idx = int(input("Выбор: ")) - 1

2. Кодировка файлов

Некоторые окружения могут сохранять файлы .env в кодировках, отличных от UTF-8:

try:
    load_dotenv(env_path)
except UnicodeDecodeError:
    load_dotenv(env_path, encoding="latin-1")

3. Управление процессами

os.setsid(), os.killpg() и обработка сигналов различаются на разных платформах:

import platform
if platform.system()!= "Windows":
    kwargs["preexec_fn"] = os.setsid

4. Разделители путей

Используйте pathlib.Path вместо строк конкатенации с /.

Вопросы безопасности

Гермес имеет доступ к терминалу. Безопасность важна.

Существующие механизмы защиты

Уровень Реализация
Передача пароля sudo Использует shlex.quote() для предотвращения повреждения команда
Обнаружение игрока Регулярные выражения в tools/approval.py с запросом подтверждения пользователя
Защита от промптов в cron Сканер блокирует шаблоны инструкции по переопределению
Список запрета записи Защищённые пути разрешаются через os.path.realpath() для предотвращения обхода симлинков
Навыки охраны Сканер безопасности для функций, настроенный из хаба
Песочница выполнения кода Дочерний процесс запускается с удаленными ключами API
Укрепление контейнера Docker: все возможности отключены, без изменения привилегий, ограничения PID

Внесение кода, чувствительного к безопасности

Процесс запроса на извлечение

Именование веток

fix/описание        # Исправление ошибок
feat/описание       # Новые функции
docs/описание       # Документация
test/описание       # Тесты
refactor/описание   # Реструктуризация кода

Перед отправкой

  1. Запустите тесты: pytesttests/ -v
  2. Протестируйте вручную: запустите hermes и проверьте изменённый код участка.
  3. Проверьте влияние на разных платформах: Учтите macOS и различные дистрибутивы Linux.
  4. Представлен сфокусированный на PR: Одно логическое изменение на PR.

Описание PR

Включите: - изменились и почему - Как тестировать это - На каких платформах вытестировали - Ссылки на сопутствующие вопросы

Сообщения коммитов

Мы используем Conventional Commits:

<тип>(<область>): <описание>
Тип Используется для
исправить Исправление ошибок
подвиг Новые функции
документы Документация
тест Тесты
рефакторинг Реструктуризация кода
работа Сборка, CI, обновление зависимостей

Области: cli, шлюз, инструменты, навыки, агент, установка, whatsapp, безопасность

Примеры:

fix(cli): предотвратить краш в save_config_value, когда model является строкой
feat(gateway): добавить изоляцию сессий для нескольких пользователей WhatsApp
fix(security): предотвратить внедрение команд в передаче пароля sudo

Сообщение о проблемах

Сообщество

Лицензия

Внося вклад, вы соглашаетесь, что ваш вклад будет соответствовать MIT License.