Перейти к содержанию

Contributing

На этой странице

Спасибо за ваш вклад в Hermes Agent! Это руководство охватывает настройку среды разработки, понимание кодовой базы и процесс принятия вашего PR.

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

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

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

Распространённые пути для вклада​

Настройка разработки​

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

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

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

[code] 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]"
uv pip install -e "./tinker-atropos"

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

[/code]

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

[code] 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

[/code]

Запуск​

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

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

[/code]

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

[code] pytest tests/ -v

[/code]

Стиль кода​

  • PEP 8 с практическими исключениями (нет строгого ограничения длины строк)
  • Комментарии: Только когда нужно объяснить неочевидные намерения, компромиссы или особенности API
  • Обработка ошибок: Перехватывайте конкретные исключения. Используйте logger.warning()/logger.error() с exc_info=True для неожиданных ошибок
  • Кроссплатформенность: Никогда не предполагайте Unix (см. ниже)
  • Пути, безопасные для профилей: Никогда не жёстко кодируйте ~/.hermes — используйте get_hermes_home() из hermes_constants для путей в коде и display_hermes_home() для сообщений пользователю. См. AGENTS.md для полных правил.

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

Hermes официально поддерживает Linux, macOS и WSL2. Нативная Windows не поддерживается, но кодовая база включает некоторые защитные паттерны для предотвращения жёстких падений в пограничных случаях. Ключевые правила:

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

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

[code] 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

[/code]

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

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

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

[/code]

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

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

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

[/code]

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

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

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

Hermes имеет доступ к терминалу. Безопасность имеет значение.

Существующие защиты​

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

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

  • Всегда используйте shlex.quote() при интерполяции пользовательского ввода в shell-команды
  • Разрешайте симлинки через os.path.realpath() перед проверками контроля доступа
  • Не логируйте секреты
  • Перехватывайте широкие исключения вокруг выполнения инструментов
  • Тестируйте на всех платформах, если ваше изменение затрагивает файловые пути или процессы

Процесс Pull Request​

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

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

[/code]

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

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

Описание PR​

Включите:

  • Что изменилось и почему
  • Как это тестировать
  • На каких платформах вы тестировали
  • Ссылки на связанные задачи (issues)

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

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

[code] <тип>(<область>): <описание>

[/code]

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

Области: cli, gateway, tools, skills, agent, install, whatsapp, security

Примеры:

[code] fix(cli): предотвращение падения в save_config_value когда модель является строкой feat(gateway): добавление изоляции многопользовательской сессии WhatsApp fix(security): предотвращение инъекции в shell при передаче sudo-пароля

[/code]

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

  • Используйте GitHub Issues
  • Укажите: ОС, версию Python, версию Hermes (hermes version), полный трейсбек ошибки
  • Укажите шаги для воспроизведения
  • Проверьте существующие задачи перед созданием дубликата
  • Для уязвимостей безопасности, пожалуйста, сообщайте приватно

Сообщество​

  • Discord: discord.gg/NousResearch
  • GitHub Discussions: Для предложений по дизайну и обсуждений архитектуры
  • Skills Hub: Загружайте специализированные скиллы и делитесь с сообществом

Лицензия​

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