Переход на установку из исходников

Чекаут исходников и пакетное приложение — две разные установки. Собранное приложение продолжает работать на своей полезной нагрузке и лежащий рядом чекаут не подхватывает. Если нужно, чтобы графический интерфейс запускал изменённый код, соберите десктоп из исходников.

Пользовательские данные обычно хранятся отдельно от приложения:

Хост	Где данные по умолчанию
Linux, macOS, WSL, Termux	`~/.hermes/`
Нативный Windows	`%LOCALAPPDATA%\hermes\`
Официальный Docker-контейнер	`/opt/data/`, смонтирован в хранилище хоста

HERMES_HOME и выбранный профиль могут переопределить эти значения. Прежде чем менять установку, запишите, какие домашние каталоги на самом деле используются у старой установки и будут использоваться у новой.

1. Сделайте резервную копию и остановите старую среду

В существующей установке выполните:

hermes backup
hermes gateway status

Храните копию вне каталогов, которые собираетесь удалять. В резервной копии могут оказаться учётные данные, так что защищайте её соответственно.

Перед передачей закройте десктоп и остановите шлюзы и сервисы, которыми владеете. Выход из десктопа и hermes gateway stop — разные операции: закрытое приложение не обязательно останавливает шлюз сообщений, которым управляют отдельно.

Блокировка шлюза на уровне профиля не даёт запустить дубликат шлюза. Блокировки сессий и конкурентный доступ к SQLite — отдельная тема; запуск второго процесса сам по себе режим журнала SQLite не переключает. На время перехода не допускайте, чтобы код разных версий писал в один и тот же домашний каталог, пока любая из них выполняет миграции.

2. Склонируйте независимый чекаут

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

Для разработки склонируйте свой форк, а канонический репозиторий добавьте как upstream. Ветку или коммит выберите до подготовки зависимостей. Не клонируйте в подписанный пакет приложения и не перезаписывайте пакетную среду выполнения.

3. Подготовьте среду для исходников

Требования к нативной сборке и текущие ограничения бутстрапа описаны в разделе Рабочий процесс разработчика. До подготовки выберите нужный HERMES_HOME, затем выполните активацию — бутстрап она запускает сама:

source ./activate
hermes --version

В нативном Windows используйте PowerShell:

. .\activate.ps1
hermes --version

Бутстрап читает пины инструментов из pm/lock.json и передаёт установку PM. Текущий собственный код Hermes работает на Python 3.14. Более широкий диапазон >=3.11,<3.15 в метаданных пакета нужен лишь для того, чтобы старые установки могли запустить апдейтер, пока PM не переведёт их на 3.14; поддерживаемым диапазоном среды выполнения он не считается. По умолчанию для исходников выбирается extra all, а не --all-extras, как у десктопного бандла.

Активация собирает окружение установленных инструментов и определяет hermes как CLI этого worktree. Функция перекрывает старую команду hermes или псевдоним MSIX, а за пределами worktree отказывается работать. Когда закончите, deactivate вернёт окружение оболочки и уберёт функцию.

Тестовые зависимости и ручные окружения описаны в разделе про настройку окружения разработки. О выбранных поколениях Python и записываемом хранилище инструментов — на странице Управление пакетами.

4. Осознанно выберите данные

Для обычной работы на том же хосте укажите тот же HERMES_HOME и профиль, что и у прежней установки. Для разработки надёжнее отдельный домашний каталог: новый код может мигрировать сохранённые данные.

Пример для POSIX:

export HERMES_HOME="$HOME/hermes-source-data"
hermes setup
hermes

Пример для PowerShell:

$env:HERMES_HOME = Join-Path $HOME 'hermes-source-data'
hermes setup
hermes

Если вы сменили домашний каталог уже после подготовки состояния PM, запустите бутстрап для нового каталога, прежде чем полагаться на выбранные в нём зависимости. Смена переменной окружения не переносит данные и не копирует состояние среды выполнения.

Чтобы собрать десктоп из исходников, запустите hermes desktop в подготовленном чекауте. Старое пакетное приложение при открытии по-прежнему запускает свой пакетный бэкенд.

Пользователям Docker

/opt/data — путь внутри контейнера, и на хосте он не обязательно пригоден. Если используется bind mount, укажите каталог на стороне хоста как HERMES_HOME для процесса из исходников. Для именованного тома или хранилища в VM Docker Desktop сначала остановите старый шлюз. Затем экспортируйте и импортируйте резервную копию или скопируйте данные через контролируемое монтирование. Проверьте владельца и права доступа на месте назначения.

Локальный docker build -t hermes-agent . даёт ещё одну установку, которой управляет образ. Работающий контейнер от этого не превращается в самообновляемый чекаут исходников. Чтобы перейти на новый образ, пересоздайте контейнер. См. Docker.

Пользователям Nix и Termux

Локальный nix run . всё так же запускает деривацию, которой владеет Nix. Файлы её пакета остаются неизменяемыми, а обновлениями по-прежнему занимается Nix. Для оболочки разработки используйте nix develop, а там, где хост это поддерживает, — описанную выше процедуру для исходников.

Дистрибутив для Termux — это APT-пакет под bionic. Бутстрап исходников для десктопа и сервера для него не поддерживается ни как путь разработки, ни как способ восстановления. Границы пакета и сборки описаны в руководстве по Termux.

Возврат назад: откат версии не всегда безопасен

Остановите среду из исходников, выйдите из её активации и откройте пакетное приложение. Прежде чем снова вызывать hermes, проверьте, какая команда находится:

command -v hermes

В Windows для этого есть Get-Command hermes -All. Не подменяйте постороннюю команду или псевдоним выполнения, не выяснив, кому он принадлежит.

Более новая ревизия исходников может поменять формат данных. Возврат к старому пакету — не обратная миграция схемы. Сохраните текущие данные и, если старый пакет этого требует, восстановите совместимую резервную копию, сделанную до перехода.

Удаление чекаута исходников не удаляет пакетное приложение. Автоматически убрать все записи инструментов PM и поколения Python оно тоже не может. Вместо удаления общего корня данных пользуйтесь диагностикой и сборкой мусора PM.

Устранение неполадок

Не та версия: проверьте, какая команда находится, затем выполните hermes --version из активированного чекаута.
Не хватает зависимостей: запустите python -m pm.cli install из нужного окружения исходников, затем перезапустите затронутый процесс Hermes.
Шлюз уже запущен: посмотрите hermes gateway status для выбранного профиля. Остановите найденного владельца и не убивайте посторонние процессы.
После первого запуска изменились навыки: более новый код может синхронизировать встроенные навыки в домашний каталог данных. Чекаут исходников — не read-only-представление этого каталога.