> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# استخدام Pi مع CometAPI

> استخدم هذا الدليل لتهيئة Pi مع CometAPI من خلال تعيين base URL وAPI key وخيارات model أو provider.

[Pi](https://github.com/earendil-works/pi) هو مشروع Pi Agent Harness. توفّر حزمة `@earendil-works/pi-coding-agent` الخاصة به واجهة سطر أوامر لوكيل برمجي تفاعلي تدعم سير عمل الملفات وshell وedit وwrite وsession وprint وJSON وRPC وSDK. يمكن لـ Pi تحميل موفّرين مخصّصين من `~/.pi/agent/models.json`، لذلك يمكنك إضافة CometAPI كإدخالات provider متوافقة مع OpenAI دون تغيير الشيفرة المصدرية لـ Pi.

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

* [مستودع Pi](https://github.com/earendil-works/pi)
* [البدء السريع لـ Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md)
* [موفّرو Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
* [النماذج المخصّصة في Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [استخدام Pi CLI](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<Note>
  يتغيّر توفّر النماذج بمرور الوقت. استبدل `your-model-id` بمعرّف model ID متاح من [صفحة نماذج CometAPI](/ar/overview/models).
</Note>

## المتطلبات المسبقة

* Node.js `>=22.19.0`
* npm
* حساب CometAPI مع API key نشط من [لوحة التحكم](https://www.cometapi.com/console/token)
* تثبيت Pi من حزمة npm الرسمية

## فهم أذونات وقت التشغيل

يعمل Pi بأذونات المستخدم والعملية اللذين يقومان بتشغيله. شغّل Pi داخل دليل المشروع الذي تريد أن يعمل عليه، واحتفظ بمسار تراجع مثل git، واستخدم حاوية أو sandbox إذا كنت بحاجة إلى حدود أقوى لنظام الملفات أو العمليات أو الشبكة أو بيانات الاعتماد.

## تهيئة المزوّد

<Steps>
  <Step title="تثبيت Pi">
    ثبّت Pi بشكل عام باستخدام npm:

    ```bash theme={null}
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```

    أكّد أن أداة CLI متاحة:

    ```bash theme={null}
    pi --version
    ```
  </Step>

  <Step title="تعيين مفتاح CometAPI API الخاص بك">
    خزّن مفتاح CometAPI API الخاص بك في متغير البيئة `COMETAPI_KEY`:

    ```bash theme={null}
    read -rsp "CometAPI API key: " COMETAPI_KEY
    printf '\n'
    export COMETAPI_KEY
    ```

    أضف أمر التصدير إلى ملف تعريف shell إذا كنت تريد أن يستمر عبر جلسات الطرفية. لا تقم بإيداع مفاتيح API في نظام التحكم في الإصدارات.
  </Step>

  <Step title="إضافة مزوّدي CometAPI إلى models.json">
    أنشئ `~/.pi/agent/models.json` إذا لم يكن موجودًا. إذا كان الملف يحتوي بالفعل على providers، فادمج الإدخالين `cometapi-responses` و`cometapi-chat` داخل الكائن `providers` الحالي:

    ```json theme={null}
    {
      "providers": {
        "cometapi-responses": {
          "name": "CometAPI Responses",
          "baseUrl": "https://api.cometapi.com/v1",
          "api": "openai-responses",
          "apiKey": "$COMETAPI_KEY",
          "models": [
            {
              "id": "your-model-id",
              "name": "CometAPI Responses model"
            }
          ]
        },
        "cometapi-chat": {
          "name": "CometAPI Chat Completions",
          "baseUrl": "https://api.cometapi.com/v1",
          "api": "openai-completions",
          "apiKey": "$COMETAPI_KEY",
          "models": [
            {
              "id": "your-model-id",
              "name": "CometAPI Chat model"
            }
          ]
        }
      }
    }
    ```

    استخدم `cometapi-responses` للنماذج أو مسارات العمل التي تتطلب OpenAI Responses API. واستخدم `cometapi-chat` للنماذج المتوافقة مع OpenAI Chat Completions. يقوم Pi بحل `$COMETAPI_KEY` وقت الطلب. احتفظ بمفتاح API في بيئتك أو ضمن سير العمل الخاص بالأسرار لديك.
  </Step>

  <Step title="التحقق من كلا المزوّدين">
    اعرض النماذج التي يمكن لـ Pi رؤيتها لمزوّد Responses:

    ```bash theme={null}
    pi --list-models cometapi-responses
    ```

    شغّل Prompt قصيرًا لمرة واحدة باستخدام مزوّد Responses:

    ```bash theme={null}
    pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."
    ```

    اعرض النماذج التي يمكن لـ Pi رؤيتها لمزوّد Chat Completions:

    ```bash theme={null}
    pi --list-models cometapi-chat
    ```

    شغّل Prompt قصيرًا لمرة واحدة باستخدام مزوّد Chat Completions:

    ```bash theme={null}
    pi --provider cometapi-chat --model your-model-id -p "Reply with one short sentence confirming the Chat Completions connection."
    ```

    للاستخدام التفاعلي، ابدأ Pi في مشروعك وحدد مزوّد CometAPI والنموذج باستخدام `/model`. إذا قمت بتحرير `models.json` أثناء جلسة تفاعلية، فافتح `/model` مرة أخرى لكي يعيد Pi تحميل إدخالات النموذج المخصصة.
  </Step>
</Steps>

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="Pi لا يعرض نموذج CometAPI">
    تأكد من أن `~/.pi/agent/models.json` هو JSON صالح وأن كل إدخال provider موجود داخل الكائن الأعلى مستوى `providers`. شغّل `pi --list-models cometapi-responses` أو `pi --list-models cometapi-chat` بعد حفظ الملف.
  </Accordion>

  <Accordion title="Pi يفيد بعدم توفر API key">
    تأكد من أن `COMETAPI_KEY` مضبوط في جلسة shell نفسها التي تشغّل Pi. إذا كنت تستخدم shell profile، فافتح terminal جديدًا أو نفّذ source للملف الشخصي قبل تشغيل Pi.
  </Accordion>

  <Accordion title="تفشل الطلبات بسبب base URL">
    استخدم `https://api.cometapi.com/v1` كقيمة `baseUrl` في `models.json`. لا توجّه Pi إلى رابط لوحة التحكم ولا تحذف اللاحقة `/v1` لمسارات OpenAI-compatible.
  </Accordion>

  <Accordion title="يفشل Pi قبل إرسال طلب إلى النموذج">
    تحقّق من إصدار Node.js لديك باستخدام `node --version`. تتطلب حزمة Pi إصدار Node.js `>=22.19.0`.
  </Accordion>

  <Accordion title="النموذج يعمل على مسار واحد ولكن ليس على الآخر">
    استخدم إدخال provider الذي يطابق فيه الحقل `api` المسار الذي يدعمه نموذجك. يستخدم `openai-responses` واجهة Responses API، بينما يستخدم `openai-completions` واجهة Chat Completions.
  </Accordion>

  <Accordion title="يمتلك Pi صلاحيات أكثر من المتوقع">
    يعمل Pi بصلاحيات المستخدم والعملية اللذين قاما بتشغيله. شغّل Pi داخل حاوية أو sandbox عندما تحتاج إلى حدود أقوى حول الملفات أو العمليات أو الوصول إلى الشبكة أو بيانات الاعتماد.
  </Accordion>
</AccordionGroup>

## موارد ذات صلة

* [البدء السريع مع CometAPI](/ar/overview/quick-start)
* [صفحة نماذج CometAPI](/ar/overview/models)
* [نماذج Pi المخصصة](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [استخدام Pi CLI](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)