أداة Python ووقت تشغيل IPython

تصف هذه الوثيقة مكدس تنفيذ Python الحالي في packages/coding-agent. تغطي سلوك الأداة، ودورة حياة النواة/البوابة، ومعالجة البيئة، ودلالات التنفيذ، وعرض المخرجات، وأنماط الفشل التشغيلي.

النطاق والملفات الرئيسية

• واجهة الأداة: src/tools/python.ts
• تنسيق النواة لكل جلسة/استدعاء: src/ipy/executor.ts
• بروتوكول النواة + تكامل البوابة: src/ipy/kernel.ts
• منسق البوابة المحلية المشتركة: src/ipy/gateway-coordinator.ts
• عارض الوضع التفاعلي لتشغيل Python الذي يبدأه المستخدم: src/modes/components/python-execution.ts
• تصفية وقت التشغيل/البيئة وتحليل مسار Python: src/ipy/runtime.ts

ما هي أداة Python

تُنفّذ أداة python خلية Python واحدة أو أكثر عبر نواة مدعومة ببوابة Jupyter Kernel Gateway (وليس عن طريق إطلاق python -c مباشرةً لكل خلية).

معاملات الأداة:

{
  cells: Array<{ code: string; title?: string }>;
  timeout?: number; // بالثواني، محدودة بين 1..600، الافتراضي 30
  cwd?: string;
  reset?: boolean; // إعادة تعيين النواة قبل الخلية الأولى فقط
}

الأداة تعمل بـ concurrency = "exclusive" للجلسة، لذا لا تتداخل الاستدعاءات.

دورة حياة البوابة

الأوضاع

هناك مساران للبوابة:

1. البوابة الخارجية (PI_PYTHON_GATEWAY_URL مُضبوطة)

   • تستخدم عنوان URL المُهيَّأ مباشرةً.
   • مصادقة اختيارية عبر PI_PYTHON_GATEWAY_TOKEN.
   • لا يتم إطلاق أي عملية بوابة محلية أو إدارتها.

2. البوابة المحلية المشتركة (المسار الافتراضي)

   • تستخدم عملية مشتركة واحدة يتم تنسيقها تحت ~/.xcsh/agent/python-gateway.
   • ملف البيانات الوصفية: gateway.json
   • ملف القفل: gateway.lock
   • أمر الإطلاق:
     • python -m kernel_gateway
     • مرتبطة بـ 127.0.0.1:<allocated-port>
     • فحص سلامة الإقلاع: GET /api/kernelspecs

تنسيق البوابة المحلية المشتركة

acquireSharedGateway():

• تأخذ قفل الملف (gateway.lock) مع نبضة قلب.
• تُعيد استخدام gateway.json إذا كان PID حياً واجتاز فحص السلامة.
• تُنظّف المعلومات/PIDs القديمة عند الحاجة.
• تبدأ بوابة جديدة حين لا توجد بوابة سليمة.

releaseSharedGateway() هي في الوقت الحالي عملية بلا أثر (إيقاف تشغيل النواة لا يُفكّك البوابة المشتركة).

shutdownSharedGateway() تُنهي العملية المشتركة صراحةً وتمسح بيانات البوابة الوصفية.

قيد مهم

python.sharedGateway=false مرفوض عند بدء تشغيل النواة:

• الخطأ: Shared Python gateway required; local gateways are disabled
• لا يوجد وضع بوابة محلية غير مشتركة لكل عملية.

دورة حياة النواة

يستخدم كل تنفيذ نواةً تُنشأ عبر POST /api/kernels على البوابة المحددة.

تسلسل إقلاع النواة:

1. فحص التوافر (checkPythonKernelAvailability)
2. إنشاء النواة (/api/kernels)
3. فتح WebSocket (/api/kernels/:id/channels)
4. تهيئة بيئة النواة (cwd، متغيرات البيئة، sys.path)
5. تنفيذ PYTHON_PRELUDE
6. تحميل وحدات الامتداد من:
   • المستخدم: ~/.xcsh/agent/modules/*.py
   • المشروع: <cwd>/.xcsh/modules/*.py (يتجاوز وحدة المستخدم بالاسم ذاته)

إيقاف تشغيل النواة:

• حذف النواة البعيدة عبر DELETE /api/kernels/:id
• إغلاق WebSocket
• استدعاء خطاف تحرير البوابة المشتركة (بلا أثر حالياً)

دلالات استمرارية الجلسة

يتحكم python.kernelMode في إعادة استخدام النواة:

• session (الافتراضي)

  • يُعيد استخدام جلسات النواة مفهرسةً بهوية الجلسة + cwd.
  • يتم تسلسل التنفيذ لكل جلسة عبر طابور انتظار.
  • تُطرد الجلسات الخاملة بعد 5 دقائق.
  • بحد أقصى 4 جلسات؛ تُطرد الأقدم عند تجاوز الحد.
  • تكشف فحوصات النبضة النوى المتوقفة.
  • يُسمح بإعادة التشغيل التلقائي مرة واحدة؛ التعطل المتكرر => فشل نهائي.

• per-call

  • يُنشئ نواةً جديدة لكل طلب تنفيذ.
  • يُوقف النواة بعد انتهاء الطلب.
  • لا استمرارية في الحالة بين الاستدعاءات.

سلوك الخلايا المتعددة في استدعاء أداة واحد

تعمل الخلايا بالتسلسل في نفس نسخة النواة لذلك الاستدعاء.

إذا أخفقت خلية وسيطة:

• تبقى حالة الخلية الأسبق في الذاكرة.
• تُعيد الأداة خطأً محدداً يشير إلى الخلية التي أخفقت.
• لا تُنفَّذ الخلايا اللاحقة.

reset=true يُطبَّق فقط على تنفيذ الخلية الأولى في ذلك الاستدعاء.

تصفية البيئة وتحليل وقت التشغيل

تُصفَّى البيئة قبل إطلاق وقت تشغيل البوابة/النواة:

• تشمل القائمة البيضاء المتغيرات الأساسية مثل PATH، HOME، متغيرات المنطقة، VIRTUAL_ENV، PYTHONPATH، وغيرها.
• بوادئ مسموح بها: LC_، XDG_، PI_
• تحذف القائمة السوداء مفاتيح API الشائعة (OpenAI/Anthropic/Gemini/إلخ.)

ترتيب اختيار وقت التشغيل:

1. البيئة الافتراضية النشطة/الموجودة (VIRTUAL_ENV، ثم <cwd>/.venv، <cwd>/venv)
2. البيئة الافتراضية المُدارة في ~/.xcsh/python-env
3. python أو python3 في PATH

عند اختيار بيئة افتراضية، يُضاف مسار bin/Scripts إلى مقدمة PATH.

تهيئة بيئة النواة داخل Python أيضاً:

• os.chdir(cwd)
• حقن خريطة البيئة المُقدَّمة في os.environ
• التأكد من أن cwd موجود في sys.path

توافر الأداة واختيار الوضع

يتحكم python.toolMode (الافتراضي both) + التجاوز الاختياري PI_PY في الكشف:

• ipy-only
• bash-only
• both

القيم المقبولة لـ PI_PY:

• 0 / bash -> bash-only
• 1 / py -> ipy-only
• mix / both -> both

إذا فشل الفحص المسبق لـ Python، يتراجع إنشاء الأداة إلى bash-only لتلك الجلسة.

تدفق التنفيذ والإلغاء/المهلة

مهلة مستوى الأداة

مهلة أداة python بالثواني، الافتراضي 30، محدودة بين 1..600.

تجمع الأداة:

• إشارة إلغاء المستدعي
• إشارة إلغاء المهلة

مع AbortSignal.any(...).

إلغاء تنفيذ النواة

عند الإلغاء/المهلة:

• يُوسَم التنفيذ بالإلغاء.
• تُحاوَل مقاطعة النواة عبر REST (POST /interrupt) وقناة التحكم interrupt_request.
• تتضمن النتيجة cancelled=true.
• تُضيف مسار المهلة تعليقاً على المخرجات: Command timed out after <n> seconds.

سلوك stdin

المدخلات التفاعلية stdin غير مدعومة.

إذا أصدرت النواة input_request:

• تسجّل الأداة stdinRequested=true
• تُصدر نصاً توضيحياً
• ترسل input_reply فارغاً
• يُعامَل التنفيذ على أنه فشل في طبقة المنفّذ

التقاط المخرجات وعرضها

فئات المخرجات الملتقطة

من رسائل النواة:

• stream -> مقاطع نص عادي
• display_data/execute_result -> معالجة العرض الغني
• error -> نص تتبع الخطأ
• MIME مخصص application/x-xcsh-status -> أحداث الحالة المنظمة

أولوية MIME في العرض:

1. text/markdown
2. text/plain
3. text/html (يُحوَّل إلى Markdown أساسي)

يُلتقط إضافةً إلى ذلك كمخرجات منظمة:

• application/json -> بيانات شجرة JSON
• image/png -> حمولات الصور
• application/x-xcsh-status -> أحداث الحالة

التخزين والاقتطاع

تتدفق المخرجات عبر OutputSink ويمكن استمرارها في تخزين الأدوات المساعدة.

يمكن أن تتضمن نتائج الأداة بيانات وصفية للاقتطاع وartifact://<id> لاسترداد المخرجات الكاملة.

سلوك العارض

• عارض الأداة (python.ts):
  • يعرض كتل خلايا الكود مع حالة لكل خلية
  • يعرض المعاينة المطوية افتراضياً لـ 10 أسطر
  • يدعم الوضع الموسّع للمخرجات الكاملة وتفاصيل الحالة الأغنى
• العارض التفاعلي (python-execution.ts):
  • يُستخدم لتنفيذ Python الذي يبدأه المستخدم في TUI
  • يعرض المعاينة المطوية افتراضياً لـ 20 سطراً
  • يقيّد الأسطر الفردية الطويلة جداً إلى 4000 حرف لسلامة العرض
  • يعرض إشعارات الإلغاء/الخطأ/الاقتطاع

دعم البوابة الخارجية

اضبط:

export PI_PYTHON_GATEWAY_URL="http://127.0.0.1:8888"
# اختياري:
export PI_PYTHON_GATEWAY_TOKEN="..."

الاختلافات في السلوك عن البوابة المحلية المشتركة:

• لا ملفات قفل/معلومات للبوابة المحلية
• لا إطلاق/إنهاء لعملية محلية
• تعمل فحوصات السلامة وعمليات CRUD للنواة على النقطة الطرفية الخارجية
• تُعرض أخطاء المصادقة مع توجيه صريح بشأن الرمز المميز

استكشاف الأخطاء التشغيلية وإصلاحها (أنماط الفشل الحالية)

• أداة Python غير متاحة

  • تحقق من python.toolMode / PI_PY.
  • إذا فشل الفحص المسبق، يتراجع وقت التشغيل إلى bash-only.

• أخطاء توافر النواة

  • يتطلب الوضع المحلي أن يكون كلٌّ من kernel_gateway وipykernel قابلَين للاستيراد في وقت تشغيل Python المحلول.

  • ثبّتهما بـ:

    python -m pip install jupyter_kernel_gateway ipykernel

• python.sharedGateway=false يسبب فشل الإقلاع

  • هذا متوقع مع التطبيق الحالي.

• أخطاء مصادقة/وصول البوابة الخارجية

  • 401/403 -> اضبط PI_PYTHON_GATEWAY_TOKEN.
  • مهلة/تعذر الوصول -> تحقق من URL/الشبكة وسلامة البوابة.

• تعليق التنفيذ ثم انتهاء المهلة

  • زد timeout الأداة (بحد أقصى 600 ثانية) إذا كان حجم العمل مشروعاً.
  • للكود المتوقف، يُشغّل الإلغاء مقاطعة النواة لكن كود المستخدم قد يحتاج إلى إعادة هيكلة.

• مطالبات stdin/input في كود Python

  • input() غير مدعومة بشكل تفاعلي في مسار وقت التشغيل هذا؛ مرّر البيانات برمجياً.

• استنفاد الموارد (EMFILE / عدد كبير جداً من الملفات المفتوحة)

  • يُشغّل مدير الجلسات استرداد البوابة المشتركة (تفكيك الجلسة + إعادة تشغيل البوابة المشتركة).

• أخطاء دليل العمل

  • تتحقق الأداة من وجود cwd وكونه دليلاً قبل التنفيذ.

متغيرات البيئة ذات الصلة

• PI_PY — تجاوز كشف الأداة (تعيين bash-only/ipy-only/both الموضّح أعلاه)
• PI_PYTHON_GATEWAY_URL — استخدام بوابة خارجية
• PI_PYTHON_GATEWAY_TOKEN — رمز مصادقة البوابة الخارجية الاختياري
• PI_PYTHON_SKIP_CHECK=1 — تجاوز فحوصات الإقلاع/التدفئة لـ Python
• PI_PYTHON_IPC_TRACE=1 — تسجيل آثار إرسال/استقبال IPC للنواة
• PI_DEBUG_STARTUP=1 — إصدار علامات تصحيح مرحلة الإقلاع