إنتقل إلى المحتوى الرئيسي

البوابة

البوابة هي بيئة تشغيل القنوات. تربط محولات الاتصال البعيدة، وتوجه الجلسات، وتفرض الموافقات، وتُتيح ضوابط المشغل لملف شخصي واحد محدد.

إذا كنت تستخدم CLI فقط، فلن تحتاج إلى البوابة. بمجرد أن تحتاج إلى Telegram أو Discord أو Email أو WhatsApp كسطح اتصال بعيد، تصبح البوابة الحد الفاصل بين القناة والعميل.

ما تفعله البوابة​

  • تشغيل محولات القنوات (Telegram، Discord، Email، WhatsApp) وفقًا لإعدادات الملف الشخصي المحدد.
  • مصادقة المستخدمين والقوائم البيضاء (allowlist) لكل قناة.
  • ربط كل محادثة بجلسة عبر سياسة مفتاح الجلسة الموحدة.
  • توصيل التقدم والمخرجات والموافقات عبر نقل القناة الأصلي.
  • الاحتفاظ بقائمة انتظار موافقات دائمة مع مدة صلاحية TTL مدتها خمس دقائق.
  • توجيه أوامر المشغل المختصرة (/status، /approve، /model، /voice، /stop، إلخ) قبل أن تصل إلى العميل.
  • إعادة بناء بيئة التشغيل (runtime) من لقطة إعدادات جديدة في كل دورة، بحيث تنعكس تغييرات MCP والمزود دون إعادة تشغيل كاملة.
  • إجراء التشخيصات والإبلاغ عن جاهزية كل قناة.

ربط الملف الشخصي​

تعمل البوابة مقابل ملف شخصي واحد محدد. عند تشغيلها في المقدمة أو تثبيتها كخدمة، يُقفل الملف الشخصي المحدد طوال عمر العملية أو وحدة الخدمة.

estacoda gateway run
estacoda gateway run --profile work

تغيير active-profile.json لا يؤثر على البوابة التي تعمل بالفعل. إذا كنت بحاجة إلى بوابة لملف شخصي مختلف، شغل نسخة ثانية أو أعد التشغيل مع الملف الشخصي الجديد.

الحالة المحلية للملف الشخصي تشمل:

الحالةالمسار
جلسات القنوات، مؤشرات الأسطح، رموز التسليم~/.estacoda/profiles/<id>/gateway/
الموافقات المعلقة (صفوف دائمة)قاعدة بيانات الجلسات العامة، جدول pending_approvals، مُحكَمة بـ profile_id
سجلات التوصيل~/.estacoda/profiles/<id>/logs/gateway.log
تنزيلات وسائط القنوات~/.estacoda/profiles/<id>/channel-media/
بيانات مصادقة WhatsApp~/.estacoda/profiles/<id>/gateway/whatsapp-auth/

تثبيتات الخدمة مرتبطة أيضًا بالملف الشخصي. تتضمن وحدة الخدمة المُنشأة أمر gateway run --profile <id>، ويحمل اسم الوحدة تجزئة مشتقة من الملف الشخصي بحيث يمكن أن تتعايش عدة ملفات شخصية.

estacoda gateway install --profile work
estacoda gateway start
estacoda gateway uninstall --profile work

التفعيل من الإعداد​

عندما يستطيع الإعداد تثبيت البوابة وتشغيلها لقناة بعيدة أصبحت جاهزة حديثًا، يكون عنوان المطالبة EstaCoda Gateway.

تظهر المطالبة أثناء onboarding الأول عندما تُكوَّن قناة جاهزة. وتظهر أيضًا في Setup Editor للمستخدم الحالي عندما يكوّن ذلك التشغيل أول قناة جاهزة جديدة.

إذا اختار المستخدم ⁨WhatsApp⁩ أثناء onboarding أو ⁨Setup Editor⁩، تستخدم ⁨EstaCoda⁩ تدفق إعداد ⁨QR⁩ نفسه المستخدم في الأمر ⁨estacoda whatsapp⁩. لا تُكتب إعدادات ⁨WhatsApp⁩ أو حالة الجلسة إلا بعد نجاح الاقتران، وأي رفض أو فشل في الاعتمادات أو انتهاء مهلة ⁨QR⁩ يترك إعداد ⁨WhatsApp⁩ دون تغيير.

لا تظهر المطالبة لتغييرات الإعداد غير الخاصة بالقنوات، ولا عند تعديل قناة بعد أن كانت هناك قناة جاهزة موجودة مسبقًا، ولا عندما تكون خدمة بوابة مدارة مثبتة أو نشطة بالفعل.

قد يظل onboarding الأول يعرض مطالبة تشغيل بعد التطبيق. أما تطبيق Setup Editor للمستخدم الحالي فلا يعرض تسليم التشغيل بعد التطبيق. استخدم EstaCoda Doctor داخل Setup Editor عندما تريد فحوصات صحة للقراءة فقط وإصلاحات مطلوبة.

نضج القنوات​

القناةحالة v0.1.0
Telegramقناة بعيدة أولية مُثبتة عمليًا (live-proven)
Discordموجودة، ليست مُثبتة عمليًا
Emailموجودة، ليست مُثبتة عمليًا
WhatsAppتعمل عبر bridge معزول؛ تتطلب experimental: true لأن الواجهة غير رسمية

Telegram هي أقوى قناة بعيدة أولية في v0.1.0. محولات Discord وEmail تبدأ وتجتاز الفحوصات الآلية، لكن التحقق ببيانات اعتماد حية يعتمد على النشر. WhatsApp يستخدم مكتبة غير رسمية ويتطلب بوابة صريحة للواجهة غير الرسمية؛ قد تقوم Meta بتعليق الحسابات التي تستخدمه.

لا تُفعّل WhatsApp في ملف شخصي إنتاجي دون فهم مخاطر الحساب.

الموافقات​

عندما يتطلب استدعاء أداة موافقة صريحة، تنشئ البوابة صفًا دائمًا في pending_approvals. يتضمن الصف معرف الملف الشخصي، معرف الجلسة، معاينة الأمر، اسم الأداة، الحالة، مدة الصلاحية، وسياق القناة.

ثوابت الموافقات:

  • الموافقات المعلقة هي استفسار فقط. نتائج deny الحتمية وحواجز الأمان الصارمة لا تنشئ صفوفًا أبدًا.
  • الملف الشخصي A لا يستطيع عرض أو حل موافقات الملف الشخصي B.
  • العمليات المحددة بالجلسة لا تحل موافقة جلسة أخرى.
  • الموافقات منتهية الصلاحية أو المحسومة مسبقًا لا يمكن الموافقة عليها لاحقًا.
  • الصفوف المُعتمدة أو المرفوضة أو منتهية الصلاحية تحذف حمولة الأمر الأصلية حيثما أمكن.

توجيهات /approve و /deny البعيدة، والأزرار المضمنة (inline buttons)، وحلول مشغل CLI جميعها تمر عبر نفس مسار ChannelGateway. المحولات (adapters) تُظهر واجهة المستخدم فقط؛ لا تُفوض الموافقات ولا تُبطل ذاكرة التخزين المؤقت للبيئة التشغيلية.

estacoda gateway approvals
estacoda gateway approvals list --profile work
estacoda gateway approvals approve <id> [--session <session-id>] [--profile <profile-id>]
estacoda gateway approvals deny <id> [--session <session-id>] [--profile <profile-id>]

تنتهي صلاحية الموافقات بعد خمس دقائق. إذا انتهت الصلاحية، يجب إعادة إصدار الأمر.

سياسات الانشغال​

عند وصول رسالة جديدة بينما العميل يعالج دورة حالية، تحدد سياسة الانشغال للقناة ما يحدث:

السياسةالسلوك
reject (افتراضي)الرد فورًا برسالة انشغال.
queueتخزين الرسالة مؤقتًا ومعالجتها بعد اكتمال الدورة الحالية.
interruptإلغاء الدورة الحالية وبدء الدورة الجديدة فورًا.

اضبطها لكل قناة في config.json الخاص بالملف الشخصي المحدد:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "busyPolicy": "queue",
      "queueDepth": 5
    }
  }
}

queueDepth مُقيَّد بين [1, 10]. القيم غير الصالحة تعود إلى reject مع تحذير وقت التشغيل.

أوامر التحكم والاختصار في البوابة​

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

  • التحكم في الجلسة: /status، /sessions، /switch، /attach، /detach، /new، /reset
  • التحكم في النموذج: /model، /model clear، /model <provider>/<model> — هذه تتجاوز قوائم انتظار الانشغال حتى يمكن تغيير المسار أثناء دورة نشطة
  • التحكم في الصوت: /voice on، /voice all، /voice off، /voice status (يدعم Discord أيضًا /voice channel و /voice leave)
  • Cron: /cron لعرض المهام المجدولة
  • الموافقات: /approvals، /approve، /deny، /revoke
  • التشخيصات: /diagnostics، /stop

يُخزَّن /model --global كمسار أساسي للملف الشخصي فقط عندما تمر المصادقة والثقة في مساحة العمل وإثبات مسار الإعدادات. يفشل مغلقًا (fail closed). /model --global clear مرفوض.

عندما يحتوي الدور النشط على subagents قيد التشغيل، فإن سياسة interrupt تضع الرسائل العادية في الطابور بدل إلغاء دور الأب. أوامر التحكم ما زالت تتجاوز هذا الطابور. /stop يلغي دور الأب النشط وعمل الأطفال النشط. /approve و/deny و/status وأوامر النموذج/التحكم تحافظ على سلوك التجاوز الحالي. يمكن أن يعرض /status ملخصات active-subagent محدودة دون prompts الأطفال، أو raw transcripts، أو provider token streams، أو credentials، أو tool arguments.

الأعطال الشائعة وكيفية قراءتها​

العرضالسبب المحتملالاستعادة
فشل تشغيل البوابة مع خطأ مفتاح مفقودمتغير البيئة المُشار إليه في botTokenEnv غير موجود.أضف الرمز إلى ~/.estacoda/profiles/<id>/.env وأعد التشغيل.
مستخدم غير مصرحالمرسل ليس في قائمة allowlist للقناة.حدّث allowedUserIds (أو ما يعادلها) في إعدادات الملف الشخصي.
سلوك ملف شخصي خاطئتم تشغيل البوابة لملف شخصي مختلف عن الذي تعدله.تحقق من estacoda gateway status، أوقف، وأعد التشغيل بالملف الشخصي المقصود.
ذاكرة تخزين مؤقت قديمةتم تغيير إعداد أو نموذج أثناء تشغيل البوابة.تُعاد بناء البيئة التشغيلية من لقطة جديدة كل دورة؛ إذا استمر الأمر، أعد تشغيل البوابة.
انتهت صلاحية الموافقةلم يستجب المشغل خلال خمس دقائق.أعد تشغيل الأمر الأصلي.
حظر أمان صارمرفضت طبقة الأمان الأمر بشكل حتمي.راجع الأمر مقابل سياسة الأمان النشطة؛ لا يمكن تجاوز الحواجز الصارمة بالموافقة.

التشخيصات​

estacoda gateway status      # الحالة الكاملة: القنوات، الموافقات، Cron، مدير الخدمة
estacoda gateway diagnose    # فحص جاهزية لكل قناة؛ يخرج برمز 1 عند التحذيرات

يفحص gateway diagnose وجود الرموز، وإمكانية الوصول إلى المضيف، وإعدادات allowlist، وبوابة ⁨WhatsApp⁩ للواجهة غير الرسمية، وجاهزية حزمة/جسر ⁨WhatsApp⁩ المعزول، وأذونات مجلد Cron. تبقى ⁨Baileys⁩ ومعالجة ⁨Boom⁩ الخاصة بـ ⁨WhatsApp⁩ داخل حزمة الجسر؛ ولا يعتمد runtime الجذري عليهما مباشرة.

إدارة الخدمة (نظرة عامة)​

يمكن لـ EstaCoda تثبيت البوابة كخدمة مدارة:

  • خدمات مستخدم systemd على Linux
  • خدمات نظام systemd على Linux
  • وكلاء LaunchAgent لمستخدم macOS
estacoda gateway install
estacoda gateway start
estacoda gateway uninstall

gateway start يبدأ خدمة نطاق المستخدم المثبتة. استخدم gateway start --system لخدمة نطاق النظام المثبتة. لجلسات المقدمة أو التشخيص، استخدم gateway run أو gateway run --dry-run أو gateway run --once.

ترث الخدمات HOME ولكن ليس بيئة الصدفة التفاعلية. احتفظ بالأسرار في ملف .env الخاص بالملف الشخصي. قد تتوقف خدمات مستخدم systemd عند تسجيل الخروج ما لم يُفعّل linger:

sudo loginctl enable-linger $USER

للحصول على دليل التشغيل الكامل للخدمة، راجع صفحة عمليات البوابة.

صفحات ذات صلة​