Why You Should Care About Checkpoints

لماذا يجب أن تهتم بنقاط الاستعادة

تخيّل أن تطلب من Hermes إعادة هيكلة جزء كبير من الكود الخاص بك، وفي منتصف الطريق تكتشف أن النهج الجديد كارثة. بدون نقاط الاستعادة، ستجد نفسك عالقًا في التراجع اليدوي عن التغييرات أو البحث في تاريخ git. مع نقاط الاستعادة، كل ما عليك فعله هو كتابة /rollback واختيار نقطة الاستعادة. إنها أشبه بآلة زمن لمشروعك.

أفضل جزء؟ نقاط الاستعادة اختيارية تمامًا. إنها معطّلة افتراضيًا في الإصدار v2، لذا إذا لم تستخدمها أبدًا، فلن تلاحظ وجودها أبدًا. لكن عندما تحتاجها، ستكون منقذًا للحياة.

تفعيل نقاط الاستعادة

لديك طريقتان لتفعيل شبكة الأمان هذه:

لكل جلسة (هذه المحادثة فقط):

hermes chat --checkpoints

بشكل عام (كل الجلسات) — عدّل ملف ~/.hermes/config.yaml:

checkpoints:
  enabled: true

ما الذي يُنشئ نقطة استعادة؟

تقوم Hermes تلقائيًا بالتقاط لقطة لمشروعك قبل أي عملية تدميرية، بما في ذلك:

• أدوات الملفات — write_file و patch
• أوامر الطرفية الخطيرة — rm, rmdir, cp, mv, sed -i, truncate, dd, shred, إعادة توجيه المخرجات (>), و git reset/clean/checkout

لتجنب الإزعاج، تنشئ Hermes نقطة استعادة واحدة على الأكثر لكل مجلد في كل دورة. لذا لن تمتلئ مساحة القرص لديك بمئات اللقطات في جلسة طويلة.

السحر خلف الكواليس

إليك الجزء الذكي: تستخدم Hermes مستودع git ظلّي مشترك واحد مخزّن في ~/.hermes/checkpoints/store/. مجلد .git الخاص بمشروعك الحقيقي لا يتم لمسه أبدًا. كل المشاريع تشارك هذا المستودع الواحد، ونظام git القائم على المحتوى يزيل تلقائيًا الملفات المكررة عبر المشاريع. لذا إذا كان مشروعان يحتويان على ملفات متشابهة، فسيتم تخزينها مرة واحدة فقط.

استخدام /rollback داخل الجلسة

بمجرد تفعيل نقاط الاستعادة، يمكنك استخدام أوامر الشرطة المائلة التالية أثناء المحادثة:

الأمر	وظيفته
/rollback	يعرض كل نقاط الاستعادة مع إحصائيات التغييرات
/rollback <N>	يستعيد نقطة الاستعادة N، مع الحفاظ على تعديلاتك اليدوية (يلغي أيضًا آخر دورة محادثة)
/rollback <N> --all	استعادة كاملة — تستبدل تعديلاتك اليدوية أيضًا
/rollback diff <N>	يعرض الفرق بين نقطة الاستعادة N والحالة الحالية
/rollback <N> <file>	يستعيد ملفًا واحدًا فقط من نقطة الاستعادة N

عند كتابة /rollback، سترى شيئًا مثل:

📸 نقاط الاستعادة لـ /path/to/project:

  1. 4270a8c  2026-03-16 04:36  قبل التصحيح  (ملف واحد، +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)

إدارة المخزن من الطرفية

خارج الجلسة، يمكنك فحص وتنظيف مخزن نقاط الاستعادة:

hermes checkpoints              # عرض الحجم الإجمالي، عدد المشاريع، التفاصيل
hermes checkpoints status       # نفس الأمر أعلاه
hermes checkpoints list         # اسم مستعار لـ status
hermes checkpoints prune        # تنظيف قسري: حذف العناصر اليتيمة، جمع القمامة، فرض حد الحجم
hermes checkpoints clear        # مسح قاعدة نقاط الاستعادة بالكامل (يطلب تأكيدًا أولاً)
hermes checkpoints clear-legacy # حذف أرشيفات الترحيل v1 فقط

ضبط الإعدادات

يمكنك التحكم في كل شيء في ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # المفتاح الرئيسي (الافتراضي: false)
  max_snapshots: 20           # الحد الأقصى لنقاط الاستعادة لكل مشروع
  max_total_size_mb: 500      # حد أقصى صارم لحجم المخزن الإجمالي
  max_file_size_mb: 10        # تجاهل الملفات الأكبر من هذا الحجم
  auto_prune: true            # تنظيف تلقائي للعناصر القديمة عند بدء التشغيل
  retention_days: 7           # الاحتفاظ بالعناصر التي تم الوصول إليها خلال هذا العدد من الأيام
  min_interval_hours: 24      # التنظيف مرة واحدة على الأكثر خلال هذه الفترة

تفصيل ذكي: التنظيف التلقائي لا يحذف أبدًا العناصر اليتيمة (المشاريع التي لم يعد مجلد العمل الخاص بها موجودًا). وذلك لأن المجلد المفقود قد يعني ببساطة قرصًا خارجيًا غير مثبّت أو VPN غير متصل بعد. تنظيف العناصر اليتيمة يتم فقط عبر الأمر الصريح hermes checkpoints prune، الذي يطلب تأكيدًا أولاً.

متى يجب عليك تفعيلها؟

إذا كنت تقوم بـعمل تجريبي، أو إعادة هيكلة كبيرة، أو تتعلم Hermes، فعّل نقاط الاستعادة. الحمل التخزيني معتدل (بفضل إزالة التكرار)، وراحة البال هائلة. إذا كنت تقوم فقط بمهام بسيطة وآمنة، فاتركها معطّلة لتوفير مساحة القرص.

نقاط الاستعادة هي إحدى تلك الميزات التي ستنساها — حتى اللحظة التي تحتاجها فيها بشدة. وعندما تأتي تلك اللحظة، ستكون سعيدًا بوجودها.

---