Checkpoints และ `/rollback` — ตาข่ายนิรภัยของโปรเจกต์คุณ

Checkpoints และ /rollback — ตาข่ายนิรภัยของโปรเจกต์คุณ

เคยไหมที่เห็น AI agent แก้ไขอะไรบางอย่างแล้วคิดว่า “เดี๋ยวนะ ฉันไม่ได้ตั้งใจจะทำแบบนั้นนี่”? เราทุกคนเคยเจอปัญหานี้กันทั้งนั้น นั่นคือเหตุผลที่ Hermes Agent มีฟีเจอร์ตาข่ายนิรภัยในตัว: checkpoints ให้คิดว่ามันคือจุดเซฟในเกม — ภาพสแนปช็อตของโปรเจกต์คุณที่ถูกถ่ายก่อนการดำเนินการที่มีความเสี่ยง พร้อมกู้คืนได้ด้วยคำสั่งเดียว

Checkpoints คืออะไร?

Checkpoints คือภาพสแนปช็อตอัตโนมัติของโปรเจกต์คุณที่ถูกถ่ายก่อน การดำเนินการที่อาจทำลายข้อมูล ถ้า agent กำลังจะลบไฟล์ เขียนทับโค้ด หรือรันคำสั่งเทอร์มินัลที่มีความเสี่ยง มันจะเซฟสถานะปัจจุบันไว้ก่อน ต่อมาคุณสามารถย้อนกลับไปยังสแนปช็อตใดก็ได้

จุดเด่นที่สุด? ประวัติ .git ของโปรเจกต์จริงของคุณจะไม่ถูกแตะต้องเลย Hermes ใช้ shared shadow store ที่ ~/.hermes/checkpoints/store/ — ซึ่งเป็น git repository แยกต่างหากที่เก็บทุกอย่างอย่างเป็นระเบียบและไม่ซ้ำซ้อนข้ามโปรเจกต์

เริ่มต้นใช้งาน: เปิดใช้งาน Checkpoints

Checkpoints เป็นแบบ opt-in ตั้งแต่เวอร์ชัน v2 ผู้ใช้ส่วนใหญ่ไม่จำเป็นต้องใช้ และพื้นที่จัดเก็บอาจเพิ่มขึ้นเรื่อย ๆ เมื่อเวลาผ่านไป ดังนั้นค่าเริ่มต้นจึงเป็นปิด

เปิดใช้งานสำหรับเซสชันเดียว:

hermes chat --checkpoints

หรือเปิดใช้งานแบบถาวรใน ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Hermes จะถ่าย Checkpoint เมื่อไหร่?

Hermes จะถ่ายสแนปช็อตโดยอัตโนมัติก่อน:

• เครื่องมือจัดการไฟล์ — write_file และ patch
• คำสั่งเทอร์มินัลที่อาจทำลายข้อมูล — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, การรีไดเรกต์เอาต์พุต (>), และ git reset/clean/checkout

ไม่ต้องกังวลเรื่องสแปม — agent จะสร้าง checkpoint สูงสุดหนึ่งอันต่อไดเรกทอรีต่อเทิร์น ดังนั้นเซสชันยาว ๆ จะยังคงสะอาด

การใช้ /rollback ในเซสชัน

เมื่อเปิดใช้งาน checkpoints แล้ว คุณจะได้คำสั่งสแลชอันทรงพลังในแชทของคุณ:

คำสั่ง	ฟังก์ชัน
/rollback	แสดงรายการ checkpoints ทั้งหมดพร้อมสถิติการเปลี่ยนแปลง
/rollback <N>	กู้คืนไปยัง checkpoint ที่ N โดยคงการแก้ไขด้วยมือของคุณไว้
/rollback <N> --all	กู้คืนแบบเต็มรูปแบบ — เขียนทับการแก้ไขด้วยมือของคุณด้วย
/rollback diff <N>	ดูตัวอย่างการเปลี่ยนแปลงระหว่าง checkpoint ที่ N กับปัจจุบัน
/rollback <N> <file>	กู้คืนไฟล์เดียวจาก checkpoint ที่ N

นี่คือตัวอย่างการแสดงรายการ checkpoints:

📸 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 (keeps your hand-edits)
  /rollback <N> --all       full restore, overwriting your hand-edits too
  /rollback diff <N>        preview changes since checkpoint N
  /rollback <N> <file>      restore a single file from checkpoint N

การจัดการพื้นที่จัดเก็บจาก Shell

นอกเซสชัน คุณสามารถใช้ CLI เพื่อตรวจสอบและจัดการพื้นที่จัดเก็บ checkpoint ของคุณ:

hermes checkpoints              # แสดงขนาด จำนวนโปรเจกต์ รายละเอียด
hermes checkpoints status       # เหมือนกับด้านบน
hermes checkpoints list         # alias ของ status
hermes checkpoints prune        # บังคับทำความสะอาด: orphan, ข้อมูลเก่า, จำกัดขนาด
hermes checkpoints clear        # ลบทั้งหมด (ถามก่อน)
hermes checkpoints clear-legacy # ลบไฟล์ migration เก่าจาก v1

ตัวอย่างผลลัพธ์:

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

ตัวเลือกการกำหนดค่า

ปรับแต่ง checkpoints ใน ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # สวิตช์หลัก (ค่าเริ่มต้น: false)
  max_snapshots: 20           # จำนวน checkpoint สูงสุดต่อโปรเจกต์
  max_total_size_mb: 500      # ขีดจำกัดขนาดพื้นที่จัดเก็บทั้งหมด
  max_file_size_mb: 10        # ข้ามไฟล์ที่ใหญ่กว่าขนาดนี้

  # การบำรุงรักษาอัตโนมัติ (เปิดโดยค่าเริ่มต้น)
  auto_prune: true
  retention_days: 7
  min_interval_hours: 24

ต้องการปิดทุกอย่าง?

checkpoints:
  enabled: false
  auto_prune: false

กลไกการทำงานเบื้องหลัง

เมื่อ Hermes ตรวจพบว่าเครื่องมือกำลังจะแก้ไขไฟล์ มันจะ:

1. หา project root ของไฟล์นั้น
2. เริ่มต้นหรือใช้ shared shadow store ที่มีอยู่
3. Stage การเปลี่ยนแปลง สร้าง tree และ commit ไปยัง ref เฉพาะโปรเจกต์ (refs/hermes/<project-hash>)

refs เหล่านี้คือประวัติ checkpoint ของคุณ พร้อมสำหรับการตรวจสอบและกู้คืนผ่าน /rollback

ความคิดสุดท้าย

Checkpoints ให้ความอุ่นใจเมื่อคุณปล่อยให้ agent ทำงานกับโค้ดของคุณ ไม่ว่าคุณจะกำลังทดลอง รีแฟกเตอร์ หรือแค่อยากได้ตาข่ายนิรภัย /rollback พร้อมช่วยเหลือคุณเสมอ เปิดใช้งานไว้ ลืมมันไปได้เลย แล้วนอนหลับสบายเพราะรู้ว่าคุณสามารถย้อนกลับได้เสมอ

ขอให้โค้ดมีความสุข — และจำไว้ จุดเซฟมีไว้เพื่ออะไรสักอย่าง!