الأتمتة

تشغّل الأتمتة تعليمة وفق جدول وتسلّم النتيجة في جلسة محادثة عادية. موجز أخبار يومي أو مراجعة أسبوعية أو تقرير شهري: تعمل كل عملية بلا واجهة على الخادم، وتظهر في قائمة محادثاتك، ويمكن فتحها ومتابعتها كأي محادثة أخرى.

المكوّنات

للأتمتة اسم وتعليمات نصية حرة ومشغّل واحد أو أكثر ونموذج اختياري (تعني القيمة الفارغة تلقائي: نموذج المحادثة الافتراضي وقت التشغيل)، وهدف تشغيل وتفضيل إشعار (داخل التطبيق أو متوقف). يحدد الهدف ما تنتجه العملية: تضع جلسة محادثة (الافتراضية) التعليمات في محادثة، بينما تشغّل مهمة Work sandbox معزولًا عبر Work وتجعله رسالة البداية، ويمكن اختياريًا اختيار سياسة Work مسماة من النموذج. وعند تشغيل الإشعارات، يظهر التشغيل الفاشل أيضًا في صندوق الإشعارات، فتصل إليك الإخفاقات حتى مع إغلاق صفحة الأتمتة. وبمعزل عن ذلك، يرسل تفعيل نتائج الأتمتة ضمن الإعدادات ← الإشعارات ← إشعارات البريد الإلكتروني بريدًا بنتيجة كل عملية تشغيل بعد أن يُعدّ أحد المسؤولين خادم بريد صادر (انظر الإشعارات). تُشفّر الأسماء والتعليمات أثناء التخزين. وتخص كل أتمتة المستخدم الذي أنشأها.

تعيد المشغلات استخدام نموذج التقويم المشترك — once وhourly وdaily وweekly وmonthly وyearly — ويمكن للأتمتة امتلاك خمسة منها كحد أقصى. يكون التشغيل التالي دائمًا أقرب حدث قادم بين مشغلاتها، محسوبًا في المنطقة الزمنية المحلية للخادم.

مشغّلات الأحداث

نوع سابع، event، بلا ساعة على الإطلاق: يعمل عندما تصل إحدى إشعاراتك.

{ "kind": "event", "event": "channel-mention", "match": "release" }

event أي نوع إشعار عدا automation-failed — إذ لا يجوز لروتين أن يعيد تشغيل نفسه من إشعار فشله الخاص. وmatch الاختياري اختبار سلسلة فرعية غير حساس لحالة الأحرف مقابل عنوان الإشعار؛ ومن دونه، يشغّل كل إشعار من ذلك النوع الروتين.

لا يسهم مشغّل الحدث أبدًا في وقت تشغيل تالٍ. لذلك تعرض أتمتة كل مشغلاتها أحداث بلا تشغيل تالٍ: تقول القائمة ونافذة التحرير يعمل عندما … بدلًا من ذلك. ومزج مشغّل حدث مع جدول أمر سليم — إذ تظل المشغلات المجدولة تقود الساعة.

يحد ضامنان من نطاق الأثر. لا يعمل الروتين من الأحداث أكثر من مرة في الدقيقة مهما كان تدفق الأحداث مزدحمًا، ولا يعيد إشعار فشل عملية تشغيل تشغيل الروتين الذي أنتجه أبدًا.

تتلقى العملية ما شغّلها، مُلحقًا بتعليماتها:

---
Trigger payload (JSON):
{"event":"channel-mention","title":"...","body":"...","href":"..."}

التنفيذ

تعمل دورة المجدول كل دقيقة خلف lease للتنسيق، لذلك لا تقدّم الجداول إلا replica واحدة. عندما يحين موعد أتمتة، تسجل الدورة عملية تشغيل وتضع مهمة automation.run.v1 دائمة في القائمة وتقدّم next_run_at عبر compare-and-set كي يعمل كل حدوث مرة واحدة على الأكثر. تنشئ المهمة جلسة محادثة بعنوان الأتمتة، ثم تضع التعليمة في خط توليد المحادثات الدائم نفسه المستخدم في كل محادثة، بما في ذلك توجيه الموفّر والقيم الافتراضية للشخصية والاستمرارية.

إذا كان الخادم متوقفًا عند مرور حدوث، تشغّله الدورة التالية مرة واحدة وتتجاوز المواعيد الأقدم الفائتة. يمحو إيقاف الأتمتة المؤقت جدولها؛ ويعيد استئنافها أو تحريرها حسابه من الوقت الحالي. ويحذف حذف الأتمتة سجل عملياتها عبر cascade لمفتاح أجنبي.

تستقر العمليات من سجل المهام الدائمة: تنجح عند اكتمال توليد المحادثة، وتفشل عندما تدخل أي مهمة قائمة dead-letter، وتفشل بوصف stalled عندما لا تبدأ عملية منتظرة خلال 30 دقيقة.

تتصرف العمليات الموجهة إلى Work بالطريقة نفسها مع دورة حياة Work بدل مهمة المحادثة: تسجل العملية المهمة التي أنشأتها (وتربط علامة العمليات بها مباشرةً)، وتنجح عندما يكمل الوكيل أو يتوقف لطلب إدخال، وتفشل إذا فشلت المهمة أو أُلغيت. ويحمل بريد نتيجة عملية موجهة إلى Work الملخصَ الذي حفظته عملية Work نفسها — ما انتهى إليه الوكيل، وهو النص نفسه الذي يعرضه سجل التشغيل الخاص بالمهمة — ويعود إلى حالة المهمة السطرية الواحدة حين تسبق عملية تشغيل الملخصات المحفوظة. يُفرض وصول Work عند تشغيل الجدول، لذلك يؤدي سحب وصول المستخدم إلى Work إلى إسكات أتمتته الموجهة إلى Work أيضًا؛ وتفشل العملية عندئذٍ بوصف work-access-denied بدل تجاوزها بصمت. تُتحقق السياسة المحددة عند حفظ الأتمتة، وتنطبق قيمة الشبكة الافتراضية وحدود الموارد فيها على كل مهمة تشغّلها الأتمتة. لا تعمل في Work إلا موفّرات النماذج المباشرة، ويجب أن يدعم النموذج الأدوات، وهي القواعد نفسها في محرر Work.

روتينات الوكلاء

يمكن بدلًا من ذلك ربط أتمتة موجهة إلى Work بمهمة Work موجودة عبر workTaskId، وهي البنية التي تستند إليها فقرة الروتينات في لوحة تفاصيل الوكيل. لا ينشئ الروتين المرتبط مهمة جديدة عند كل تشغيل؛ بل يبدأ كل حدوث تشغيلًا داخل مساحة العمل والمحادثة الخاصتين بالمهمة نفسها، باستخدام نموذج المهمة وموفّرها وسياسة وقت تشغيلها. لذلك لا تنطبق حقول النموذج والسياسة على مستوى الأتمتة، وتُحذف أي سياسة مقدمة عند الحفظ. يُتحقق من الربط عند حفظ الأتمتة (يجب أن تكون المهمة موجودة ومملوكة للمستدعي). عند التنفيذ، تؤدي المهمة المحذوفة إلى فشل العملية بوصف work-task-missing، بينما تؤدي المهمة التي تعمل بالفعل — أو تحتفظ بمعاينة حية — إلى فشل الحدوث صراحةً بوصف work-task-busy بدل وضعه في طابور خلفها.

مشغّلات الويب هوك

إلى جانب الجدول الزمني، يمكن لنظام خارجي أن يشغّل الأتمتة: خط تكامل مستمر، أو خدمة cron، أو أتمتة منزلية. في نافذة تحرير الأتمتة، يولّد مشغّل الويب هوك ← تفعيل سرًا خاصًا بكل أتمتة؛ ولا يُخزَّن منه إلا تجزئة SHA-256، لذلك يظهر النص الصريح مرة واحدة فقط. وتبطل إعادة توليد السر السرَّ السابق فورًا، ويغلق تعطيل الويب هوك نقطة النهاية من جديد.

يشغّل النظام الخارجي الأتمتة على النحو التالي:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..."

(وتصلح X-Libre-Webhook-Secret: lwh_... ترويسةً بديلة.) الاستجابة هي 202 مع معرّف العملية المضافة إلى الطابور، وهو مسار التشغيل اليدوي نفسه الذي يسلكه التشغيل الآن، فتستقر العمليات وتُشعر وتظهر في السجل بالطريقة نفسها. تجري مقارنة السر في زمن ثابت، وتتلقى الأتمتة غير الموجودة والسر الخاطئ الاستجابة نفسها (فلا يوجد كاشف لمعرّفات الأتمتة)، وتجيب الأتمتة الموقوفة مؤقتًا بـ 409: فبخلاف المالك عبر التشغيل الآن، لا يستطيع المستدعي الخارجي التشغيل رغم الإيقاف المؤقت.

يدخل كائن JSON في جسم الطلب مع العملية بوصفه حمولة المشغّل، كي يرى الروتين ما يتفاعل معه:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..." \
  -H "Content-Type: application/json" \
  -d '{"commit":"abc123","branch":"main"}'

تُلحق الحمولة بالتعليمات التي تنفذها العملية، تحت عنوان Trigger payload (JSON): — لعمليات المحادثة ومهام Work الجديدة وروتينات المهام المرتبطة على السواء. ولا تُحمل إلا كائنات JSON (تُتجاهل المصفوفات والقيم البدائية)، وتُسقط الحمولة التي تتجاوز صيغتها المتسلسلة 4000 حرف بدل بترها، مع تحذير في سجل الخادم. ويتصرف التشغيل بلا جسم بالضبط كما كان من قبل.

API

تتطلب كل نقاط النهاية عدا تشغيل الويب هوك مصادقةً ولا تعمل إلا على أتمتة المستدعي نفسه؛ أما تشغيل الويب هوك فيصادق بدلًا من ذلك بالسر الخاص بالأتمتة.

الطريقة	المسار	الغرض
GET	/api/automations	سرد الأتمتة
POST	/api/automations	إنشاء أتمتة
GET	/api/automations/occurrences?from=&to=	الحدوثات القادمة المحسوبة
GET	/api/automations/runs	سجل العمليات (قابل للتصفية)
GET	/api/automations/runs/summary	عدد غير المشاهد ومجموعات 30 يومًا
POST	/api/automations/runs/seen	وضع علامة مشاهدة على العمليات المنتهية
GET	/api/automations/:automationId	قراءة أتمتة واحدة
PUT	/api/automations/:automationId	تحديث أتمتة
DELETE	/api/automations/:automationId	حذف أتمتة
POST	/api/automations/:automationId/pause	إيقاف الجدول مؤقتًا
POST	/api/automations/:automationId/resume	استئناف الجدول
POST	/api/automations/:automationId/run	التشغيل الآن (202 مع معرّف عملية)
POST	/api/automations/:automationId/webhook	التشغيل عبر السر (202)
POST	/api/automations/:automationId/webhook-secret	توليد السر أو إعادة توليده
DELETE	/api/automations/:automationId/webhook-secret	تعطيل الويب هوك

يمكن للمستخدم الاحتفاظ بما يصل إلى 50 أتمتة؛ وتُحد الأسماء عند 200 حرف والتعليمات عند 20,000.