Карта владения кодовой базой
Hermes — большой репозиторий, и почти любой вклад затрагивает ровно одну подсистему. На этой странице каждая подсистема сопоставлена с исходными каталогами и документом, с которого стоит начать перед внесением изменений. Используйте её, чтобы найти нужный стартовый документ, правильное место для изменения и каталог с тестами (тесты зеркалируют структуру исходников: код в tools/ тестируется в tests/tools/, плагины — в tests/plugins/<type>/, и так далее).
| Подсистема | Исходные каталоги | Точка входа в документацию |
|---|---|---|
| Ядро агента (цикл, транспорты, сжатие) | agent/, run_agent.py | Цикл агента, Сжатие и кэширование контекста |
| Сборка промпта | agent/prompt_builder.py, agent/system_prompt.py | Сборка промпта |
| Провайдеры моделей и транспорты | agent/transports/, plugins/model-providers/, hermes_cli/models.py | Добавление провайдеров, Плагины провайдеров моделей, Среда выполнения провайдера |
| Встроенные инструменты | tools/ | Добавление инструментов, Среда выполнения инструментов |
| Шлюз сообщений | gateway/, plugins/platforms/ | Внутреннее устройство шлюза, Добавление адаптеров платформ |
| CLI | hermes_cli/ | Расширение CLI |
| Система плагинов | plugins/ | Разработка плагина Hermes |
| Навыки (встроенные и опциональные) | skills/, optional-skills/ | Создание навыков |
| Cron / отложенные задачи | cron/ | Внутреннее устройство cron |
| Хранилище сессий | hermes_state.py, hermes_state_*.py | Хранилище сессий |
| Стек браузера | tools/browser_tool.py, tools/browser_supervisor.py, tools/browser_cdp_tool.py | Browser Supervisor |
| Egress-файрвол | agent/proxy_sources/iron_proxy.py | Внутреннее устройство egress |
| ACP (интеграция с IDE) | acp_adapter/ | Внутреннее устройство ACP |
| Десктопное приложение | apps/desktop/ | SDK плагинов десктопа, Разработка UI для worktree |
| TUI | ui-tui/, tui_gateway/ | Разработка UI для worktree |
| Сайт документации | website/ | Как внести вклад |
| Тесты | tests/, tests-js/ | Как внести вклад → Перед отправкой |
Из этой карты вытекает несколько правил:
- Изменения должны оставаться внутри своей подсистемы. Если плагину нужно править файлы ядра — это признак неудачного дизайна: вместо этого расширьте общий интерфейс плагинов (см. критерии приёма вклада в
AGENTS.mdрепозитория). - Для каждого изменённого каталога исходников запускайте зеркальный каталог тестов. Изменение в
plugins/platforms/telegram/требует зелёногоtests/plugins/platforms/, а не только того тестового файла, который пришёл на ум в первую очередь. - Когда затронуты две подсистемы, изменение принадлежит более узкой. Правку лучше сделать в адаптере или плагине, чем в ядре агента: ядро — это узкое горлышко, и за каждое добавление в нём приходится платить при каждом обращении к API.