Điểm kiểm tra và `/rollback`

Hermes Agent tự động chụp nhanh dự án của bạn trước các hoạt động phá hủy và cho phép bạn khôi phục nó bằng một lệnh duy nhất. Điểm kiểm tra được bật theo mặc định — không mất phí khi không có công cụ biến đổi tệp nào kích hoạt.

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ữ git bóng riêng biệt trong ~/.hermes/checkpoints/ — dự án thực sự của bạn .git không bao giờ được chạm tới.

Đ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 , mv , sed -i , truncate , 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	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

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 shadow git repo gắn với thư mục đó.
- Thực hiện và cam kết trạng thái hiện tại với lý do ngắn gọn, dễ đọc.
Những cam kết 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 .

Cấu hình

Điểm kiểm tra được bật theo mặc định. Định cấu hình trong ~/.hermes/config.yaml :

checkpoints:
  enabled: true          

# master switch (default: true)
  max_snapshots: 50      

# max checkpoints per directory

Để vô hiệu hóa:

checkpoints:
  enabled: false

Khi bị tắt, Trình quản lý điểm kiểm tra sẽ không hoạt động và không bao giờ thử các thao tác git.

Đ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:

📸 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

Mỗi mục hiển thị:

Băm ngắn
Dấu thời gian
Lý do (điều gì đã kích hoạt ảnh chụp nhanh)
Tóm tắt thay đổi (tập tin đã thay đổi, chèn/xóa)

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ế:

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')

Sự khác biệt dài được giới hạn ở 80 dòng để tránh làm ngập terminal.

Đang khôi phục bằng `/rollback`

Khôi phục điểm kiểm tra theo số:

/rollback 1

Đằng sau hậu trường, Hermes:

Xác minh cam kết mục tiêu tồn tại trong kho lưu trữ bóng tối.
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.
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.
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.

Về thành công:

✅ 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.

```Việc hoàn tác cuộc hội thoại sẽ đảm bảo tổng đài viên không "ghi nhớ" những thay đổi đã được khôi phục, tránh nhầm lẫn ở lượt tiếp theo.

#

# 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

 

Điều này hữu ích khi tác nhân thực hiện thay đổi đối với nhiều tệp nhưng chỉ cần hoàn nguyên một tệp.

#

# Bảo vệ an toàn và hiệu suất

Để giữ cho điểm kiểm tra an toàn và nhanh chóng, Hermes áp dụng một số lan can:

- **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 để tránh hoạt động git chậm.
- **Ả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

Tất cả các kho lưu trữ bóng tối đều tồn tại dưới:

```text
~/.hermes/checkpoints/
  ├── <hash1>/   

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

Mỗi <hash> được lấy từ đường dẫn tuyệt đối của thư mục làm việc. Bên trong mỗi repo bóng bạn sẽ tìm thấy:

Nội bộ git tiêu chuẩn ( HEAD , refs/ , objects/ )
Tệp info/exclude chứa danh sách bỏ qua được sắp xếp
Tệp HERMES_WORKDIR trỏ trở lại thư mục gốc của dự án

Thông thường bạn không bao giờ cần phải chạm vào những thứ này một cách thủ công.

Các phương pháp hay nhất

Bật điểm kiểm tra — chúng được bật theo mặc định và không mất phí khi không có tệp nào được sửa đổi.
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.
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 kho lưu trữ, hãy xem hướng dẫn trên Git Worktrees.