نقاط التفتيش و `/rollback` — شبكة الأمان لعملياتك الخطرة

هل سبق لك أن شاهدت وكيل ذكاء اصطناعي ينفّذ أمراً مثل rm -rf أو يكتب فوق ملف وفكّرت: “أتمنى حقاً أنه يعرف ما يفعله”؟ مع Hermes Agent v2، أصبح لديك الآن شبكة أمان حقيقية — نقاط التفتيش — التي يمكنها التقاط لقطة لحالة مشروعك قبل العمليات الخطرة واستعادتها بأمر واحد.

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

تفعيل نقاط التفتيش

يمكنك تفعيل نقاط التفتيش لكل جلسة باستخدام علامة بسيطة:

hermes chat --checkpoints

أو تفعيلها عالمياً في ~/.hermes/config.yaml:

checkpoints:
  enabled: true

هذا كل شيء. بمجرد التفعيل، تقوم Hermes تلقائياً بالتقاط لقطة لمشروعك قبل أي عملية خطرة.

ما الذي يستدعي إنشاء نقطة تفتيش

تقوم Hermes بإنشاء نقطة تفتيش تلقائياً قبل:

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

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

كيف يعمل في الخلفية

يحدث السحر عبر مدير نقاط التفتيش الداخلي الذي يحافظ على مستودع git ظلي مشترك واحد في ~/.hermes/checkpoints/store/. لا يتم لمس .git الحقيقي لمشروعك أبداً — كل شيء يعيش في هذا المخزن المنفصل.

إليك التدفق:

تكتشف Hermes عندما تكون الأدوات على وشك تعديل ملفات في شجرة العمل الخاصة بك.
مرة واحدة لكل دورة محادثة (لكل مجلد)، تقوم بتحديد جذر مشروع معقول.
تقوم بتهيئة المخزن الظلي المشترك أو إعادة استخدامه.
تقوم بإضافة الملفات إلى فهرس خاص بالمشروع، وبناء شجرة، والالتزام بمرجع خاص بالمشروع (refs/hermes/<project-hash>).

بما أن كل المشاريع تشارك نفس المخزن، فإن قاعدة بيانات كائنات 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)

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

خارج الجلسة، يمكنك فحص وإدارة مخزن نقاط التفتيش باستخدام أوامر CLI:

الأمر	الوصف
`hermes checkpoints`	عرض الحجم الإجمالي، عدد المشاريع، تفصيل لكل مشروع
`hermes checkpoints status`	نفس الأمر `checkpoints` المجرد
`hermes checkpoints list`	اسم مستعار لـ `status`
`hermes checkpoints prune`	فرض تنظيف: حذف العناصر اليتيمة/القديمة، جمع القمامة، فرض حد الحجم
`hermes checkpoints clear`	حذف قاعدة نقاط التفتيش بالكامل (يطلب تأكيداً أولاً)
`hermes checkpoints clear-legacy`	حذف أرشيفات `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      # الحد الأدنى للفاصل الزمني بين عمليات التنظيف التلقائية

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

لتعطيل كل شيء:

checkpoints:
  enabled: false
  auto_prune: false

عندما يكون enabled: false، يكون مدير نقاط التفتيش بلا وظيفة ولا يحاول أبداً إجراء عمليات git. عندما يكون auto_prune: false، ينمو المخزن حتى تقوم يدوياً بتشغيل hermes checkpoints prune.

الخلاصة

تمنحك نقاط التفتيش الثقة للسماح لـ Hermes بالعمل بحرية، مع العلم أنه يمكنك دائماً العودة إلى حالة معروفة وجيدة. سواء كنت تجرب إعادة هيكلة، أو تختبر أوامر خطرة، أو تريد فقط راحة البال، فإن أمر /rollback يساندك.

جرّبه في جلستك القادمة — قد تجد أنه يصبح جزءاً أساسياً من سير عملك.