بيئة التشغيل
بيئة تشغيل EstaCoda هي البيئة التي تملك تنفيذ الجلسة. تحمّل ملفًا شخصيًا واحدًا محددًا، وتبني البنية المشتركة لبيئة التشغيل، وتجمع المكونات المقيّدة بالجلسة، وتنفّذ عمل المزوّدين والأدوات تحت السياسة النشطة، ثم تحفظ الحالة الناتجة.
تشرح هذه الصفحة كيف يتم إنشاء بيئة التشغيل، ما الذي يُعاد استخدامه، ما الذي يُعاد بناؤه لكل جلسة، وأين تحدث الأعطال عادة.
ما هي بيئة التشغيل
تجمع بيئة التشغيل بين بنية مشتركة ومكونات تنفيذ مقيّدة بالجلسة.
| المجال | أمثلة |
|---|---|
| حالة الملف الشخصي | الإعدادات، الاعتمادات، ملفات الذاكرة، المهارات، حالة البوابة |
| بنية المزوّدين المشتركة | سجل المزوّدين، منفّذ المزوّدين، المسار الأساسي، مسارات الرجوع الاحتياطي، المسارات المساعدة |
| بنية الأدوات المشتركة | مزوّدو الأدوات المدمجة، أدوات MCP المكتشفة، مدير العمليات، backend المتصفح |
| بنية الذاكرة المشتركة | مخزن الذاكرة، مزوّد الذاكرة، فهرس الذاكرة، خدمة الاسترجاع، باني سياق prompt |
| المكونات المقيّدة بالجلسة | سجل الأدوات، منفّذ الأدوات، مخطط الأدوات، حلقة جولات المزوّد، موجّه بيئة التشغيل، حلقة الوكيل |
| الحفظ | قاعدة بيانات الجلسات، artifacts، مسار التنفيذ، cron، حالة سير العمل حيث تتوفر |
| السياسة | وضع الأمان، مخزن الثقة، التحكم بالموافقات، سياسة منع الفشل في الجلسات الفرعية |
تُحمّل إعدادات بيئة التشغيل من ملف شخصي واحد محدد فقط. تتحكم ثقة المساحة العملية في سلوك الإجراءات المحلية، وقد تؤثر في قدرات بيئة التشغيل الموثوقة مثل بدء MCP، لكنها لا تغيّر ملف الإعدادات الشخصي الذي يتم تحميله.
اختيار الملف الشخصي
تُحمّل إعدادات بيئة التشغيل من ملف شخصي واحد، بهذا الترتيب:
profileIdصريح مُمرر إلى الأمر- الملف الشخصي النشط إذا لم يُمرر ملف شخصي صريح
defaultإذا لم يكن هناك ملف شخصي نشط
لا يوجد دمج بين إعدادات المستخدم والمشروع. تعيش حالة الملف الشخصي تحت:
~/.estacoda/profiles/<id>/
تُقيّد الجلسات بـ profile_id في قاعدة بيانات الجلسات. يرفض createRuntime() جلسة موجودة إذا كانت تلك الجلسة تنتمي إلى ملف شخصي مختلف عن ملف بيئة التشغيل الجاري إنشاؤها.
راجع البنية لخريطة حدود الحالة الكاملة.
إنشاء بيئة التشغيل
يمر إنشاء بيئة التشغيل بثلاث مراحل عملية.
المرحلة A: البنية المشتركة
يبني createRuntime() البنية المشتركة للملف الشخصي والجلسة المحددين.
ينشئ أو يحل:
| البنية | أمثلة |
|---|---|
| مسارات الحالة | مجلد الحالة العام، مجلد حالة الملف الشخصي، جذر المساحة العملية |
| المخازن | مخزن الذاكرة، مخزن artifacts، مخزن cron، قاعدة بيانات الجلسات |
| بنية الذاكرة | مخزن فهرس الذاكرة، مزامنة فهرس الذاكرة، استرجاع الذاكرة المحلية، سياق memory prompt |
| بنية المزوّدين | سجل المزوّدين، منفّذ المزوّدين، المسار الأساسي، مسارات الرجوع الاحتياطي، المسارات المساعدة |
| بنية المهارات | المهارات الرسمية، مهارات الملف الشخصي، المهارات المستخرجة من الحزم، مخازن تطور المهارات |
| بنية MCP | خوادم MCP المهيأة وأدوات MCP المكتشفة، مقيّدة بحالة قدرات بيئة التشغيل الموثوقة |
| حالة العمليات والوسائط | مدير العمليات، جذر وسائط القنوات، ذاكرة الصوت المؤقتة، ذاكرة الصور المؤقتة |
| بنية المتصفح | backend المتصفح، دورة حياة CDP المحلي الخاضعة للإشراف، التنظيف الطارئ |
| بنية الصوت | عامل Whisper المحلي عند تهيئته |
| بنية prompt | محمّل سياق المشروع، موسّع مراجع السياق، خدمة ضغط الجلسة |
| بنية التفويض المشتركة | FileStateTracker، مسارات الأصل، بنية المزوّدين والأدوات المشتركة |
| مسار التنفيذ | TrajectoryRecorder للجلسة النشطة |
يُحقن التحكم بالموافقات أثناء إنشاء بيئة التشغيل، وتستخدمه طرق بيئة التشغيل التي تمنح الموافقات أو تفحصها أو تلغيها.
المرحلة B: المكونات المقيّدة بالجلسة
يجمع AgentLoopBuilder.buildSession() مكونات التنفيذ المقيّدة بالجلسة.
ينشئ:
| المكوّن | الدور |
|---|---|
ToolRegistry | سجل الأدوات المرئي للجلسة |
ToolExecutor | ينفّذ إجراءات الأدوات تحت سياسة الأمان |
ToolCallPlanner | يربط استدعاءات أدوات المزوّد بخطط أدوات قابلة للتنفيذ |
RunRecorder | يسجل أحداث الجولة والأدوات والجلسة وبيانات مسار التنفيذ |
MemoryRecallOrchestrator | يجهّز سياق الاسترجاع لكل جولة |
ToolPlanRunner | يشغّل الأدوات المخططة، ويدير التوازي، وحدود الفشل، وحزم المتابعة |
ProviderTurnLoop | يشغّل تكرارات المزوّد وينهي خرج المزوّد |
SkillPlaybookRunner | ينفّذ خطوات أدوات skill playbook |
NativeToolExecutor | ينفّذ أوامر بيئة التشغيل الأصلية |
IntentRouter | يوجّه قصد المستخدم إلى مسارات بيئة التشغيل والمهارات |
RuntimeRouter | يختار التنفيذ الأصلي، أو تنفيذ المهارة، أو التنفيذ المدعوم بالمزوّد |
AgentLoop | ينسّق حد الجولة والحفظ |
يحدث تسجيل الأدوات على مراحل حتى تحصل الأدوات على سياق بيئة التشغيل والجلسة الصحيح:
pre-skill-visibilitypost-skill-visibilitypost-memory-providerpost-tool-executor
تُضاف أدوات MCP المكتشفة إلى سجل الأدوات المرئي للجلسة أثناء إنشاء الجلسة، إلى جانب مراحل تسجيل الأدوات المدمجة.
المرحلة C: ربط سير العمل
بعد عودة AgentLoopBuilder.buildSession()، يربط createRuntime() دعم سير العمل عندما تكون قاعدة بيانات الجلسات من نوع SQLiteSessionDB.
يشمل ربط سير العمل:
| المكوّن | الدور |
|---|---|
SQLiteWorkflowStore | يحفظ تشغيلات سير العمل، والخطوات، والأحداث، والأقفال، وartifacts |
WorkflowLockService | ينسّق أقفال سير العمل |
WorkflowEngine | ينفّذ خطط سير العمل |
WorkflowProcessRegistry | يتتبع العمليات المرتبطة بسير العمل |
WorkflowEventSummaryService | يضغط سجل أحداث سير العمل |
WorkflowCommandDispatcher | يتعامل مع أوامر سير العمل |
WorkflowAgentLoopAdapter | يمرّر جولات سير العمل النشطة عبر حلقة الوكيل |
WorkflowRestartRecovery | يعلّم التشغيلات المنقطعة ويستعيد الأقفال القديمة |
يحاول النظام ربط سير العمل دون أن يجعل فشله سببًا لإسقاط إنشاء بيئة التشغيل. إذا فشل إعداد سير العمل، يمكن أن يستمر إنشاء بيئة التشغيل من دون دعم سير العمل، ويجب أن تبلغ أوامر سير العمل المتخصصة عن القدرة المفقودة.
حل مسارات المزوّدين
تحل بيئة التشغيل ثلاثة أنواع من مسارات المزوّدين.
المسار الأساسي
يأتي المسار الأساسي من model في إعدادات الملف الشخصي. يُستخدم للاستدلال العادي.
إذا لم يكن المسار الأساسي قابلًا للتشغيل بسبب غياب الاعتمادات، أو تقادم النموذج، أو فشل المزوّد، يبلغ EstaCoda عن الفشل. لا يرجع بصمت إلى مسار آخر إلا إذا كانت مسارات الرجوع الاحتياطي مهيأة.
مسارات الرجوع الاحتياطي
تأتي مسارات الرجوع الاحتياطي من model.fallbacks. لا تُجرّب إلا عندما يفشل المسار الأساسي أثناء التنفيذ.
تحافظ مسارات الرجوع الاحتياطي على بيانات المسار مثل:
| البيانات | الاستخدام |
|---|---|
apiKeyEnv | متغير بيئة الاعتمادات |
baseUrl | نقطة نهاية المزوّد |
apiMode | وضع الموائم، مثل OpenAI-compatible أو OpenAI Responses |
authMethod | وضع الاعتماد أو المصادقة |
إذا فشلت كل مسارات الرجوع الاحتياطي، تبلغ الجولة عن الخطأ وتتوقف.
المسارات المساعدة
المسارات المساعدة هي مسارات نماذج متخصصة مهيأة تحت auxiliaryModels. تستخدم سجل المزوّدين ومسار التنفيذ نفسهما المستخدمين للمسارات الأساسية.
| الخانة | الغرض |
|---|---|
vision | تحليل الصور |
compression | ضغط الجلسة دلاليًا |
assessor | تصنيف الموافقات الذكي |
web_extract | استخراج الويب |
session_search | البحث الدلالي في الجلسات |
mcp | تفويض أدوات MCP |
memory_flush | عمليات الذاكرة |
delegation | تفويض الوكلاء الفرعيين |
skills_library | توزيع المهارات |
title_generation | توليد عنوان الجلسة |
curator | تنقيح الذاكرة |
memory_compaction | اختزال ملفات الذاكرة |
profile_context | توليد سياق الملف الشخصي |
تفشل أسماء المهام المساعدة غير المدعومة أثناء تطبيع الإعدادات.
حد تنفيذ المزوّدين
يعامل ProviderTurnLoop خرج المزوّد كقابل للاستخدام فقط بعد الإنهاء. يمكن للبث أن يصدر رموزًا مرئية حية، لكن هذه الأسطح لا تستخدم إلا الخرج المرئي النهائي:
| السطح | يستخدم الخرج النهائي |
|---|---|
| استدعاءات الأدوات القابلة للتنفيذ | نعم |
| محتوى المساعد المحفوظ | نعم |
| السجل المرسل إلى المزوّد | نعم |
| الملخصات والضغط | نعم |
| مدخلات الذاكرة | نعم |
| تعلم المهارات | نعم |
| التصدير | نعم |
قواعد أمان البث:
- تُجمع أجزاء استدعاءات الأدوات المبثوثة أثناء بقاء البث مفتوحًا.
- أخطاء البث تتخلص من الأجزاء المجموعة.
- البث غير المكتمل يبقى فشلًا من جهة المزوّد.
[DONE]علامة نقل داخلية، وليست خرجًا ظاهرًا للمستخدم.- اكتمال النقل للنص المرئي فقط قد ينتهي بـ
finishReason: "unknown". - اكتمال النقل مع أجزاء أدوات غير منتهية يفشل كـ
incomplete-stream. - تدعم OpenAI-compatible chat completions البث.
- تنفيذ OpenAI Responses موجود. بث Responses ليس جزءًا من خط أساس بيئة التشغيل المدعوم حاليًا.
ProviderExecutionResult.toolCalls هو المرجع الحاسم. استدعاءات الأدوات المقتطعة بسبب الطول تُعاد مرة واحدة على سلسلة المسار الناجح. إذا بقيت مقتطعة بسبب الطول بعد الإعادة، تعيد بيئة التشغيل نص رفض حتميًا ولا تنفّذ أي أدوات.
الاستدلال مادة مخفية. الاستدلال الخام محلي للجولة فقط. الخرج المرئي، والسجل المرسل إلى المزوّد، والضغط الدلالي، والملخصات، والذاكرة، وتعلم المهارات، والتصدير تزيل الاستدلال الخام وكتل الاستدلال المخفية المضمنة.
يمكن للنص المرئي ذي finishReason: "length" أن يتابع على سلسلة المسار الناجح. رسائل المتابعة الاصطناعية محلية فقط. لا تُحفظ الأجزاء الوسطية. يُحفظ النص المرئي النهائي مرة واحدة. تستخدم المتابعة قصّ التداخل الدقيق.
حد الأدوات
المزوّد لا يعرف كيف ينفّذ الأدوات. منفّذ الأدوات لا يعرف كيف يستدعي المزوّدين. حلقة الوكيل تربط الاثنين.
| المكوّن | المسؤولية |
|---|---|
| المزوّد | يعيد نصًا مرئيًا واستدعاءات أدوات نهائية |
ToolCallPlanner | يحل استدعاءات أدوات المزوّد إلى تعريفات أدوات معروفة |
ToolExecutor | ينفّذ إجراءات أدوات فعلية تحت السياسة |
ToolPlanRunner | يشغّل خطط الأدوات ويبني حزم المتابعة |
ProviderTurnLoop | يعيد نتائج الأدوات إلى المزوّد عند الحاجة |
AgentLoop | ينسّق حد الجولة الكامل |
تصنيفات مخاطر الأدوات تقود الحجب والموافقة:
| تصنيف الخطر | المعنى |
|---|---|
safe | قراءة منخفضة الخطر أو حساب محلي |
caution | يحتاج إلى عناية أو قد يكشف حالة محلية |
external-side-effect | يمكن أن يؤثر في أنظمة خارجية |
irreversible | يمكن أن ينشئ تغييرات يصعب عكسها |
تُقيّد سياسة الأمان على أساس targetKey الموحّد، لا على أساس ملخص العرض.
دورة حياة بيئة تشغيل CLI
في الوضع التفاعلي لـ CLI، تبقى بيئة التشغيل قائمة عبر الجولات داخل الجلسة النشطة. هذا يتجنب إعادة بناء بيئة التشغيل كاملة بعد كل رسالة، ويحافظ على الحالة المقيّدة بالجلسة متاحة في الذاكرة.
يتم التخلص من بيئة تشغيل CLI عند خروج الجلسة أو إيقاف العملية. يوقف التخلص الموارد التي تملكها بيئة التشغيل مثل خوادم MCP، وموارد دورة حياة المتصفح، وعوامل Whisper المحلية، ومزامنة فهرس الذاكرة، واتصالات قاعدة بيانات الجلسات عندما تكون بيئة التشغيل هي المالكة لها.
دورة حياة بيئة تشغيل البوابة
يستخدم وضع البوابة RuntimeCache.
لا تُنشأ بيئة تشغيل البوابة من الصفر لكل جولة واردة. تطلب البوابة من الذاكرة المؤقتة بيئة تشغيل مرتبطة بـ sessionId وruntime fingerprint الحالي.
| حالة الذاكرة المؤقتة | السلوك |
|---|---|
| لا يوجد إدخال | إنشاء بيئة تشغيل |
| تطابق في الذاكرة المؤقتة | إعادة استخدام بيئة التشغيل |
| عدم تطابق runtime fingerprint | إنشاء بيئة تشغيل بديلة وتعطيل الإدخال القديم |
| إدخال معلّق | إنشاء بيئة تشغيل بديلة |
| إبطال صريح | تعليق الإدخال واستبداله عند الاستخدام التالي |
| تجاوز مهلة الخمول | التخلص من بيئة التشغيل الخاملة |
| تجاوز حد LRU | التخلص من أقل بيئات التشغيل الخاملة استخدامًا مؤخرًا |
الإعدادات الافتراضية في التنفيذ الحالي:
| الإعداد | الافتراضي |
|---|---|
| الحد الأقصى لبيئات التشغيل المخزنة مؤقتًا | 50 |
| مهلة الخمول | 30 minutes |
| مهلة التخلص | 10 seconds |
هذه افتراضيات تنفيذ، وليست ضمانات API عامة. افحص RuntimeCache للقيم الحالية.
تبطل البوابة بيئات التشغيل المخزنة مؤقتًا عندما تتغير حالة تؤثر في السياسة، مثل منح أو إلغاء موافقة دائمة أو تغيير تجاوز نموذج الجلسة.
تُفهرس إدخالات ذاكرة بيئة التشغيل المؤقتة حسب sessionId. تُقيّد صفوف الجلسات بـ profile_id، ويرفض createRuntime() حالات عدم تطابق الملف الشخصي والجلسة. مع ذلك، يجب أن تعامل وثائق ذاكرة بيئة التشغيل المؤقتة هوية الجلسة كحد حساس.
بيئة تشغيل التفويض
يبني delegate_task حلقات وكلاء فرعيين عبر DefaultChildAgentLoopFactory، الذي يستخدم AgentLoopBuilder المشترك.
تُعاد استخدام البنية التي يملكها الأصل:
| المعاد استخدامه من الأصل | أمثلة |
|---|---|
| بنية المزوّدين المشتركة | سجل المزوّدين، منفّذ المزوّدين، المسارات |
| المخازن | قاعدة بيانات الجلسات، مزوّد الذاكرة، مخزن artifacts |
| بنية بيئة التشغيل المشتركة | مدير العمليات، backend المتصفح، مخزن الثقة |
| بنية MCP | تسجيلات أدوات MCP |
| حالة التفويض | SubagentRegistry، FileStateTracker |
المكونات المقيّدة بالجلسة تكون جديدة لكل جلسة فرعية. تمتلك الجلسات الفرعية سجل أدوات، ومنفّذ أدوات، وحلقة جولات مزوّد، وموجّه بيئة تشغيل، وحلقة وكيل خاصة بها.
تُحفظ الجلسات الفرعية مع معرف الجلسة الأصلية، ودور الجلسة الفرعية وعمق التفويض، وصلاحية الأدوات الفعلية، والتشخيصات المحذوفة أو المحجوبة، وبيانات تجاوز النموذج حيث توجد، وبيانات كبت بيئة التشغيل.
تُحل صلاحية أدوات الجلسة الفرعية قبل بناء schemas المزوّد. يحتفظ الملف الافتراضي للجلسة الفرعية فقط بأدوات read-only-local وread-only-network المرئية للأصل، ويزيل الأدوات المحجوبة بالتطابق الدقيق أو بالبادئة، ويستبعد مجموعات أدوات المتصفح والوسائط وMCP. يبقى terminal.run مستبعدًا.
موافقات الجلسات الفرعية غير تفاعلية وتفشل باتجاه المنع. قرارات المنع الصارمة تعمل أولًا. أي إجراء يحتاج إلى سؤال، أو يستخدم منح الأصل، أو يستخدم طوابير الموافقة المعلقة، أو يعتمد على موافقات محفوظة أو موافقات جلسة، يُرفض داخل بيئة تشغيل الجلسة الفرعية.
تأخذ متابعة حالة الملفات لقطات من قراءات الأصل قبل التفويض، وتصدر تحذيرات استشارية عن الملفات القديمة عندما تمس كتابات الجلسة الفرعية مسارات متتبعة. ذاكرة النتيجة اختيارية، وتحفظ معاينة محدودة للمهمة مع بيانات حالة/سبب حتمية.
تركيب memory prompt
يُجهّز سياق الذاكرة لكل جولة قبل تركيب prompt المزوّد. يجمع MemoryRecallOrchestrator سياق الاسترجاع، ويعرض MemoryPromptContextBuilder سياق memory prompt المرجعي.
يشمل مسار تركيب prompt:
- سياق memory prompt المرجعي
- سياق المشروع، بما في ذلك
AGENTS.md - إشعار ضغط اختياري
- سجل الجلسة
- استرجاع الجلسة والاسترجاع الخارجي اختياريًا
- رسالة المستخدم الحية
- مرفقات القنوات
- القصد، وتعليمات المهارة، وإعداد المهارة، وموارد المهارة
- خطة سير العمل
- قائمة الأدوات
- سياق مرجعي صريح
- نتائج الأدوات أو تغذية المتابعة الراجعة
الاسترجاع، والاسترجاع الخارجي، وملخصات الضغط هي سياق مرجعي فقط. تُضمّن من أجل الاستمرارية، لكنها لا تُعامل كتعليمات موثوقة.
الضغط الدلالي لجولة المزوّد يملكه AgentLoop، لا ProviderTurnLoop. عندما يكون مفعّلًا ويتجاوز العتبة، يحافظ AgentLoop على سجل الأصل عبر ضغطه داخل جلسة فرعية قبل تركيب prompt المزوّد.
التخلص من بيئة التشغيل
التخلص من بيئة التشغيل مسؤول عن تنظيف الموارد التي تملكها بيئة التشغيل.
يشمل التخلص:
| المورد | التنظيف |
|---|---|
| دورة حياة المتصفح | إيقاف دورة الحياة، تنظيف الجلسات، إغلاق backend المملوك |
| Whisper المحلي | التخلص من العامل عند وجوده |
| خوادم MCP | إيقاف خوادم MCP المحمّلة |
| مزامنة فهرس الذاكرة | التخلص من عامل المزامنة |
| قاعدة بيانات الجلسات | إغلاق الاتصال عندما تملكه بيئة التشغيل |
يتم التخلص من بيئات التشغيل المخزنة مؤقتًا في البوابة عبر RuntimeCache.safeDispose()، الذي يطبق مهلة حتى لا يمنع التخلص العالق تنظيف الذاكرة المؤقتة إلى الأبد.
فشل بدء بيئة التشغيل
| الفشل | ماذا يحدث | أول أمر للفحص |
|---|---|---|
| إعداد ملف شخصي مفقود | يفشل إنشاء بيئة التشغيل مبكرًا | estacoda verify |
| عدم تطابق الملف الشخصي والجلسة | يرفض إنشاء بيئة التشغيل الجلسة | estacoda sessions list |
| المسار الأساسي غير قابل للتشغيل | تبلغ الجولة عن فشل المزوّد/النموذج | estacoda model diagnose |
| مسار مساعد مفقود | يرجع النظام الفرعي المستدعي حيث يكون الرجوع مدعومًا | estacoda model show |
| خادم MCP غير متاح | لا تُسجّل أدوات MCP؛ تستمر بيئة التشغيل | estacoda gateway diagnose |
| backend المتصفح غير متاح | تبلغ أدوات المتصفح عن أخطاء اتصال | estacoda doctor |
| قفل SQLite أو تلفه | تفشل عمليات الجلسات أو سير العمل | افحص أذونات ~/.estacoda/sessions.sqlite |
| ربط سير العمل غير متاح | تستمر بيئة التشغيل من دون دعم سير العمل | أوامر سير العمل والسجلات المرتبطة به |
كيفية فحص حالة بيئة التشغيل
# المسار الأساسي الحالي والجاهزية
estacoda model show
# تشخيص حي ضد المزوّد المهيأ
estacoda model diagnose
# عرض المزوّدين المعروفين في الكتالوج
estacoda model list
# جاهزية الإعداد الكاملة
estacoda verify
# التشخيص العام
estacoda doctor
# جاهزية البوابة
estacoda gateway diagnose
# حالة البوابة الكاملة، بما في ذلك حالة ذاكرة بيئة التشغيل المؤقتة عند توفرها
estacoda gateway status
# الجلسات الأخيرة
estacoda sessions list
# الجلسة الحالية
estacoda sessions current
# مخطط اعتماديات الكود
estacoda knowledge code summary
estacoda knowledge code refresh
مرتبط
- البنية - بنية النظام وحدود الحالة
- مرجع المزوّدين - مصفوفة نضج المزوّدين
- المزوّدون - إعداد المزوّدين من منظور المستخدم
- الأدوات - نظرة عامة على الأدوات
- تفاصيل البوابة الداخلية - توجيه البوابة، والموافقات، وسلوك القنوات