🏠 Главная › Developer Guide › contributing

sidebar_position: 4 title: "Contributing" description: "How to contribute to Hermes Agent — dev setup, code style, PR process" lang: ru

Вклад

Благодарим вас за вклад в развитие Hermes Agent! В этом руководстве рассказывается о настройке среды разработки, понимании кодовой базы и объединении вашего PR.

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

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

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

Общие пути вклада

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

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

Требование Заметки
Гит С поддержкой --recurse-submodules и установленным расширением git-lfs
Питон 3.11+ uv установит его, если он отсутствует
УФ Менеджер пакетов Fast Python (install)
Node.js 20+ Необязательно — необходимо для инструментов браузера и моста WhatsApp (соответствует корневым движкам package.json)

Клонировать и установить

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

# Create venv with Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Install with all extras (messaging, cron, CLI menus, dev tools)
uv pip install -e ".[all,dev]"
uv pip install -e "./tinker-atropos"

# Optional: browser tools
npm install

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

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

# Add at minimum an LLM provider key:
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

Беги

# Symlink for global access
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# Verify
hermes doctor
hermes chat -q "Hello"

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

pytest tests/ -v

Стиль кода

Межплатформенная совместимость

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

1. termios и fcntl предназначены только для Unix.

Всегда ловите ImportError и NotImplementedError:

try:
    from simple_term_menu import TerminalMenu
    menu = TerminalMenu(options)
    idx = menu.show()
except (ImportError, NotImplementedError):
    # Fallback: numbered menu
    for i, opt in enumerate(options):
        print(f"  {i+1}. {opt}")
    idx = int(input("Choice: ")) - 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/description        # Bug fixes
feat/description       # New features
docs/description       # Documentation
test/description       # Tests
refactor/description   # Code restructuring

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

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

PR-описание

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

Сообщения о фиксации

Мы используем Обычные фиксации:

<type>(<scope>): <description>
Тип Использовать для
fix Исправления ошибок
feat Новые возможности
docs Документация
test Тесты
refactor Реструктуризация кода
chore Сборка, CI, обновления зависимостей

Области применения: cli, gateway, tools, skills, agent, install, whatsapp, security

Примеры:

fix(cli): prevent crash in save_config_value when model is a string
feat(gateway): add WhatsApp multi-user session isolation
fix(security): prevent shell injection in sudo password piping

Проблемы с отчетами

Сообщество

Лицензия

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