omp (Oh My Pi) + JoinGonka Gateway: وكيل بأدوار النماذج

الخطوة 1: تثبيت omp. الطرق الرسمية من README المشروع:

# macOS and Linux
curl -fsSL https://omp.sh/install | sh

# Homebrew
brew install can1357/tap/omp

# via Bun (requires Bun 1.3.14 or newer)
bun install -g @oh-my-pi/pi-coding-agent

# Windows (PowerShell)
irm https://omp.sh/install.ps1 | iex

الخطوة 2: الحصول على مفتاح. سجّل في gate.joingonka.ai/register، أكّد عنوانك، وأنشئ مفتاحاً بالبادئة jg- في قسم «مفاتيح API». مفتاح واحد ورصيد واحد يعملان مع جميع نماذج الشبكة.

الخطوة 3: تشغيل المثبّت.

npx @joingonka/setup --tool omp

سيسألك المثبّت عن المفتاح — لا يُمرَّر المفتاح عبر وسائط سطر الأوامر حتى لا يبقى في سجل الصدفة — وسيقوم بأربعة أمور:

• سيكتب المزوّد joingonka في ~/.omp/agent/models.yml: عنوان البوابة، البروتوكول openai-completions، المفتاح كنص صريح، وثلاثة نماذج للشبكة بنوافذ سياق حقيقية وحدود استجابة فعلية؛ وسيحصل الملف على صلاحيات 600؛
• سيضبط النموذج الافتراضي — modelRoles.default في ~/.omp/agent/config.yml — على DeepSeek V4 Flash، لكن فقط إذا كان الدور فارغاً أو يشير إلى نموذج غادر الشبكة: فهو لا يتجاوز اختيارك، بل يرشدك إلى كيفية التبديل؛
• سيأخذ نسخة احتياطية من الملف السابق قبل الكتابة، ويترك بقية المزوّدين والأدوار والتعليقات كما هي؛
• في النهاية سيرسل طلباً حياً إلى البوابة وسيخبرك مباشرةً ما إذا قُبل المفتاح والعنوان والنموذج.

لتحديد نموذج افتراضي آخر، استخدم العلم --model مع الاختصار deepseek أو glm أو minimax — النموذج المحدَّد صراحةً يُكتب دائماً. لملفات الإعدادات والخوادم هناك وضع بلا أسئلة، يُؤخذ فيه المفتاح من متغير بيئة:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool omp --model glm --non-interactive

يتعامل المثبّت تلقائياً مع المواقع غير القياسية للإعدادات: ملف تعريف مسمّى (OMP_PROFILE) ودليل وكيل منقول (PI_CODING_AGENT_DIR). ينقل models.json القديم إلى models.yml تماماً كما يفعل omp نفسه — فلن تضيع المزوّدات السابقة. وإذا وُجد بجانبه settings.json قديم بدون config.yml، فلن ينشئ المثبّت config.yml حتى لا يتخطى omp نقل إعداداته الخاص: سيطلب منك تشغيل omp مرة واحدة وإعادة الأمر.

كل ما يفعله المُثبِّت يمكن كتابته يدويًا. هناك ملفان فقط، ولكل منهما مهمته: models.yml يصف المزوّدين والنماذج، وconfig.yml يحتفظ بالإعدادات — بما في ذلك أي نموذج يشغل أي دور.

# ~/.omp/agent/models.yml
providers:
  joingonka:
    baseUrl: https://gate.joingonka.ai/v1
    api: openai-completions
    apiKey: jg-your-key
    models:
      - id: deepseek-ai/DeepSeek-V4-Flash-0731
        name: DeepSeek V4 Flash (Gonka)
        input: [text]
        contextWindow: 380000
        maxTokens: 32768
        reasoning: true
      - id: zai-org/GLM-5.3-Flash
        name: GLM-5.3 Flash (Gonka)
        input: [text]
        contextWindow: 390000
        maxTokens: 8192
        reasoning: true
      - id: MiniMaxAI/MiniMax-M2.7
        name: MiniMax M2.7 (Gonka)
        input: [text]
        contextWindow: 200000
        maxTokens: 8192

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731

وضع المفتاح كنص صريح هو الخيار الأقل مشاكل: يُقلع omp من أي بيئة، ويكفي تقييد صلاحيات الملف بالأمر chmod 600 ~/.omp/agent/models.yml. وإن أردت إبقاء المفتاح خارج الملف، فاكتب في apiKey اسم المتغيّر، مثل JOINGONKA_API_KEY، ثم صدّره في الصدفة التي تشغّل منها omp: فهذا هو ترتيب حلّ المفتاح الموصوف في وثائق المشروع.

الحقل الاختياري cost (السعر لكل مليون رمز) لا يلزم إلا لتقدير تكلفة الجلسة في واجهة omp. يكتب فيه المُثبِّت السعر الحيّ للبوابة لحظة التثبيت؛ وفي الإعداد اليدوي يمكن حذف الحقل — فهذا التقدير لا علاقة له بفاتورتك، والاستهلاك الفعلي يظهر في لوحة الحساب.

يُكتب مُحدِّد النموذج على الصيغة provider/model-id. يُفصل اسم المزوّد عند أول شرطة مائلة، لذا تُكتب معرّفات الشبكة التي تحوي شرطة مائلة خاصة بها كما هي: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. وبدلًا من تعديل config.yml يمكن تعيين الدور من الواجهة — بالأمر /model داخل الجلسة أو عبر معالج omp setup.

في omp، لا يتم اختيار نموذج واحد لكل شيء، بل يتم اختيار النماذج حسب الأدوار - وهذا هو الركيزة الأساسية للتكوين. الأدوار المضمنة للحوار هي: default، smol، slow، plan، commit، task، tiny، memory، advisor و vision. ليس من الضروري تعيين الكل: الأدوار غير المحددة مثل smol و slow تأخذ في البداية نموذج الدور default، وتعمل الوكلاء الفرعيون بدون دور task على نموذج الجلسة الحالية، وتتبع commit و tiny نموذج smol. تكوين من سطر واحد default يعمل بالكامل.

تقسيم الأدوار بين نماذج الشبكة لا يهدف إلى التوفير — فأسعار DeepSeek V4 Flash و GLM-5.3 Flash و MiniMax M2.7 متساوية — بل من أجل السلوك والسعة: النموذج الذي يتمتع بالقدرة على الاستنتاج يخطط بشكل أفضل، والنموذج ذو الإجابات الطويلة يكتب بشكل أفضل، ولا داعي لوضع المهام الخلفية البسيطة في نفس قائمة انتظار المهمة الرئيسية.

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
  slow: joingonka/zai-org/GLM-5.3-Flash
  plan: joingonka/zai-org/GLM-5.3-Flash
  tiny: joingonka/MiniMaxAI/MiniMax-M2.7

retry:
  fallbackChains:
    default:
      - joingonka/zai-org/GLM-5.3-Flash

كتلة retry.fallbackChains — هي تأمين لساعات الذروة: عندما يجيب النموذج الرئيسي باستمرار بـ 429، يقوم omp بنقل بقية الخطوة إلى العنصر التالي في السلسلة، وبعد وقفة قصيرة يعود إلى الرئيسي. يمكن أن يكون مفتاح السلسلة دوراً، أو نموذجاً محدداً، أو المزود بالكامل (joingonka/*).

لعملية تشغيل واحدة يتم إعادة تعريف الدور بواسطة العلم: omp --model slow يطلق الجلسة على نموذج الدور slow، بينما تقوم --smol و --slow و --plan باستبدال نموذج الدور نفسه. داخل الجلسة، يقوم Ctrl+P بتقليب نماذج الأدوار، ويفتح /model قائمة الاختيار؛ وفي تبويب Roles هناك يتم تعيين الأدوار وبدائلها.

يمكن إضافة مستوى التفكير إلى قيمة الدور — :low، :medium، :high. هذا هو بناء جملة omp، أما كيفية فهم النموذج لمستوى التفكير فيعتمد عليه هو نفسه: في GLM-5.3 Flash، على سبيل المثال، هذا مفتاح ثنائي — التفاصيل في مراجعة النموذج. وتفصيلة مفيدة أخرى: يمكن إعادة تعريف الأدوار لمستودع واحد بملف <repo>/.omp/config.yml مع نفس كتلة modelRoles. تبقى المزودات والمفاتيح في الدليل الرئيسي، لذا لن يصل المفتاح إلى المستودع.

أولاً، تأكد من أن omp يرى المزوّد:

omp models joingonka

تأتي الإجابة في جدول من ثلاثة صفوف يحوي نوافذ السياق وحدود الإخراج من models.yml، مقرّبة إلى الآلاف (الإخراج مختصر: لدى omp أعمدة إضافية هي thinking وimages):

joingonka (3)
model                                context  max-out
deepseek-ai/DeepSeek-V4-Flash-0731      380K      33K
MiniMaxAI/MiniMax-M2.7                  200K     8.2K
zai-org/GLM-5.3-Flash                   390K     8.2K

ثم نجري تشغيلاً واحداً بدون واجهة. ضع في مجلد فارغ ملفاً فيه خطأ واضح واطلب من الوكيل العثور عليه:

omp -p "Read calc.py and tell me in one sentence whether it has a bug."

على الوكيل أن يستدعي أداة القراءة بنفسه وأن يجيب في صلب الموضوع — مع تحديد التعبير الذي يقع فيه الخطأ. في تشغيلنا بتاريخ 21 سبتمبر 2026، مرّت هذه الحلقة — الطلب، استدعاء الأداة، النتيجة، الإجابة — بسلاسة مع DeepSeek V4 Flash وGLM-5.3 Flash؛ أما MiniMax M2.7 — فراجع الصف الأخير في الجدول أدناه.

الفحص الثالث — من جهة البوابة: في لوحة التحكم ضمن قسم «الاستخدام» سيظهر الطلب في تفصيل «حسب النماذج»، وفي كتلة «حسب المفاتيح» سيُحدَّث وقت آخر طلب. إذا كان المكان فارغاً، فإن omp يتصل بمزوّد آخر: تحقق من إعدادات الأدوار بالأمر omp config get modelRoles.

إذا حدث خطب ما، فعادةً ما يُقرأ التشخيص مباشرةً من الرسالة:

تستهلك أداة الوكيل التوكنات بشكل مختلف عن الدردشة: مع كل عبارة تكتبها، يضيف omp برومبت النظام ووصف الأدوات، وعادة ما تستغرق المهمة عدة خطوات. في تجربتنا، حتى مع وجود أداة قراءة واحدة مفعلة، كان كل دور يستهلك حوالي 3.5 ألف توكن مدخل؛ ومع المجموعة الكاملة سيكون العدد أكبر. لذلك، السعر لكل توكن هو العامل الحاسم هنا.

من خلال JoinGonka Gateway، تبلغ تكلفة التوكنات $0.0069 للمليون عند الإدخال و $0.021 للمليون عند الإخراج — السعر متطابق لجميع نماذج الشبكة ويتم جلبه في هذه الصفحة من مصدر مباشر.

التقديرات في العمود الأيمن تعتمد على أسعار سبتمبر 2026. للمقارنة — كيف يمكنك الدفع مقابل النماذج في omp:

يعرض شريط حالة omp تقدير تكلفة الجلسة. يتم حسابه بناءً على حقل cost في models.yml: يقوم المثبت بإدخال سعر البوابة في وقت التثبيت، وبما أن سعر الدولار في الشبكة يتذبذب مع سعر صرف GNK، فإن التقدير هو مجرد إرشاد. الاستهلاك الدقيق والرصيد المتبقي — في لوحة التحكم، في قسمي "الاستخدام" و "الفواتير". لماذا تم اختيار DeepSeek V4 Flash كخيار افتراضي، موضح بالتفصيل في مراجعة النموذج.

وضع الموافقات. يعمل omp افتراضيًا في وضع yolo: يوافق بنفسه على القراءة والكتابة وتنفيذ الأوامر. هذا مريح في مشروعك الخاص، لكنه مع كود شخص آخر سبب لتشديد الوضع أو اللجوء إلى حاوية:

omp config set tools.approvalMode write

في وضع write لا يطلب الوكيل الإذن إلا لتنفيذ الأوامر، وفي always-ask يطلبه أيضًا للكتابة. ولتشغيل واحد يقوم بالمهمة نفسها الخيار --approval-mode. هذه خاصية في omp نفسه، ولا تعتمد على مزوّد النموذج.

Pi وomp قريبان لكن بإعدادات مختلفة. إعداد أداة لا ينتقل إلى الأخرى: فالمجلدات والصيغ وأسماء الحقول لكل منهما خاصة به.

عدة بيئات. الملف الشخصي المسمّى (omp --profile work أو المتغير OMP_PROFILE) ينقل كل الإعدادات إلى ~/.omp/profiles/<name>/agent — مريح لفصل مفاتيح العمل والمفاتيح الشخصية. أما مجلد الوكيل الحالي فيطبعه omp config path.

إذا احتجت الوكيل داخل المحرر. يستطيع omp العمل داخل Zed عبر بروتوكول ACP — وهو الوكيل نفسه بالإعدادات نفسها، دون حاجة لإعادة كتابة المزوّد والأدوار.