# الأتمتة والجدولة

## مهام Cron

جدوِل إيقاظ الوكلاء بتوقيت دقيق. تستمر مهام Cron عبر إعادة تشغيل البوابة وتدعم أنماط جدولة مرنة.

### أنواع الجدولة

| النوع | الوصف | مثال |
|------|-------------|---------|
| **تعبير Cron** | صيغة cron القياسية مع المنطقة الزمنية | `0 7 * * *` (يومياً الساعة 7 صباحاً) |
| **الفاصل الزمني** | تكرار بفواصل زمنية ثابتة | `30m`، `2h`، `1d` |
| **مرة واحدة** | تشغيل مرة واحدة في وقت محدد | `2026-03-15T16:00:00Z` |

### أهداف الجلسة

- **الجلسة الرئيسية**, إضافة إلى قائمة الانتظار كحدث نظام في المحادثة الرئيسية للوكيل
- **الجلسة المعزولة**, التشغيل في جلسة مخصصة (`cron:<jobId>`) لتجنب تلويث المحادثات الرئيسية

### أوضاع التسليم

| الوضع | الوصف |
|------|-------------|
| **بدون** | تنفيذ صامت (لا يُنشر أي مخرج) |
| **إعلان** | نشر النتيجة في قناة محددة |
| **Webhook** | HTTP POST للنتيجة إلى عنوان URL خارجي |

### تذكيرات لمرة واحدة

اضبط تذكيراً لوقت محدد. يستيقظ الوكيل ويعالج التذكير ويحذف المهمة اختيارياً بعد التشغيل.

### المهام المتكررة

جدوِل المهام المتكررة بتعبيرات cron ودعم المنطقة الزمنية. تتبع المهام سجل تنفيذها (نجاح، فشل، توقيت).

---

## Webhooks

استقبال الأحداث من الخدمات الخارجية وتوجيهها إلى الوكلاء.

### Gmail Pub/Sub

التكامل مع نظام الإشعارات الفورية لـ Gmail لتشغيل إجراءات الوكيل عند وصول رسائل بريد إلكتروني:

1. إعداد موضوع واشتراك GCP Pub/Sub
2. تكوين تصفية علامات Gmail
3. توجيه التسليم الفوري إلى عنوان URL الـ webhook الخاص بك
4. يستقبل Neotask الرسائل ويضيف أحداث الوكيل إلى قائمة الانتظار

### Webhooks مخصصة

تسجيل نقاط نهاية HTTP التي تشغّل دورات الوكيل عند استدعائها. مفيد للتكامل مع خطوط أنابيب CI/CD وأنظمة المراقبة وأي خدمة يمكنها إرسال طلبات HTTP.

---

## أحداث النظام

أحداث النظام هي إشارات تيقظ الوكيل للمعالجة:

- **فوري**, المعالجة في نبضة القلب التالية
- **نبضة القلب التالية**, إضافة إلى قائمة الانتظار لعملية تسجيل وصول مجدولة

استخدم أحداث النظام لسير العمل التفاعلي, يستيقظ الوكلاء عند حدوث شيء ما بدلاً من جدول زمني ثابت.

---

## نبضة القلب

نبضة القلب إشارة دورية (الافتراضية ~15 ثانية) تمنح الوكلاء فرصة لمعالجة العمل المعلق:

- التحقق من أحداث النظام الجديدة
- معالجة الرسائل في قائمة الانتظار
- تشغيل عمليات الأتمتة المعلقة

يمكن تفعيل نبضة القلب أو تعطيلها أو تكوينها لكل وكيل على حدة.

---

## الخطافات

أتمتة مدفوعة بالأحداث تشغّل أوامر الطرفية أو السكريبتات استجابةً لأحداث البوابة:

- **عند استقبال رسالة**, التنفيذ عند استقبال رسالة
- **عند دور الوكيل**, التنفيذ قبل أو بعد معالجة الوكيل للرسالة
- **عند حدث قناة**, التنفيذ عند أحداث خاصة بالقناة (الانضمام، المغادرة، رد الفعل)

تعمل الخطافات على مضيف البوابة ولها إمكانية الوصول إلى بيانات سياق الحدث.

---

## حالات الاستخدام

| السيناريو | الحل |
|----------|----------|
| الإحاطة الصباحية اليومية | مهمة Cron الساعة 7 صباحاً ← يلخص الوكيل التحديثات الليلية |
| إنشاء تقارير أسبوعية | مهمة Cron كل يوم الاثنين ← ينشئ الوكيل التقارير ويرسلها بالبريد الإلكتروني |
| مراقبة البريد الإلكتروني | webhook Gmail ← يعالج الوكيل رسائل البريد الواردة |
| إشعارات البناء | webhook CI/CD ← يعلن الوكيل نتائج البناء على Discord |
| التحقق من البيانات ساعياً | Cron مبني على فاصل زمني ← يتحقق الوكيل من لوحة التحكم ويُنبّه عند الشذوذات |
| المنشورات الاجتماعية المجدولة | مهمة Cron ← يصيغ الوكيل المحتوى وينشره في الأوقات المثلى |