🏠 Главная › user guide › checkpoints and rollback

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

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

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

hermes chat --checkpoints

Или глобально в ~/.hermes/config.yaml:

checkpoints:
  enabled: true

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

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

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

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

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

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

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

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

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

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

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

flowchart LR
  user["Команда пользователя\n(hermes, gateway)"]
  agent["AIAgent\n(run_agent.py)"]
  tools["Файловые и терминальные инструменты"]
  cpMgr["CheckpointManager"]
  store["Общее теневое хранилище\n~/.hermes/checkpoints/store/"]

  user --> agent
  agent -->|"вызов инструмента"| tools
  tools -->|"перед изменением\nensure_checkpoint()"| cpMgr
  cpMgr -->|"git add/commit-tree/update-ref"| store
  cpMgr -->|"OK / пропущено"| tools
  tools -->|"применить изменения"| agent

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

Настраиваем в ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # основной переключатель (по умолчанию: false — опционально)
  max_snapshots: 20           # максимальное количество контрольных точек на проект (применяется через перезапись ссылки и сборку мусора)
  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

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

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

Из сессии CLI:

/rollback

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

📸 Контрольные точки для /path/to/project:

  1. 4270a8c  2026-03-16 04:36  перед patch  (1 файл, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  перед write_file
  3. b3f9d2e  2026-03-16 04:34  перед терминалом: sed -i s/old/new/ config.py  (1 файл, +1/-1)

  /rollback <N>             восстановить контрольную точку N
  /rollback diff <N>        предпросмотр изменений с момента контрольной точки N
  /rollback <N> <файл>      восстановить один файл из контрольной точки N

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

hermes checkpoints

Пример результата:

База контрольных точек: /home/you/.hermes/checkpoints
Общий размер:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Проекты:        12

  РАБОЧАЯ ДИРЕКТОРИЯ                                           КОММИТЫ    ПОСЛЕДНЕЕ КАСАНИЕ  СОСТОЯНИЕ
  /home/you/code/hermes-agent                                        20       2ч назад  активен
  /home/you/code/experiments/rl-runner                                8       1д назад  активен
  /home/you/code/old-prototype                                        3       9д назад  осиротел...

Архивы legacy (1):
  legacy-20260506-050616                           4.2 MB

Очистить с помощью: 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

Под капотом Гермес:

  1. Проверяет, существует ли встроенный коммит в теневом хранилище.
  2. Создает предварительный откатный снимок текущего состояния, чтобы вы могли позже «отменить отмену».
  3. Восстанавливает отслеживаемые файлы в вашем рабочем каталоге.
  4. Отменяет последний виток разговора, чтобы имя контекстного агента восстановило состояние файловой системы.

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

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

/rollback 1 src/broken_file.py

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

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

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

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

Миграция с v1

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

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

hermes checkpoints clear-legacy

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

Рекомендации

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