تشغيل البوابة

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

حد الملف الشخصي

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

• إعدادات البوابة (config.json)
• حالة البوابة (gateway/)
• سجلات البوابة (logs/gateway.log)
• رموز القنوات (.env)
• قاعدة بيانات الجلسات (sessions.sqlite، عامة لكن محدودة بواسطة profile_id)

# تشغيل البوابة في المقدمة للملف الشخصي النشط الحالي
estacoda gateway run

# تشغيل البوابة في المقدمة لملف شخصي محدد
estacoda gateway run --profile work

التشغيل والبدء

estacoda gateway run              # مشرف البوابة في المقدمة. السجلات في الطرفية.
estacoda gateway run --dry-run    # فحص الجاهزية فقط. لا قفل، لا PID، لا محولات.
estacoda gateway run --once       # تمريرة مشرف واحدة ثم خروج.

estacoda gateway install          # تثبيت خدمة نطاق المستخدم.
estacoda gateway start            # بدء خدمة نطاق المستخدم المثبتة.
estacoda gateway start --system   # بدء خدمة نطاق النظام المثبتة.

gateway run هو مسار المقدمة والتشخيص. استخدمه عندما تريد السجلات في الطرفية الحالية ولا تريد إدخال مدير خدمة في المسار.

gateway run --dry-run يفحص الجاهزية بدون تشغيل المحولات أو الاستطلاع على الواجهات البعيدة أو الدخول إلى حلقة المراقبة. استخدمه للتحقق من الإعدادات قبل الالتزام بعملية حية. gateway run --once ينفذ تمريرة مشرف واحدة ثم يخرج.

gateway start يبدأ خدمة مثبتة. افتراضياً يتحكم في خدمة نطاق المستخدم للملف الشخصي المحدد. gateway start --system يتحكم فقط في خدمة نطاق النظام. إذا كانت خدمة النظام فقط موجودة ولم تمرر --system، يفشل الأمر بإغلاق آمن ويطلب من المشغل إعادة التشغيل مع --system.

يلزم gateway install قبل gateway start. الخيار gateway start --background مُهمَل ولم يعد ينشئ عملية خلفية غير مُدارة؛ استخدم تثبيت الخدمة ثم تشغيلها للتشغيل الدائم.

مطالبة التفعيل من الإعداد

مطالبة الإعداد التي تعرض تثبيت البوابة وتشغيلها عنوانها EstaCoda Gateway.

تظهر المطالبة:

• أثناء onboarding الأول عندما تُكوَّن قناة جاهزة.
• أثناء Setup Editor للمستخدم الحالي عندما تُكوَّن أول قناة جاهزة جديدة.

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

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

الإيقاف

estacoda gateway stop               # SIGTERM مؤدب، انتظار حتى 10ث
estacoda gateway stop --force       # SIGKILL إذا فشل الإيقاف المؤدب (الوضع غير المدار)

إذا كانت هناك خدمة مستخدم مثبتة، يستدعي stop إلى systemd أو launchd. في systemd، stop --force لا زال يستخدم systemctl stop، ولا يرسل SIGKILL مباشرة. إذا لم يكن هناك خدمة، يقرأ stop ملف PID، ويرسل SIGTERM، وينتظر، ثم يُزيل ملفات PID/الحالة/القفل.

إعادة التشغيل

estacoda gateway restart            # إعادة تشغيل خدمة نطاق المستخدم المثبتة
estacoda gateway restart --graceful # مرادف لـ restart في v0.1.0
estacoda gateway restart --system   # إعادة تشغيل خدمة نطاق النظام

restart يستدعي الخدمة المثبتة وفق قواعد الاختيار نفسها التي يستخدمها start: خدمة المستخدم افتراضياً، وخدمة النظام فقط مع --system. إذا لم توجد خدمة مدارة، يفشل مع إرشاد التثبيت ولا ينشئ عملية خلفية غير مُدارة. يبقى restart --graceful مرادفاً لـ restart.

الخدمات المدارة

estacoda gateway install                    # تثبيت خدمة مستخدم systemd/launchd
estacoda gateway install --profile work     # تثبيت للملف الشخصي "work"
estacoda gateway install --force            # إيقاف الخدمة الموجودة واستبدالها
sudo estacoda gateway install --system --run-as-user estacoda  # نطاق النظام

estacoda gateway uninstall                  # إزالة خدمة المستخدم
sudo estacoda gateway uninstall --system    # إزالة خدمة النظام

المديرون المدعومون: systemd Linux (المستخدم والنظام)، launchd macOS (المستخدم).

كل ملف شخصي يحصل على الوحدة الخاصة به مع لاحقة hash. يمكن لعدة ملفات شخصية أن تكون لها خدمات مستقلة.

ملاحظات تشغيلية:

• الخدمات تستخدم HOME صريحاً لكنها لا تستخدم بيئة الشل التفاعلية.
• ضع رموز البوت ومفاتيح API في .env الخاص بالملف الشخصي، وليس فقط في متغيرات shell.
• خدمات المستخدم systemd قد تتوقف عند الخروج ما لم يكن linger مُفعلاً: sudo loginctl enable-linger $USER.
• مخرجات الخدمة تذهب إلى الدولية. استخدم journalctl --user -u <unit> -f لخدمات المستخدم.
• التثبيتات في وضع المصدر تثبّت مسار المسار المطلق بشكل مباشر. إذا تحرك المستودع، أزل الخدمة وأعد تثبيتها.
• الخدمات المُنشأة تستدعي gateway run --profile <id>.
• gateway start وgateway stop وgateway restart تستهدف خدمة المستخدم المثبتة افتراضياً. استخدم --system لخدمة نطاق النظام المثبتة.

التشخيص

estacoda gateway diagnose         # فحص الجاهزية لكل قناة
estacoda gateway status           # حالة البوابة الكاملة

gateway diagnose يفحص:

• وجود رمز Telegram، المستخدمين المسموح لهم، المحادثات
• وجود رمز Discord
• بيانات Email IMAP/SMTP، الاعتماد، العناوين
• بوابة WhatsApp للواجهة غير الرسمية، جاهزية حزمة الجسر المعزولة، كتابة دليل المصادقة، ربط الجهاز، تفويض المستخدم، dmPolicy، groupPolicy، mode، وضغط الطابور
• أذونات دليل cron

يرجع رمز الخروج 1 إذا كانت هناك تحذيرات.

gateway status يظهر:

• حالة مدير الخدمة
• حالة العملية
• جميع القنوات المكوّنة مع حالاتها
• منصات موجه التوصيل
• مؤشرات السطح النشطة
• عدد الموافقات المعلقة
• ملخص مهام cron وأخطاؤها الأخيرة
• أخطاء التوصيل الأخيرة
• تحذيرات الإعداد/البيئة المفقودة
• ملخصات active-subagent محدودة عندما يعرّض runtime عمل أطفال مفوض

تمكين وتعطيل القناة

estacoda channels enable telegram
estacoda channels disable telegram

الأسماء الصالحة: telegram، discord، email، whatsapp (غير حساسة للحالة).

enable يضعع enabled: true في إعدادات الملف الشخصي. disable يضعع enabled: false. كلاهما امتثاليتان ويحفظان بقية الحقول.

إعداد WhatsApp

estacoda whatsapp

يستخدم إعداد ⁨WhatsApp⁩ تدفق ⁨QR⁩ مشتركاً. يمكن تشغيله من القدرات الاختيارية في onboarding الأول، أو من ⁨Setup Editor⁩، أو من الأمر المستقل ⁨estacoda whatsapp⁩. يوضح كل سطح أن النقل غير رسمي ومدعوم بـ ⁨Baileys⁩، ويحافظ على الاعتمادات داخل scripts/whatsapp-bridge/، ويفحص جاهزية حزمة الجسر، ويسأل قبل إصلاح الاعتمادات، ويعرض رمز ⁨QR⁩ في الطرفية، ولا يكتب الإعدادات أو حالة الجلسة إلا بعد نجاح الاقتران. رفض الاعتمادات أو فشلها، وانتهاء مهلة ⁨QR⁩ أو فشل الاقتران، يترك إعداد ⁨WhatsApp⁩ دون تغيير. لا توجد واجهة pairing code لجهاز ⁨WhatsApp⁩.

إذا لم تُدخل مرسلين مسموحين، يكتب wizard القيمة dmPolicy: "pairing" بحيث يكون الجهاز مربوطاً لكن ينتظر تفويض مستخدم آمن. حالة logged-out تتطلب re-pair/reset صريحاً لدليل مصادقة WhatsApp الخاص بالملف الشخصي المحدد فقط.

نضج القناة

القناة	النضج	ملاحظة
Telegram	مثبت عمليًا	أقوى قناة بعيدة أولية مثبتة عمليًا لـ v0.1.0
Discord	موجود، غير مثبت عمليًا	المحول موجود؛ التحقق الحي غير كامل
Email	موجودة، غير مثبتة عمليًا	المحول موجود؛ المرفقات غير مدعومة
WhatsApp	تشغيلي مع خطر واجهة خارجية	محصور خلف experimental: true. يستخدم مكتبة Baileys غير الرسمية.

قائمة الموافقات

تستخدم البوابة جدول pending_approvals دائم في قاعدة بيانات الجلسات. الصفوف محدودة بواسطة profile_id. الموافقات المعلقة سؤال فقط: نتائج الرفض الحتمي والحظر الصارم لن تصبح أبداً موافقات معلقة.

estacoda gateway approvals        # سرد الموافقات المعلقة
estacoda gateway approvals approve <id>
estacoda gateway approvals deny <id>

سياسة الإشغال

عندما يرسل المستخدم إدخالاً بينما الوكيل في معالجة دورة:

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

إذا كان الدور النشط يحتوي على subagents قيد التشغيل، تُصفّ الرسائل العادية في الطابور تحت interrupt بدل إلغاء دور الأب. أوامر التحكم ما زالت تتجاوز الطابور: /stop يلغي دور الأب وعمل الأطفال، و/approve و/deny يحلان الموافقات، و/status يمكن أن يعرض حالة active-subagent محدودة، وأوامر النموذج/التحكم تحافظ على سلوك التجاوز الحالي.

التكوين في إعدادات الملف الشخصي:

{
  "channels": {
    "telegram": {
      "busyPolicy": "queue",
      "queueDepth": 3
    }
  }
}

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

الرد الصوتي

وضع الرد الصوتي في البوابة متاح عندما يكون مدير حالة الصوت وإعدادات TTS موجودة. يكون النص auto-TTS أولويًا ويفشل بشكل مفتوح إذا لم يكن المزود جاهزاً. الميديا المولدة زائلة ومحدودة بالدليل المؤقت.

/voice on|all|off|status

/voice on يضعع الدردشة لـ voice_only. /voice all (أو /voice tts) يمكّن TTS. /voice off يعطل auto-TTS. /voice status يبلغ الوضع الحالي.

حالة الصوت مخزنة في:

~/.estacoda/profiles/<profile-id>/gateway/voice-mode.json

ربط Telegram

يستخدم Telegram ربط بوت مع الرمز. يجب أن يكون الرمز في .env الخاص بالملف الشخصي كـ ESTACODA_TELEGRAM_BOT_TOKEN (أو المتغير المسمى في botTokenEnv). يجب تكوين المستخدمين والمحادثات المسموحة قبل أن يبدأ المحول في استقبال الرسائل.

estacoda channels status telegram

بث Telegram

بث Telegram خيار توصيل تجريبي تحت channels.telegram.streaming.enabled. يكون مفعلاً افتراضيًا لقنوات Telegram المُعدّة. لتعطيله، اضبط channels.telegram.streaming.enabled على false. عند تفعيله، تحرر provider tokens رسائل Telegram أثناء الدور، وتغلق حدود الأدوات رسالة البث الحالية، ويظهر تقدم الأداة تحت تلك الرسالة المغلقة، ثم تبدأ provider tokens اللاحقة رسالة بث جديدة تحت رسالة التقدم.

البث خاص بالتوصيل فقط. يبقى response.text النهائي هو المرجع، ولا تتغير حالة الجلسة، أو الذاكرة، أو تنفيذ الأدوات، أو الموافقات، أو المنتجات، أو حالة سير العمل. تستخدم التعديلات الجزئية HTML escaping خفيفًا. أما final edit أو fallback delivery فيستخدمان منسق Telegram العادي.

الحدود التشغيلية:

• يعمل بث Telegram قبل توجيه النص النهائي العادي. إذا لم يتمكن البث من توصيل الرد المكتمل، يرجع ChannelGateway إلى توصيل DeliveryRouter العادي.
• يتطلب الدور إشارة إلغاء.
• تنظيف provider fallback/failure، أو تدهور Telegram flood-control، أو الحمولات الجزئية الكبيرة، أو التباس الموافقة/المنتجات، أو الإلغاء، أو فشل final edit يمكن أن يفرض fallback للنص النهائي العادي.
• تدهور الدور النشط لا يعطل البث عالميًا للأدوار المستقبلية.

الرجوع مجرد تغيير إعداد:

{
  "channels": {
    "telegram": {
      "streaming": {
        "enabled": false
      }
    }
  }
}

أعد تشغيل أو إعادة تحميل عملية البوابة المرتبطة بذلك profile بعد تغيير الإعداد.

السجلات

سجلات البوابة للملف الشخصي النشط:

~/.estacoda/profiles/<profile-id>/logs/gateway.log

في وضع المقدّم، تظهر السجلات أيضًا في الطرفية. في الخلفية أو الخدمة المدارة، تذهب إلى ملف السجل الخاص بالملف الشخصي أو الدولية النظامية.

أنماط الفشل

العرض	السبب المحتمل	الإصلاح
فشل بدء البوابة	رمز أو متغير بيئة مفقود	أضف الرمز إلى .env الخاص بالملف الشخصي، شغل gateway diagnose
القناة غير جاهزة	مستخدم غير مسموح أو قائمة مفقودة	اضبط قائمة السماح للقناة (allowedUsers/allowedGroups؛ يسميها إعداد WhatsApp المرسلين المسموحين)
سلوك ملف شخصي خاطئ	البوابة تم تشغيلها ضد ملف آخر	اتحقق من active-profile.json أو استخدم --profile
ذاكرة تشغيل قديمة	بيانات جلسة قديمة	أعد تشغيل البوابة أو شغل gateway restart
انتهاء صلاحية الموافقة	انتهت الوقت المسموح للموافقة المعلقة	أعد إصدار الأمر؛ الموافقات لها TTL
حظر أمان صارم	الأمر يطابق الحد الأدنى الخطي	أعد صياغة الأمر؛ الحظر الصارم لا يمكن تجاوزه

وضع تحديث البوابة

estacoda update --gateway هو المسار الغير تفاعلي للتحديثات المُدارة للبوابة.

• السجل إلى ~/.estacoda/logs/update.log.
• بعد تحديث managed-source ناجح، يحاول إعادة تشغيل خدمة البوابة عبر مدير الخدمات.
• إذا لم يتم اكتشاف خدمة مدارة، يطبع توجيهات التشغيل اليدوي: estacoda gateway restart.
• لا يعيد تشغيل عمليات المستخدمين عشوائياً.

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

إيقاف البوابة أثناء إلغاء التثبيت

estacoda uninstall يوقف البوابة قبل إزالة كود التثبيت أو بيانات المستخدم.

• يستخدم مدير الخدمات (estacoda gateway uninstall-service).
• لا مكاملات pkill، killall، systemctl، أو launchctl في مسار إلغاء التثبيت.
• على Termux، يتم تخطي إزالة الخدمة النظامية; ويتم تنظيف مسارات الملفات المُغلقة المعروفة أفضل جهد.
• يحدث قبل إزالة الكود قبل الحذف بواسطة --purge.

ما لم يتم توثيقه هنا

• مرجع الأوامر المائلة بالكامل غير مدرج هنا; راجع البوابة للسلوك الموجّه للمستخدم.

صفحات ذات صلة

• البوابة — دليل البوابة من وجهة نظر المستخدم
• القنوات — إعدادات القنوات
• الصوت — سلوك الصوت
• النسخ الاحتياطي والحالة — النسخ الاحتياطي لحالة البوابة