Crush + JoinGonka Gateway: وكيل Charm على نماذج شبكة Gonka

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

# Homebrew
brew install charmbracelet/tap/crush

# npm
npm install -g @charmland/crush

# Arch Linux
yay -S crush-bin

# Windows
winget install charmbracelet.crush

# Go
go install github.com/charmbracelet/crush@latest

هناك أيضًا وصف لمستودعات الحزم الخاصة بـ Debian وUbuntu وFedora وRHEL وNix وScoop، وعلى صفحة الإصدارات توجد ملفات ثنائية جاهزة. للتحقق استخدم crush --version، وستأتيك سطر بالشكل crush version v0.96.1.

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

الخطوة 3: تشغيل أداة التثبيت.

npx @joingonka/setup --tool crush

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

• تكتب المزوّد joingonka في ~/.config/crush/crush.json: النوع openai-compat، وعنوان البوابة، والمفتاح كنص صريح، وثلاثة نماذج من الشبكة مع نوافذ السياق وحدود الاستجابة والأسعار لكل مليون رمز، والتي تأخذها لحظة التثبيت مباشرة من البوابة، — وعلى أساسها يحسب Crush تكلفة الجلسة. سيحصل الملف على صلاحيات 600؛
• تعيّن النماذج: في خانة large — ‏DeepSeek V4 Flash، وفي small — ‏MiniMax M2.7، بينما يبقى GLM-5.3 Flash في القائمة للاختيار اليدوي. وهي تفعل ذلك فقط إذا كانت خانة large فارغة أو تشير إلى نموذجنا الذي غادر الشبكة؛ أما اختيار غيرنا فيبقى كما هو، وسيظهر في المخرجات تلميح لكيفية التبديل؛
• تتحقق من أن الاختيار سيُفعَّل: النموذج من واجهة Crush يُحفظ في ملف الحالة، وهذا الملف يتجاوز الإعدادات، — وهذا ما يتناوله القسم الخاص بـ large وsmall؛
• تُنشئ نسخة احتياطية، وتترك بقية المزوّدين والإعدادات كما كانت، وتنتهي بطلب حيّ إلى البوابة للتحقق فورًا من المفتاح والعنوان والنموذج.

يمكن تحديد نموذج آخر عبر العلم --model بالاختصار deepseek أو glm أو minimax؛ والنموذج المحدد صراحةً يُكتب دائمًا. تتعامل أداة التثبيت مع المجلدات غير القياسية تمامًا كما يفعل Crush نفسه: CRUSH_GLOBAL_CONFIG للإعدادات، وCRUSH_GLOBAL_DATA لملف الحالة، وكذلك XDG_CONFIG_HOME وXDG_DATA_HOME. للسيرفرات والسكربتات يوجد وضع بدون أسئلة، وفيه يُؤخذ المفتاح من متغير البيئة:

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

أصبح crushrc هو التنسيق الأساسي لـ Crush الآن، لكن أداة التثبيت تكتب crush.json: فكل الإصدارات تفهمه. وإذا كان لديك crushrc بالفعل، سيدمج Crush الملفين معًا، وعند تطابق المفاتيح يفوز crushrc، بينما لا تلمسه أداة التثبيت نفسها.

كل ما يفعله المثبِّت يمكن كتابته يدويًا. إليك ملف ~/.config/crush/crush.json العامل — وقد مرّرنا هذا الملف عبر البوابة:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "joingonka": {
      "name": "JoinGonka (Gonka)",
      "type": "openai-compat",
      "base_url": "https://gate.joingonka.ai/v1",
      "api_key": "jg-your-key",
      "models": [
        { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek V4 Flash (Gonka)",
          "context_window": 380000, "default_max_tokens": 32768,
          "can_reason": true, "supports_attachments": false },
        { "id": "MiniMaxAI/MiniMax-M2.7", "name": "MiniMax M2.7 (Gonka)",
          "context_window": 200000, "default_max_tokens": 8192,
          "can_reason": false, "supports_attachments": false },
        { "id": "zai-org/GLM-5.3-Flash", "name": "GLM-5.3 Flash (Gonka)",
          "context_window": 390000, "default_max_tokens": 8192,
          "can_reason": true, "supports_attachments": false }
      ]
    }
  },
  "models": {
    "large": { "provider": "joingonka", "model": "deepseek-ai/DeepSeek-V4-Flash-0731" },
    "small": { "provider": "joingonka", "model": "MiniMaxAI/MiniMax-M2.7" }
  }
}

لا يقبل Crush إلا JSON صارمًا: تعليق أو فاصلة زائدة — ولن يبدأ. حقول السعر (cost_per_1m_in، cost_per_1m_out وحقلان للتخزين المؤقت) لا تحتاجها إلا حاسبة التكلفة: فالمثبِّت يكتب فيها سعر البوابة الحيّ، وبدونها يعمل Crush ويعرض صفرًا — لكن المحرر مع المخطط من $schema سيظل يبرزها كحقول إلزامية.

المزوّد نفسه بصيغة crushrc — وهو Bash عادي مع أوامر Crush المدمجة. الملف ~/.config/crush/crushrc:

provider add joingonka \
  --name "JoinGonka (Gonka)" \
  --type openai-compat \
  --base-url "https://gate.joingonka.ai/v1" \
  --api-key "${JOINGONKA_API_KEY:?set JOINGONKA_API_KEY}"

model add joingonka/deepseek-ai/DeepSeek-V4-Flash-0731 \
  --name "DeepSeek V4 Flash (Gonka)" \
  --context-window 380000 --default-max-tokens 32768 --can-reason true

model add joingonka/MiniMaxAI/MiniMax-M2.7 \
  --name "MiniMax M2.7 (Gonka)" \
  --context-window 200000 --default-max-tokens 8192

model add joingonka/zai-org/GLM-5.3-Flash \
  --name "GLM-5.3 Flash (Gonka)" \
  --context-window 390000 --default-max-tokens 8192 --can-reason true

model large joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
model small joingonka/MiniMaxAI/MiniMax-M2.7

يُسمّى النموذج هنا بصيغة provider/model-id: ما قبل الشرطة المائلة الأولى هو اسم المزوّد، وما بعدها معرّف الشبكة كما هو. أما الصيغة ${JOINGONKA_API_KEY:?…} فتُبقي المفتاح خارج الملف، لكن دون متغير مُصدَّر لن يبدأ Crush — وخطأ عند البدء خير من طلبات بمفتاح فارغ.

لا يتم اختيار نموذج واحد في Crush لكل شيء، بل يتم اختيار نموذج لفتحتين:

يتم اختيار النموذج الثالث للشبكة، GLM-5.3 Flash الخاص بالاستدلال، للمنطق المعقد، مع الأخذ في الاعتبار أن سقف الاستجابة الخاص به هو 8192 وجزء منه يذهب للاستدلال — التفاصيل في مراجعة النموذج. بالنسبة لكل تشغيل، يتم تحديد النموذج بالاسم الكامل: crush run -m joingonka/zai-org/GLM-5.3-Flash "…". تعرض crush models joingonka جميع الأسماء المتاحة.

ملف الحالة. لا يسجل Crush النموذج المختار في الواجهة عبر ctrl+l في crush.json، بل في ملف حالة الجهاز: ~/.local/share/crush/crush.json، وفي Windows — %LOCALAPPDATA%\crush\crush.json. هذا الملف له الأولوية على إعدادات المستخدم و crushrc: يقرأها Crush بالترتيب /etc/crush/crush.json → ~/.config/crush/crush.json → ~/.config/crush/crushrc → ملف الحالة، وكل ملف لاحق يلغي السابق. فقط إعدادات المشروع — crush.json أو crushrc في المجلد الخاص به — لها أولوية أعلى. ستعرض crush dirs أماكن وجود الملفات على جهازك.

في تشغيلنا التجريبي، فتحنا اختيار النماذج — يظهر الموفر “JoinGonka (Gonka)” هناك مع علامة “✓ Configured” — واخترنا MiniMax M2.7. استجاب Crush بـ “Large model changed to MiniMax M2.7 (Gonka)” وسجل في ملف الحالة:

{"models":{"large":{"model":"MiniMaxAI/MiniMax-M2.7","provider":"joingonka","max_tokens":8192}}, …}

الآن هذا النموذج أهم مما هو مكتوب في crush.json. يتعرف المثبت على هذا الموقف ويتصرف بطرق مختلفة:

• بدون --model لا يلمس ملف الحالة — فهذا هو اختيار عملك — لكنه يحذر صراحةً بالنموذج الذي سيفتح به Crush بالفعل: Heads-up: Crush will still start with joingonka/MiniMaxAI/MiniMax-M2.7, not joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. سيفعل الشيء نفسه إذا تم اختيار GLM-5.3 Flash أو نموذج لموفر آخر في الواجهة؛
• مع --model صريح يقوم بتعديل إدخال واحد فقط في ملف الحالة — models.large — بعد حفظ نسخة احتياطية، ويكتب ما كان عليه وما أصبح. بخلاف ذلك، لن يكون للعلم أي تأثير. بعد هذا التشغيل، فتح Crush في تجربتنا على النموذج المحدد في العلم.

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

crush models joingonka

ستأتيك ثلاثة أسطر في الرد:

joingonka/MiniMaxAI/MiniMax-M2.7
joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
joingonka/zai-org/GLM-5.3-Flash

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

crush run -q "Read calc.py and tell me in one sentence whether it has a bug."

يجب أن يستدعي الوكيل بنفسه أداة قراءة الملف وأن يجيب بشكل جوهري، مع رقم السطر. في تجربتنا، وجدت الخطأ جميع النماذج الثلاثة على الشبكة، واستغرقت المهمة 20-40 ثانية. العلامة -q تخفي مؤشر الانتظار. في وضع crush run تتم الموافقة على جميع استدعاءات الأدوات تلقائيًا، لذا شغّله داخل مشروعك. في الواجهة العادية (الأمر crush) يظهر النموذج النشط في سطر الحالة: ◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka). يحفظ Crush الجلسات والسجل في مجلد .crush الخاص بالمشروع، المحمي من git بـ .gitignore خاص به؛ ويطبع السجل الأمر crush logs. من جهة البوابة، يظهر الطلب في لوحة التحكم: قسم «الاستخدام»، وتفصيل «حسب النماذج» و«حسب المفاتيح».

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

ينفق الوكيل (agent) الرموز (tokens) بشكل مختلف عن المحادثة: يضيف Crush إلى كل جملة من جملك موجه نظام ووصفاً لأدواته، وعادة ما تستغرق المهمة عدة خطوات. في تشغيلنا التجريبي، حمل كل طلب إلى النموذج حوالي 11.5 ألف رمز إدخال، واستغرقت مهمة "قراءة الملف والعثور على الخطأ" طلبين إلى ثلاثة و 23-35 ألف رمز، معظمها إدخال. لذلك، السعر لكل رمز هنا هو العامل الحاسم.

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

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

يحسب عداد التكلفة في واجهة Crush بناءً على حقول السعر من ملف الإعدادات. يدخل هناك سعر البوابة وقت التثبيت، بينما يتغير سعر الدولار في الشبكة مع سعر صرف GNK، لذا فإن العداد هو مجرد تقدير. الاستهلاك الدقيق والرصيد المتبقي موجودان في لوحة التحكم، في أقسام «الاستخدام» و«الفواتير». لماذا يتم اختيار DeepSeek V4 Flash افتراضياً لفتحة large، تمت مناقشته بالتفصيل في مراجعة النموذج.

الأذونات. يسأل Crush افتراضيًا في الواجهة عن الإذن قبل استدعاء أي أداة. علم --yolo يعطّل كل الأسئلة دفعة واحدة، أما الأدوات الموثوقة بشكل انتقائي فتُدرَج في ملف الإعدادات:

# crushrc
permissions allow view ls grep

# crush.json
"permissions": { "allowed_tools": ["view", "ls", "grep"] }

نذكّر بأن crush run يوافق على كل شيء بنفسه. هذه خاصية من خصائص Crush ولا تعتمد على مزوّد النموذج.

مهلة الطلب. يقطع Crush الطلب إذا لم يصل من النموذج أي جزء من الرد لفترة طويلة: في الإصدار 0.96.1 دقيقتان من الصمت (توثّق الوثائق 60 ثانية، لكن في الشيفرة وفي اختبارنا دقيقتان). لا تعيد رسائل ping الخدمية التي يستخدمها البوابة للحفاظ على الاتصال تصفير هذا العدّاد — تحققنا من ذلك على منصة اختبار محلية. أما البوابة في ساعات الذروة فتنتظر أول token من الشبكة حتى 150 ثانية، لذا يستحسن رفع هامش الأمان:

# crushrc
option request-timeout 300

# crush.json
"options": { "request_timeout": 300 }

التوقيعات في الـ commits. تحمل الـ commits وطلبات الدمج التي ينشئها Crush افتراضيًا سطر Assisted-by: Crush:<model> وعبارة "Generated with Crush". إذا لم تكن بحاجة لذلك:

# crushrc
option attribution-trailer-style none
option attribution-generated-with false

# crush.json
"options": { "attribution": { "trailer_style": "none", "generated_with": false } }

المقاييس. يرسل Crush للمطوّرين إحصاءات استخدام مجهولة الهوية — بيانات وصفية فقط، دون prompts أو ردود. يُعطَّل عبر المتغير CRUSH_DISABLE_METRICS=1 أو DO_NOT_TRACK=1. أما البوابة من جانبها فلا تحتفظ بمحتوى الـ prompts والردود — ولا يبقى في الإحصاءات سوى مجاميع الاستهلاك.

الإعدادات هي شيفرة. ينفّذ Crush كلاً من crushrc وcrush.json بصلاحيات الـ shell الخاصة بك: $(…) في حقل المفتاح سيُنفَّذ عند التحميل، كما سيعمل crushrc الخاص بالمشروع بمجرد فتحك Crush في ذلك المجلد. لا تشغّل الوكيل في مستودع شخص آخر دون قراءة إعداداته.