🏠 Главная › Документация › Руководство

Контрольные точки и `/rollback`

Hermes Agent может автоматически создавать снимки вашего проекта перед деструктивными операциями и восстанавливать их одной командой. Контрольные точки являются опциональными начиная с v2 — большинство пользователей никогда не используют /rollback, а хранилище теневых копий со временем занимает значительное место, поэтому по умолчанию эта функция отключена.

Включите контрольные точки для сессии с помощью --checkpoints:

hermes chat --checkpoints

Или включите глобально в ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Эта подстраховка работает на основе внутреннего Менеджера контрольных точек (Checkpoint Manager), который хранит единое общее теневое git-репозиторий в ~/.hermes/checkpoints/store/ — ваш реальный .git проекта никогда не затрагивается. Все проекты, с которыми работает агент, используют одно и то же хранилище, поэтому контентно-адресуемая объектная база данных git дедуплицирует данные между проектами и между шагами.

Что вызывает создание контрольной точки

Контрольные точки создаются автоматически перед:

Агент создаёт не более одной контрольной точки на директорию за шаг, чтобы длительные сессии не засоряли хранилище снимками.

Краткая справка

Слэш-команды внутри сессии:

Команда Описание
/rollback Показать все контрольные точки со статистикой изменений
/rollback <N> Восстановить контрольную точку N (также отменяет последний шаг чата)
/rollback diff <N> Показать diff между контрольной точкой N и текущим состоянием
/rollback <N> <file> Восстановить один файл из контрольной точки N

CLI для просмотра и управления хранилищем вне сессии:

Команда Описание
hermes checkpoints Показать общий размер, количество проектов, разбивку по проектам
hermes checkpoints status То же, что и просто checkpoints
hermes checkpoints list Псевдоним для status
hermes checkpoints prune Принудительная очистка: удалить осиротевшие/устаревшие записи, GC, применить лимит размера
hermes checkpoints clear Полностью удалить базу контрольных точек (с запросом подтверждения)
hermes checkpoints clear-legacy Удалить только архивы legacy-* от миграции с v1

Как работают контрольные точки

На высоком уровне:

flowchart LR
  user["User command\\n(hermes, gateway)"]
  agent["AIAgent\\n(run_agent.py)"]
  tools["File & terminal tools"]
  cpMgr["CheckpointManager"]
  store["Shared shadow store\\n~/.hermes/checkpoints/store/"]

  user --> agent
  agent -->|"tool call"| tools
  tools -->|"before mutate\\nensure_checkpoint()"| cpMgr
  cpMgr -->|"git add/commit-tree/update-ref"| store
  cpMgr -->|"OK / skipped"| tools
  tools -->|"apply changes"| agent

Конфигурация

Настройте в ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # главный переключатель (по умолчанию: false — опционально)
  max_snapshots: 20           # максимум контрольных точек на проект (применяется через перезапись ref + gc)
  max_total_size_mb: 500      # жёсткий лимит общего размера хранилища; самые старые коммиты удаляются
  max_file_size_mb: 10        # пропускать файлы больше этого размера

  # Автоматическое обслуживание (включено по умолчанию): очистка ~/.hermes/checkpoints/ при запуске
  # и удаление записей проектов, чья рабочая директория больше не существует
  # (осиротевшие) или чей last_touch старше retention_days. Выполняется не чаще
  # одного раза в min_interval_hours, отслеживается через маркер .last_prune.
  auto_prune: true
  retention_days: 7
  delete_orphans: true
  min_interval_hours: 24

Чтобы отключить всё:

checkpoints:
  enabled: false
  auto_prune: false

При enabled: false Менеджер контрольных точек ничего не делает и никогда не выполняет git-операции. При auto_prune: false хранилище растёт, пока вы вручную не выполните hermes checkpoints prune.

Просмотр контрольных точек

Из CLI-сессии:

/rollback

Hermes отвечает отформатированным списком со статистикой изменений:

📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  before write_file
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

  /rollback <N>             restore to checkpoint N
  /rollback diff <N>        preview changes since checkpoint N
  /rollback <N> <file>      restore a single file from checkpoint N

Просмотр хранилища из командной строки

hermes checkpoints

Пример вывода:

Checkpoint base: /home/you/.hermes/checkpoints
Total size:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Projects:        12

  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
  /home/you/code/hermes-agent                                        20       2h ago  live
  /home/you/code/experiments/rl-runner                                8       1d ago  live
  /home/you/code/old-prototype                                        3       9d ago  orphan
  ...

Legacy archives (1):
  legacy-20260506-050616                           4.2 MB

Clear with: hermes checkpoints clear-legacy

Принудительная полная очистка (игнорирует 24-часовой маркер идемпотентности):

hermes checkpoints prune --retention-days 3 --max-size-mb 200

Просмотр изменений с помощью /rollback diff

Перед выполнением восстановления просмотрите, что изменилось с момента создания контрольной точки:

/rollback diff 1

Это покажет сводку статистики git diff, а затем сам diff.

Восстановление с помощью /rollback

/rollback 1

Внутренний процесс Hermes:

  1. Проверяет, существует ли целевой коммит в теневом хранилище.

  2. Создаёт снимок перед откатом текущего состояния, чтобы вы могли «отменить отмену» позже.

  3. Восстанавливает отслеживаемые файлы в вашей рабочей директории.

  4. Отменяет последний шаг диалога, чтобы контекст агента соответствовал восстановленному состоянию файловой системы.

Восстановление одного файла

Восстановите только один файл из контрольной точки, не затрагивая остальную часть директории:

/rollback 1 src/broken_file.py

Защита безопасности и производительности

Где хранятся контрольные точки

~/.hermes/checkpoints/
  ├── store/                 # единое общее bare git-репозиторий
  │   ├── HEAD, objects/     # внутренности git (общие для всех проектов)
  │   ├── refs/hermes/<hash> # per-project указатель ветки
  │   ├── indexes/<hash>     # per-project git-индекс
  │   ├── projects/<hash>.json  # workdir + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # маркер идемпотентности автоочистки
  └── legacy-<ts>/           # архивированные per-project теневые репозитории до v2

Каждый <hash> вычисляется из абсолютного пути рабочей директории. Обычно вам никогда не нужно трогать их вручную — используйте hermes checkpoints status / prune / clear.

Миграция с v1

До переработки в v2 каждая рабочая директория имела собственное полное теневое git-репозиторий непосредственно в ~/.hermes/checkpoints/<hash>/. Такая структура не могла дедуплицировать объекты между проектами и имела документированно неработающий очиститель — хранилище росло без ограничений.

При первом запуске v2 все pre-v2 теневые репозитории перемещаются в ~/.hermes/checkpoints/legacy-<timestamp>/, чтобы новая единая структура хранилища начиналась чистой. Старая история /rollback всё ещё доступна для ручного просмотра через git в архиве legacy; когда вы убедитесь, что она больше не нужна, выполните:

hermes checkpoints clear-legacy

чтобы освободить место. Архивы legacy также удаляются при auto_prune после истечения retention_days.

Лучшие практики

О запуске нескольких агентов параллельно в одном репозитории читайте в руководстве по Git worktrees.