البوابة الداخلية

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

هذه الصفحة للمشرفين والمشغّلين الذين يفحصون estacoda gateway run، أو خدمات البوابة المُدارة، أو تسليم الرسائل عبر القنوات، أو الموافقات، أو الجولات العالقة، أو سلوك دورة حياة الموائمات. إعداد القنوات الموجه للمستخدم موجود في القنوات. كتيبات التشغيل موجودة في عمليات البوابة.

---

ما الذي تغطيه هذه الصفحة

استخدم هذه الصفحة عندما تحتاج إلى فحص:

• لماذا بدأت عملية البوابة أو لم تبدأ
• ما موائمات القنوات التي سُجلت وهل هي سليمة
• لماذا لم تتحول رسالة واردة إلى جولة
• هل أُعيد استخدام بيئة التشغيل، أو أُعيد إنشاؤها، أو عُلّقت، أو أُخرجت من Runtime cache
• لماذا اعتُبرت جلسة مشغولة أو عالقة
• كيف تُصف الموافقات القادمة عبر القنوات وتُحل
• أين تعيش ملفات حالة البوابة
• ما hooks والتشخيصات التي يجب أن توجد لتشغيل بوابة معين

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

---

شكل البوابة

تتكوّن عملية البوابة من ثلاث طبقات:

الطبقة	الدور
المشرف	يملك دورة حياة العملية، والأقفال، والموائمات، وRuntime cache، والجولات النشطة، وticks الخاصة بـ cron، والإيقاف.
بوابة القنوات	تربط رسائل القنوات بالجلسات، وتفحص تفويض القناة، وتوجّه الموافقات، وتسلّم الردود.
بيئة التشغيل	تشغّل حلقة الوكيل العادية للجلسة والملف الشخصي المحلولين.

يمكن أن تشمل موائمات القنوات المهيأة Telegram وDiscord وEmail وWhatsApp وأي موائم مسجل يطبق عقد القنوات. نضج الموائم خاص بكل قناة. يجب ألا تفترض البوابة أن كل الموائمات تملك دلالات التسليم، أو polling، أو pairing، أو الموافقات نفسها.

تُعامل رسائل القنوات الواردة كجولات. تحل البوابة سطح القناة/الجلسة، وتستعير أو تنشئ بيئة تشغيل لتلك الجلسة، وتشغّل حلقة الوكيل، ثم توجّه النتيجة عبر طبقة تسليم القناة.

---

المشرف

GatewaySupervisor في src/gateway/supervisor.ts هو المنسق الأعلى مستوى.

يوصل:

المسؤولية	المكوّن
دورة حياة الموائم	AdapterResilienceSupervisor لكل موائم
Runtime cache	RuntimeCache مفهرسة حسب الجلسة
تتبع الجولات	ActiveTurnRegistry
صف الموافقات	GatewayApprovalQueue
توجيه الرسائل/الجلسات	ChannelGateway
توحيد التسليم	DeliveryRouter
تنفيذ cron	tickCron مع CronStore
نظافة الجلسات	SessionHygieneService
حالة الصوت	VoiceStateManager
مراقبة دورة الحياة	HookRegistry

يملك المشرف شؤون مستوى العملية. لا يتخذ قرارات سلامة المزوّد أو الأدوات مباشرة؛ تبقى تلك القرارات في بيئة التشغيل، وتنفيذ الأدوات، وسياسة الأمان، وصف موافقات القنوات.

---

حدود الحالة

حالة البوابة محلية للملف الشخصي. للملف الشخصي <id>، تعيش حالة البوابة العادية تحت:

~/.estacoda/profiles/<id>/gateway/

تشمل الملفات المهمة:

الملف	الغرض
gateway.pid	سجل PID للبوابة الأمامية أو غير المُدارة.
gateway.lock	قفل عملية يمنع تشغيل أكثر من بوابة للحالة نفسها الخاصة بالملف الشخصي.
gateway-state.json	لقطة دورة حياة المشرف.
adapter-runtime-state.json	لقطة حالة بيئة تشغيل الموائمات.
runtime-cache-state.json	تشخيصات Runtime cache والجولات النشطة.
.clean_shutdown	علامة تُكتب بعد مسار إيقاف نظيف.
channel-sessions.json	حالة ربط جلسات القنوات.
channel-approvals.json	حالة سطح موافقات القنوات.
delivery/	حالة فائض التسليم وartifacts.
logs/	سجلات تشخيص محلية للبوابة مثل أخطاء التسليم.

يمكن لبعض المساعدات منخفضة المستوى أن تقبل أيضًا مجلد حالة عام وتشتق ~/.estacoda/gateway/. في مسارات بيئة التشغيل العادية الواعية بالملف الشخصي، استخدم مسار حالة البوابة المحلي للملف الشخصي من resolveProfileStateHome(...).

---

Runtime cache

تستخدم البوابة RuntimeCache لتجنب إنشاء بيئة تشغيل جديدة لكل جولة واردة. تُفهرس بيئات التشغيل حسب sessionId ويُعاد استخدامها عندما يظل runtime fingerprint مطابقًا.

سلوك Runtime cache	الافتراضي
الحد الأقصى للإدخالات	50
مهلة الخمول	30 دقيقة
عدم تطابق البصمة	ينشئ بيئة تشغيل جديدة ويتقاعد الإدخال القديم.
إدخال معلّق	ينشئ بيئة تشغيل جديدة عند الاستعارة التالية.
مهلة التخلص	10 ثوانٍ لكل محاولة التخلص من بيئة تشغيل.

تشمل أسباب الإخراج من Runtime cache:

السبب	المحفّز
ttl	كان الإدخال خاملًا مدة أطول من TTL المهيأ.
lru	تجاوزت Runtime cache الحد الأقصى لعدد الإدخالات.
suspend	عُلّقت بيئة التشغيل بعد خطأ أو مسار حلقة عالقة.
fingerprint-mismatch	تغيرت بصمة الإعدادات/النموذج/بيئة التشغيل.
invalidate	إبطال صريح.
disposeAll	إيقاف البوابة أو التخلص من Runtime cache.

تُكتب تشخيصات Runtime cache إلى runtime-cache-state.json. هذه الحالة تشخيصية فقط: تسجل أعدادًا، ومفاتيح جولات عالقة مجزأة، وملخصات معلّقة، وhash لبصمة بيئة التشغيل. يجب ألا تحتوي على نصوص رسائل، أو prompts، أو chat IDs خام، أو أسرار.

---

مرونة الموائمات

يُغلّف كل موائم قناة داخل AdapterResilienceSupervisor.

يتعامل الغلاف مع:

• دورة حياة البدء والإيقاف
• أخطاء البدء وpoll القابلة لإعادة المحاولة
• حالة بيئة تشغيل الموائم
• إطلاق hooks للمراقبة
• تصنيف أخطاء جسر WhatsApp حيث ينطبق ذلك

افتراضيات backoff:

المعامل	الافتراضي
التأخير الأساسي	ثانية واحدة
الحد الأقصى للتأخير	60 ثانية
الحد الأقصى للمحاولات	5
jitter	20%

يمكن أن تنتقل حالة الموائم عبر حالات مثل starting وhealthy وdegraded وretry_scheduled وfailed وstopped. لا يوفّر كل موائم polling. إذا كان لدى الموائم pollOnce، يستطيع المشرف تشغيله. أما الموائمات القائمة على callbacks فيمكنها تسليم الرسائل عبر handler البدء الخاص بها.

---

الجولات النشطة

يتتبع ActiveTurnRegistry الجولات الجارية حسب مفتاح جلسة بوابة. يُشتق المفتاح عادة من هوية القناة/الجلسة، مثل سطح دردشة Telegram.

الافتراضيات:

السلوك	الافتراضي
عتبة التعليق	5 دقائق
الحد الأقصى لفحوصات التعليق	3
مهلة تهدئة إقرار الانشغال	30 ثانية
حجم سجل الجولات العالقة	50

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

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

---

صف الموافقات

تستخدم موافقات البوابة جدول pending_approvals دائمًا في قاعدة بيانات جلسات SQLite. الصفوف مقيّدة بالملف الشخصي وقد تكون مقيّدة بالجلسة أيضًا.

GatewayApprovalQueue مسؤول عن:

• إنشاء صفوف الموافقات المعلقة
• polling للصفوف الموافق عليها أو المرفوضة
• إنهاء صلاحية الموافقات القديمة
• حل الموافقات بالمعرف
• إبقاء قرارات hardline والرفض الحتمي خارج صف الموافقات القابلة للموافقة

موافقات البوابة المعلقة ask-only. قرارات الرفض الحتمي وحواجز السلامة الصارمة يجب ألا تصبح صفوف موافقة دائمة يمكن الموافقة عليها لاحقًا من قناة.

يجب ألا تعدّل موائمات القنوات صف الموافقات مباشرة. تنسيق الموافقات يخص ChannelGateway والصف.

---

إدارة الخدمة

يمكن تشغيل البوابة في الواجهة الأمامية أو كخدمة مُدارة.

أوامر الواجهة الأمامية والتشخيص:

estacoda gateway run
estacoda gateway run --dry-run
estacoda gateway run --once
estacoda gateway run --profile <id>

أوامر الخدمة المُدارة:

estacoda gateway install
estacoda gateway install --profile <id>
estacoda gateway install --force
sudo estacoda gateway install --system --run-as-user <user>

estacoda gateway start
estacoda gateway stop
estacoda gateway restart

estacoda gateway uninstall
sudo estacoda gateway uninstall --system

مديرو الخدمة المدعومون هم خدمات Linux systemd بنطاق المستخدم/النظام وخدمات macOS launchd بنطاق المستخدم. التثبيت بنطاق المستخدم هو المسار العادي. التثبيت بنطاق النظام يتطلب systemd، وصلاحيات root، و--run-as-user صريحًا.

الخدمات المولّدة تستدعي gateway run --profile <id>. تستخدم قيم بيئة خدمة صريحة، وليس بالضرورة بيئة shell التفاعلية للمشغّل. ضع رموز القنوات واعتمادات المزوّدين في .env الخاص بالملف الشخصي.

---

دورة الحياة

يعمل بدء التشغيل عادة كالتالي:

1. حل الملف الشخصي النشط أو المطلوب.
2. فحص مجلد حالة البوابة وحالة القفل.
3. الحصول على gateway.lock.
4. كتابة gateway.pid وgateway-state.json.
5. تحميل إعدادات بيئة التشغيل وإعدادات القنوات.
6. بناء أغلفة مرونة الموائمات.
7. بناء خدمات البوابة مثل التسليم، والموافقات، وRuntime cache، وسجل الجولات النشطة.
8. بدء دورة حياة الموائمات.
9. تشغيل ticks الخاصة بالمشرف، وpolling الموائمات حيث يتوفر، وticks الخاصة بـ cron، وانتهاء صلاحية الموافقات، ونبضات التشخيص.

يعمل الإيقاف عادة كالتالي:

1. التوقف عن قبول عمل جديد.
2. تفريغ الجولات النشطة حتى المهلة المهيأة.
3. إيقاف الموائمات.
4. التخلص من إدخالات Runtime cache.
5. حذف ملفات PID، وحالة المشرف، وحالة بيئة تشغيل الموائمات.
6. تحرير gateway.lock.
7. كتابة .clean_shutdown فقط لمسار إيقاف نظيف.

إذا لم تترك العملية السابقة دليل إيقاف نظيف موثوقًا، يعامل بدء التشغيل التشغيل السابق كغير نظيف ويشغّل تنظيف الحالة القديمة حيث يكون ذلك آمنًا. لا تُعاد الجولات الجارية تلقائيًا من ذاكرة العملية. تبقى قاعدة بيانات الجلسات السجل الدائم لحالة الجلسات المكتملة والموافقات المعلقة.

---

Hooks

HookRegistry يطلق أحداث دورة حياة best-effort. hooks مراقبة داخلية، وليست مسار تحكم. يجب ألا يكسر فشل handler hook البوابة.

تشمل فئات الأحداث:

الفئة	أمثلة
المشرف	supervisor:start، supervisor:stop، supervisor:drain:start، supervisor:drain:complete، supervisor:crash
الموائم	adapter:start، adapter:stop، adapter:error، adapter:retry، adapter:degraded، adapter:recovered
الجلسة	session:turn:start، session:turn:complete، session:turn:error، session:turn:abort
Runtime cache	session:cache:hit، session:cache:miss، session:cache:evict
التسليم	delivery:success، delivery:error
الصوت/STT	gateway:stt:preprocess
Cron	cron:tick:start، cron:tick:complete، cron:job:fail

قواعد الخصوصية:

• لا تصدر نصوص رسائل، أو prompts، أو خرج نموذج، أو tokens، أو هويات موائم خام، أو مفاتيح HMAC خام، أو أسرار موافقات، أو chat/user IDs خام.
• استخدم معرفات مجزأة عندما تكون مفاتيح الجلسات أو هويات القنوات مطلوبة.
• الأعداد، والمدد، والقيم المنطقية، ونوع القناة، ونوع الموائم، ومعرفات الجلسات المبهمة، ومعرفات الجولات، ومعرفات الإدخالات، ومعرفات المهام، ومعرفات التنفيذ، وفئات الأخطاء مقبولة.

---

الفحص والاختبارات

أوامر مفيدة:

estacoda gateway diagnose
estacoda gateway status
estacoda gateway approvals
estacoda gateway run --dry-run
estacoda gateway run --once

ملفات مفيدة:

• src/gateway/supervisor.ts
• src/gateway/adapter-resilience.ts
• src/gateway/active-turn-registry.ts
• src/gateway/approval-queue.ts
• src/gateway/hook-registry.ts
• src/gateway/runtime-cache-state.ts
• src/gateway/service-manager.ts
• src/channels/channel-gateway.ts
• src/channels/delivery-router.ts
• src/channels/session-hygiene-service.ts
• src/runtime/runtime-cache.ts

فحوصات مركزة:

pnpm exec vitest run src/gateway/supervisor.test.ts
pnpm exec vitest run src/gateway/adapter-resilience.test.ts
pnpm exec vitest run src/gateway/active-turn-registry.test.ts
pnpm exec vitest run src/gateway/approval-queue.test.ts
pnpm exec vitest run src/gateway/runtime-cache-state.test.ts
pnpm exec vitest run src/gateway/service-manager.test.ts
pnpm exec vitest run src/runtime/runtime-cache.test.ts
pnpm exec vitest run src/channels/channel-gateway.test.ts

عند فحص مشكلة في البوابة، ابدأ بـ estacoda gateway status، ثم افحص مجلد البوابة المحلي للملف الشخصي بحثًا عن لقطات الحالة. إذا احتوت ملفات الحالة على نصوص رسائل خام، أو chat IDs خام، أو tokens، أو محتوى prompt، فاعتبر ذلك bug.

---

مرتبط

• البنية - بنية النظام وحدود الحالة
• بيئة التشغيل - إنشاء بيئة التشغيل وحدود الجلسات
• بيئة تشغيل الأدوات - حدود تنفيذ استدعاءات أدوات المزوّد
• عمليات البوابة - إدارة الخدمة وكتيبات التشغيل
• القنوات - إعداد القنوات وتهيئتها
• الأمان والموافقات - سلوك الموافقات