تثبيت Pi وإعداد OmniProxy

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

الوكيل الفرعي يعني إسناد جزء من المهمة إلى مساعد آخر، أما وضع التخطيط فيعني ترتيب الخطوات أولًا ثم بدء التنفيذ. هاتان الميزتان غير متاحتين ضمن الوظائف الافتراضية، ويمكنك أن تطلب من Pi إنشاءهما أو تثبيت حزمة شاركها شخص آخر.

التحضير قبل التثبيت

يستخدم macOS وLinux برنامج تثبيت نصيًا، أي أمرًا واحدًا يتولى التنزيل والتثبيت تلقائيًا. أما Windows فيستخدم أمر PowerShell المتاح في الصفحة الرئيسية لـ Pi؛ وPowerShell هو بيئة سطر أوامر مضمّنة في Windows. ويمكن أيضًا تثبيت Pi داخل WSL، وهي بيئة Linux تعمل ضمن Windows.

إذا اخترت التثبيت عبر npm، فيجب أولًا تجهيز Node.js بالإصدار 22.19 أو أحدث. npm هو مدير الحزم المستخدم مع Node.js، ويمكن من خلاله تثبيت Pi من سطر الأوامر.

macOS وLinux

install.sh

• استخدم curl مع البرنامج النصي الرسمي
• يثبّت برنامج التثبيت إصدارات الاعتماديات
• استخدم pi update للتحديث

Windows

install.ps1

• استخدم أمر PowerShell من الموقع الرسمي
• يوفر Git for Windows بيئة Bash
• يمكن أيضًا استخدام WSL

إذا كان Node مثبتًا بالفعل

npm

• يتطلب Node 22.19+
• اسم الحزمة هو pi-coding-agent
• أضف --ignore-scripts

التثبيت والتشغيل لأول مرة

افتح الطرفية على macOS أو Linux، ثم شغّل:

curl -fsSL https://pi.dev/install.sh | sh

افتح PowerShell على Windows، ثم شغّل:

powershell -c "irm https://pi.dev/install.ps1 | iex"

إذا كان Node.js 22.19 أو إصدار أحدث مثبتًا بالفعل، فيمكنك أيضًا استخدام الأمر البديل الوارد في Quickstart:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

قد يتوقف برنامج التثبيت النصي لطرح أسئلة عند تشغيله في طرفية تفاعلية، وعليك متابعة الخطوات وفقًا لما يظهر على الشاشة. إذا كان لديك إصدار مناسب من Node، فلن يعرض أمر npm هذا أي أسئلة. وللتثبيت في دليل آخر، أضف --prefix /مسارك. بهذه الطريقة تم تثبيت Pi 1.1.0 بتاريخ 2026-10-09.

لا يحتاج التثبيت العادي عبر npm إلى نصوص دورة حياة الاعتماديات، وهي نصوص تشغّلها الحزم تلقائيًا أثناء التثبيت. يثبّت برنامج التثبيت النصي إصدارات الاعتماديات، ويمكن التحديث لاحقًا باستخدام pi update. أما تحديث تثبيت npm فيعتمد على مدير الحزم الذي تستخدمه. يثبّت مستخدمو Nix البرنامج من flake الخاص بـ Pi؛ وflake هو إعداد يستخدمه Nix لوصف البرامج واعتمادياتها، ولا يستطيع pi update تحديث تثبيت Nix.

بعد اكتمال التثبيت، تأكد أولًا من أن الطرفية تستطيع العثور على Pi:

pi --version

إذا أردت أن ينفّذ النموذج أوامر Bash على Windows، فمن المستحسن لمعظم المستخدمين المحليين تثبيت Git for Windows. Bash هو بيئة الأوامر التي يستخدمها Pi لتشغيل بعض الأوامر. يبحث Pi بالتسلسل عن shellPath في ~/.pi/agent/settings.json، ثم Git Bash داخل Program Files، ثم bash.exe ضمن PATH. يُستخدم shellPath لتحديد موقع Bash، بينما PATH هي قائمة الأدلة التي يستخدمها النظام للبحث عن الأوامر.

بعد التشغيل، يمكنك إدخال !printf 'Bash is working\n' للتحقق. وإذا كانت الملفات والأدوات موجودة بالفعل داخل WSL، فثبّت Pi في بيئة Linux تلك باتباع Quickstart.

بعد ذلك، انتقل إلى المجلد الذي تريد من Pi فحصه أو العمل عليه، ثم شغّل البرنامج:

cd /path/to/folder
pi

سيكون هذا المجلد نطاق العمل الحالي لـ Pi، وسيُستخدم لاكتشاف الملفات والإعدادات وكذلك لتجميع الجلسات.

الحصول على معلمات الاتصال من OmniProxy

جهّز أولًا القيم الثلاث التالية من OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: انسخ المعرّف الكامل من قائمة النماذج الحالية في OmniProxy

يمثل baseUrl عنوان الواجهة التي يرسل Pi الطلبات إليها، ويجب أن ينتهي بـ /v1. ويمثل apiKey المفتاح المستخدم للوصول إلى الواجهة. أما Model ID فهو اسم النموذج المطلوب استدعاؤه، ويجب نسخه كاملًا من قائمة النماذج الحالية في OmniProxy.

ضع openai-completions في الحقل api كما في مثال الواجهة المتوافقة. يحدد هذا الحقل تنسيق الواجهة الذي سيستخدمه Pi لإرسال الطلبات.

يجب نسخ معرّف النموذج كاملًا مع الاحتفاظ بالشرطات المائلة الموجودة في الاسم. بتاريخ 2026-10-09، كان معرّفا المقارنة في وثائق المورّدين هما gemini-3.8-flash وgrok-4.7. لا تنسخ اسمًا غير موجود في القائمة.

إدخال إعدادات الأداة

تُكتب إعدادات النماذج المخصصة على مستوى المستخدم في Pi داخل models.json. يوجد هذا الملف في دليل agent، والدليل الافتراضي هو ~/.pi/agent، لذلك يكون المسار الكامل ~/.pi/agent/models.json. إذا ضُبط متغير البيئة PI_CODING_AGENT_DIR، فسيستخدم Pi الدليل المحدد في ذلك المتغير؛ ويمكن فهم متغير البيئة على أنه قيمة إعداد يوفرها النظام ليقرأها البرنامج.

أدخل القيم وفق مثال الواجهة المتوافقة:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

يُستخدم providers لسرد الخدمات المتصلة، ويُستخدم models لسرد النماذج المتاحة للاختيار. يجب أن يطابق id لكل نموذج قيمة Model ID الكاملة الموجودة في قائمة النماذج الحالية في OmniProxy، بينما يشير input هنا إلى أن الإدخال نصي.

يمكن كتابة قيمة apiKey مباشرة، أو كتابتها بصيغة $NAME أو ${NAME} ليقرأها Pi من متغير بيئة. أما القيمة التي تبدأ بعلامة ! فستُعامل على أنها أمر ويجري تنفيذها مع كل طلب. لا تودع المفتاح الحقيقي في المستودع. وإذا لم تتحقق البوابة من المفتاح، فيمكنك إدخال سلسلة أحرف بديلة تُستخدم محليًا فقط. تمكّن Pi من قراءة الملف بهذه الطريقة بتاريخ 2026-10-09.

يؤدي فتح /model إلى إعادة تحميل هذا الملف. و/model هو مدخل عرض النماذج واختيارها داخل Pi. لن تظهر النماذج المخصصة في /model قبل أن يتمكن Pi من تحليل بيانات الاعتماد. بعد تحديد النموذج، اضغط Ctrl+S لحفظه كنموذج افتراضي للجلسات الجديدة.

الملف

models.json

• المجلد الافتراضي هو ~/.pi/agent
• أضف عنصرًا إلى providers
• استخدم completions في api

العنوان

baseUrl

• اجعله ينتهي بـ /v1
• يمكن أن تشير apiKey إلى متغير
• يجب أن يكون id النموذج دقيقًا

الاختيار

/model

• سيُعاد تحميل الملف عند فتحه
• حدّد النموذج الذي أضفته للتو
• يمكن استخدام Ctrl+S لحفظه كافتراضي

التحقق باستخدام مهمة حقيقية

بعد إكمال الإعداد، يمكنك إجراء فحص غير تفاعلي داخل دليل يحتوي على ملفات. يعني التشغيل غير التفاعلي أن Pi لا يدخل في محادثة مستمرة، بل ينتهي بعد إكمال هذه المهمة الواحدة. استبدل القيمة التي تلي --model بالمعرّف الكامل الموجود في قائمة OmniProxy الحالية:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "اقرأ السطر الأول من الملف الذي أحدده، ولا تعدّل الملف."

يتيح --tools read هنا أداة القراءة فقط، كما تنص المهمة بوضوح على عدم تعديل الملف. بتاريخ 2026-10-09، تمكّن Pi 1.1.0 من قراءة محتوى الملف. استغرق الرد الأول نحو دقيقتين.

يمكنك أيضًا استخدام الوضع التفاعلي: انتقل إلى الدليل وشغّل pi، ثم اختر النموذج باستخدام /model. تتمثل إحدى المهام النموذجية في Quickstart في مطالبة Pi بشرح كيفية تنظيم المستودع وكيفية تشغيل الفحوصات. راقب ما إذا كان يقرأ الملفات ويقدم الشرح، ثم تحقق من المصدر ومعرّف النموذج في سجل الاستدعاءات داخل OmniProxy.

التشغيل

يمكن تشغيل pi

• استخدم cd للانتقال إلى المجلد أولًا
• يعرض pi --version نتيجة
• يظهر اسم النموذج أسفل الواجهة

المهمة

قرأ المجلد

• اسأله عن كيفية تنظيم المستودع
• راجع الملفات التي يعرضها
• لا تكتفِ برسالة حفظ الإعداد

السجل

يظهر في البوابة

• المصدر هو Pi
• معرّف النموذج متطابق
• احتفظ بالمفتاح محليًا

الأخطاء الشائعة

• تعذر العثور على pi: أعد فتح الطرفية ثم جرّب pi --version. عند التثبيت عبر npm، تأكد من أن دليل bin العام موجود ضمن PATH.
• النموذج المخصص غير موجود في /model: تأكد من وجود models.json داخل ~/.pi/agent/ ومن إمكانية تحليل apiKey، ثم أعد فتح /model.
• يعرض Windows رسالة تفيد بتعذر العثور على Bash: ثبّت Git for Windows، أو اضبط shellPath في ~/.pi/agent/settings.json. يجب كتابة الشرطة المائلة العكسية مرتين داخل JSON.
• رُفض الطلب: تحقق من أن قيمة api هي openai-completions، وأن baseUrl ينتهي بـ /v1. لا تفعّل مفاتيح توافق إضافية لمجرد أن الطرف الآخر يصف واجهته بأنها متوافقة.
• معرّف النموذج غير صالح: أعد نسخه من قائمة OmniProxy الحالية.

المراجع الرسمية

تتوفر أوامر التثبيت في موقع Pi وQuickstart. وتتوفر معلومات ملف النماذج في Choose a Model وConfiguration. وتتوفر معلومات بيئة الأوامر على Windows في Run Pi on Windows. أما معرّفات النماذج المستخدمة في الأمثلة فتتوفر في قائمة نماذج Gemini وصفحة نماذج xAI.

استبدل كل عنصر نائب بقيم إعداد OmniProxy الخاصة بك. لا تنشر مفتاحاً حقيقياً أبداً.

لا يثبت الحفظ الناجح أو HTTP 200 وحده توافق Agent الكامل. تحقق من المصدر والنموذج في سجل استدعاءات OmniProxy.

المصادر الرسمية · Pi ↗