🏠 Главная › User Guide › checkpoints and rollback

sidebar_position: 8 sidebar_label: "Checkpoints & Rollback" title: "Checkpoints and /rollback" description: "Filesystem safety nets for destructive operations using shadow git repos and automatic snapshots" lang: ru

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

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

Эта система безопасности поддерживается внутренним Checkpoint Manager, который хранит отдельный теневой репозиторий git под ~/.hermes/checkpoints/ — ваш реальный проект .git никогда не будет затронут.

Что вызывает контрольную точку

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

Агент создает не более одной контрольной точки для каждого каталога за ход, поэтому длительные сеансы не рассылают спам-снимки.

Краткий справочник

| Команда | Описание | | lang: ru

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

Как работают контрольно-пропускные пункты

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

flowchart LR
  user["User command\n(hermes, gateway)"]
  agent["AIAgent\n(run_agent.py)"]
  tools["File & terminal tools"]
  cpMgr["CheckpointManager"]
  shadowRepo["Shadow git repo\n~/.hermes/checkpoints/<hash>"]

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

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

Контрольные точки включены по умолчанию. Настройте в ~/.hermes/config.yaml:

checkpoints:
  enabled: true          # master switch (default: true)
  max_snapshots: 50      # max checkpoints per directory

  # Auto-maintenance (opt-in): sweep ~/.hermes/checkpoints/ at startup
  # and delete shadow repos whose working directory no longer exists
  # (orphans) or whose newest commit is older than retention_days.
  # Runs at most once per min_interval_hours, tracked via a
  # .last_prune marker inside ~/.hermes/checkpoints/.
  auto_prune: false           # default off — enable to reclaim disk
  retention_days: 7
  delete_orphans: true        # delete repos whose workdir is gone
  min_interval_hours: 24

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

checkpoints:
  enabled: false

Если этот параметр отключен, диспетчер контрольных точек не работает и никогда не пытается выполнить операции git.

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

Из сеанса 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

Каждая запись показывает:

Предварительный просмотр изменений с помощью /rollback diff

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

/rollback diff 1

Это показывает сводку статистики git diff, за которой следует фактическая разница:

test.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test.py b/test.py
--- a/test.py
+++ b/test.py
@@ -1 +1 @@
-print('original content')
+print('modified content')

Длинные различия ограничены 80 строками, чтобы избежать переполнения терминала.

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

Восстановление на КПП по номеру:

/rollback 1

За кулисами Гермес:

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

Об успехе:

✅ Restored to checkpoint 4270a8c5: before patch
A pre-rollback snapshot was saved automatically.
(^_^)b Undid 4 message(s). Removed: "Now update test.py to ..."
  4 message(s) remaining in history.
  Chat turn undone to match restored file state.

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

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

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

/rollback 1 src/broken_file.py

Это полезно, когда агент внес изменения в несколько файлов, но нужно отменить только один.

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

Чтобы обеспечить безопасность и скорость прохождения контрольно-пропускных пунктов, Hermes применяет несколько ограждений:

Где живут контрольно-пропускные пункты

Все теневые репозитории находятся под:

~/.hermes/checkpoints/
  ├── <hash1>/   # shadow git repo for one working directory
  ├── <hash2>/
  └── ...

Каждый <hash> получается из абсолютного пути к рабочему каталогу. Внутри каждого теневого репозитория вы найдете:

Обычно вам никогда не придется прикасаться к ним вручную.

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

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