Điểm kiểm tra và

/rollback ``Đại lý Hermes có thể tự động chụp nhanh dự án của bạn trước các hoạt động phá hủy và khôi phục nó bằng một lệnh duy nhất. Các điểm kiểm tra được chọn tham gia kể từ phiên bản 2 — hầu hết người dùng không bao giờ sử dụng

/rollback ` và bộ lưu trữ trong cửa hàng ẩn không còn tầm thường theo thời gian nên mặc định sẽ tắt.

Kích hoạt điểm kiểm tra mỗi phiên với

--checkpoints

:

Hermes chat --checkpoints

`
``Hoặc kích hoạt toàn cầu trong 

~/.Hermes/config.yaml

:

`YAML
checkpoints:
  enabled: true

`
``Mạng lưới an toàn này được cung cấp bởi **Trình quản lý điểm kiểm tra** nội bộ, giữ một kho lưu trữ bóng git được chia sẻ duy nhất trong 

~/.Hermes/checkpoints/store/

 - dự án thực sự của bạn 

.git
` không bao giờ được chạm vào. Mọi dự án mà tác nhân làm việc đều chia sẻ cùng một cửa hàng, do đó, DB đối tượng có thể định địa chỉ nội dung của git sẽ loại bỏ trùng lặp giữa các dự án và giữa các lượt.

## Điều gì kích hoạt điểm kiểm tra

Điểm kiểm tra được thực hiện tự động trước:
- **Công cụ tệp** — 
`write_file
` và 
`patch

`
- **Lệnh đầu cuối phá hủy** — 
`rm

, 
`rmdir

, 
`cp

, 
`install

, 
`mv

, 
`sed -i

, 
`truncate

, 
`dd

, 
`shred

, chuyển hướng đầu ra (

>

) và 
`git reset

/
`clean

/
`checkout
``Tác nhân tạo **tối đa một điểm kiểm tra cho mỗi thư mục trong mỗi lượt**, do đó, các phiên chạy kéo dài sẽ không gửi ảnh chụp nhanh spam.

## Tham khảo nhanh

Lệnh gạch chéo trong phiên:

| Lệnh | Mô tả |
|----------|-------------|
| 

/rollback
` | Liệt kê tất cả các điểm kiểm tra với số liệu thống kê thay đổi |
| 

/rollback <N>
` | Khôi phục về điểm kiểm tra N (đồng thời hoàn tác lượt trò chuyện cuối cùng) |
| 

/rollback diff <N>
` | Xem trước sự khác biệt giữa điểm kiểm tra N và trạng thái hiện tại |
| 

/rollback <N> <file>
` | Khôi phục một tệp từ điểm kiểm tra N |

CLI để kiểm tra và quản lý cửa hàng ngoài phiên:

| Lệnh | Mô tả |
|----------|-------------|
| 
`Hermes checkpoints
` | Hiển thị tổng quy mô, số lượng dự án, phân tích từng dự án |
| 
`Hermes checkpoints status
` | Tương tự như 
`checkpoints
` trần |
| 
`Hermes checkpoints list
` | Bí danh cho 
`status
` |
| 
`Hermes checkpoints prune
` | Buộc quét: xóa trẻ mồ côi/cũ, GC, thực thi giới hạn kích thước |
| 
`Hermes checkpoints clear
` | Nuke toàn bộ căn cứ trạm kiểm soát (yêu cầu trước) |
| 
`Hermes checkpoints clear-legacy
` | Chỉ xóa các kho lưu trữ 
`legacy-*
` khỏi quá trình di chuyển v1 |

## Cách hoạt động của điểm kiểm tra

Ở mức độ cao:
- Hermes phát hiện khi nào các công cụ sắp **sửa đổi tệp** trong cây làm việc của bạn.
- Một lần cho mỗi lượt hội thoại (mỗi thư mục), nó:
  - Giải quyết một dự án gốc hợp lý cho tập tin.
  - Khởi tạo hoặc sử dụng lại **kho bóng chia sẻ duy nhất** tại 

~/.Hermes/checkpoints/store/

.
  - Các giai đoạn thành chỉ mục cho mỗi dự án, xây dựng cây và cam kết tham chiếu cho mỗi dự án (
`refs/Hermes/<project-hash

).
- Các giới thiệu cho mỗi dự án này tạo thành lịch sử điểm kiểm tra mà bạn có thể kiểm tra và khôi phục thông qua 

/rollback

.

`mermaid
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

`

## Cấu hình

Cấu hình trong 

~/.Hermes/config.yaml

:

``` yaml
checkpoints:
  enabled: false              # master switch (default: false — opt-in)
  max_snapshots: 20           # max checkpoints per project (enforced via ref rewrite + gc)
  max_total_size_mb: 500      # hard cap on total store size; oldest commits dropped
  max_file_size_mb: 10        # skip any single file larger than this

# Auto-maintenance (on by default): sweep ~/.Hermes/checkpoints/ at startup

  # and delete project entries whose working directory no longer exists
  # (orphans) or whose last_touch is older than retention_days. Runs at most
  # once per min_interval_hours, tracked via a .last_prune marker.
  auto_prune: true
  retention_days: 7
  delete_orphans: true
  min_interval_hours: 24

`
``Để vô hiệu hóa mọi thứ:

``` yaml
checkpoints:
  enabled: false
  auto_prune: false

`
``Khi 
`enabled: false

, Trình quản lý điểm kiểm tra không hoạt động và không bao giờ thử các thao tác git. Khi 
`auto_prune: false

, cửa hàng sẽ tăng lên cho đến khi bạn chạy 
`Hermes checkpoints prune
` theo cách thủ công.

## Điểm kiểm tra danh sách

Từ phiên CLI:

`
/rollback

`
``Hermes phản hồi bằng một danh sách được định dạng hiển thị số liệu thống kê thay đổi:

`text
📸 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

`

## Kiểm tra Store từ Shell

``` bash
Hermes checkpoints

`
``Đầu ra mẫu:

`text
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

`
``Buộc quét toàn bộ (bỏ qua điểm đánh dấu tạm thời 24h):

`bash
Hermes checkpoints prune --retention-days 3 --max-size-mb 200

`

## Xem trước các thay đổi với 

/rollback diff
``Trước khi cam kết khôi phục, hãy xem trước những gì đã thay đổi kể từ điểm kiểm tra:

`
/rollback diff 1

`
``Điều này hiển thị tóm tắt chỉ số git diff theo sau là khác biệt thực tế.

## Khôi phục bằng 

/rollback

`

/rollback 1

`
``Đằng sau hậu trường, Hermes:
1. Xác minh cam kết mục tiêu tồn tại trong kho lưu trữ bóng tối.

2. Chụp **ảnh chụp nhanh trước khi quay lại** trạng thái hiện tại để bạn có thể "hoàn tác" sau này.
3. Khôi phục các tập tin được theo dõi trong thư mục làm việc của bạn.
4. **Hoàn tác lượt hội thoại cuối cùng** để bối cảnh của tác nhân khớp với trạng thái hệ thống tệp được khôi phục.

## Khôi phục một tệp

Chỉ khôi phục một tệp từ điểm kiểm tra mà không ảnh hưởng đến phần còn lại của thư mục:

`
/rollback 1 src/broken_file.py

`

## Bảo vệ an toàn và hiệu suất- **Tính khả dụng của Git** — nếu không tìm thấy 
`git
` trên 
`PATH

, các điểm kiểm tra sẽ bị vô hiệu hóa một cách rõ ràng.
- **Phạm vi thư mục** — Hermes bỏ qua các thư mục quá rộng (root 

/

, home 

$HOME

).
- **Kích thước kho lưu trữ** — các thư mục có hơn 50.000 tệp bị bỏ qua.
- **Giới hạn kích thước mỗi tệp** — các tệp lớn hơn 
`max_file_size_mb
` (mặc định 10 MB) sẽ bị loại khỏi ảnh chụp nhanh. Ngăn chặn việc vô tình nuốt phải tập dữ liệu, trọng lượng mô hình hoặc phương tiện được tạo.
- **Tổng giới hạn kích thước cửa hàng** — khi cửa hàng vượt quá 
`max_total_size_mb
` (mặc định 500 MB), cam kết cũ nhất cho mỗi dự án sẽ bị loại bỏ luân phiên cho đến dưới giới hạn.
- **Cắt tỉa thực sự** — 
`max_snapshots
` được thực thi bằng cách viết lại tham chiếu cho mỗi dự án và chạy 
`git gc --prune=now
` sau đó, để các đối tượng lỏng lẻo không tích lũy.
- **Ảnh chụp nhanh không thay đổi** — nếu không có thay đổi nào kể từ ảnh chụp nhanh cuối cùng thì điểm kiểm tra sẽ bị bỏ qua.
- **Lỗi không nghiêm trọng** — tất cả lỗi bên trong Trình quản lý điểm kiểm tra đều được ghi lại ở cấp độ gỡ lỗi; công cụ của bạn tiếp tục chạy.

## Nơi kiểm tra trực tiếp

``` text
~/.Hermes/checkpoints/
  ├── store/                 # single shared bare git repo
  │   ├── HEAD, objects/     # git internals (shared across projects)
  │   ├── refs/Hermes/<hash # per-project branch tip
  │   ├── indexes/<hash     # per-project git index
  │   ├── projects/<hash.JSON  # workdir + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # auto-prune idempotency marker
  └── legacy-<ts/           # archived pre-v2 per-project shadow repos

`
``Mỗi 

<hash
` được lấy từ đường dẫn tuyệt đối của thư mục làm việc. Thông thường, bạn không bao giờ cần phải chạm vào những thứ này theo cách thủ công — thay vào đó hãy sử dụng 
`Hermes checkpoints status
` / 
`prune
` / 
`clear

.

### Di chuyển từ v1

Trước khi viết lại v2, mỗi thư mục làm việc đều có kho lưu trữ bóng tối hoàn chỉnh của riêng nó ngay trong 

~/.Hermes/checkpoints/<hash/

. Bố cục đó không thể loại bỏ các đối tượng trong các dự án và có một công cụ cắt tỉa không hoạt động được ghi lại — cửa hàng sẽ phát triển mà không bị ràng buộc.

Trong lần chạy v2 đầu tiên, mọi kho lưu trữ bóng trước v2 đều được chuyển vào 

~/.Hermes/checkpoints/legacy-<timestamp/
` để bố cục một cửa hàng mới bắt đầu rõ ràng. Lịch sử 

/rollback
` cũ vẫn có thể truy cập được bằng cách kiểm tra thủ công kho lưu trữ cũ bằng 
`git

; một khi bạn tự tin rằng mình không cần nó, hãy chạy:

`bash
Hermes checkpoints clear-legacy

`
``để lấy lại không gian. Các kho lưu trữ kế thừa cũng bị 
`auto_prune
` quét sau 
`retention_days

.

## Các phương pháp hay nhất
- **Chỉ bật điểm kiểm tra khi bạn cần** — 
`Hermes chat --checkpoints
` hoặc 
`enabled: true
` theo hồ sơ.

- **Sử dụng 

/rollback diff
` trước khi khôi phục** — xem trước những gì sẽ thay đổi để chọn điểm kiểm tra phù hợp.
- **Sử dụng 

/rollback
` thay vì 
`git reset

** khi bạn chỉ muốn hoàn tác các thay đổi do tác nhân điều khiển.
- **Thỉnh thoảng kiểm tra 
`Hermes checkpoints status

** nếu bạn sử dụng điểm kiểm tra thường xuyên — hiển thị dự án nào đang hoạt động và cửa hàng tính chi phí cho bạn.
- **Kết hợp với cây công việc Git** để đảm bảo an toàn tối đa — giữ mỗi phiên Hermes trong cây/nhánh làm việc riêng của nó, với các điểm kiểm tra là một lớp bổ sung.

Để chạy song song nhiều tác nhân trên cùng một repo, hãy xem hướng dẫn về [Git worktrees](./git-worktrees.md).